3 * $Id: dsa.h,v 1.8 2001/02/03 16:08:24 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.8 2001/02/03 16:08:24 mdw
34 * Add consistency checking for public keys.
36 * Revision 1.7 2000/07/29 09:59:44 mdw
37 * Share data structures with Diffie-Hellman stuff.
39 * Revision 1.6 2000/07/01 11:20:51 mdw
40 * New functions for freeing public and private keys.
42 * Revision 1.5 2000/06/17 10:53:42 mdw
43 * Minor changes for key fetching. Typesetting fixes.
45 * Revision 1.4 1999/12/22 15:52:44 mdw
46 * Reworking for new prime-search system.
48 * Revision 1.3 1999/12/10 23:29:48 mdw
49 * Change header file guard names.
51 * Revision 1.2 1999/11/20 22:23:48 mdw
52 * Allow event handler to abort the search process.
54 * Revision 1.1 1999/11/19 19:28:00 mdw
55 * Implementation of the Digital Signature Algorithm.
59 #ifndef CATACOMB_DSA_H
60 #define CATACOMB_DSA_H
66 /*----- Notes on the Digital Signature Algorithm --------------------------*
68 * The Digital Signature Algorithm was designed by the NSA for US Government
69 * use. It's defined in FIPS 186-1. Whether it's covered by patents is
70 * under dispute, although it looks relatively clear. It produces compact
71 * signatures, and is relatively easy to compute. It seems strong, if
72 * appropriate parameters are chosen.
75 /*----- Header files ------------------------------------------------------*/
81 #ifndef CATACOMB_KEY_H
85 #ifndef CATACOMB_KEYCHECK_H
86 # include "keycheck.h"
93 #ifndef CATACOMB_PGEN_H
97 /*----- Data structures ---------------------------------------------------*/
99 /* --- The parameters and keys are the same as for Diffie-Hellman --- */
101 typedef dh_param dsa_param
;
102 typedef dh_pub dsa_pub
;
103 typedef dh_priv dsa_priv
;
105 /* --- DSA key seed structure --- */
107 typedef struct dsa_seed
{
108 void *p
; /* Pointer to seed material */
109 size_t sz
; /* Size of seed material */
110 unsigned count
; /* Iterations to find @p@ */
113 /* --- DSA signature structure --- *
115 * This is the recommended structure for a DSA signature. The actual signing
116 * function can cope with arbitrary-sized objects given appropriate
117 * parameters, however.
120 #define DSA_SIGLEN 20
122 typedef struct dsa_sig
{
123 octet r
[DSA_SIGLEN
]; /* 160-bit @r@ value */
124 octet s
[DSA_SIGLEN
]; /* 160-bit @s@ value */
127 /*----- Key fetching ------------------------------------------------------*/
129 #define dsa_paramfetch dh_paramfetch
130 #define dsa_pubfetch dh_pubfetch
131 #define dsa_privfetch dh_privfetch
133 #define DSA_PARAMFETCHSZ DH_PARAMFETCHSZ
134 #define DSA_PUBFETCHSZ DH_PUBFETCHSZ
135 #define DSA_PRIVFETCHSZ DH_PRIVFETCHSZ
137 #define dsa_paramfree dh_paramfree
138 #define dsa_pubfree dh_pubfree
139 #define dsa_privfree dh_privfree
141 /*----- DSA stepper -------------------------------------------------------*/
143 typedef struct dsa_stepctx
{
145 /* --- To be initialized by the client --- */
147 grand
*r
; /* Random number generator */
148 mp
*q
; /* Force @p@ to be a multiple */
149 size_t bits
; /* Number of bits in the result */
150 unsigned or; /* OR mask for low order bits */
151 unsigned count
; /* Counts the number of steps made */
152 void *seedbuf
; /* Pointer to seed buffer */
155 /* --- @dsa_step@ --- *
157 * The stepper chooses random integers, ensures that they are a multiple of
158 * @q@ (if specified), sets the low-order bits, and then tests for
159 * divisibility by small primes.
162 extern int dsa_step(int /*rq*/, pgen_event */
*ev*/
, void */
*p*/
);
164 /*----- Functions provided ------------------------------------------------*/
166 /* --- @dsa_gen@ --- *
168 * Arguments: @dsa_param *dp@ = where to store parameters
169 * @unsigned ql@ = length of @q@ in bits
170 * @unsigned pl@ = length of @p@ in bits
171 * @unsigned steps@ = number of steps to find @q@
172 * @const void *k@ = pointer to key material
173 * @size_t sz@ = size of key material
174 * @dsa_seed *sd@ = optional pointer for output seed information
175 * @pgen_proc *event@ = event handler function
176 * @void *ectx@ = argument for event handler
178 * Returns: @PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise.
180 * Use: Generates the DSA shared parameters from a given seed value.
181 * This can take quite a long time.
183 * The algorithm used is a compatible extension of the method
184 * described in the DSA standard, FIPS 186. The standard
185 * requires that %$q$% be 160 bits in size (i.e., @ql == 160@)
186 * and that the length of %$p$% be %$L = 512 + 64l$% for some
187 * %$l$%. Neither limitation applies to this implementation.
190 extern int dsa_gen(dsa_param */
*dp*/
, unsigned /*ql*/, unsigned /*pl*/,
191 unsigned /*steps*/, const void */
*k*/
, size_t /*sz*/,
192 dsa_seed */
*sd*/
, pgen_proc */
*event*/
, void */
*ectx*/
);
194 /* --- @dsa_checkparam@ --- *
196 * Arguments: @keycheck *kc@ = keycheck state
197 * @const dsa_param *dp@ = pointer to the parameter set
198 * @const dsa_seed *ds@ = pointer to seed information
200 * Returns: Zero if all OK, or return status from function.
202 * Use: Checks a set of DSA parameters for consistency and security.
205 extern int dsa_checkparam(keycheck */
*kc*/
, const dsa_param */
*dp*/
,
206 const dsa_seed */
*ds*/
);
208 /* --- @dsa_mksig@ --- *
210 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
211 * @mp *a@ = secret signing key
212 * @mp *m@ = message to be signed
213 * @mp *k@ = random data
214 * @mp **rr, **ss@ = where to put output parameters
218 * Use: Computes a DSA signature of a message.
221 extern void dsa_mksig(const dsa_param */
*dp*/
, mp */
*a*/
,
222 mp */
*m*/
, mp */
*k*/
,
223 mp
**/
*rr*/
, mp
**/
*ss*/
);
225 /* --- @dsa_sign@ --- *
227 * Arguments: @dsa_param *dp@ = pointer to DSA parameters
228 * @mp *a@ = pointer to secret signing key
229 * @const void *m@ = pointer to message
230 * @size_t msz@ = size of the message
231 * @const void *k@ = secret random data for securing signature
232 * @size_t ksz@ = size of secret data
233 * @void *r@ = pointer to output space for @r@
234 * @size_t rsz@ = size of output space for @r@
235 * @void *s@ = pointer to output space for @s@
236 * @size_t ssz@ = size of output space for @s@
240 * Use: Signs a message, storing the results in a big-endian binary
244 extern void dsa_sign(dsa_param */
*dp*/
, mp */
*a*/
,
245 const void */
*m*/
, size_t /*msz*/,
246 const void */
*k*/
, size_t /*ksz*/,
247 void */
*r*/
, size_t /*rsz*/,
248 void */
*s*/
, size_t /*ssz*/);
250 /* --- @dsa_vrfy@ --- *
252 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
253 * @mp *y@ = public verification key
254 * @mp *m@ = message which was signed
255 * @mp *r, *s@ = the signature
257 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
259 * Use: Verifies a DSA digital signature.
262 extern int dsa_vrfy(const dsa_param */
*dp*/
, mp */
*y*/
,
263 mp */
*m*/
, mp */
*r*/
, mp */
*s*/
);
265 /* --- @dsa_verify@ --- *
267 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
268 * @mp *y@ = public verification key
269 * @const void *m@ = pointer to message block
270 * @size_t msz@ = size of message block
271 * @const void *r@ = pointer to @r@ signature half
272 * @size_t rsz@ = size of @r@
273 * @const void *s@ = pointer to @s@ signature half
274 * @size_t ssz@ = size of @s@
276 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
278 * Use: Verifies a DSA digital signature.
281 extern int dsa_verify(const dsa_param */
*dp*/
, mp */
*y*/
,
282 const void */
*m*/
, size_t /*msz*/,
283 const void */
*r*/
, size_t /*rsz*/,
284 const void */
*s*/
, size_t /*ssz*/);
286 /*----- That's all, folks -------------------------------------------------*/