.Dd December 7, 2003
.Dt LIBDSA 3
.Os NetBSD 1.4T
.Sh NAME
.Nm dsa_init ,
.Nm dsa_gen_priv ,
.Nm dsa_priv_to_pub ,
.Nm dsa_set_pub ,
.Nm dsa_sign ,
.Nm dsa_verify ,
.Nm dsa_done
.Nd DSA signature routines
.Sh SYNOPSIS
.Fd #include <gmp.h>
.Fd #include <dsa.h>
.br
.Nm cc
.Op Ar arguments
.Fl ldsa
.Fl lgmp
.br
.Ft void *
.Fn dsa_init "const MP_INT *p" "const MP_INT *q" "const MP_INT *g" "const MP_INT *y"
.Ft int
.Fn dsa_gen_priv "const void *handle" "void (*randomness)(void *buf, int len)" "void *x"
.Ft int
.Fn dsa_priv_to_pub "const void *handle" "const void *x" "MP_INT *y"
.Ft int
.Fn dsa_set_pub "void *handle" "MP_INT *y"
.Ft int
.Fn dsa_sign "const void *handle" "const void *h" "const void *x" "void (*randomness)(void *buf, int len)" "MP_INT *r" "MP_INT *s"
.Ft int
.Fn dsa_verify "const void *handle" "const void *h" "const MP_INT *r" "const MP_INT *s"
.Ft void
.Fn dsa_done "void *handle"
.Sh DESCRIPTION
These functions perform digital signature operations using the DSA.
When a call's return value is not void but is not described with the
call's functional description, it is an error status and is described
in the ERRORS section.
.Pp
.Fn dsa_init
takes the public-key parameters
.Pf ( Fa p ,
.Fa q ,
and
.Fa g )
in libgmp large-integer format and creates an internal data structure,
a pointer to which it returns.  The
.Fa y
argument is the public-key value corresponding to a particular private
key, or a null pointer.  The format of the returned structure is
private to the library and is not documented here; this pointer is good
for nothing but passing to the other routines.  All necessary values
are copied; the arguments may be freed or reused for other purposes
once the call returns.
.Pp
.Fn dsa_gen_priv
generates a private-key value
.Fa x .
.Fa handle
points to a data structure returned by
.Fn dsa_init
which is used only for its
.Fa q
value; the
.Fa randomness
argument points to a function which is called to obtain underlying
randomness.  The resulting secret data blob will be no more secure than
the source of the random bits returned by this function.
.Fa randomness
is passed a buffer pointer and length, and is expected to fill the
buffer with random data, eight bits per byte.  The returned private key
is returned by writing it through
.Fa x ,
which must point to a block of 20 bytes.
.Pp
.Fn dsa_priv_to_pub
converts a private data block (such as is generated by
.Fn dsa_gen_priv ) ,
.Fa x ,
which must point to a 20-byte data block, to a public-key value
suitable for using as the
.Fa y
argument to
.Fn dsa_init
or
.Fn dsa_set_pub .
.Pp
.Fn dsa_set_pub
takes a public-key
.Fa y
value and installs it in the private data structure passed in.  This
replaces the
.Fa y
value passed to
.Fn dsa_init ,
and the same notes apply as to the
.Fa y
argument there.
.Pp
.Fn dsa_sign
creates a digital signature.
.Fa handle
is a pointer returned by a previous
.Fn dsa_init
call;
.Fa h
is a pointer to a 20-byte data block containing the message hash to be
signed.
.Fa x
is a pointer to a 20-byte block containing the private key to be used
to create the signature.
.Fa randomness
is a pointer to a function called to get random data, with the same
interface as the similar argument to
.Fn dsa_gen_priv ,
above.  Finally,
.Fa r
and
.Fa s
are where the signature parameters are returned.  These two
.Dv MP_INT Ns s
must be already initialized (in the
.Xr mpz_init 3
sense); they will be set to the resulting signature.  This function
does not use the
.Fa y
value in the public-key handle.
.Pp
.Fn dsa_verify
checks a signature.
.Fa handle
and
.Fa h
are the public-key parameters block to be used and the message hash
whose signature is to be checked;
.Fa r
and
.Fa s
are the signature.  The return value is nonzero if the signature
verifies, zero if it fails.
.Pp
.Fn dsa_done
frees the internal data structure.  The
.Fa handle
must not be used further.
.Pp
.Sh ERRORS
The library code assumes that all argument pointers are valid and that
the private data blocks do not get corrupted.
.Pp
Some of the functions can fail for various reasons.  Here are the
failure conditions and how they are indicated:
.Pp
.Fn dsa_init
returns a null pointer on failure.  This occurs if
.Xr malloc 3
fails, if the
.Fa y
argument is not a null pointer but the value is out of range (not
smaller than
.Fa p ) ,
or if
.Fa q
is longer than 160 bits.
.Pp
.Fn dsa_gen_priv
has no failure modes.
.Pp
.Fn dsa_priv_to_pub
will fail, returning zero, if the
.Fa x
data blob contains a value not smaller than the
.Fa q
in the
.Fa handle ;
otherwise, it returns nonzero.
.Pp
.Fn dsa_set_pub
will fail, returning zero, if the
.Fa y
argument is not a null pointer but contains a value not smaller than
the
.Fa p
in the
.Fa handle ;
otherwise, it returns nonzero.
.Pp
.Fn dsa_sign
will fail, returning zero, if the
.Fa x
data blob contains a value not less than the
.Fa q
in the handle or if the random k value chosen does not have a
reciprocal modulo
.Fa q
(which latter means that
.Fa q
is not a prime).
.Pp
.Fn dsa_verify
has some error conditions (such as a zero
.Fa s ,
or a
.Fa handle
which has no
.Fa y
value set), but they are all reflected through the interface as a
verification failure (a zero return value).
.Pp
.Fn dsa_done
has no failure modes.
.Sh BUGS
Code blindly assumes 8-bit
.Do
char
.Dc Ns s.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .