Change header file guard names.

[u/mdw/catacomb] / dsa.h

/* -*-c-*-
 *
 * $Id: dsa.h,v 1.3 1999/12/10 23:29:48 mdw Exp $
 *
 * Digital Signature Algorithm
 *
 * (c) 1999 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 * 
 * Catacomb is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: dsa.h,v $
 * Revision 1.3  1999/12/10 23:29:48  mdw
 * Change header file guard names.
 *
 * Revision 1.2  1999/11/20 22:23:48  mdw
 * Allow event handler to abort the search process.
 *
 * Revision 1.1  1999/11/19 19:28:00  mdw
 * Implementation of the Digital Signature Algorithm.
 *
 */

#ifndef CATACOMB_DSA_H
#define CATACOMB_DSA_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Notes on the Digital Signature Algorithm --------------------------*
 *
 * The Digital Signature Algorithm was designed by the NSA for US Government
 * use.  It's defined in FIPS 186-1.  Whether it's covered by patents is
 * under dispute, although it looks relatively clear.  It produces compact
 * signatures, and is relatively easy to compute.  It seems strong, if
 * appropriate parameters are chosen.
 */

/*----- Header files ------------------------------------------------------*/

#ifndef CATACOMB_MP_H
#  include "mp.h"
#endif

/*----- Event codes -------------------------------------------------------*/

enum {
  DSAEV_OK,				/* Everything is fine */

  DSAEV_FINDQ,				/* Search for a @q@ */
  DSAEV_FAILQ,				/* @q@ failed primality test */
  DSAEV_PASSQ,				/* @q@ passeed one iteration */
  DSAEV_GOODQ,				/* Found good prime @q@ */

  DSAEV_FINDP,				/* Search for a @p@ */
  DSAEV_TRYP,				/* Try prospective @p@ */
  DSAEV_FAILP,				/* @p@ failed primality test */
  DSAEV_PASSP,				/* @p@ passed one iteration */
  DSAEV_GOODP,				/* @p@ accepted as being prime */

  DSAEV_FINDG,				/* Search for a @g@ */
  DSAEV_TRYH,				/* Try prospective @h@ */
  DSAEV_FAILH,				/* @h@ failed */
  DSAEV_GOODG				/* @g@ accepted as a generator */
};

/*----- Data structures ---------------------------------------------------*/

/* --- DSA parameter structure --- *
 *
 * These parameters can, and probably should, be shared among a group of
 * users.
 */

typedef struct dsa_param {
  mp *p, *q;				/* Prime numbers %$p$% and %$q$% */
  mp *g;				/* Generates order-%$q$% subgroup */
} dsa_param;

/* --- DSA signature structure --- *
 *
 * This is the recommended structure for a DSA signature.  The actual signing
 * function can cope with arbitrary-sized objects given appropriate
 * parameters, however.
 */

#define DSA_SIGLEN 20

typedef struct dsa_sig {
  octet r[DSA_SIGLEN];			/* 160-bit @r@ value */
  octet s[DSA_SIGLEN];			/* 160-bit @s@ value */
} dsa_sig;

/*----- Functions provided ------------------------------------------------*/

/* --- @dsa_seed@ --- *
 *
 * Arguments:	@dsa_param *dp@ = where to store parameters
 *		@unsigned l@ = bitlength of @p@ in bits
 *		@const void *k@ = pointer to key material
 *		@int (*proc)(int ev, mp *m, void *p)@ = event procedure
 *		@size_t sz@ = size of key material
 *
 * Returns:	Zero if all went well, nonzero if key material was
 *		unsuitable (one of the @DSAEV@ codes).
 *
 * Use:		Generates the DSA shared parameters from a given seed value.
 *		This can take quite a long time.  The size of @p@ in bits is
 *		%$l = 512 + 64l'$%.  The DSA standard, FIPS 186, only allows
 *		%$0 \le l' \le 8$%.  This implementation has no such limit,
 *		although @l@ must be a multiple of 8.
 *
 *		The event procedure is informed of various happenings during
 *		generation.  It is passed an event code describing what
 *		happened, and a multiprecision number which pertains to the
 *		event code.  It may abort the search at any time by returning
 *		a nonzero value, which is returned as the result of the
 *		function.
 */

extern int dsa_seed(dsa_param */*dp*/, unsigned /*l*/,
		    const void */*k*/, size_t /*sz*/,
		    int (*proc)(int /*ev*/, mp */*m*/, void */*p*/),
		    void */*p*/);

/* --- @dsa_mksig@ --- *
 *
 * Arguments:	@const dsa_param *dp@ = pointer to DSA parameters
 *		@mp *a@ = secret signing key
 *		@mp *m@ = message to be signed
 *		@mp *k@ = random data
 *		@mp **rr, **ss@ = where to put output parameters
 *
 * Returns:	---
 *
 * Use:		Computes a DSA signature of a message.
 */

extern void dsa_mksig(const dsa_param */*dp*/, mp */*a*/,
		      mp */*m*/, mp */*k*/,
		      mp **/*rr*/, mp **/*ss*/);

/* --- @dsa_sign@ --- *
 *
 * Arguments:	@dsa_param *dp@ = pointer to DSA parameters
 *		@mp *a@ = pointer to secret signing key
 *		@const void *m@ = pointer to message
 *		@size_t msz@ = size of the message
 *		@const void *k@ = secret random data for securing signature
 *		@size_t ksz@ = size of secret data
 *		@void *r@ = pointer to output space for @r@
 *		@size_t rsz@ = size of output space for @r@
 *		@void *s@ = pointer to output space for @s@
 *		@size_t ssz@ = size of output space for @s@
 *
 * Returns:	---
 *
 * Use:		Signs a message, storing the results in a big-endian binary
 *		form.
 */

extern void dsa_sign(dsa_param */*dp*/, mp */*a*/,
		     const void */*m*/, size_t /*msz*/,
		     const void */*k*/, size_t /*ksz*/,
		     void */*r*/, size_t /*rsz*/,
		     void */*s*/, size_t /*ssz*/);

/* --- @dsa_vrfy@ --- *
 *
 * Arguments:	@const dsa_param *dp@ = pointer to DSA parameters
 *		@mp *y@ = public verification key
 *		@mp *m@ = message which was signed
 *		@mp *r, *s@ = the signature
 *
 * Returns:	Zero if the signature is a forgery, nonzero if it's valid.
 *
 * Use:		Verifies a DSA digital signature.
 */

extern int dsa_vrfy(const dsa_param */*dp*/, mp */*y*/,
		    mp */*m*/, mp */*r*/, mp */*s*/);

/* --- @dsa_verify@ --- *
 *
 * Arguments:	@const dsa_param *dp@ = pointer to DSA parameters
 *		@mp *y@ = public verification key
 *		@const void *m@ = pointer to message block
 *		@size_t msz@ = size of message block
 *		@const void *r@ = pointer to @r@ signature half
 *		@size_t rsz@ = size of @r@
 *		@const void *s@ = pointer to @s@ signature half
 *		@size_t ssz@ = size of @s@
 *
 * Returns:	Zero if the signature is a forgery, nonzero if it's valid.
 *
 * Use:		Verifies a DSA digital signature.
 */

extern int dsa_verify(const dsa_param */*dp*/, mp */*y*/,
	       const void */*m*/, size_t /*msz*/,
	       const void */*r*/, size_t /*rsz*/,
	       const void */*s*/, size_t /*ssz*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif