3 * $Id: dsa.h,v 1.1 1999/11/19 19:28:00 mdw Exp $
5 * Digital Signature Algorithm
7 * (c) 1999 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of Catacomb.
14 * Catacomb is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU Library General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
19 * Catacomb is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU Library General Public License for more details.
24 * You should have received a copy of the GNU Library General Public
25 * License along with Catacomb; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.1 1999/11/19 19:28:00 mdw
34 * Implementation of the Digital Signature Algorithm.
45 /*----- Notes on the Digital Signature Algorithm --------------------------*
47 * The Digital Signature Algorithm was designed by the NSA for US Government
48 * use. It's defined in FIPS 186-1. Whether it's covered by patents is
49 * under dispute, although it looks relatively clear. It produces compact
50 * signatures, and is relatively easy to compute. It seems strong, if
51 * appropriate parameters are chosen.
54 /*----- Header files ------------------------------------------------------*/
60 /*----- Event codes -------------------------------------------------------*/
63 DSAEV_OK, /* Everything is fine */
65 DSAEV_FAILQ, /* @q@ failed primality test */
66 DSAEV_PASSQ, /* @q@ passeed one iteration */
67 DSAEV_GOODQ, /* Found good prime @q@ */
69 DSAEV_TRYP, /* Try prospective @p@ */
70 DSAEV_FAILP, /* @p@ failed primality test */
71 DSAEV_PASSP, /* @p@ passed one iteration */
72 DSAEV_GOODP, /* @p@ accepted as being prime */
74 DSAEV_TRYH, /* Try prospective @h@ */
75 DSAEV_FAILH, /* @h@ failed */
76 DSAEV_GOODG /* @g@ accepted as a generator */
79 /*----- Data structures ---------------------------------------------------*/
81 /* --- DSA parameter structure --- *
83 * These parameters can, and probably should, be shared among a group of
87 typedef struct dsa_param {
88 mp *p, *q; /* Prime numbers %$p$% and %$q$% */
89 mp *g; /* Generates order-%$q$% subgroup */
92 /* --- DSA signature structure --- *
94 * This is the recommended structure for a DSA signature. The actual signing
95 * function can cope with arbitrary-sized objects given appropriate
96 * parameters, however.
101 typedef struct dsa_sig {
102 octet r[DSA_SIGLEN]; /* 160-bit @r@ value */
103 octet s[DSA_SIGLEN]; /* 160-bit @s@ value */
106 /*----- Functions provided ------------------------------------------------*/
108 /* --- @dsa_seed@ --- *
110 * Arguments: @dsa_param *dp@ = where to store parameters
111 * @unsigned l@ = bitlength of @p@ in bits
112 * @const void *k@ = pointer to key material
113 * @size_t sz@ = size of key material
114 * @void (*proc)(int ev, mp *m, void *p)@ = event procedure
115 * @void *p@ = argument for event procedure
117 * Returns: Zero if all went well, nonzero if key material was
118 * unsuitable (one of the @DSAEV@ codes).
120 * Use: Generates the DSA shared parameters from a given seed value.
121 * This can take quite a long time. The size of @p@ in bits is
122 * %$l = 512 + 64l'$%. The DSA standard, FIPS 186, only allows
123 * %$0 \le l' \le 8$%. This implementation has no such limit,
124 * although @l@ must be a multiple of 8.
126 * The event procedure is informed of various happenings during
127 * generation. It is passed an event code describing what
128 * happened, and a multiprecision number which pertains to the
132 extern int dsa_seed(dsa_param */*dp*/, unsigned /*l*/,
133 const void */*k*/, size_t /*sz*/,
134 void (*proc)(int /*ev*/, mp */*m*/, void */*p*/),
137 /* --- @dsa_mksig@ --- *
139 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
140 * @const mp *a@ = secret signing key
141 * @const mp *m@ = message to be signed
142 * @const mp *k@ = random data
143 * @mp **rr, **ss@ = where to put output parameters
147 * Use: Computes a DSA signature of a message.
150 extern void dsa_mksig(const dsa_param */*dp*/, const mp */*a*/,
151 const mp */*m*/, const mp */*k*/,
152 mp **/*rr*/, mp **/*ss*/);
154 /* --- @dsa_sign@ --- *
156 * Arguments: @dsa_param *dp@ = pointer to DSA parameters
157 * @mp *a@ = pointer to secret signing key
158 * @const void *m@ = pointer to message
159 * @size_t msz@ = size of the message
160 * @const void *k@ = secret random data for securing signature
161 * @size_t ksz@ = size of secret data
162 * @void *r@ = pointer to output space for @r@
163 * @size_t rsz@ = size of output space for @r@
164 * @void *s@ = pointer to output space for @s@
165 * @size_t ssz@ = size of output space for @s@
169 * Use: Signs a message, storing the results in a big-endian binary
173 extern void dsa_sign(dsa_param */*dp*/, mp */*a*/,
174 const void */*m*/, size_t /*msz*/,
175 const void */*k*/, size_t /*ksz*/,
176 void */*r*/, size_t /*rsz*/,
177 void */*s*/, size_t /*ssz*/);
179 /* --- @dsa_vrfy@ --- *
181 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
182 * @const mp *y@ = public verification key
183 * @const mp *m@ = message which was signed
184 * @const mp *r, *s@ = the signature
186 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
188 * Use: Verifies a DSA digital signature.
191 extern int dsa_vrfy(const dsa_param */*dp*/, const mp */*y*/,
192 const mp */*m*/, const mp */*r*/, const mp */*s*/);
194 /* --- @dsa_verify@ --- *
196 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
197 * @const mp *y@ = public verification key
198 * @const void *m@ = pointer to message block
199 * @size_t msz@ = size of message block
200 * @const void *r@ = pointer to @r@ signature half
201 * @size_t rsz@ = size of @r@
202 * @const void *s@ = pointer to @s@ signature half
203 * @size_t ssz@ = size of @s@
205 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
207 * Use: Verifies a DSA digital signature.
210 extern int dsa_verify(const dsa_param */*dp*/, const mp */*y*/,
211 const void */*m*/, size_t /*msz*/,
212 const void */*r*/, size_t /*rsz*/,
213 const void */*s*/, size_t /*ssz*/);
215 /*----- That's all, folks -------------------------------------------------*/