3 * $Id: dsa.h,v 1.3 1999/12/10 23:29:48 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.3 1999/12/10 23:29:48 mdw
34 * Change header file guard names.
36 * Revision 1.2 1999/11/20 22:23:48 mdw
37 * Allow event handler to abort the search process.
39 * Revision 1.1 1999/11/19 19:28:00 mdw
40 * Implementation of the Digital Signature Algorithm.
44 #ifndef CATACOMB_DSA_H
45 #define CATACOMB_DSA_H
51 /*----- Notes on the Digital Signature Algorithm --------------------------*
53 * The Digital Signature Algorithm was designed by the NSA for US Government
54 * use. It's defined in FIPS 186-1. Whether it's covered by patents is
55 * under dispute, although it looks relatively clear. It produces compact
56 * signatures, and is relatively easy to compute. It seems strong, if
57 * appropriate parameters are chosen.
60 /*----- Header files ------------------------------------------------------*/
66 /*----- Event codes -------------------------------------------------------*/
69 DSAEV_OK
, /* Everything is fine */
71 DSAEV_FINDQ
, /* Search for a @q@ */
72 DSAEV_FAILQ
, /* @q@ failed primality test */
73 DSAEV_PASSQ
, /* @q@ passeed one iteration */
74 DSAEV_GOODQ
, /* Found good prime @q@ */
76 DSAEV_FINDP
, /* Search for a @p@ */
77 DSAEV_TRYP
, /* Try prospective @p@ */
78 DSAEV_FAILP
, /* @p@ failed primality test */
79 DSAEV_PASSP
, /* @p@ passed one iteration */
80 DSAEV_GOODP
, /* @p@ accepted as being prime */
82 DSAEV_FINDG
, /* Search for a @g@ */
83 DSAEV_TRYH
, /* Try prospective @h@ */
84 DSAEV_FAILH
, /* @h@ failed */
85 DSAEV_GOODG
/* @g@ accepted as a generator */
88 /*----- Data structures ---------------------------------------------------*/
90 /* --- DSA parameter structure --- *
92 * These parameters can, and probably should, be shared among a group of
96 typedef struct dsa_param
{
97 mp
*p
, *q
; /* Prime numbers %$p$% and %$q$% */
98 mp
*g
; /* Generates order-%$q$% subgroup */
101 /* --- DSA signature structure --- *
103 * This is the recommended structure for a DSA signature. The actual signing
104 * function can cope with arbitrary-sized objects given appropriate
105 * parameters, however.
108 #define DSA_SIGLEN 20
110 typedef struct dsa_sig
{
111 octet r
[DSA_SIGLEN
]; /* 160-bit @r@ value */
112 octet s
[DSA_SIGLEN
]; /* 160-bit @s@ value */
115 /*----- Functions provided ------------------------------------------------*/
117 /* --- @dsa_seed@ --- *
119 * Arguments: @dsa_param *dp@ = where to store parameters
120 * @unsigned l@ = bitlength of @p@ in bits
121 * @const void *k@ = pointer to key material
122 * @int (*proc)(int ev, mp *m, void *p)@ = event procedure
123 * @size_t sz@ = size of key material
125 * Returns: Zero if all went well, nonzero if key material was
126 * unsuitable (one of the @DSAEV@ codes).
128 * Use: Generates the DSA shared parameters from a given seed value.
129 * This can take quite a long time. The size of @p@ in bits is
130 * %$l = 512 + 64l'$%. The DSA standard, FIPS 186, only allows
131 * %$0 \le l' \le 8$%. This implementation has no such limit,
132 * although @l@ must be a multiple of 8.
134 * The event procedure is informed of various happenings during
135 * generation. It is passed an event code describing what
136 * happened, and a multiprecision number which pertains to the
137 * event code. It may abort the search at any time by returning
138 * a nonzero value, which is returned as the result of the
142 extern int dsa_seed(dsa_param */
*dp*/
, unsigned /*l*/,
143 const void */
*k*/
, size_t /*sz*/,
144 int (*proc
)(int /*ev*/, mp */
*m*/
, void */
*p*/
),
147 /* --- @dsa_mksig@ --- *
149 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
150 * @mp *a@ = secret signing key
151 * @mp *m@ = message to be signed
152 * @mp *k@ = random data
153 * @mp **rr, **ss@ = where to put output parameters
157 * Use: Computes a DSA signature of a message.
160 extern void dsa_mksig(const dsa_param */
*dp*/
, mp */
*a*/
,
161 mp */
*m*/
, mp */
*k*/
,
162 mp
**/
*rr*/
, mp
**/
*ss*/
);
164 /* --- @dsa_sign@ --- *
166 * Arguments: @dsa_param *dp@ = pointer to DSA parameters
167 * @mp *a@ = pointer to secret signing key
168 * @const void *m@ = pointer to message
169 * @size_t msz@ = size of the message
170 * @const void *k@ = secret random data for securing signature
171 * @size_t ksz@ = size of secret data
172 * @void *r@ = pointer to output space for @r@
173 * @size_t rsz@ = size of output space for @r@
174 * @void *s@ = pointer to output space for @s@
175 * @size_t ssz@ = size of output space for @s@
179 * Use: Signs a message, storing the results in a big-endian binary
183 extern void dsa_sign(dsa_param */
*dp*/
, mp */
*a*/
,
184 const void */
*m*/
, size_t /*msz*/,
185 const void */
*k*/
, size_t /*ksz*/,
186 void */
*r*/
, size_t /*rsz*/,
187 void */
*s*/
, size_t /*ssz*/);
189 /* --- @dsa_vrfy@ --- *
191 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
192 * @mp *y@ = public verification key
193 * @mp *m@ = message which was signed
194 * @mp *r, *s@ = the signature
196 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
198 * Use: Verifies a DSA digital signature.
201 extern int dsa_vrfy(const dsa_param */
*dp*/
, mp */
*y*/
,
202 mp */
*m*/
, mp */
*r*/
, mp */
*s*/
);
204 /* --- @dsa_verify@ --- *
206 * Arguments: @const dsa_param *dp@ = pointer to DSA parameters
207 * @mp *y@ = public verification key
208 * @const void *m@ = pointer to message block
209 * @size_t msz@ = size of message block
210 * @const void *r@ = pointer to @r@ signature half
211 * @size_t rsz@ = size of @r@
212 * @const void *s@ = pointer to @s@ signature half
213 * @size_t ssz@ = size of @s@
215 * Returns: Zero if the signature is a forgery, nonzero if it's valid.
217 * Use: Verifies a DSA digital signature.
220 extern int dsa_verify(const dsa_param */
*dp*/
, mp */
*y*/
,
221 const void */
*m*/
, size_t /*msz*/,
222 const void */
*r*/
, size_t /*rsz*/,
223 const void */
*s*/
, size_t /*ssz*/);
225 /*----- That's all, folks -------------------------------------------------*/