EVP_DigestSignInit.pod 4.3 KB
Newer Older
1 2 3 4
=pod

=head1 NAME

5 6
EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal,
EVP_DigestSign - EVP signing functions
7 8 9 10 11 12

=head1 SYNOPSIS

 #include <openssl/evp.h>

 int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
R
Rich Salz 已提交
13
                        const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
14
 int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
15 16
 int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);

17 18 19 20
 int EVP_DigestSign(EVP_MD_CTX *ctx, unsigned char *sigret,
                    size_t *siglen, const unsigned char *tbs,
                    size_t tbslen);

21 22 23 24 25
=head1 DESCRIPTION

The EVP signature routines are a high level interface to digital signatures.

EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from
R
Richard Levitte 已提交
26 27
ENGINE B<impl> and private key B<pkey>. B<ctx> must be created with
EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the
28 29 30 31 32 33
EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can
be used to set alternative signing options.

EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
signature context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data. This function is currently implemented
34
using a macro.
35 36 37 38 39 40 41 42

EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>.
If B<sig> is B<NULL> then the maximum size of the output buffer is written to
the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the
B<siglen> parameter should contain the length of the B<sig> buffer, if the
call is successful the signature is written to B<sig> and the amount of data
written to B<siglen>.

43
EVP_DigestSign() signs B<tbslen> bytes of data at B<tbs> and places the
J
Josh Soref 已提交
44
signature in B<sig> and its length in B<siglen> in a similar way to
45 46
EVP_DigestSignFinal().

47 48
=head1 RETURN VALUES

49 50 51 52
EVP_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignaFinal() and
EVP_DigestSign() return 1 for success and 0 or a negative value for failure. In
particular a return value of -2 indicates the operation is not supported by the
public key algorithm.
53

R
Rich Salz 已提交
54
The error codes can be obtained from L<ERR_get_error(3)>.
55 56 57 58 59 60 61

=head1 NOTES

The B<EVP> 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.

D
Dr. Stephen Henson 已提交
62 63 64 65
EVP_DigestSign() is a one shot operation which signs a single block of data
in one function. For algorithms that support streaming it is equivalent to
calling EVP_DigestSignUpdate() and EVP_DigestSignFinal(). For algorithms which
do not support streaming (e.g. PureEdDSA) it is the only way to sign data.
66

67 68 69 70 71 72
In previous versions of OpenSSL there was a link between message digest types
and public key algorithms. This meant that "clone" digests such as EVP_dss1()
needed to be used to sign using SHA1 and DSA. This is no longer necessary and
the use of clone digest is now discouraged.

For some key types and parameters the random number generator must be seeded
R
Rich Salz 已提交
73
or the operation will fail.
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89

The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
context. This means that calls to EVP_DigestSignUpdate() and
EVP_DigestSignFinal() can be called later to digest and sign additional data.

Since only a copy of the digest context is ever finalized the context must
be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
will occur.

The use of EVP_PKEY_size() with these functions is discouraged because some
signature operations may have a signature length which depends on the
parameters set. As a result EVP_PKEY_size() would have to return a value
which indicates the maximum possible signature for any set of parameters.

=head1 SEE ALSO

R
Rich Salz 已提交
90
L<EVP_DigestVerifyInit(3)>,
91
L<EVP_DigestInit(3)>,
92 93 94
L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>,
L<SHA1(3)>, L<dgst(1)>
95 96 97

=head1 HISTORY

R
Rich Salz 已提交
98
EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal()
99
were first added to OpenSSL 1.0.0.
100

R
Rich Salz 已提交
101 102
=head1 COPYRIGHT

103
Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved.
R
Rich Salz 已提交
104 105 106 107 108 109 110

Licensed under the OpenSSL license (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut