1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption 6*2175Sjp161948 7*2175Sjp161948=head1 SYNOPSIS 8*2175Sjp161948 9*2175Sjp161948 #include <openssl/evp.h> 10*2175Sjp161948 11*2175Sjp161948 int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 12*2175Sjp161948 unsigned char **ek, int *ekl, unsigned char *iv, 13*2175Sjp161948 EVP_PKEY **pubk, int npubk); 14*2175Sjp161948 int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, 15*2175Sjp161948 int *outl, unsigned char *in, int inl); 16*2175Sjp161948 int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, 17*2175Sjp161948 int *outl); 18*2175Sjp161948 19*2175Sjp161948=head1 DESCRIPTION 20*2175Sjp161948 21*2175Sjp161948The EVP envelope routines are a high level interface to envelope 22*2175Sjp161948encryption. They generate a random key and IV (if required) then 23*2175Sjp161948"envelope" it by using public key encryption. Data can then be 24*2175Sjp161948encrypted using this key. 25*2175Sjp161948 26*2175Sjp161948EVP_SealInit() initializes a cipher context B<ctx> for encryption 27*2175Sjp161948with cipher B<type> using a random secret key and IV. B<type> is normally 28*2175Sjp161948supplied by a function such as EVP_des_cbc(). The secret key is encrypted 29*2175Sjp161948using one or more public keys, this allows the same encrypted data to be 30*2175Sjp161948decrypted using any of the corresponding private keys. B<ek> is an array of 31*2175Sjp161948buffers where the public key encrypted secret key will be written, each buffer 32*2175Sjp161948must contain enough room for the corresponding encrypted key: that is 33*2175Sjp161948B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual 34*2175Sjp161948size of each encrypted secret key is written to the array B<ekl>. B<pubk> is 35*2175Sjp161948an array of B<npubk> public keys. 36*2175Sjp161948 37*2175Sjp161948The B<iv> parameter is a buffer where the generated IV is written to. It must 38*2175Sjp161948contain enough room for the corresponding cipher's IV, as determined by (for 39*2175Sjp161948example) EVP_CIPHER_iv_length(type). 40*2175Sjp161948 41*2175Sjp161948If the cipher does not require an IV then the B<iv> parameter is ignored 42*2175Sjp161948and can be B<NULL>. 43*2175Sjp161948 44*2175Sjp161948EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties 45*2175Sjp161948as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as 46*2175Sjp161948documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual 47*2175Sjp161948page. 48*2175Sjp161948 49*2175Sjp161948=head1 RETURN VALUES 50*2175Sjp161948 51*2175Sjp161948EVP_SealInit() returns 0 on error or B<npubk> if successful. 52*2175Sjp161948 53*2175Sjp161948EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for 54*2175Sjp161948failure. 55*2175Sjp161948 56*2175Sjp161948=head1 NOTES 57*2175Sjp161948 58*2175Sjp161948Because a random secret key is generated the random number generator 59*2175Sjp161948must be seeded before calling EVP_SealInit(). 60*2175Sjp161948 61*2175Sjp161948The public key must be RSA because it is the only OpenSSL public key 62*2175Sjp161948algorithm that supports key transport. 63*2175Sjp161948 64*2175Sjp161948Envelope encryption is the usual method of using public key encryption 65*2175Sjp161948on large amounts of data, this is because public key encryption is slow 66*2175Sjp161948but symmetric encryption is fast. So symmetric encryption is used for 67*2175Sjp161948bulk encryption and the small random symmetric key used is transferred 68*2175Sjp161948using public key encryption. 69*2175Sjp161948 70*2175Sjp161948It is possible to call EVP_SealInit() twice in the same way as 71*2175Sjp161948EVP_EncryptInit(). The first call should have B<npubk> set to 0 72*2175Sjp161948and (after setting any cipher parameters) it should be called again 73*2175Sjp161948with B<type> set to NULL. 74*2175Sjp161948 75*2175Sjp161948=head1 SEE ALSO 76*2175Sjp161948 77*2175Sjp161948L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, 78*2175Sjp161948L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, 79*2175Sjp161948L<EVP_OpenInit(3)|EVP_OpenInit(3)> 80*2175Sjp161948 81*2175Sjp161948=head1 HISTORY 82*2175Sjp161948 83*2175Sjp161948EVP_SealFinal() did not return a value before OpenSSL 0.9.7. 84*2175Sjp161948 85*2175Sjp161948=cut 86