]>
Commit | Line | Data |
---|---|---|
f7173262 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
0ab18e79 | 5 | EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, |
d8652be0 | 6 | EVP_SignFinal_ex, EVP_SignFinal |
6942a0d6 | 7 | - EVP signing functions |
f7173262 DSH |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/evp.h> | |
12 | ||
3811eed8 DSH |
13 | int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); |
14 | int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); | |
d8652be0 | 15 | int EVP_SignFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s, |
b4250010 | 16 | EVP_PKEY *pkey, OSSL_LIB_CTX *libctx, const char *propq); |
0ab18e79 SL |
17 | int EVP_SignFinal(EVP_MD_CTX *ctx, unsigned char *sig, unsigned int *s, |
18 | EVP_PKEY *pkey); | |
f7173262 | 19 | |
3811eed8 DSH |
20 | void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); |
21 | ||
f7173262 DSH |
22 | =head1 DESCRIPTION |
23 | ||
8c1cbc72 | 24 | The EVP signature routines are a high-level interface to digital |
f7173262 DSH |
25 | signatures. |
26 | ||
03d65ca2 RL |
27 | EVP_SignInit_ex() sets up signing context I<ctx> to use digest |
28 | I<type> from B<ENGINE> I<impl>. I<ctx> must be created with | |
25191fff | 29 | EVP_MD_CTX_new() before calling this function. |
f7173262 | 30 | |
03d65ca2 RL |
31 | EVP_SignUpdate() hashes I<cnt> bytes of data at I<d> into the |
32 | signature context I<ctx>. This function can be called several times on the | |
33 | same I<ctx> to include additional data. | |
f7173262 | 34 | |
d8652be0 | 35 | EVP_SignFinal_ex() signs the data in I<ctx> using the private key |
0ab18e79 SL |
36 | I<pkey> and places the signature in I<sig>. The library context I<libctx> and |
37 | property query I<propq> are used when creating a context to use with the key | |
38 | I<pkey>. I<sig> must be at least C<EVP_PKEY_size(pkey)> bytes in size. I<s> is | |
39 | an OUT parameter, and not used as an IN parameter. | |
6e6ba36d | 40 | The number of bytes of data written (i.e. the length of the signature) |
03d65ca2 | 41 | will be written to the integer at I<s>, at most C<EVP_PKEY_size(pkey)> bytes |
6e6ba36d | 42 | will be written. |
3811eed8 | 43 | |
d8652be0 | 44 | EVP_SignFinal() is similar to EVP_SignFinal_ex() but uses default |
0ab18e79 SL |
45 | values of NULL for the library context I<libctx> and the property query I<propq>. |
46 | ||
03d65ca2 RL |
47 | EVP_SignInit() initializes a signing context I<ctx> to use the default |
48 | implementation of digest I<type>. | |
f7173262 | 49 | |
f7173262 DSH |
50 | =head1 RETURN VALUES |
51 | ||
d8652be0 | 52 | EVP_SignInit_ex(), EVP_SignUpdate(), EVP_SignFinal_ex() and |
0ab18e79 | 53 | EVP_SignFinal() return 1 for success and 0 for failure. |
f7173262 | 54 | |
9b86974e | 55 | The error codes can be obtained by L<ERR_get_error(3)>. |
f7173262 DSH |
56 | |
57 | =head1 NOTES | |
58 | ||
59 | The B<EVP> interface to digital signatures should almost always be used in | |
8c1cbc72 | 60 | preference to the low-level interfaces. This is because the code then becomes |
f7173262 DSH |
61 | transparent to the algorithm used and much more flexible. |
62 | ||
262c0088 DMSP |
63 | When signing with DSA private keys the random number generator must be seeded. |
64 | If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to | |
65 | external circumstances (see L<RAND(7)>), the operation will fail. | |
66 | This requirement does not hold for RSA signatures. | |
f7173262 | 67 | |
3811eed8 DSH |
68 | The call to EVP_SignFinal() internally finalizes a copy of the digest context. |
69 | This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called | |
70 | later to digest and sign additional data. | |
71 | ||
72 | Since only a copy of the digest context is ever finalized the context must | |
c12a2d27 | 73 | be cleaned up after use by calling EVP_MD_CTX_free() or a memory leak |
3811eed8 DSH |
74 | will occur. |
75 | ||
f7173262 DSH |
76 | =head1 BUGS |
77 | ||
1bc74519 | 78 | Older versions of this documentation wrongly stated that calls to |
3811eed8 | 79 | EVP_SignUpdate() could not be made after calling EVP_SignFinal(). |
f7173262 | 80 | |
29cf84c6 DSH |
81 | Since the private key is passed in the call to EVP_SignFinal() any error |
82 | relating to the private key (for example an unsuitable key and digest | |
83 | combination) will not be indicated until after potentially large amounts of | |
84 | data have been passed through EVP_SignUpdate(). | |
85 | ||
86 | It is not possible to change the signing parameters using these function. | |
87 | ||
88 | The previous two bugs are fixed in the newer EVP_SignDigest*() function. | |
89 | ||
f7173262 DSH |
90 | =head1 SEE ALSO |
91 | ||
6942a0d6 | 92 | L<EVP_PKEY_size(3)>, L<EVP_PKEY_bits(3)>, L<EVP_PKEY_security_bits(3)>, |
9b86974e | 93 | L<EVP_VerifyInit(3)>, |
73fb82b7 | 94 | L<EVP_DigestInit(3)>, |
b97fdb57 RL |
95 | L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, |
96 | L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, | |
1903a9b7 | 97 | L<SHA1(3)>, L<openssl-dgst(1)> |
f7173262 | 98 | |
0ab18e79 SL |
99 | =head1 HISTORY |
100 | ||
d8652be0 | 101 | The function EVP_SignFinal_ex() was added in OpenSSL 3.0. |
0ab18e79 | 102 | |
e2f92610 RS |
103 | =head1 COPYRIGHT |
104 | ||
33388b44 | 105 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 106 | |
4746f25a | 107 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
108 | this file except in compliance with the License. You can obtain a copy |
109 | in the file LICENSE in the source distribution or at | |
110 | L<https://www.openssl.org/source/license.html>. | |
111 | ||
112 | =cut |