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