X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fcrypto%2FEVP_SealInit.pod;h=e920e3e310bc1f3a040c1d764a9bc331b1f8e977;hb=fde2257f055f187e8e78542ea6d64ad6c206d10b;hp=1579d110fa282035237df1a65a89855e6c143133;hpb=9886f420145883100ada06a1184eff195a133b39;p=openssl.git

diff --git a/doc/crypto/EVP_SealInit.pod b/doc/crypto/EVP_SealInit.pod
index 1579d110fa..e920e3e310 100644
--- a/doc/crypto/EVP_SealInit.pod
+++ b/doc/crypto/EVP_SealInit.pod
@@ -8,42 +8,50 @@ EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption
 
  #include <openssl/evp.h>
 
- int EVP_SealInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char **ek,
-		int *ekl, unsigned char *iv,EVP_PKEY **pubk, int npubk);
- void EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
+                  unsigned char **ek, int *ekl, unsigned char *iv,
+                  EVP_PKEY **pubk, int npubk);
+ int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
          int *outl, unsigned char *in, int inl);
- void EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
+ int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
          int *outl);
 
 =head1 DESCRIPTION
 
 The EVP envelope routines are a high level interface to envelope
-encryption. They generate a random key and then "envelope" it by
-using public key encryption. Data can then be encrypted using this
-key.
-
-EVP_SealInit() initialises a cipher context B<ctx> for encryption
-with cipher B<type> using a random secret key and IV supplied in
-the B<iv> parameter. B<type> is normally supplied by a function such
-as EVP_des_cbc(). The secret key is encrypted using one or more public
-keys, this allows the same encrypted data to be decrypted using any
-of the corresponding private keys. B<ek> is an array of buffers where
-the public key encrypted secret key will be written, each buffer must
-contain enough room for the corresponding encrypted key: that is
+encryption. They generate a random key and IV (if required) then
+"envelope" it by using public key encryption. Data can then be
+encrypted using this key.
+
+EVP_SealInit() initializes a cipher context B<ctx> for encryption
+with cipher B<type> using a random secret key and IV. B<type> is normally
+supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted
+using one or more public keys, this allows the same encrypted data to be
+decrypted using any of the corresponding private keys. B<ek> is an array of
+buffers where the public key encrypted secret key will be written, each buffer
+must contain enough room for the corresponding encrypted key: that is
 B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual
 size of each encrypted secret key is written to the array B<ekl>. B<pubk> is
 an array of B<npubk> public keys.
 
+The B<iv> parameter is a buffer where the generated IV is written to. It must
+contain enough room for the corresponding cipher's IV, as determined by (for
+example) EVP_CIPHER_iv_length(type).
+
+If the cipher does not require an IV then the B<iv> parameter is ignored
+and can be B<NULL>.
+
 EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties
 as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as 
-documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual
+documented on the L<EVP_EncryptInit(3)> manual
 page. 
 
 =head1 RETURN VALUES
 
-EVP_SealInit() returns -1 on error or B<npubk> if successful.
+EVP_SealInit() returns 0 on error or B<npubk> if successful.
 
-EVP_SealUpdate() and EVP_SealFinal() do not return values.
+EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for
+failure.
 
 =head1 NOTES
 
@@ -59,12 +67,15 @@ but symmetric encryption is fast. So symmetric encryption is used for
 bulk encryption and the small random symmetric key used is transferred
 using public key encryption.
 
-=head1 SEE ALSO
+It is possible to call EVP_SealInit() twice in the same way as
+EVP_EncryptInit(). The first call should have B<npubk> set to 0
+and (after setting any cipher parameters) it should be called again
+with B<type> set to NULL.
 
-L<evp(3)|evp(3)>,L<rand(3)|rand(3)>
-L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,
-L<EVP_OpenInit(3)|EVP_OpenInit(3)>
+=head1 SEE ALSO
 
-=head1 HISTORY
+L<evp(3)>, L<rand(3)>,
+L<EVP_EncryptInit(3)>,
+L<EVP_OpenInit(3)>
 
 =cut