From: Dr. Stephen Henson Date: Tue, 7 Mar 2000 17:35:25 +0000 (+0000) Subject: Manual pages for EVP signing and verifying. X-Git-Tag: OpenSSL_0_9_5a-beta1~86 X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=f71732627a9f528a4966e55853bdf88aec207fae Manual pages for EVP signing and verifying. --- diff --git a/doc/crypto/EVP_SignInit.pod b/doc/crypto/EVP_SignInit.pod new file mode 100644 index 0000000000..bbc9203c9c --- /dev/null +++ b/doc/crypto/EVP_SignInit.pod @@ -0,0 +1,85 @@ +=pod + +=head1 NAME + +EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions + +=head1 SYNOPSIS + + #include + + void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); + void EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey); + + int EVP_PKEY_size(EVP_PKEY *pkey); + +=head1 DESCRIPTION + +The EVP signature routines are a high level interface to digital +signatures. + +EVP_SignInit() initialises a signing context B to using digest +B: this will typically be supplied by a function such as +EVP_sha1(). + +EVP_SignUpdate() hashes B bytes of data at B into the +signature context B. This funtion can be called several times on the +same B to include additional data. + +EVP_SignFinal() signs the data in B using the private key B +and places the signature in B. If the B parameter is not NULL +then the number of bytes of data written (i.e. the length of the signature) +will be written to the integer at B, at most EVP_PKEY_size(pkey) bytes +will be written. After calling EVP_SignFinal() no additional calls to +EVP_SignUpdate() can be made, but EVP_SignInit() can be called to initialiase +a new signature operation. + +EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual +signature returned by EVP_SignFinal() may be smaller. + +=head1 RETURN VALUES + +EVP_SignInit() and EVP_SignUpdate() do not return values. + +EVP_SignFinal() returns 1 for success and 0 for failure. + +EVP_PKEY_size() returns the maximum size of a signature in bytes. + +The error codes can be obtained by L. + +=head1 NOTES + +The B interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +Due to the link between message digests and public key algorithms the correct +digest algorithm must be used with the correct public key type. A list of +algorithms and associated public key algorithms appears in +L. + +When signing with DSA private keys the random number generator must be seeded +or the operation will fail. The random number generator does not need to be +seeded for RSA signatures. + +=head1 BUGS + +Several of the functions do not return values: maybe they should. Although the +internal digest operations will never fail some future hardware based operations +might. + +=head1 SEE ALSO + +L, +L, L, +L, L, L, +L, L, L, +L, L + +=head1 HISTORY + +EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are +available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/doc/crypto/EVP_VerifyInit.pod b/doc/crypto/EVP_VerifyInit.pod new file mode 100644 index 0000000000..3b5e07f4ad --- /dev/null +++ b/doc/crypto/EVP_VerifyInit.pod @@ -0,0 +1,71 @@ +=pod + +=head1 NAME + +EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification functions + +=head1 SYNOPSIS + + #include + + void EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); + void EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); + int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey); + +=head1 DESCRIPTION + +The EVP signature verification routines are a high level interface to digital +signatures. + +EVP_VerifyInit() initialises a verification context B to using digest +B: this will typically be supplied by a function such as EVP_sha1(). + +EVP_VerifyUpdate() hashes B bytes of data at B into the +verification context B. This funtion can be called several times on the +same B to include additional data. + +EVP_VerifyFinal() verifies the data in B using the public key B +and against the B bytes at B. After calling EVP_VerifyFinal() +no additional calls to EVP_VerifyUpdate() can be made, but EVP_VerifyInit() +can be called to initialiase a new verification operation. + +=head1 RETURN VALUES + +EVP_VerifyInit() and EVP_VerifyUpdate() do not return values. + +EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some +other error occurred. + +The error codes can be obtained by L. + +=head1 NOTES + +The B interface to digital signatures should almost always be used in +preference to the low level interfaces. This is because the code then becomes +transparent to the algorithm used and much more flexible. + +Due to the link between message digests and public key algorithms the correct +digest algorithm must be used with the correct public key type. A list of +algorithms and associated public key algorithms appears in +L. + +=head1 BUGS + +Several of the functions do not return values: maybe they should. Although the +internal digest operations will never fail some future hardware based operations +might. + +=head1 SEE ALSO + +L, +L, L, +L, L, L, +L, L, L, +L, L + +=head1 HISTORY + +EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are +available in all versions of SSLeay and OpenSSL. + +=cut