Renamed from `rsa-decrypt', since the name was no longer appropriate.

[u/mdw/catacomb] / rsa.h

/* -*-c-*-
 *
 * $Id: rsa.h,v 1.2 2000/06/17 12:07:36 mdw Exp $
 *
 * The RSA public-key cryptosystem
 *
 * (c) 1999 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 * 
 * Catacomb is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: rsa.h,v $
 * Revision 1.2  2000/06/17 12:07:36  mdw
 * Add key fetching interface.  Add new rsa_decrypt interface.
 *
 * Revision 1.1  1999/12/22 15:50:45  mdw
 * Initial RSA support.
 *
 */

#ifndef CATACOMB_RSA_H
#define CATACOMB_RSA_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#ifndef CATACOMB_GRAND_H
#  include "grand.h"
#endif

#ifndef CATACOMB_KEY_H
#  include "key.h"
#endif

#ifndef CATACOMB_MP_H
#  include "mp.h"
#endif

#ifndef CATACOMB_PGEN_H
#  include "pgen.h"
#endif

/*----- Data structures ---------------------------------------------------*/

typedef struct rsa_pub {
  mp *n;
  mp *e;
} rsa_pub;

typedef struct rsa_param {
  mp *n, *p, *q, *q_inv;
  mp *e, *d, *dp, *dq;
} rsa_param, rsa_priv;

typedef struct rsa_decctx {
  rsa_param *rp;
  grand *r;
  mpmont nm, pm, qm;
} rsa_decctx;

/*----- Key fetching ------------------------------------------------------*/

extern const key_fetchdef rsa_pubfetch[];
#define RSA_PUBFETCHSZ 4

extern const key_fetchdef rsa_privfetch[];
#define RSA_PRIVFETCHSZ 12

/*----- Functions provided ------------------------------------------------*/

/* --- @rsa_gen@ --- *
 *
 * Arguments:	@rsa_param *rp@ = pointer to block to be filled in
 *		@unsigned nbits@ = required modulus size in bits
 *		@grand *r@ = random number source
 *		@unsigned n@ = number of attempts to make
 *		@pgen_proc *event@ = event handler function
 *		@void *ectx@ = argument for the event handler
 *
 * Returns:	Zero if all went well, nonzero otherwise.
 *
 * Use:		Constructs a pair of strong RSA primes and other useful RSA
 *		parameters.  A small encryption exponent is chosen if
 *		possible.
 */

extern int rsa_gen(rsa_param */*rp*/, unsigned /*nbits*/,
		   grand */*r*/, unsigned /*n*/,
		   pgen_proc */*event*/, void */*ectx*/);

/* --- @rsa_deccreate@ --- *
 *
 * Arguments:	@rsa_decctx *rd@ = pointer to an RSA decryption context
 *		@rsa_priv *rp@ = pointer to RSA private key
 *		@grand *r@ = pointer to random number source for blinding
 *
 * Returns:	---
 *
 * Use:		Initializes an RSA decryption context.  Keeping a context
 *		for several decryption or signing operations provides a minor
 *		performance benefit.
 *
 *		The random number source may be null if blinding is not
 *		desired.  This improves decryption speed, at the risk of
 *		permitting timing attacks.
 */

extern void rsa_deccreate(rsa_decctx */*rd*/, rsa_param */*rp*/,
			  grand */*r*/);

/* --- @rsa_decdestroy@ --- *
 *
 * Arguments:	@rsa_decctx *rd@ = pointer to an RSA decryption context
 *
 * Returns:	---
 *
 * Use:		Destroys an RSA decryption context.
 */

extern void rsa_decdestroy(rsa_decctx */*rd*/);

/* --- @rsa_dec@ --- *
 *
 * Arguments:	@rsa_decctx *rd@ = pointer to RSA decryption context
 *		@mp *d@ = destination
 *		@mp *c@ = ciphertext message
 *
 * Returns:	The recovered plaintext message.
 *
 * Use:		Performs RSA decryption.  This function takes advantage of
 *		knowledge of the key factors in order to speed up
 *		decryption.  It also blinds the ciphertext prior to
 *		decryption and unblinds it afterwards to thwart timing
 *		attacks.
 */

extern mp *rsa_dec(rsa_decctx */*rd*/, mp */*d*/, mp */*c*/);

/* --- @rsa_decrypt@ --- *
 *
 * Arguments:	@rsa_param *rp@ = pointer to RSA parameters
 *		@mp *d@ = destination
 *		@mp *c@ = ciphertext message
 *		@grand *r@ = pointer to random number source for blinding
 *
 * Returns:	Correctly decrypted message.
 *
 * Use:		Performs RSA decryption, very carefully.
 */

extern mp *rsa_decrypt(rsa_param */*rp*/, mp */*d*/, mp */*c*/,
		       grand */*r*/);

/* --- @rsa_recover@ --- *
 *
 * Arguments:	@rsa_param *rp@ = pointer to parameter block
 *
 * Returns:	Zero if all went well, nonzero if the parameters make no
 *		sense.
 *
 * Use:		Derives the full set of RSA parameters given a minimal set.
 */

extern int rsa_recover(rsa_param */*rp*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif