Overhaul `math' representation machinery.

[u/mdw/catacomb] / pub / dsa.h

/* -*-c-*-
 *
 * 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.
 */

#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_DH_H
#  include "dh.h"
#endif

#ifndef CATACOMB_KEY_H
#  include "key.h"
#endif

#ifndef CATACOMB_KEYCHECK_H
#  include "keycheck.h"
#endif

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

#ifndef CATACOMB_PGEN_H
#  include "pgen.h"
#endif

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

/* --- The parameters and keys are the same as for Diffie-Hellman --- */

typedef dh_param dsa_param;
typedef dh_pub dsa_pub;
typedef dh_priv dsa_priv;

/* --- DSA key seed structure --- */

typedef struct dsa_seed {
  void *p;				/* Pointer to seed material */
  size_t sz;				/* Size of seed material */
  unsigned count;			/* Iterations to find @p@ */
} dsa_seed;

/* --- 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;

/*----- Key fetching ------------------------------------------------------*/

#define dsa_paramfetch dh_paramfetch
#define dsa_pubfetch dh_pubfetch
#define dsa_privfetch dh_privfetch

#define DSA_PARAMFETCHSZ DH_PARAMFETCHSZ
#define DSA_PUBFETCHSZ DH_PUBFETCHSZ
#define DSA_PRIVFETCHSZ DH_PRIVFETCHSZ

#define dsa_paramfree dh_paramfree
#define dsa_pubfree dh_pubfree
#define dsa_privfree dh_privfree

/*----- DSA stepper -------------------------------------------------------*/

typedef struct dsa_stepctx {

  /* --- To be initialized by the client --- */

  grand *r;				/* Random number generator */
  mp *q;				/* Force @p@ to be a multiple */
  size_t bits;				/* Number of bits in the result */
  unsigned or;				/* OR mask for low order bits */
  unsigned count;			/* Counts the number of steps made */
  void *seedbuf;			/* Pointer to seed buffer */
} dsa_stepctx;

/* --- @dsa_step@ --- *
 *
 * The stepper chooses random integers, ensures that they are a multiple of
 * @q@ (if specified), sets the low-order bits, and then tests for
 * divisibility by small primes.
 */

extern pgen_proc dsa_step;

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

/* --- @dsa_gen@ --- *
 *
 * Arguments:	@dsa_param *dp@ = where to store parameters
 *		@unsigned ql@ = length of @q@ in bits
 *		@unsigned pl@ = length of @p@ in bits
 *		@unsigned steps@ = number of steps to find @q@
 *		@const void *k@ = pointer to key material
 *		@size_t sz@ = size of key material
 *		@dsa_seed *sd@ = optional pointer for output seed information
 *		@pgen_proc *event@ = event handler function
 *		@void *ectx@ = argument for event handler
 *
 * Returns:	@PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise.
 *
 * Use:		Generates the DSA shared parameters from a given seed value.
 *		This can take quite a long time.
 *
 *		The algorithm used is a compatible extension of the method
 *		described in the DSA standard, FIPS 186.  The standard
 *		requires that %$q$% be 160 bits in size (i.e., @ql == 160@)
 *		and that the length of %$p$% be %$L = 512 + 64l$% for some
 *		%$l$%.  Neither limitation applies to this implementation.
 */

extern int dsa_gen(dsa_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/,
		   unsigned /*steps*/, const void */*k*/, size_t /*sz*/,
		   dsa_seed */*sd*/, pgen_proc */*event*/, void */*ectx*/);

/* --- @dsa_checkparam@ --- *
 *
 * Arguments:	@keycheck *kc@ = keycheck state
 *		@const dsa_param *dp@ = pointer to the parameter set
 *		@const dsa_seed *ds@ = pointer to seed information
 *
 * Returns:	Zero if all OK, or return status from function.
 *
 * Use:		Checks a set of DSA parameters for consistency and security.
 */

extern int dsa_checkparam(keycheck */*kc*/, const dsa_param */*dp*/,
			  const dsa_seed */*ds*/);

/* --- @dsa_h2n@ --- *
 *
 * Arguments:	@mp *d@ = destination integer
 *		@mp *r@ = order of the DSA group
 *		@const void *h@ = pointer to message hash
 *		@size_t hsz@ = size (in bytes) of the hash output
 *
 * Returns:	Resulting integer.
 *
 * Use:		Converts a hash to an integer in the demented way necessary
 *		for DSA/ECDSA.  This is, of course, completely insane, but
 *		there you go.
 */

extern mp *dsa_h2n(mp */*d*/, mp */*r*/, const void */*h*/, size_t /*hsz*/);

/* --- @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