In evp.h rev. 1.57 2018/02/17 16:54:08,

jsing@ provided EVP_CIPHER_CTX_reset(3).
Merge the documentation, most from Richard Levitte
via OpenSSL commit 05fdb8d3 Dec 18 17:09:45 2015 +0100.
Also merge improvements to the EXAMPLES section from OpenSSL,
fixing one additional bug that still remains in OpenSSL.

While here, improve information on the deprecated functions,
sort RETURN VALUES, and add a few missing functions to it,
though that section still remains incomplete.

1 files changed, 96 insertions, 70 deletions

diff --git a/src/lib/libcrypto/man/EVP_EncryptInit.3 b/src/lib/libcrypto/man/EVP_EncryptInit.3
index f883d1ce2a..a9377b2264 100644
--- a/src/lib/libcrypto/man/EVP_EncryptInit.3
+++ b/src/lib/libcrypto/man/EVP_EncryptInit.3
@@ -1,8 +1,9 @@
-.\" $OpenBSD: EVP_EncryptInit.3,v 1.7 2018/02/14 00:19:03 schwarze Exp $
+.\" $OpenBSD: EVP_EncryptInit.3,v 1.8 2018/02/19 10:04:08 schwarze Exp $
 .\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800
 .\" selective merge up to: OpenSSL 5c5eb286 Dec 5 00:36:43 2017 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
+.\" and Richard Levitte <levitte@openssl.org>.
 .\" Copyright (c) 2000-2002, 2005, 2012-2016 The OpenSSL Project.
 .\" All rights reserved.
 .\"
@@ -50,11 +51,13 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: February 14 2018 $
+.Dd $Mdocdate: February 19 2018 $
 .Dt EVP_ENCRYPTINIT 3
 .Os
 .Sh NAME
 .Nm EVP_CIPHER_CTX_new ,
+.Nm EVP_CIPHER_CTX_reset ,
+.Nm EVP_CIPHER_CTX_cleanup ,
 .Nm EVP_CIPHER_CTX_init ,
 .Nm EVP_CIPHER_CTX_free ,
 .Nm EVP_EncryptInit_ex ,
@@ -76,7 +79,6 @@
 .Nm EVP_CIPHER_CTX_set_key_length ,
 .Nm EVP_CIPHER_CTX_ctrl ,
 .Nm EVP_CIPHER_CTX_rand_key ,
-.Nm EVP_CIPHER_CTX_cleanup ,
 .Nm EVP_get_cipherbyname ,
 .Nm EVP_get_cipherbynid ,
 .Nm EVP_get_cipherbyobj ,
@@ -164,6 +166,14 @@
 .In openssl/evp.h
 .Ft EVP_CIPHER_CTX *
 .Fn EVP_CIPHER_CTX_new void
+.Ft int
+.Fo EVP_CIPHER_CTX_reset
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fc
+.Ft int
+.Fo EVP_CIPHER_CTX_cleanup
+.Fa "EVP_CIPHER_CTX *ctx"
+.Fc
 .Ft void
 .Fo EVP_CIPHER_CTX_init
 .Fa "EVP_CIPHER_CTX *ctx"
@@ -301,10 +311,6 @@
 .Fa "EVP_CIPHER_CTX *ctx"
 .Fa "unsigned char *key"
 .Fc
-.Ft int
-.Fo EVP_CIPHER_CTX_cleanup
-.Fa "EVP_CIPHER_CTX *ctx"
-.Fc
 .Ft const EVP_CIPHER *
 .Fo EVP_get_cipherbyname
 .Fa "const char *name"
@@ -401,15 +407,35 @@ The EVP cipher routines are a high level interface to certain symmetric
 ciphers.
 .Pp
 .Fn EVP_CIPHER_CTX_new
-creates a cipher context.
+creates a new, empty cipher context.
+.Pp
+.Fn EVP_CIPHER_CTX_reset
+clears all information from
+.Fa ctx
+and frees all allocated memory associated with it, except the
+.Fa ctx
+object itself, such that it can be reused for another series of calls to
+.Fn EVP_CipherInit ,
+.Fn EVP_CipherUpdate ,
+and
+.Fn EVP_CipherFinal .
+It is also suitable for cipher contexts on the stack that were used
+and are no longer needed.
+.Fn EVP_CIPHER_CTX_cleanup
+is a deprecated alias for
+.Fn EVP_CIPHER_CTX_reset .
 .Pp
 .Fn EVP_CIPHER_CTX_init
