Correct GCM docs.
[openssl.git] / doc / man3 / EVP_EncryptInit.pod
index 6695f02..0aaba05 100644 (file)
@@ -19,8 +19,8 @@ EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param,
 EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb,
 EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb,
 EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb,
-EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc,
-EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_rc2_cbc,
+EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_rc4_hmac_md5,
+EVP_idea_cbc, EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_rc2_cbc,
 EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc,
 EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc,
 EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc,
@@ -30,6 +30,8 @@ EVP_aes_192_cbc, EVP_aes_192_ecb, EVP_aes_192_cfb, EVP_aes_192_ofb,
 EVP_aes_256_cbc, EVP_aes_256_ecb, EVP_aes_256_cfb, EVP_aes_256_ofb,
 EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm,
 EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm,
+EVP_aes_128_cbc_hmac_sha1, EVP_aes_256_cbc_hmac_sha1,
+EVP_aes_128_cbc_hmac_sha256, EVP_aes_256_cbc_hmac_sha256,
 EVP_chacha20, EVP_chacha20_poly1305 - EVP cipher routines
 
 =head1 SYNOPSIS
@@ -43,40 +45,34 @@ EVP_chacha20, EVP_chacha20_poly1305 - EVP cipher routines
  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);
+                        ENGINE *impl, unsigned char *key, unsigned char *iv);
  int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
-         int *outl, unsigned char *in, int inl);
- int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
-         int *outl);
+                       int *outl, unsigned char *in, int inl);
+ int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
 
  int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-         ENGINE *impl, unsigned char *key, unsigned char *iv);
+                        ENGINE *impl, unsigned char *key, unsigned char *iv);
  int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
-         int *outl, unsigned char *in, int inl);
- int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
-         int *outl);
+                       int *outl, unsigned char *in, int inl);
+ int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 
  int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-         ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
+                       ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
  int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
-         int *outl, unsigned char *in, int inl);
- int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
-         int *outl);
+                      int *outl, unsigned char *in, int inl);
+ int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 
  int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-         unsigned char *key, unsigned char *iv);
- int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
-         int *outl);
+                     unsigned char *key, unsigned char *iv);
+ int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
 
  int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-         unsigned char *key, unsigned char *iv);
- int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
-         int *outl);
+                     unsigned char *key, unsigned char *iv);
+ int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 
  int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-         unsigned char *key, unsigned char *iv, int enc);
- int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
-         int *outl);
+                    unsigned char *key, unsigned char *iv, int enc);
+ int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 
  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);
@@ -446,9 +442,8 @@ either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN.
  EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
 
 Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal
-when decrypting data and must be made B<before> any data is processed (e.g.
-before any EVP_DecryptUpdate() call). For OCB mode the taglen must
-either be 16 or the value previously set via EVP_CTRL_AEAD_SET_TAG.
+when decrypting data. For OCB mode the taglen must either be 16 or the value
+previously set via EVP_CTRL_AEAD_SET_TAG.
 
 In OCB mode calling this with B<tag> set to NULL sets the tag length. The tag
 length can only be set before specifying an IV. If not called a default tag
@@ -538,101 +533,107 @@ 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
-         * another source.
-         */
-        unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
-        unsigned char iv[] = {1,2,3,4,5,6,7,8};
-        char intext[] = "Some Crypto Text";
-        EVP_CIPHER_CTX ctx;
-        FILE *out;
-
-        ctx = EVP_CIPHER_CTX_new();
-        EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv);
-
-        if(!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext)))
-                {
-                /* Error */
-                return 0;
-                }
-        /* Buffer passed to EVP_EncryptFinal() must be after data just
-         * encrypted to avoid overwriting it.
-         */
-        if(!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen))
-                {
-                /* Error */
-                return 0;
-                }
-        outlen += tmplen;
-        EVP_CIPHER_CTX_free(ctx);
-        /* Need binary mode for fopen because encrypted data is
-         * binary data. Also cannot use strlen() on it because
-         * it won't be null terminated and may contain embedded
-         * nulls.
-         */
-        out = fopen(outfile, "wb");
-        fwrite(outbuf, 1, outlen, out);
-        fclose(out);
-        return 1;
-        }
+ {
+     unsigned char outbuf[1024];
+     int outlen, tmplen;
+     /*
+      * Bogus key and IV: we'd normally set these from
+      * another source.
+      */
+     unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
+     unsigned char iv[] = {1,2,3,4,5,6,7,8};
+     char intext[] = "Some Crypto Text";
+     EVP_CIPHER_CTX *ctx;
+     FILE *out;
+
+     ctx = EVP_CIPHER_CTX_new();
+     EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv);
+
+     if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) {
+         /* Error */
+         EVP_CIPHER_CTX_free(ctx);
+         return 0;
+     }
+     /*
+      * Buffer passed to EVP_EncryptFinal() must be after data just
+      * encrypted to avoid overwriting it.
+      */
+     if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) {
+         /* Error */
+         EVP_CIPHER_CTX_free(ctx);
+         return 0;
+     }
+     outlen += tmplen;
+     EVP_CIPHER_CTX_free(ctx);
+     /*
+      * Need binary mode for fopen because encrypted data is
+      * binary data. Also cannot use strlen() on it because
+      * it won't be NUL terminated and may contain embedded
+      * NULs.
+      */
+     out = fopen(outfile, "wb");
+     if (out == NULL) {
+         /* Error */
+         return 0;
+     }
+     fwrite(outbuf, 1, outlen, out);
+     fclose(out);
+     return 1;
+ }
 
 The ciphertext from the above example can be decrypted using the B<openssl>
 utility with the command line (shown on two lines for clarity):
 
- openssl idea -d <filename
-          -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708
+ openssl idea -d \
+     -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 <filename
 
 General encryption and decryption function example using FILE I/O and AES128
 with a 128-bit key:
 
  int do_crypt(FILE *in, FILE *out, int do_encrypt)
-        {
-        /* 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;
-        /* Bogus key and IV: we'd normally set these from
-         * another source.
-         */
-        unsigned char key[] = "0123456789abcdeF";
-        unsigned char iv[] = "1234567887654321";
-
-        /* Don't set key or IV right away; we want to check lengths */
-        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);
-
-        /* Now we can set key and IV */
-        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))
-                        {
-                        /* Error */
-                        EVP_CIPHER_CTX_free(ctx);
-                        return 0;
-                        }
-                fwrite(outbuf, 1, outlen, out);
-                }
-        if(!EVP_CipherFinal_ex(ctx, outbuf, &outlen))
-                {
-                /* Error */
-                EVP_CIPHER_CTX_free(ctx);
-                return 0;
-                }
-        fwrite(outbuf, 1, outlen, out);
-
-        EVP_CIPHER_CTX_free(ctx);
-        return 1;
-        }
+ {
+     /* 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;
+     /*
+      * Bogus key and IV: we'd normally set these from
+      * another source.
+      */
+     unsigned char key[] = "0123456789abcdeF";
+     unsigned char iv[] = "1234567887654321";
+
+     /* Don't set key or IV right away; we want to check lengths */
+     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);
+
+     /* Now we can set key and IV */
+     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)) {
+             /* Error */
+             EVP_CIPHER_CTX_free(ctx);
+             return 0;
+         }
+         fwrite(outbuf, 1, outlen, out);
+     }
+     if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) {
+         /* Error */
+         EVP_CIPHER_CTX_free(ctx);
+         return 0;
+     }
+     fwrite(outbuf, 1, outlen, out);
+
+     EVP_CIPHER_CTX_free(ctx);
+     return 1;
+ }
 
 
 =head1 SEE ALSO