3 * Digital Signature Algorithm
5 * (c) 1999 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
12 * Catacomb is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Library General Public License as
14 * published by the Free Software Foundation; either version 2 of the
15 * License, or (at your option) any later version.
17 * Catacomb is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Library General Public License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with Catacomb; if not, write to the Free
24 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
28 #ifndef CATACOMB_DSA_H
29 #define CATACOMB_DSA_H
35 /*----- Notes on the Digital Signature Algorithm --------------------------*
37 * The Digital Signature Algorithm was designed by the NSA for US Government
38 * use. It's defined in FIPS 186-1. Whether it's covered by patents is
39 * under dispute, although it looks relatively clear. It produces compact
40 * signatures, and is relatively easy to compute. It seems strong, if
41 * appropriate parameters are chosen.
44 /*----- Header files ------------------------------------------------------*/
46 #include <mLib/macros.h>
52 #ifndef CATACOMB_GRAND_H
56 #ifndef CATACOMB_KEY_H
60 #ifndef CATACOMB_KEYCHECK_H
61 # include "keycheck.h"
68 #ifndef CATACOMB_PGEN_H
72 /*----- Data structures ---------------------------------------------------*/
74 /* --- The parameters and keys are the same as for Diffie-Hellman --- */
76 typedef dh_param dsa_param
;
77 typedef dh_pub dsa_pub
;
78 typedef dh_priv dsa_priv
;
80 /* --- DSA key seed structure --- */
82 typedef struct dsa_seed
{
83 void *p
; /* Pointer to seed material */
84 size_t sz
; /* Size of seed material */
85 unsigned count
; /* Iterations to find @p@ */
88 /* --- DSA signature structure --- *
90 * This is the recommended structure for a DSA signature. The actual signing
91 * function can cope with arbitrary-sized objects given appropriate
92 * parameters, however.
97 typedef struct dsa_sig
{
98 octet r
[DSA_SIGLEN
]; /* 160-bit @r@ value */
99 octet s
[DSA_SIGLEN
]; /* 160-bit @s@ value */
102 /*----- Key fetching ------------------------------------------------------*/
104 #define dsa_paramfetch dh_paramfetch
105 #define dsa_pubfetch dh_pubfetch
106 #define dsa_privfetch dh_privfetch
108 #define DSA_PARAMFETCHSZ DH_PARAMFETCHSZ
109 #define DSA_PUBFETCHSZ DH_PUBFETCHSZ
110 #define DSA_PRIVFETCHSZ DH_PRIVFETCHSZ
112 #define dsa_paramfree dh_paramfree
113 #define dsa_pubfree dh_pubfree
114 #define dsa_privfree dh_privfree
116 /*----- DSA stepper -------------------------------------------------------*/
118 typedef struct dsa_stepctx
{
120 /* --- To be initialized by the client --- */
122 grand
*r
; /* Random number generator */
123 mp
*q
; /* Force @p@ to be a multiple */
124 size_t bits
; /* Number of bits in the result */
125 unsigned or; /* OR mask for low order bits */
126 unsigned count
; /* Counts the number of steps made */
127 void *seedbuf
; /* Pointer to seed buffer */
130 /* --- @dsa_step@ --- *
132 * The stepper chooses random integers, ensures that they are a multiple of
133 * @q@ (if specified), sets the low-order bits, and then tests for
134 * divisibility by small primes.
137 extern pgen_proc dsa_step
;
139 /*----- Functions provided ------------------------------------------------*/
141 /* --- @dsa_gen@ --- *
143 * Arguments: @dsa_param *dp@ = where to store parameters
144 * @unsigned ql@ = length of @q@ in bits
145 * @unsigned pl@ = length of @p@ in bits
146 * @unsigned steps@ = number of steps to find @q@
147 * @const void *k@ = pointer to key material
148 * @size_t sz@ = size of key material
149 * @dsa_seed *sd@ = optional pointer for output seed information
150 * @pgen_proc *event@ = event handler function
151 * @void *ectx@ = argument for event handler
153 * Returns: @PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise.
155 * Use: Generates the DSA shared parameters from a given seed value.
156 * This can take quite a long time.
158 * The algorithm used is a compatible extension of the method
159 * described in the DSA standard, FIPS 186. The standard
160 * requires that %$q$% be 160 bits in size (i.e., @ql == 160@)
161 * and that the length of %$p$% be %$L = 512 + 64l$% for some
162 * %$l$%. Neither limitation applies to this implementation.
165 extern int dsa_gen(dsa_param */
*dp*/
, unsigned /*ql*/, unsigned /*pl*/,
166 unsigned /*steps*/, const void */
*k*/
, size_t /*sz*/,
167 dsa_seed */
*sd*/
, pgen_proc */
*event*/
, void */
*ectx*/
);
169 /* --- @dsa_checkparam@ --- *
171 * Arguments: @keycheck *kc@ = keycheck state
172 * @const dsa_param *dp@ = pointer to the parameter set
173 * @const dsa_seed *ds@ = pointer to seed information
175 * Returns: Zero if all OK, or return status from function.
177 * Use: Checks a set of DSA parameters for consistency and security.
180 extern int dsa_checkparam(keycheck */
*kc*/
, const dsa_param */
*dp*/
,
181 const dsa_seed */
*ds*/
);
183 /* --- @dsa_h2n@ --- *
185 * Arguments: @mp *d@ = destination integer
186 * @mp *r@ = order of the DSA group
187 * @const void *h@ = pointer to message hash
188 * @size_t hsz@ = size (in bytes) of the hash output
190 * Returns: Resulting integer.
192 * Use: Converts a hash to an integer in the demented way necessary
193 * for DSA/ECDSA. This is, of course, completely insane, but
197 extern mp
*dsa_h2n(mp */
*d*/
, mp */
*r*/
, const void */
*h*/
, size_t /*hsz*/);
199 /* --- @dsa_nonce@ --- *
201 * Arguments: @mp *d@ = destination integer
202 * @mp *q@ = order of the DSA group
203 * @mp *x@ = secret key
204 * @const octet *m@ = message hash
205 * @const gchash *ch@ = hash class
206 * @grand *r@ = random bit source, or null
210 * Use: Generates a nonce for use in DSA (or another Fiat--Shamir
214 extern mp
*dsa_nonce(mp */
*d*/
, mp */
*q*/
, mp */
*x*/
, const octet */
*m*/
,
215 const gchash */
*ch*/
, grand */
*r*/
);
217 /* --- @dsa_mksig@ --- *
219 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
220 * @mp *a@ = secret signing key
221 * @mp *m@ = message to be signed
222 * @mp *k@ = random data
223 * @mp **rr, **ss@ = where to put output parameters
227 * Use: Computes a DSA signature of a message.
229 * This function is deprecated. It's really rather badly
230 * designed, and hard to use securely (and hard to fix). Please
231 * use @gdsa_sign@ instead.
235 #ifndef CATACOMB_DSAIMPL
236 DEPRECATED("please use `gdsa_sign' instead")
238 void dsa_mksig(const dsa_param */
*dp*/
, mp */
*a*/
, mp */
*m*/
, mp */
*k*/
,
239 mp
**/
*rr*/
, mp
**/
*ss*/
);
241 /* --- @dsa_sign@ --- *
243 * Arguments: @dsa_param *dp@ = pointer to DSA parameters
244 * @mp *a@ = pointer to secret signing key
245 * @const void *m@ = pointer to message
246 * @size_t msz@ = size of the message
247 * @const void *k@ = secret random data for securing signature
248 * @size_t ksz@ = size of secret data
249 * @void *r@ = pointer to output space for @r@
250 * @size_t rsz@ = size of output space for @r@
251 * @void *s@ = pointer to output space for @s@
252 * @size_t ssz@ = size of output space for @s@
256 * Use: Signs a message, storing the results in a big-endian binary
259 * This function is deprecated. It's really rather badly
260 * designed, and hard to use securely (and hard to fix). Please
261 * use @gdsa_sign@ instead.
265 #ifndef CATACOMB_DSAIMPL
266 DEPRECATED("please use `gdsa_sign' instead")
268 void dsa_sign(dsa_param */
*dp*/
, mp */
*a*/
,
269 const void */
*m*/
, size_t /*msz*/,
270 const void */
*k*/
, size_t /*ksz*/,
271 void */
*r*/
, size_t /*rsz*/, void */
*s*/
, size_t /*ssz*/);
273 /* --- @dsa_vrfy@ --- *
275 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
276 * @mp *y@ = public verification key
277 * @mp *m@ = message which was signed
278 * @mp *r, *s@ = the signature
280 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
282 * Use: Verifies a DSA digital signature.
285 extern int dsa_vrfy(const dsa_param */
*dp*/
, mp */
*y*/
,
286 mp */
*m*/
, mp */
*r*/
, mp */
*s*/
);
288 /* --- @dsa_verify@ --- *
290 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
291 * @mp *y@ = public verification key
292 * @const void *m@ = pointer to message block
293 * @size_t msz@ = size of message block
294 * @const void *r@ = pointer to @r@ signature half
295 * @size_t rsz@ = size of @r@
296 * @const void *s@ = pointer to @s@ signature half
297 * @size_t ssz@ = size of @s@
299 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
301 * Use: Verifies a DSA digital signature.
304 extern int dsa_verify(const dsa_param */
*dp*/
, mp */
*y*/
,
305 const void */
*m*/
, size_t /*msz*/,
306 const void */
*r*/
, size_t /*rsz*/,
307 const void */
*s*/
, size_t /*ssz*/);
309 /*----- That's all, folks -------------------------------------------------*/