Document the new EVP_CIPHER and EVP_CIPHER_CTX functionality
[openssl.git] / doc / crypto / EVP_EncryptInit.pod
index 8f3216b..f064d67 100644 (file)
@@ -2,11 +2,11 @@
 
 =head1 NAME
 
-EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate,
-EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate,
-EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate,
-EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length,
-EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit,
+EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free,
+EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex,
+EVP_DecryptInit_ex, EVP_DecryptUpdate, EVP_DecryptFinal_ex,
+EVP_CipherInit_ex, EVP_CipherUpdate, EVP_CipherFinal_ex,
+EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_EncryptInit,
 EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal,
 EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname,
 EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid,
@@ -35,7 +35,9 @@ EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
 
  #include <openssl/evp.h>
 
- void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a);
+ EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
+ int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
+ void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
 
  int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
         ENGINE *impl, unsigned char *key, unsigned char *iv);
@@ -76,7 +78,6 @@ EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
  int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
  int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
  int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
- int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a);
 
  const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
  #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
@@ -90,16 +91,18 @@ EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
  #define EVP_CIPHER_mode(e)            ((e)->flags) & EVP_CIPH_MODE)
  int EVP_CIPHER_type(const EVP_CIPHER *ctx);
 
- #define EVP_CIPHER_CTX_cipher(e)      ((e)->cipher)
- #define EVP_CIPHER_CTX_nid(e)         ((e)->cipher->nid)
- #define EVP_CIPHER_CTX_block_size(e)  ((e)->cipher->block_size)
- #define EVP_CIPHER_CTX_key_length(e)  ((e)->key_len)
- #define EVP_CIPHER_CTX_iv_length(e)   ((e)->cipher->iv_len)
- #define EVP_CIPHER_CTX_get_app_data(e)        ((e)->app_data)
- #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d))
- #define EVP_CIPHER_CTX_type(c)         EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
- #define EVP_CIPHER_CTX_flags(e)               ((e)->cipher->flags)
- #define EVP_CIPHER_CTX_mode(e)                ((e)->cipher->flags & EVP_CIPH_MODE)
+ const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx);
+ int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx);
+ void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx);
+ void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data);
+ int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx);
+ void EVP_CIPHER_CTX_set_flags(const EVP_CIPHER_CTX *ctx, int flags);
+ void EVP_CIPHER_CTX_clear_flags(const EVP_CIPHER_CTX *ctx, int flags);
+ int EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags);
+ int EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx);
 
  int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
  int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
@@ -109,10 +112,16 @@ EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
 The EVP cipher routines are a high level interface to certain
 symmetric ciphers.
 
-EVP_CIPHER_CTX_init() initializes cipher contex B<ctx>.
+EVP_CIPHER_CTX_new() creates a cipher context.
+
+EVP_CIPHER_CTX_free() clears all information from a cipher context
+and free up any allocated memory associate with it, including B<ctx>
+itself. This function should be called after all operations using a
+cipher are complete so sensitive information does not remain in
+memory.
 
 EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
-with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized
+with cipher B<type> from ENGINE B<impl>. B<ctx> must be created
 before calling this function. B<type> is normally supplied
 by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
 default implementation is used. B<key> is the symmetric key to use
@@ -159,10 +168,11 @@ performed depends on the value of the B<enc> parameter. It should be set
 to 1 for encryption, 0 for decryption and -1 to leave the value unchanged
 (the actual value of 'enc' being supplied in a previous call).
 
-EVP_CIPHER_CTX_cleanup() clears all information from a cipher context
-and free up any allocated memory associate with it. It should be called
-after all operations using a cipher are complete so sensitive information
-does not remain in memory.
+EVP_CIPHER_CTX_reset() clears all information from a cipher context
+and free up any allocated memory associate with it, except the B<ctx>
+itself. This function should be called anytime B<ctx> is to be reused
+for another EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal()
+series of calls.
 
 EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
 similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and
@@ -250,6 +260,9 @@ and set.
 
 =head1 RETURN VALUES
 
+EVP_CIPHER_CTX_new() returns a pointer to a newly created
+B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
+
 EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
 return 1 for success and 0 for failure.
 
@@ -259,7 +272,7 @@ EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
 EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure.
 EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
 
-EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure.
+EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure.
 
 EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
 return an B<EVP_CIPHER> structure or NULL on error.
@@ -511,7 +524,7 @@ for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
 Encrypt a string using IDEA:
 
  int do_crypt(char *outfile)
-       {
+       {
        unsigned char outbuf[1024];
        int outlen, tmplen;
        /* Bogus key and IV: we'd normally set these from
@@ -523,10 +536,10 @@ Encrypt a string using IDEA:
        EVP_CIPHER_CTX ctx;
        FILE *out;
 
-       EVP_CIPHER_CTX_init(&ctx);
-       EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv);
+       ctx = EVP_CIPHER_CTX_new();
+       EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv);
 
-       if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
+       if(!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext)))
                {
                /* Error */
                return 0;
@@ -534,13 +547,13 @@ Encrypt a string using IDEA:
        /* 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 */
                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
          * it wont be null terminated and may contain embedded
@@ -566,7 +579,7 @@ with a 128-bit key:
        /* Allow enough space in output buffer for additional block */
        unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
        int inlen, outlen;
-       EVP_CIPHER_CTX ctx;
+       EVP_CIPHER_CTX *ctx;
        /* Bogus key and IV: we'd normally set these from
         * another source.
         */
@@ -574,36 +587,36 @@ with a 128-bit key:
        unsigned char iv[] = "1234567887654321";
 
        /* Don't set key or IV right away; we want to check lengths */
-       EVP_CIPHER_CTX_init(&ctx);
+       ctx = EVP_CIPHER_CTX_new();
        EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
                do_encrypt);
-       OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16);
-       OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16);
+       OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16);
+       OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16);
 
        /* Now we can set key and IV */
-       EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
+       EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt);
 
        for(;;)
                {
                inlen = fread(inbuf, 1, 1024, in);
                if(inlen <= 0) break;
-               if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen))
+               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;
        }
 
@@ -616,4 +629,9 @@ L<evp(3)>
 
 Support for OCB mode was added in OpenSSL 1.1.0
 
+B<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0.  As a result,
+EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup()
+disappeared.  EVP_CIPHER_CTX_init() remains as an alias for
+EVP_CIPHER_CTX_reset().
+
 =cut