/* -*-c-*-
*
- * $Id: rsa.h,v 1.2 2000/06/17 12:07:36 mdw Exp $
+ * $Id: rsa.h,v 1.3 2000/07/01 11:24:37 mdw Exp $
*
* The RSA public-key cryptosystem
*
/*----- Revision history --------------------------------------------------*
*
* $Log: rsa.h,v $
+ * Revision 1.3 2000/07/01 11:24:37 mdw
+ * Remove bad type name `rsa_param'. New functions for freeing public and
+ * private keys. Add types and functions for doing pubic key operations,
+ * and padded RSA operations.
+ *
* Revision 1.2 2000/06/17 12:07:36 mdw
* Add key fetching interface. Add new rsa_decrypt interface.
*
/*----- 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 int (*rsa_encodeproc)(const void */*m*/, size_t /*msz*/,
+ void */*buf*/, size_t /*sz*/, void */*p*/);
+typedef int (*rsa_decodeproc)(const void */*m*/, size_t /*msz*/,
+ dstr */*d*/, void */*p*/);
/*----- Key fetching ------------------------------------------------------*/
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.
*
* 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
+ * @const void *m@ = pointer to input message
+ * @size_t sz@ = size of input message
+ * @dstr *d@ = pointer to output string
+ * @rsa_encodeproc e@ = encoding procedure
+ * @void *earg@ = argument pointer for encoding procedure
+ *
+ * Returns: The length of the output string if successful, negative on
+ * failure.
*
- * Use: Performs RSA decryption, very carefully.
+ * Use: Computes an RSA digital signature.
*/
-extern mp *rsa_decrypt(rsa_param */*rp*/, mp */*d*/, mp */*c*/,
- grand */*r*/);
+extern int rsa_sign(rsa_privctx */*rp*/, const void */*m*/, size_t /*sz*/,
+ dstr */*d*/, rsa_encodeproc /*e*/, void */*earg*/);
+
+/* --- @rsa_decrypt@ --- *
+ *
+ * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context
+ * @const void *m@ = pointer to input message
+ * @size_t sz@ = size of input message
+ * @dstr *d@ = pointer to output string
+ * @rsa_decodeproc 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 signature verification.
+ */
+
+extern int rsa_decrypt(rsa_privctx */*rp*/, const void */*m*/, size_t /*sz*/,
+ dstr */*d*/, rsa_decodeproc /*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
+ * @const void *m@ = pointer to input message
+ * @size_t sz@ = size of input message
+ * @dstr *d@ = pointer to output string
+ * @rsa_encodeproc e@ = encoding procedure
+ * @void *earg@ = argument pointer for encoding procedure
+ *
+ * Returns: The length of the output string if successful, negative on
+ * failure.
+ *
+ * Use: Does RSA encryption.
+ */
+
+extern int rsa_encrypt(rsa_pubctx */*rp*/, const void */*m*/, size_t /*sz*/,
+ dstr */*d*/, rsa_encodeproc /*e*/, void */*earg*/);
+
+/* --- @rsa_verify@ --- *
+ *
+ * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key contxt
+ * @const void *m@ = pointer to input message
+ * @size_t sz@ = size of input message
+ * @dstr *d@ = pointer to output string
+ * @rsa_decodeproc 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 signature verification.
+ */
+
+extern int rsa_verify(rsa_pubctx */*rp*/, const void */*m*/, size_t /*sz*/,
+ dstr */*d*/, rsa_decodeproc /*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.
* 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*/);
/*----- That's all, folks -------------------------------------------------*/
projects / u / mdw / catacomb / commitdiff