-initializes the cipher context
-.Fa ctx .
+is a deprecated function to clear a cipher context on the stack
+before use.
+Do not use it on a cipher context returned from
+.Fn EVP_CIPHER_CTX_new
+or one one that was already used.
 .Pp
 .Fn EVP_CIPHER_CTX_free
-clears all information from a cipher context and frees up any
-allocated memory associate with it, including
+clears all information from
+.Fa ctx
+and frees all allocated memory associated with it, including
 .Fa ctx
 itself.
 This function should be called after all operations using a cipher
@@ -428,8 +454,11 @@ for encryption with cipher
 from
 .Vt ENGINE
 .Fa impl .
+If
 .Fa ctx
-must be initialized before calling this function.
+points to an unused object on the stack, it must be initialized with
+.Fn EVP_MD_CTX_init
+before calling this function.
 .Fa type
 is normally supplied by a function such as
 .Fn EVP_aes_256_cbc .
@@ -524,25 +553,19 @@ the value unchanged (the actual value of
 .Fa enc
 being supplied in a previous call).
 .Pp
-.Fn EVP_CIPHER_CTX_cleanup
-clears all information from a cipher context and free up any allocated
-memory associated with it.
-It should be called after all operations using a cipher are complete so
-sensitive information does not remain in memory.
-.Pp
 .Fn EVP_EncryptInit ,
 .Fn EVP_DecryptInit ,
 and
 .Fn EVP_CipherInit
-behave in a similar way to
+are deprecated functions behaving like
 .Fn EVP_EncryptInit_ex ,
 .Fn EVP_DecryptInit_ex ,
 and
 .Fn EVP_CipherInit_ex
-except the
-.Fa ctx
-parameter does not need to be initialized and they always use the
-default cipher implementation.
+except that they always use the default cipher implementation
+and that they require
+.Fn EVP_CIPHER_CTX_reset
+before they can be used on a context that was already used.
 .Pp
 .Fn EVP_EncryptFinal ,
 .Fn EVP_DecryptFinal ,
@@ -556,7 +579,9 @@ and
 In previous releases of OpenSSL, they also used to clean up the
 .Fa ctx ,
 but this is no longer done and
-.Fn EVP_CIPHER_CTX_cleanup
+.Fn EVP_CIPHER_CTX_reset
+or
+.Fn EVP_CIPHER_CTX_free
 must be called to free any context resources.
 .Pp
 .Fn EVP_get_cipherbyname ,
@@ -782,31 +807,31 @@ for success or
 .Dv NULL
 for failure.
 .Pp
+.Fn EVP_CIPHER_CTX_reset ,
+.Fn EVP_CIPHER_CTX_cleanup ,
 .Fn EVP_EncryptInit_ex ,
 .Fn EVP_EncryptUpdate ,
+.Fn EVP_EncryptFinal_ex ,
+.Fn EVP_DecryptInit_ex ,
+.Fn EVP_DecryptUpdate ,
+.Fn EVP_DecryptFinal_ex ,
+.Fn EVP_CipherInit_ex ,
+.Fn EVP_CipherUpdate ,
+.Fn EVP_CipherFinal_ex ,
+.Fn EVP_EncryptInit ,
+.Fn EVP_EncryptFinal ,
+.Fn EVP_DecryptInit ,
+.Fn EVP_DecryptFinal ,
+.Fn EVP_CipherInit ,
+.Fn EVP_CipherFinal ,
+.Fn EVP_CIPHER_CTX_set_key_length ,
 and
-.Fn EVP_EncryptFinal_ex
-return 1 for success and 0 for failure.
-.Pp
-.Fn EVP_DecryptInit_ex
-and
-.Fn EVP_DecryptUpdate
-return 1 for success and 0 for failure.
-.Fn EVP_DecryptFinal_ex
-returns 0 if the decrypt failed or 1 for success.
-.Pp
-.Fn EVP_CipherInit_ex
-and
-.Fn EVP_CipherUpdate
-return 1 for success and 0 for failure.
-.Fn EVP_CipherFinal_ex
-returns 0 for a decryption failure or 1 for success.
-.Pp
 .Fn EVP_CIPHER_CTX_rand_key
-and
-.Fn EVP_CIPHER_CTX_cleanup
 return 1 for success or 0 for failure.
 .Pp
