X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/81e9d7ec6f841c47b32a538961a67f99a4937840..a6864ad907239985bd1f6eab414cec6171930d46:/rsa.h diff --git a/rsa.h b/rsa.h index 0aabdd2..f4b1c14 100644 --- a/rsa.h +++ b/rsa.h @@ -1,13 +1,13 @@ /* -*-c-*- * - * $Id: rsa.h,v 1.2 2000/06/17 12:07:36 mdw Exp $ + * $Id: rsa.h,v 1.4 2004/04/08 01:36:15 mdw Exp $ * * The RSA public-key cryptosystem * * (c) 1999 Straylight/Edgeware */ -/*----- Licensing notice --------------------------------------------------* +/*----- Licensing notice --------------------------------------------------* * * This file is part of Catacomb. * @@ -15,29 +15,18 @@ * 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 @@ -51,6 +40,14 @@ # include "grand.h" #endif +#ifndef CATACOMB_GCIPHER_H +# include "gcipher.h" +#endif + +#ifndef CATACOMB_GHASH_H +# include "ghash.h" +#endif + #ifndef CATACOMB_KEY_H # include "key.h" #endif @@ -65,21 +62,50 @@ /*----- Data structures ---------------------------------------------------*/ +/* --- RSA private and public keys --- */ + typedef struct rsa_pub { mp *n; mp *e; } rsa_pub; -typedef struct rsa_param { +typedef struct rsa_priv { mp *n, *p, *q, *q_inv; mp *e, *d, *dp, *dq; -} rsa_param, rsa_priv; +} rsa_priv; -typedef struct rsa_decctx { - rsa_param *rp; +/* --- RSA private and public key contexts --- * + * + * These are used to store information about `active' keys which will speed + * up the various operations. + */ + +typedef struct rsa_privctx { + rsa_priv *rp; grand *r; mpmont nm, pm, qm; -} rsa_decctx; +} rsa_privctx; + +typedef struct rsa_pubctx { + mpmont mm; + rsa_pub *rp; +} rsa_pubctx; + +/* --- Encoding and decoding function schemas --- * + * + * See `oaep.h' and `pkcs1.h' for appropriate encoding functions. + */ + +typedef mp *rsa_pad(mp */*d*/, const void */*m*/, size_t /*msz*/, + octet */*b*/, size_t /*sz*/, + unsigned long /*nbits*/, void */*p*/); + +typedef int rsa_decunpad(mp */*m*/, octet */*b*/, size_t /*sz*/, + unsigned long /*nbits*/, void */*p*/); + +typedef int rsa_vrfunpad(mp */*s*/, const void */*m*/, size_t /*msz*/, + octet */*b*/, size_t /*sz*/, + unsigned long /*nbits*/, void */*p*/); /*----- Key fetching ------------------------------------------------------*/ @@ -89,37 +115,29 @@ extern const key_fetchdef rsa_pubfetch[]; extern const key_fetchdef rsa_privfetch[]; #define RSA_PRIVFETCHSZ 12 -/*----- Functions provided ------------------------------------------------*/ - -/* --- @rsa_gen@ --- * +/* --- @rsa_pubfree@, @rsa_privfree@ --- * * - * 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 + * Arguments: @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block * - * Returns: Zero if all went well, nonzero otherwise. + * Returns: --- * - * Use: Constructs a pair of strong RSA primes and other useful RSA - * parameters. A small encryption exponent is chosen if - * possible. + * Use: Frees an RSA key block. */ -extern int rsa_gen(rsa_param */*rp*/, unsigned /*nbits*/, - grand */*r*/, unsigned /*n*/, - pgen_proc */*event*/, void */*ectx*/); +extern void rsa_pubfree(rsa_pub */*rp*/); +extern void rsa_privfree(rsa_priv */*rp*/); + +/*----- RSA private key operations ----------------------------------------*/ -/* --- @rsa_deccreate@ --- * +/* --- @rsa_privcreate@ --- * * - * Arguments: @rsa_decctx *rd@ = pointer to an RSA decryption context + * Arguments: @rsa_privctx *rd@ = pointer to an RSA private key 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 + * Use: Initializes an RSA private-key context. Keeping a context * for several decryption or signing operations provides a minor * performance benefit. * @@ -128,55 +146,206 @@ extern int rsa_gen(rsa_param */*rp*/, unsigned /*nbits*/, * permitting timing attacks. */ -extern void rsa_deccreate(rsa_decctx */*rd*/, rsa_param */*rp*/, - grand */*r*/); +extern void rsa_privcreate(rsa_privctx */*rd*/, rsa_priv */*rp*/, + grand */*r*/); -/* --- @rsa_decdestroy@ --- * +/* --- @rsa_privdestroy@ --- * * - * Arguments: @rsa_decctx *rd@ = pointer to an RSA decryption context + * Arguments: @rsa_privctx *rd@ = pointer to an RSA decryption context * * Returns: --- * * Use: Destroys an RSA decryption context. */ -extern void rsa_decdestroy(rsa_decctx */*rd*/); +extern void rsa_privdestroy(rsa_privctx */*rd*/); -/* --- @rsa_dec@ --- * +/* --- @rsa_privop@ --- * * - * Arguments: @rsa_decctx *rd@ = pointer to RSA decryption context + * Arguments: @rsa_privctx *rd@ = pointer to RSA private key context * @mp *d@ = destination - * @mp *c@ = ciphertext message + * @mp *c@ = input message * - * Returns: The recovered plaintext message. + * Returns: The transformed output 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 + * Use: Performs an RSA private key operation. 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*/); +extern mp *rsa_privop(rsa_privctx */*rd*/, mp */*d*/, mp */*c*/); -/* --- @rsa_decrypt@ --- * +/* --- @rsa_qprivop@ --- * * - * Arguments: @rsa_param *rp@ = pointer to RSA parameters + * Arguments: @rsa_priv *rp@ = pointer to RSA parameters * @mp *d@ = destination - * @mp *c@ = ciphertext message + * @mp *c@ = input message * @grand *r@ = pointer to random number source for blinding * - * Returns: Correctly decrypted message. + * Returns: Correctly transformed output message + * + * Use: Performs an RSA private key operation, very carefully. + */ + +extern mp *rsa_qprivop(rsa_priv */*rp*/, mp */*d*/, mp */*c*/, grand */*r*/); + +/* --- @rsa_sign@ --- * + * + * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context + * @mp *d@ = where to put the result + * @const void *m@ = pointer to input message + * @size_t msz@ = size of input message + * @rsa_pad *e@ = encoding procedure + * @void *earg@ = argument pointer for encoding procedure + * + * Returns: The signature, as a multiprecision integer, or null on + * failure. + * + * Use: Computes an RSA digital signature. + */ + +extern mp *rsa_sign(rsa_privctx */*rp*/, mp */*d*/, + const void */*m*/, size_t /*msz*/, + rsa_pad */*e*/, void */*earg*/); + +/* --- @rsa_decrypt@ --- * + * + * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context + * @mp *m@ = encrypted message, as a multiprecision integer + * @dstr *d@ = pointer to output string + * @rsa_decunpad *e@ = decoding procedure + * @void *earg@ = argument pointer for decoding procedure * - * Use: Performs RSA decryption, very carefully. + * Returns: The length of the output string if successful, negative on + * failure. + * + * Use: Does RSA decryption. */ -extern mp *rsa_decrypt(rsa_param */*rp*/, mp */*d*/, mp */*c*/, - grand */*r*/); +extern int rsa_decrypt(rsa_privctx */*rp*/, mp */*m*/, + dstr */*d*/, rsa_decunpad */*e*/, void */*earg*/); + +/*----- RSA public key operations -----------------------------------------*/ + +/* --- @rsa_pubcreate@ --- * + * + * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context + * @rsa_pub *rp@ = pointer to RSA public key + * + * Returns: --- + * + * Use: Initializes an RSA public-key context. + */ + +extern void rsa_pubcreate(rsa_pubctx */*rd*/, rsa_pub */*rp*/); + +/* --- @rsa_pubdestroy@ --- * + * + * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context + * + * Returns: --- + * + * Use: Destroys an RSA public-key context. + */ + +extern void rsa_pubdestroy(rsa_pubctx */*rd*/); + +/* --- @rsa_pubop@ --- * + * + * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context + * @mp *d@ = destination + * @mp *p@ = input message + * + * Returns: The transformed output message. + * + * Use: Performs an RSA public key operation. + */ + +extern mp *rsa_pubop(rsa_pubctx */*rd*/, mp */*d*/, mp */*p*/); + +/* --- @rsa_qpubop@ --- * + * + * Arguments: @rsa_pub *rp@ = pointer to RSA parameters + * @mp *d@ = destination + * @mp *p@ = input message + * + * Returns: Correctly transformed output message. + * + * Use: Performs an RSA public key operation. + */ + +extern mp *rsa_qpubop(rsa_pub */*rp*/, mp */*d*/, mp */*c*/); + +/* --- @rsa_encrypt@ --- * + * + * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key context + * @mp *d@ = proposed destination integer + * @const void *m@ = pointer to input message + * @size_t msz@ = size of input message + * @rsa_pad *e@ = encoding procedure + * @void *earg@ = argument pointer for encoding procedure + * + * Returns: The encrypted message, as a multiprecision integer, or null + * on failure. + * + * Use: Does RSA encryption. + */ + +extern mp *rsa_encrypt(rsa_pubctx */*rp*/, mp */*d*/, + const void */*m*/, size_t /*msz*/, + rsa_pad */*e*/, void */*earg*/); + +/* --- @rsa_verify@ --- * + * + * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key contxt + * @mp *s@ = the signature, as a multiprecision integer + * @const void *m@ = pointer to message to verify, or null + * @size_t sz@ = size of input message + * @dstr *d@ = pointer to output string, or null + * @rsa_vfrunpad *e@ = decoding procedure + * @void *earg@ = argument pointer for decoding procedure + * + * Returns: The length of the output string if successful (0 if no output + * was wanted); negative on failure. + * + * Use: Does RSA signature verification. To use a signature scheme + * with recovery, pass in @m == 0@ and @d != 0@: the recovered + * message should appear in @d@. To use a signature scheme with + * appendix, provide @m != 0@ and @d == 0@; the result should be + * zero for success. + */ + +extern int rsa_verify(rsa_pubctx */*rp*/, mp */*s*/, + const void */*m*/, size_t /*sz*/, dstr */*d*/, + rsa_vrfunpad */*e*/, void */*earg*/); + +/*----- Miscellaneous operations ------------------------------------------*/ + +/* --- @rsa_gen@ --- * + * + * Arguments: @rsa_priv *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_priv */*rp*/, unsigned /*nbits*/, + grand */*r*/, unsigned /*n*/, + pgen_proc */*event*/, void */*ectx*/); /* --- @rsa_recover@ --- * * - * Arguments: @rsa_param *rp@ = pointer to parameter block + * Arguments: @rsa_priv *rp@ = pointer to parameter block * * Returns: Zero if all went well, nonzero if the parameters make no * sense. @@ -184,7 +353,47 @@ extern mp *rsa_decrypt(rsa_param */*rp*/, mp */*d*/, mp */*c*/, * Use: Derives the full set of RSA parameters given a minimal set. */ -extern int rsa_recover(rsa_param */*rp*/); +extern int rsa_recover(rsa_priv */*rp*/); + +/*----- Padding schemes ---------------------------------------------------*/ + +/* --- PKCS1 padding --- */ + +typedef struct pkcs1 { + grand *r; /* Random number source */ + const void *ep; /* Encoding parameters block */ + size_t epsz; /* Size of the parameter block */ +} pkcs1; + +extern rsa_pad pkcs1_cryptencode; +extern rsa_decunpad pkcs1_cryptdecode; +extern rsa_pad pkcs1_sigencode; +extern rsa_vrfunpad pkcs1_sigdecode; + +/* --- OAEP --- */ + +typedef struct oaep { + const gccipher *cc; /* Cipher class for masking */ + const gchash *ch; /* Hash class for parameter block */ + grand *r; /* Random number source */ + const void *ep; /* Encoding parameters block */ + size_t epsz; /* Size of the parameter block */ +} oaep; + +extern rsa_pad oaep_encode; +extern rsa_decunpad oaep_decode; + +/* --- PSS --- */ + +typedef struct pss { + const gccipher *cc; /* Cipher class for masking */ + const gchash *ch; /* Hash class for choosing a seed */ + grand *r; /* Random number source */ + size_t ssz; /* Requested salt size */ +} pss; + +extern rsa_pad pss_encode; +extern rsa_vrfunpad pss_decode; /*----- That's all, folks -------------------------------------------------*/