| 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 |
|
|---|
| 13 | The EVP library provides a high-level interface to cryptographic
|
|---|
| 14 | functions.
|
|---|
| 15 |
|
|---|
| 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".
|
|---|
| 18 |
|
|---|
| 19 | The L<B<EVP_DigestSign>I<XXX>|EVP_DigestSignInit(3)> and
|
|---|
| 20 | L<B<EVP_DigestVerify>I<XXX>|EVP_DigestVerifyInit(3)> functions implement
|
|---|
| 21 | digital signatures and Message Authentication Codes (MACs). Also see the older
|
|---|
| 22 | L<B<EVP_Sign>I<XXX>|EVP_SignInit(3)> and L<B<EVP_Verify>I<XXX>|EVP_VerifyInit(3)>
|
|---|
| 23 | functions.
|
|---|
| 24 |
|
|---|
| 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.
|
|---|
| 27 |
|
|---|
| 28 | The B<EVP_PKEY>I<XXX> functions provide a high level interface to
|
|---|
| 29 | asymmetric algorithms. To create a new EVP_PKEY see
|
|---|
| 30 | L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated
|
|---|
| 31 | with a private key of a particular algorithm by using the functions
|
|---|
| 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)>.
|
|---|
| 36 |
|
|---|
| 37 | The EVP_PKEY functions support the full range of asymmetric algorithm operations:
|
|---|
| 38 |
|
|---|
| 39 | =over 4
|
|---|
| 40 |
|
|---|
| 41 | =item For key agreement see L<EVP_PKEY_derive(3)>
|
|---|
| 42 |
|
|---|
| 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)>.
|
|---|
| 45 | However, note that
|
|---|
| 46 | these functions do not perform a digest of the data to be signed. Therefore
|
|---|
| 47 | normally you would use the L<EVP_DigestSignInit(3)>
|
|---|
| 48 | functions for this purpose.
|
|---|
| 49 |
|
|---|
| 50 | =item For encryption and decryption see L<EVP_PKEY_encrypt(3)>
|
|---|
| 51 | and L<EVP_PKEY_decrypt(3)> respectively. However, note that
|
|---|
| 52 | these functions perform encryption and decryption only. As public key
|
|---|
| 53 | encryption is an expensive operation, normally you would wrap
|
|---|
| 54 | an encrypted message in a "digital envelope" using the L<EVP_SealInit(3)> and
|
|---|
| 55 | L<EVP_OpenInit(3)> functions.
|
|---|
| 56 |
|
|---|
| 57 | =back
|
|---|
| 58 |
|
|---|
| 59 | The L<EVP_BytesToKey(3)> function provides some limited support for password
|
|---|
| 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 |
|
|---|
| 64 | The L<B<EVP_Encode>I<XXX>|EVP_EncodeInit(3)> and
|
|---|
| 65 | L<B<EVP_Decode>I<XXX>|EVP_EncodeInit(3)> functions implement base 64 encoding
|
|---|
| 66 | and decoding.
|
|---|
| 67 |
|
|---|
| 68 | All the symmetric algorithms (ciphers), digests and asymmetric algorithms
|
|---|
| 69 | (public key algorithms) can be replaced by ENGINE modules providing alternative
|
|---|
| 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.
|
|---|
| 78 | Also makes code harder to adapt to new algorithms and some options are not
|
|---|
| 79 | cleanly supported at the low level and some operations are more efficient
|
|---|
| 80 | using the high level interface.
|
|---|
| 81 |
|
|---|
| 82 | =head1 SEE ALSO
|
|---|
| 83 |
|
|---|
| 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)>,
|
|---|
| 91 | L<EVP_EncodeInit(3)>,
|
|---|
| 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)>,
|
|---|
| 103 | L<ENGINE_by_id(3)>
|
|---|
| 104 |
|
|---|
| 105 | =head1 COPYRIGHT
|
|---|
| 106 |
|
|---|
| 107 | Copyright 2000-2018 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
|
|---|
