]>
Commit | Line | Data |
---|---|---|
9886f420 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/evp.h> | |
10 | ||
4a6a2032 NL |
11 | int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, |
12 | unsigned char **ek, int *ekl, unsigned char *iv, | |
13 | EVP_PKEY **pubk, int npubk); | |
e366f2b8 | 14 | int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, |
9886f420 | 15 | int *outl, unsigned char *in, int inl); |
e366f2b8 | 16 | int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, |
9886f420 DSH |
17 | int *outl); |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | The EVP envelope routines are a high level interface to envelope | |
da45180d DSH |
22 | encryption. They generate a random key and IV (if required) then |
23 | "envelope" it by using public key encryption. Data can then be | |
24 | encrypted using this key. | |
9886f420 | 25 | |
c8973693 | 26 | EVP_SealInit() initializes a cipher context B<ctx> for encryption |
da45180d | 27 | with cipher B<type> using a random secret key and IV. B<type> is normally |
740ceb5b | 28 | supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted |
da45180d DSH |
29 | using one or more public keys, this allows the same encrypted data to be |
30 | decrypted using any of the corresponding private keys. B<ek> is an array of | |
31 | buffers where the public key encrypted secret key will be written, each buffer | |
32 | must contain enough room for the corresponding encrypted key: that is | |
9886f420 DSH |
33 | B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual |
34 | size of each encrypted secret key is written to the array B<ekl>. B<pubk> is | |
35 | an array of B<npubk> public keys. | |
36 | ||
da45180d DSH |
37 | The B<iv> parameter is a buffer where the generated IV is written to. It must |
38 | contain enough room for the corresponding cipher's IV, as determined by (for | |
39 | example) EVP_CIPHER_iv_length(type). | |
40 | ||
41 | If the cipher does not require an IV then the B<iv> parameter is ignored | |
42 | and can be B<NULL>. | |
43 | ||
9886f420 | 44 | EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties |
1bc74519 | 45 | as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as |
9b86974e | 46 | documented on the L<EVP_EncryptInit(3)> manual |
1bc74519 | 47 | page. |
9886f420 DSH |
48 | |
49 | =head1 RETURN VALUES | |
50 | ||
e366f2b8 | 51 | EVP_SealInit() returns 0 on error or B<npubk> if successful. |
9886f420 | 52 | |
fd75eb50 DSH |
53 | EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for |
54 | failure. | |
9886f420 DSH |
55 | |
56 | =head1 NOTES | |
57 | ||
58 | Because a random secret key is generated the random number generator | |
59 | must be seeded before calling EVP_SealInit(). | |
60 | ||
61 | The public key must be RSA because it is the only OpenSSL public key | |
62 | algorithm that supports key transport. | |
63 | ||
64 | Envelope encryption is the usual method of using public key encryption | |
65 | on large amounts of data, this is because public key encryption is slow | |
66 | but symmetric encryption is fast. So symmetric encryption is used for | |
67 | bulk encryption and the small random symmetric key used is transferred | |
68 | using public key encryption. | |
69 | ||
a91dedca DSH |
70 | It is possible to call EVP_SealInit() twice in the same way as |
71 | EVP_EncryptInit(). The first call should have B<npubk> set to 0 | |
c8973693 | 72 | and (after setting any cipher parameters) it should be called again |
a91dedca DSH |
73 | with B<type> set to NULL. |
74 | ||
9886f420 DSH |
75 | =head1 SEE ALSO |
76 | ||
b97fdb57 | 77 | L<evp(7)>, L<RAND_bytes(3)>, |
9b86974e RS |
78 | L<EVP_EncryptInit(3)>, |
79 | L<EVP_OpenInit(3)> | |
9886f420 | 80 | |
e2f92610 RS |
81 | =head1 COPYRIGHT |
82 | ||
83 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
84 | ||
85 | Licensed under the OpenSSL license (the "License"). You may not use | |
86 | this file except in compliance with the License. You can obtain a copy | |
87 | in the file LICENSE in the source distribution or at | |
88 | L<https://www.openssl.org/source/license.html>. | |
89 | ||
90 | =cut |