3 * $Id: dsa.h,v 1.6 2000/07/01 11:20:51 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.6 2000/07/01 11:20:51 mdw
34 * New functions for freeing public and private keys.
36 * Revision 1.5 2000/06/17 10:53:42 mdw
37 * Minor changes for key fetching. Typesetting fixes.
39 * Revision 1.4 1999/12/22 15:52:44 mdw
40 * Reworking for new prime-search system.
42 * Revision 1.3 1999/12/10 23:29:48 mdw
43 * Change header file guard names.
45 * Revision 1.2 1999/11/20 22:23:48 mdw
46 * Allow event handler to abort the search process.
48 * Revision 1.1 1999/11/19 19:28:00 mdw
49 * Implementation of the Digital Signature Algorithm.
53 #ifndef CATACOMB_DSA_H
54 #define CATACOMB_DSA_H
60 /*----- Notes on the Digital Signature Algorithm --------------------------*
62 * The Digital Signature Algorithm was designed by the NSA for US Government
63 * use. It's defined in FIPS 186-1. Whether it's covered by patents is
64 * under dispute, although it looks relatively clear. It produces compact
65 * signatures, and is relatively easy to compute. It seems strong, if
66 * appropriate parameters are chosen.
69 /*----- Header files ------------------------------------------------------*/
71 #ifndef CATACOMB_KEY_H
79 #ifndef CATACOMB_PGEN_H
83 /*----- Data structures ---------------------------------------------------*/
85 /* --- DSA parameter structure --- *
87 * These parameters can, and probably should, be shared among a group of
91 typedef struct dsa_param
{
92 mp
*p
, *q
; /* Prime numbers %$p$% and %$q$% */
93 mp
*g
; /* Generates order-%$q$% subgroup */
96 typedef struct dsa_pub
{
97 dsa_param dp
; /* Shared parameters */
98 mp
*y
; /* Public key */
101 typedef struct dsa_priv
{
102 dsa_param dp
; /* Shared parameters */
103 mp
*x
; /* Private key */
104 mp
*y
; /* %$y \equiv g^x \pmod{p}$% */
107 /* --- DSA signature structure --- *
109 * This is the recommended structure for a DSA signature. The actual signing
110 * function can cope with arbitrary-sized objects given appropriate
111 * parameters, however.
114 #define DSA_SIGLEN 20
116 typedef struct dsa_sig
{
117 octet r
[DSA_SIGLEN
]; /* 160-bit @r@ value */
118 octet s
[DSA_SIGLEN
]; /* 160-bit @s@ value */
121 /*----- Key fetching ------------------------------------------------------*/
123 extern const key_fetchdef dsa_paramfetch
[];
124 #define DSA_PARAMFETCHSZ 5
126 extern const key_fetchdef dsa_pubfetch
[];
127 #define DSA_PUBFETCHSZ 6
129 extern const key_fetchdef dsa_privfetch
[];
130 #define DSA_PRIVFETCHSZ 9
132 /* --- @dsa_paramfree@, @dsa_pubfree@, @dsa_privfree@ --- *
134 * Arguments: @dsa_param *dp@, @dsa_pub *dp@, @dsa_priv *dp@ = pointer
135 * to key block to free
139 * Use: Frees a DSA key block.
142 extern void dsa_paramfree(dsa_param */
*dp*/
);
143 extern void dsa_pubfree(dsa_pub */
*dp*/
);
144 extern void dsa_privfree(dsa_priv */
*dp*/
);
146 /*----- DSA stepper -------------------------------------------------------*/
148 typedef struct dsa_stepctx
{
150 /* --- To be initialized by the client --- */
152 grand
*r
; /* Random number generator */
153 mp
*q
; /* Force @p@ to be a multiple */
154 size_t bits
; /* Number of bits in the result */
155 unsigned or; /* OR mask for low order bits */
158 /* --- @dsa_step@ --- *
160 * The stepper chooses random integers, ensures that they are a multiple of
161 * @q@ (if specified), sets the low-order bits, and then tests for
162 * divisibility by small primes.
165 extern int dsa_step(int /*rq*/, pgen_event */
*ev*/
, void */
*p*/
);
167 /*----- Functions provided ------------------------------------------------*/
169 /* --- @dsa_seed@ --- *
171 * Arguments: @dsa_param *dp@ = where to store parameters
172 * @unsigned ql@ = length of @q@ in bits
173 * @unsigned pl@ = length of @p@ in bits
174 * @unsigned steps@ = number of steps to find @q@
175 * @const void *k@ = pointer to key material
176 * @size_t sz@ = size of key material
177 * @pgen_proc *event@ = event handler function
178 * @void *ectx@ = argument for event handler
180 * Returns: @PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise.
182 * Use: Generates the DSA shared parameters from a given seed value.
183 * This can take quite a long time.
185 * The algorithm used is a compatible extension of the method
186 * described in the DSA standard, FIPS 186. The standard
187 * requires that %$q$% be 160 bits in size (i.e., @ql == 160@)
188 * and that the length of %$p$% be %$L = 512 + 64l$% for some
189 * %$l$%. Neither limitation applies to this implementation.
192 extern int dsa_seed(dsa_param */
*dp*/
, unsigned /*ql*/, unsigned /*pl*/,
193 unsigned /*steps*/, const void */
*k*/
, size_t /*sz*/,
194 pgen_proc */
*event*/
, void */
*ectx*/
);
196 /* --- @dsa_mksig@ --- *
198 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
199 * @mp *a@ = secret signing key
200 * @mp *m@ = message to be signed
201 * @mp *k@ = random data
202 * @mp **rr, **ss@ = where to put output parameters
206 * Use: Computes a DSA signature of a message.
209 extern void dsa_mksig(const dsa_param */
*dp*/
, mp */
*a*/
,
210 mp */
*m*/
, mp */
*k*/
,
211 mp
**/
*rr*/
, mp
**/
*ss*/
);
213 /* --- @dsa_sign@ --- *
215 * Arguments: @dsa_param *dp@ = pointer to DSA parameters
216 * @mp *a@ = pointer to secret signing key
217 * @const void *m@ = pointer to message
218 * @size_t msz@ = size of the message
219 * @const void *k@ = secret random data for securing signature
220 * @size_t ksz@ = size of secret data
221 * @void *r@ = pointer to output space for @r@
222 * @size_t rsz@ = size of output space for @r@
223 * @void *s@ = pointer to output space for @s@
224 * @size_t ssz@ = size of output space for @s@
228 * Use: Signs a message, storing the results in a big-endian binary
232 extern void dsa_sign(dsa_param */
*dp*/
, mp */
*a*/
,
233 const void */
*m*/
, size_t /*msz*/,
234 const void */
*k*/
, size_t /*ksz*/,
235 void */
*r*/
, size_t /*rsz*/,
236 void */
*s*/
, size_t /*ssz*/);
238 /* --- @dsa_vrfy@ --- *
240 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
241 * @mp *y@ = public verification key
242 * @mp *m@ = message which was signed
243 * @mp *r, *s@ = the signature
245 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
247 * Use: Verifies a DSA digital signature.
250 extern int dsa_vrfy(const dsa_param */
*dp*/
, mp */
*y*/
,
251 mp */
*m*/
, mp */
*r*/
, mp */
*s*/
);
253 /* --- @dsa_verify@ --- *
255 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
256 * @mp *y@ = public verification key
257 * @const void *m@ = pointer to message block
258 * @size_t msz@ = size of message block
259 * @const void *r@ = pointer to @r@ signature half
260 * @size_t rsz@ = size of @r@
261 * @const void *s@ = pointer to @s@ signature half
262 * @size_t ssz@ = size of @s@
264 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
266 * Use: Verifies a DSA digital signature.
269 extern int dsa_verify(const dsa_param */
*dp*/
, mp */
*y*/
,
270 const void */
*m*/
, size_t /*msz*/,
271 const void */
*r*/
, size_t /*rsz*/,
272 const void */
*s*/
, size_t /*ssz*/);
274 /*----- That's all, folks -------------------------------------------------*/