General utilities cleanup. Add signature support to catcrypt. Throw in

[u/mdw/catacomb] / rsa.h

/* -*-c-*-
 *
 * $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 --------------------------------------------------* 
 *
 * 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.
 */

#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_GCIPHER_H
#  include "gcipher.h"
#endif

#ifndef CATACOMB_GHASH_H
#  include "ghash.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 ---------------------------------------------------*/

/* --- RSA private and public keys --- */

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

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

/* --- 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_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 ------------------------------------------------------*/

extern const key_fetchdef rsa_pubfetch[];
#define RSA_PUBFETCHSZ 4

extern const key_fetchdef rsa_privfetch[];
#define RSA_PRIVFETCHSZ 12

/* --- @rsa_pubfree@, @rsa_privfree@ --- *
 *
 * Arguments:   @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block
 *
 * Returns:     ---
 *
 * Use:         Frees an RSA key block.
 */

extern void rsa_pubfree(rsa_pub */*rp*/);
extern void rsa_privfree(rsa_priv */*rp*/);

/*----- RSA private key operations ----------------------------------------*/

/* --- @rsa_privcreate@ --- *
 *
 * 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 private-key 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_privcreate(rsa_privctx */*rd*/, rsa_priv */*rp*/,
                           grand */*r*/);

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

extern void rsa_privdestroy(rsa_privctx */*rd*/);

/* --- @rsa_privop@ --- *
 *
 * Arguments:   @rsa_privctx *rd@ = pointer to RSA private key context
 *              @mp *d@ = destination
 *              @mp *c@ = input message
 *
 * Returns:     The transformed output message.
 *
 * 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_privop(rsa_privctx */*rd*/, mp */*d*/, mp */*c*/);

/* --- @rsa_qprivop@ --- *
 *
 * Arguments:   @rsa_priv *rp@ = pointer to RSA parameters
 *              @mp *d@ = destination
 *              @mp *c@ = input message
 *              @grand *r@ = pointer to random number source for blinding
 *
 * 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
 *
 * Returns:     The length of the output string if successful, negative on
 *              failure.
 *
 * Use:         Does RSA decryption.
 */

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_priv *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_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 -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif