]>
Commit | Line | Data |
---|---|---|
69431c29 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | evp - high-level cryptographic functions | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/evp.h> | |
10 | ||
11 | =head1 DESCRIPTION | |
12 | ||
393e826e | 13 | The EVP library provides a high-level interface to cryptographic |
69431c29 UM |
14 | functions. |
15 | ||
32b28859 DMSP |
16 | The L<B<EVP_Seal>I<XXX>|EVP_SealInit(3)> and L<B<EVP_Open>I<XXX>|EVP_OpenInit(3)> |
17 | functions provide public key encryption and decryption to implement digital "envelopes". | |
69431c29 | 18 | |
32b28859 DMSP |
19 | The L<B<EVP_DigestSign>I<XXX>|EVP_DigestSignInit(3)> and |
20 | L<B<EVP_DigestVerify>I<XXX>|EVP_DigestVerifyInit(3)> functions implement | |
aafbe1cc | 21 | digital signatures and Message Authentication Codes (MACs). Also see the older |
32b28859 | 22 | L<B<EVP_Sign>I<XXX>|EVP_SignInit(3)> and L<B<EVP_Verify>I<XXX>|EVP_VerifyInit(3)> |
aafbe1cc | 23 | functions. |
69431c29 | 24 | |
32b28859 DMSP |
25 | Symmetric encryption is available with the L<B<EVP_Encrypt>I<XXX>|EVP_EncryptInit(3)> |
26 | functions. The L<B<EVP_Digest>I<XXX>|EVP_DigestInit(3)> functions provide message digests. | |
69431c29 | 27 | |
8c1cbc72 | 28 | The B<EVP_PKEY>I<XXX> functions provide a high-level interface to |
aafbe1cc | 29 | asymmetric algorithms. To create a new EVP_PKEY see |
9b86974e | 30 | L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated |
aafbe1cc | 31 | with a private key of a particular algorithm by using the functions |
cc57dc96 | 32 | described on the L<EVP_PKEY_fromdata(3)> page, or |
9b86974e | 33 | new keys can be generated using L<EVP_PKEY_keygen(3)>. |
c85c5e1a | 34 | EVP_PKEYs can be compared using L<EVP_PKEY_eq(3)>, or printed using |
a732a4c3 SL |
35 | L<EVP_PKEY_print_private(3)>. L<EVP_PKEY_todata(3)> can be used to convert a |
36 | key back into an L<OSSL_PARAM(3)> array. | |
aafbe1cc MC |
37 | |
38 | The EVP_PKEY functions support the full range of asymmetric algorithm operations: | |
ed77017b | 39 | |
e1271ac2 | 40 | =over 4 |
aafbe1cc | 41 | |
9b86974e | 42 | =item For key agreement see L<EVP_PKEY_derive(3)> |
aafbe1cc | 43 | |
9b86974e RS |
44 | =item For signing and verifying see L<EVP_PKEY_sign(3)>, |
45 | L<EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)>. | |
aafbe1cc | 46 | However, note that |
8c1cbc72 | 47 | these functions do not perform a digest of the data to be signed. Therefore, |
9b86974e | 48 | normally you would use the L<EVP_DigestSignInit(3)> |
aafbe1cc MC |
49 | functions for this purpose. |
50 | ||
9b86974e RS |
51 | =item For encryption and decryption see L<EVP_PKEY_encrypt(3)> |
52 | and L<EVP_PKEY_decrypt(3)> respectively. However, note that | |
aafbe1cc MC |
53 | these functions perform encryption and decryption only. As public key |
54 | encryption is an expensive operation, normally you would wrap | |
9b86974e RS |
55 | an encrypted message in a "digital envelope" using the L<EVP_SealInit(3)> and |
56 | L<EVP_OpenInit(3)> functions. | |
aafbe1cc MC |
57 | |
58 | =back | |
59 | ||
9b86974e | 60 | The L<EVP_BytesToKey(3)> function provides some limited support for password |
aafbe1cc MC |
61 | based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible |
62 | implementation. However, new applications should not typically use this (preferring, for example, | |
63 | PBKDF2 from PCKS#5). | |
64 | ||
32b28859 DMSP |
65 | The L<B<EVP_Encode>I<XXX>|EVP_EncodeInit(3)> and |
66 | L<B<EVP_Decode>I<XXX>|EVP_EncodeInit(3)> functions implement base 64 encoding | |
d202a602 MC |
67 | and decoding. |
68 | ||
5165148f | 69 | All the symmetric algorithms (ciphers), digests and asymmetric algorithms |
a9c85cea | 70 | (public key algorithms) can be replaced by ENGINE modules providing alternative |
5165148f DSH |
71 | implementations. If ENGINE implementations of ciphers or digests are registered |
72 | as defaults, then the various EVP functions will automatically use those | |
73 | implementations automatically in preference to built in software | |
74 | implementations. For more information, consult the engine(3) man page. | |
75 | ||
8c1cbc72 | 76 | Although low-level algorithm specific functions exist for many algorithms |
5165148f | 77 | their use is discouraged. They cannot be used with an ENGINE and ENGINE |
8c1cbc72 | 78 | versions of new algorithms cannot be accessed using the low-level functions. |
1bc74519 | 79 | Also makes code harder to adapt to new algorithms and some options are not |
8c1cbc72 GN |
80 | cleanly supported at the low-level and some operations are more efficient |
81 | using the high-level interface. | |
5bf73873 | 82 | |
69431c29 UM |
83 | =head1 SEE ALSO |
84 | ||
9b86974e RS |
85 | L<EVP_DigestInit(3)>, |
86 | L<EVP_EncryptInit(3)>, | |
87 | L<EVP_OpenInit(3)>, | |
88 | L<EVP_SealInit(3)>, | |
89 | L<EVP_DigestSignInit(3)>, | |
90 | L<EVP_SignInit(3)>, | |
91 | L<EVP_VerifyInit(3)>, | |
d202a602 | 92 | L<EVP_EncodeInit(3)>, |
9b86974e | 93 | L<EVP_PKEY_new(3)>, |
cc57dc96 | 94 | L<EVP_PKEY_fromdata(3)>, |
a732a4c3 | 95 | L<EVP_PKEY_todata(3)>, |
9b86974e RS |
96 | L<EVP_PKEY_keygen(3)>, |
97 | L<EVP_PKEY_print_private(3)>, | |
98 | L<EVP_PKEY_decrypt(3)>, | |
99 | L<EVP_PKEY_encrypt(3)>, | |
100 | L<EVP_PKEY_sign(3)>, | |
101 | L<EVP_PKEY_verify(3)>, | |
102 | L<EVP_PKEY_verify_recover(3)>, | |
103 | L<EVP_PKEY_derive(3)>, | |
104 | L<EVP_BytesToKey(3)>, | |
a9c85cea | 105 | L<ENGINE_by_id(3)> |
69431c29 | 106 | |
e2f92610 RS |
107 | =head1 COPYRIGHT |
108 | ||
8020d79b | 109 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 110 | |
3187791e | 111 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
112 | this file except in compliance with the License. You can obtain a copy |
113 | in the file LICENSE in the source distribution or at | |
114 | L<https://www.openssl.org/source/license.html>. | |
115 | ||
116 | =cut |