+.Fn EVP_CIPHER_CTX_set_padding
+always returns 1.
+.Pp
 .Fn EVP_get_cipherbyname ,
 .Fn EVP_get_cipherbynid ,
 and
@@ -832,9 +857,6 @@ and
 .Fn EVP_CIPHER_CTX_key_length
 return the key length.
 .Pp
-.Fn EVP_CIPHER_CTX_set_padding
-always returns 1.
-.Pp
 .Fn EVP_CIPHER_iv_length
 and
 .Fn EVP_CIPHER_CTX_iv_length
@@ -1102,10 +1124,11 @@ do_crypt(char *outfile)
         const char intext[] = "Some Crypto Text";
         EVP_CIPHER_CTX *ctx;
         FILE *out;
-        EVP_CIPHER_CTX_init(&ctx);
-        EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv);
 
-        if (!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext,
+        ctx = EVP_CIPHER_CTX_new();
+        EVP_EncryptInit_ex(ctx, EVP_bf_cbc(), NULL, key, iv);
+
+        if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext,
             strlen(intext))) {
                 /* Error */
                 EVP_CIPHER_CTX_free(ctx);
@@ -1115,13 +1138,13 @@ do_crypt(char *outfile)
          * Buffer passed to EVP_EncryptFinal() must be after data just
          * encrypted to avoid overwriting it.
          */
-        if (!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen)) {
+        if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) {
                 /* Error */
                 EVP_CIPHER_CTX_free(ctx);
                 return 0;
         }
         outlen += tmplen;
-        EVP_CIPHER_CTX_cleanup(&ctx);
+        EVP_CIPHER_CTX_free(ctx);
         /*
          * Need binary mode for fopen because encrypted data is
          * binary data. Also cannot use strlen() on it because
@@ -1147,49 +1170,49 @@ openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F \e
            -iv 0102030405060708 -d
 .Ed
 .Pp
-General encryption, decryption function example using FILE I/O and RC2
-with an 80-bit key:
+General encryption, decryption function example using FILE I/O and AES128
+with an 128-bit key:
 .Bd -literal
 int
 do_crypt(FILE *in, FILE *out, int do_encrypt)
 {
         /* Allow enough space in output buffer for additional block */
-        inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
+        unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
         int inlen, outlen;
+        EVP_CIPHER_CTX *ctx;
+
         /*
          * Bogus key and IV: we'd normally set these from
          * another source.
          */
-        unsigned char key[] = "0123456789";
-        unsigned char iv[] = "12345678";
+        unsigned char key[] = "0123456789abcdeF";
+        unsigned char iv[] = "1234567887654321";
 
-        /* Don't set key or IV because we will modify the parameters */
-        EVP_CIPHER_CTX_init(&ctx);
-        EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
-        EVP_CIPHER_CTX_set_key_length(&ctx, 10);
-        /* We finished modifying parameters so now we can set key and IV */
-        EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
+        ctx = EVP_CIPHER_CTX_new();
+        EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
+            do_encrypt);
+        EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt);
 
-        for(;;) {
+        for (;;) {
                 inlen = fread(inbuf, 1, 1024, in);
                 if (inlen <= 0)
                         break;
-                if (!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf,
+                if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf,
                     inlen)) {
                         /* Error */
-                        EVP_CIPHER_CTX_cleanup(&ctx);
+                        EVP_CIPHER_CTX_free(ctx);
                         return 0;
                 }
                 fwrite(outbuf, 1, outlen, out);
         }
-        if (!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) {
+        if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) {
                 /* Error */
-                EVP_CIPHER_CTX_cleanup(&ctx);
+                EVP_CIPHER_CTX_free(ctx);
                 return 0;
         }
         fwrite(outbuf, 1, outlen, out);
 
-        EVP_CIPHER_CTX_cleanup(&ctx);
+        EVP_CIPHER_CTX_free(ctx);
         return 1;
 }
 .Ed
@@ -1206,6 +1229,9 @@ do_crypt(FILE *in, FILE *out, int do_encrypt)
 and
 .Fn EVP_CIPHER_CTX_set_padding
 appeared in OpenSSL 0.9.7.
+.Pp
+.Fn EVP_CIPHER_CTX_reset
+fist appeared in OpenSSL 1.1.0.
 .Sh BUGS
 For RC5 the number of rounds can currently only be set to 8, 12 or 16.
 This is a limitation of the current RC5 code rather than the EVP