X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/ba6e6b64033b1f9de49feccb5c9cd438354481f7..0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a:/pub/dsa.h diff --git a/pub/dsa.h b/pub/dsa.h new file mode 100644 index 0000000..3b93d93 --- /dev/null +++ b/pub/dsa.h @@ -0,0 +1,277 @@ +/* -*-c-*- + * + * Digital Signature Algorithm + * + * (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_DSA_H +#define CATACOMB_DSA_H + +#ifdef __cplusplus + extern "C" { +#endif + +/*----- Notes on the Digital Signature Algorithm --------------------------* + * + * The Digital Signature Algorithm was designed by the NSA for US Government + * use. It's defined in FIPS 186-1. Whether it's covered by patents is + * under dispute, although it looks relatively clear. It produces compact + * signatures, and is relatively easy to compute. It seems strong, if + * appropriate parameters are chosen. + */ + +/*----- Header files ------------------------------------------------------*/ + +#ifndef CATACOMB_DH_H +# include "dh.h" +#endif + +#ifndef CATACOMB_KEY_H +# include "key.h" +#endif + +#ifndef CATACOMB_KEYCHECK_H +# include "keycheck.h" +#endif + +#ifndef CATACOMB_MP_H +# include "mp.h" +#endif + +#ifndef CATACOMB_PGEN_H +# include "pgen.h" +#endif + +/*----- Data structures ---------------------------------------------------*/ + +/* --- The parameters and keys are the same as for Diffie-Hellman --- */ + +typedef dh_param dsa_param; +typedef dh_pub dsa_pub; +typedef dh_priv dsa_priv; + +/* --- DSA key seed structure --- */ + +typedef struct dsa_seed { + void *p; /* Pointer to seed material */ + size_t sz; /* Size of seed material */ + unsigned count; /* Iterations to find @p@ */ +} dsa_seed; + +/* --- DSA signature structure --- * + * + * This is the recommended structure for a DSA signature. The actual signing + * function can cope with arbitrary-sized objects given appropriate + * parameters, however. + */ + +#define DSA_SIGLEN 20 + +typedef struct dsa_sig { + octet r[DSA_SIGLEN]; /* 160-bit @r@ value */ + octet s[DSA_SIGLEN]; /* 160-bit @s@ value */ +} dsa_sig; + +/*----- Key fetching ------------------------------------------------------*/ + +#define dsa_paramfetch dh_paramfetch +#define dsa_pubfetch dh_pubfetch +#define dsa_privfetch dh_privfetch + +#define DSA_PARAMFETCHSZ DH_PARAMFETCHSZ +#define DSA_PUBFETCHSZ DH_PUBFETCHSZ +#define DSA_PRIVFETCHSZ DH_PRIVFETCHSZ + +#define dsa_paramfree dh_paramfree +#define dsa_pubfree dh_pubfree +#define dsa_privfree dh_privfree + +/*----- DSA stepper -------------------------------------------------------*/ + +typedef struct dsa_stepctx { + + /* --- To be initialized by the client --- */ + + grand *r; /* Random number generator */ + mp *q; /* Force @p@ to be a multiple */ + size_t bits; /* Number of bits in the result */ + unsigned or; /* OR mask for low order bits */ + unsigned count; /* Counts the number of steps made */ + void *seedbuf; /* Pointer to seed buffer */ +} dsa_stepctx; + +/* --- @dsa_step@ --- * + * + * The stepper chooses random integers, ensures that they are a multiple of + * @q@ (if specified), sets the low-order bits, and then tests for + * divisibility by small primes. + */ + +extern pgen_proc dsa_step; + +/*----- Functions provided ------------------------------------------------*/ + +/* --- @dsa_gen@ --- * + * + * Arguments: @dsa_param *dp@ = where to store parameters + * @unsigned ql@ = length of @q@ in bits + * @unsigned pl@ = length of @p@ in bits + * @unsigned steps@ = number of steps to find @q@ + * @const void *k@ = pointer to key material + * @size_t sz@ = size of key material + * @dsa_seed *sd@ = optional pointer for output seed information + * @pgen_proc *event@ = event handler function + * @void *ectx@ = argument for event handler + * + * Returns: @PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise. + * + * Use: Generates the DSA shared parameters from a given seed value. + * This can take quite a long time. + * + * The algorithm used is a compatible extension of the method + * described in the DSA standard, FIPS 186. The standard + * requires that %$q$% be 160 bits in size (i.e., @ql == 160@) + * and that the length of %$p$% be %$L = 512 + 64l$% for some + * %$l$%. Neither limitation applies to this implementation. + */ + +extern int dsa_gen(dsa_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/, + unsigned /*steps*/, const void */*k*/, size_t /*sz*/, + dsa_seed */*sd*/, pgen_proc */*event*/, void */*ectx*/); + +/* --- @dsa_checkparam@ --- * + * + * Arguments: @keycheck *kc@ = keycheck state + * @const dsa_param *dp@ = pointer to the parameter set + * @const dsa_seed *ds@ = pointer to seed information + * + * Returns: Zero if all OK, or return status from function. + * + * Use: Checks a set of DSA parameters for consistency and security. + */ + +extern int dsa_checkparam(keycheck */*kc*/, const dsa_param */*dp*/, + const dsa_seed */*ds*/); + +/* --- @dsa_h2n@ --- * + * + * Arguments: @mp *d@ = destination integer + * @mp *r@ = order of the DSA group + * @const void *h@ = pointer to message hash + * @size_t hsz@ = size (in bytes) of the hash output + * + * Returns: Resulting integer. + * + * Use: Converts a hash to an integer in the demented way necessary + * for DSA/ECDSA. This is, of course, completely insane, but + * there you go. + */ + +extern mp *dsa_h2n(mp */*d*/, mp */*r*/, const void */*h*/, size_t /*hsz*/); + +/* --- @dsa_mksig@ --- * + * + * Arguments: @const dsa_param *dp@ = pointer to DSA parameters + * @mp *a@ = secret signing key + * @mp *m@ = message to be signed + * @mp *k@ = random data + * @mp **rr, **ss@ = where to put output parameters + * + * Returns: --- + * + * Use: Computes a DSA signature of a message. + */ + +extern void dsa_mksig(const dsa_param */*dp*/, mp */*a*/, + mp */*m*/, mp */*k*/, + mp **/*rr*/, mp **/*ss*/); + +/* --- @dsa_sign@ --- * + * + * Arguments: @dsa_param *dp@ = pointer to DSA parameters + * @mp *a@ = pointer to secret signing key + * @const void *m@ = pointer to message + * @size_t msz@ = size of the message + * @const void *k@ = secret random data for securing signature + * @size_t ksz@ = size of secret data + * @void *r@ = pointer to output space for @r@ + * @size_t rsz@ = size of output space for @r@ + * @void *s@ = pointer to output space for @s@ + * @size_t ssz@ = size of output space for @s@ + * + * Returns: --- + * + * Use: Signs a message, storing the results in a big-endian binary + * form. + */ + +extern void dsa_sign(dsa_param */*dp*/, mp */*a*/, + const void */*m*/, size_t /*msz*/, + const void */*k*/, size_t /*ksz*/, + void */*r*/, size_t /*rsz*/, + void */*s*/, size_t /*ssz*/); + +/* --- @dsa_vrfy@ --- * + * + * Arguments: @const dsa_param *dp@ = pointer to DSA parameters + * @mp *y@ = public verification key + * @mp *m@ = message which was signed + * @mp *r, *s@ = the signature + * + * Returns: Zero if the signature is a forgery, nonzero if it's valid. + * + * Use: Verifies a DSA digital signature. + */ + +extern int dsa_vrfy(const dsa_param */*dp*/, mp */*y*/, + mp */*m*/, mp */*r*/, mp */*s*/); + +/* --- @dsa_verify@ --- * + * + * Arguments: @const dsa_param *dp@ = pointer to DSA parameters + * @mp *y@ = public verification key + * @const void *m@ = pointer to message block + * @size_t msz@ = size of message block + * @const void *r@ = pointer to @r@ signature half + * @size_t rsz@ = size of @r@ + * @const void *s@ = pointer to @s@ signature half + * @size_t ssz@ = size of @s@ + * + * Returns: Zero if the signature is a forgery, nonzero if it's valid. + * + * Use: Verifies a DSA digital signature. + */ + +extern int dsa_verify(const dsa_param */*dp*/, mp */*y*/, + const void */*m*/, size_t /*msz*/, + const void */*r*/, size_t /*rsz*/, + const void */*s*/, size_t /*ssz*/); + +/*----- That's all, folks -------------------------------------------------*/ + +#ifdef __cplusplus + } +#endif + +#endif