=head1 NAME
-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,
-EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length,
-EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher,
-EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length,
-EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data,
-EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags,
-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_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,
-EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb,
-EVP_aes_128_cbc, EVP_aes_128_ecb, EVP_aes_128_cfb, EVP_aes_128_ofb,
-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
+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,
+EVP_CIPHER_block_size,
+EVP_CIPHER_key_length,
+EVP_CIPHER_iv_length,
+EVP_CIPHER_flags,
+EVP_CIPHER_mode,
+EVP_CIPHER_type,
+EVP_CIPHER_CTX_cipher,
+EVP_CIPHER_CTX_nid,
+EVP_CIPHER_CTX_block_size,
+EVP_CIPHER_CTX_key_length,
+EVP_CIPHER_CTX_iv_length,
+EVP_CIPHER_CTX_get_app_data,
+EVP_CIPHER_CTX_set_app_data,
+EVP_CIPHER_CTX_type,
+EVP_CIPHER_CTX_flags,
+EVP_CIPHER_CTX_mode,
+EVP_CIPHER_param_to_asn1,
+EVP_CIPHER_asn1_to_param,
+EVP_CIPHER_CTX_set_padding,
+EVP_enc_null
+- EVP cipher routines
=head1 SYNOPSIS
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, const unsigned char *key, const 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, const 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, const unsigned char *key, const 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, const 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, const unsigned char *key, const 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, const 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);
+ const unsigned char *key, const 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);
+ const unsigned char *key, const 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);
+ const unsigned char *key, const 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);
int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
+ int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key);
const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
const EVP_CIPHER *EVP_get_cipherbynid(int nid);
int EVP_CIPHER_nid(const EVP_CIPHER *e);
int EVP_CIPHER_block_size(const EVP_CIPHER *e);
- int EVP_CIPHER_key_length(const EVP_CIPHER *e)
int EVP_CIPHER_key_length(const EVP_CIPHER *e);
int EVP_CIPHER_iv_length(const EVP_CIPHER *e);
unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e);
EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and
-EVP_CipherInit_ex() except the B<ctx> parameter does not need to be
-initialized and they always use the default cipher implementation.
+EVP_CipherInit_ex() except they always use the default cipher implementation.
EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are
identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
an B<EVP_CIPHER_CTX> structure.
EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
-EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or
-EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then
+EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE,
+EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE,
+EVP_CIPH_WRAP_MODE or EVP_CIPH_OCB_MODE. If the cipher is a stream cipher then
EVP_CIPH_STREAM_CIPHER is returned.
EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
and set.
+EVP_CIPHER_CTX_rand_key() generates a random key of the appropriate length
+based on the cipher context. The EVP_CIPHER can provide its own random key
+generation routine to support keys of a specific form. B<Key> must point to a
+buffer at least as big as the value returned by EVP_CIPHER_CTX_key_length().
+
=head1 RETURN VALUES
EVP_CIPHER_CTX_new() returns a pointer to a newly created
EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure.
EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater
-than zero for success and zero or a negative number.
+than zero for success and zero or a negative number on failure.
+
+EVP_CIPHER_CTX_rand_key() returns 1 for success.
=head1 CIPHER LISTING
All algorithms have a fixed key length unless otherwise stated.
+Refer to L<SEE ALSO> for the full list of ciphers available through the EVP
+interface.
+
=over 4
=item EVP_enc_null()
Null cipher: does nothing.
-=item EVP_aes_128_cbc(), EVP_aes_128_ecb(), EVP_aes_128_cfb(), EVP_aes_128_ofb()
-
-AES with a 128-bit key in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_aes_192_cbc(), EVP_aes_192_ecb(), EVP_aes_192_cfb(), EVP_aes_192_ofb()
-
-AES with a 192-bit key in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_aes_256_cbc(), EVP_aes_256_ecb(), EVP_aes_256_cfb(), EVP_aes_256_ofb()
-
-AES with a 256-bit key in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_ofb()
-
-DES in CBC, ECB, CFB and OFB modes respectively.
-
-=item EVP_des_ede_cbc(), EVP_des_ede(), EVP_des_ede_ofb(), EVP_des_ede_cfb()
+=back
-Two key triple DES in CBC, ECB, CFB and OFB modes respectively.
+=head1 AEAD Interface
-=item EVP_des_ede3_cbc(), EVP_des_ede3(), EVP_des_ede3_ofb(), EVP_des_ede3_cfb()
+The EVP interface for Authenticated Encryption with Associated Data (AEAD)
+modes are subtly altered and several additional I<ctrl> operations are supported
+depending on the mode specified.
-Three key triple DES in CBC, ECB, CFB and OFB modes respectively.
+To specify additional authenticated data (AAD), a call to EVP_CipherUpdate(),
+EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
+parameter B<out> set to B<NULL>.
-=item EVP_desx_cbc()
+When decrypting, the return value of EVP_DecryptFinal() or EVP_CipherFinal()
+indicates whether the operation was successful. If it does not indicate success,
+the authentication operation has failed and any output data B<MUST NOT> be used
+as it is corrupted.
-DESX algorithm in CBC mode.
+=head2 GCM and OCB Modes
-=item EVP_rc4()
+The following I<ctrl>s are supported in GCM and OCB modes.
-RC4 stream cipher. This is a variable key length cipher with default key length 128 bits.
+=over 4
-=item EVP_rc4_40()
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
-RC4 stream cipher with 40 bit key length.
-This is obsolete and new code should use EVP_rc4()
-and the EVP_CIPHER_CTX_set_key_length() function.
+Sets the IV length. This call can only be made before specifying an IV. If
+not called a default IV length is used.
-=item EVP_idea_cbc() EVP_idea_ecb(), EVP_idea_cfb(), EVP_idea_ofb()
+For GCM AES and OCB AES the default is 12 (i.e. 96 bits). For OCB mode the
+maximum is 15.
-IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
-=item EVP_rc2_cbc(), EVP_rc2_ecb(), EVP_rc2_cfb(), EVP_rc2_ofb()
+Writes C<taglen> bytes of the tag value to the buffer indicated by C<tag>.
+This call can only be made when encrypting data and B<after> all data has been
+processed (e.g. after an EVP_EncryptFinal() call).
-RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
-length cipher with an additional parameter called "effective key bits" or "effective key length".
-By default both are set to 128 bits.
+For OCB, C<taglen> must either be 16 or the value previously set via
+B<EVP_CTRL_AEAD_SET_TAG>.
-=item EVP_rc2_40_cbc(), EVP_rc2_64_cbc()
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
-RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits.
-These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and
-EVP_CIPHER_CTX_ctrl() to set the key length and effective key length.
+Sets the expected tag to C<taglen> bytes from C<tag>.
+The tag length can only be set before specifying an IV.
+C<taglen> must be between 1 and 16 inclusive.
-=item EVP_bf_cbc(), EVP_bf_ecb(), EVP_bf_cfb(), EVP_bf_ofb()
+For GCM, this call is only valid when decrypting data.
-Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
-length cipher.
+For OCB, this call is valid when decrypting data to set the expected tag,
+and before encryption to set the desired tag length.
-=item EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), EVP_cast5_ofb()
+In OCB mode, calling this before encryption with C<tag> set to C<NULL> sets the
+tag length. If this is not called prior to encryption, a default tag length is
+used.
-CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key
-length cipher.
+For OCB AES, the default tag length is 16 (i.e. 128 bits). It is also the
+maximum tag length for OCB.
-=item EVP_rc5_32_12_16_cbc(), EVP_rc5_32_12_16_ecb(), EVP_rc5_32_12_16_cfb(), EVP_rc5_32_12_16_ofb()
+=back
-RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length
-cipher with an additional "number of rounds" parameter. By default the key length is set to 128
-bits and 12 rounds.
+=head2 CCM Mode
-=item EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm()
+The EVP interface for CCM mode is similar to that of the GCM mode but with a
+few additional requirements and different I<ctrl> values.
-AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively.
-These ciphers require additional control operations to function correctly: see
-the L</GCM and OCB Modes> section below for details.
+For CCM mode, the total plaintext or ciphertext length B<MUST> be passed to
+EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output
+and input parameters (B<in> and B<out>) set to B<NULL> and the length passed in
+the B<inl> parameter.
-=item EVP_aes_128_ocb(void), EVP_aes_192_ocb(void), EVP_aes_256_ocb(void)
+The following I<ctrl>s are supported in CCM mode.
-Offset Codebook Mode (OCB) for 128, 192 and 256 bit keys respectively.
-These ciphers require additional control operations to function correctly: see
-the L</GCM and OCB Modes> section below for details.
+=over 4
-=item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm()
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
-AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively.
-These ciphers require additional control operations to function correctly: see
-CCM mode section below for details.
+This call is made to set the expected B<CCM> tag value when decrypting or
+the length of the tag (with the C<tag> parameter set to NULL) when encrypting.
+The tag length is often referred to as B<M>. If not set a default value is
+used (12 for AES).
-=item EVP_chacha20()
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)
-The ChaCha20 stream cipher. The key length is 256 bits, the IV is 96 bits long.
+Sets the CCM B<L> value. If not set a default is used (8 for AES).
-=item EVP_chacha20_poly1305()
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
-Authenticated encryption with ChaCha20-Poly1305. Like EVP_chacha20() the key is
-256 bits and the IV is 96 bits. This supports additional authenticated
-data (AAD) and produces a 128 bit authentication tag. See the
-L</GCM and OCB Modes> section for more information.
+Sets the CCM nonce (IV) length. This call can only be made before specifying an
+nonce value. The nonce length is given by B<15 - L> so it is 7 by default for
+AES.
=back
-=head1 GCM and OCB Modes
+=head2 SIV Mode
-For GCM and OCB mode ciphers the behaviour of the EVP interface is subtly
+For SIV mode ciphers the behaviour of the EVP interface is subtly
altered and several additional ctrl operations are supported.
-To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(),
-EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
-parameter B<out> set to B<NULL>.
+To specify any additional authenticated data (AAD) and/or a Nonce, a call to
+EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made
+with the output parameter B<out> set to B<NULL>.
+
+RFC5297 states that the Nonce is the last piece of AAD before the actual
+encrypt/decrypt takes place. The API does not differentiate the Nonce from
+other AAD.
When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal()
indicates if the operation was successful. If it does not indicate success
the authentication operation has failed and any output data B<MUST NOT>
be used as it is corrupted.
-The following ctrls are supported in both GCM and OCB modes:
-
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL);
+The following ctrls are supported in both SIV modes.
-Sets the IV length: this call can only be made before specifying an IV. If
-not called a default IV length is used. For GCM AES and OCB AES the default is
-12 (i.e. 96 bits). For OCB mode the maximum is 15.
+=over 4
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>.
This call can only be made when encrypting data and B<after> all data has been
-processed (e.g. after an EVP_EncryptFinal() call). For OCB mode the taglen must
-either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN.
+processed (e.g. after an EVP_EncryptFinal() call). For SIV mode the taglen must
+be 16.
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
+=item 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.
+before any EVP_DecryptUpdate() call). For SIV mode the taglen must be 16.
-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
-length is used. For OCB AES the default is 16 (i.e. 128 bits). This is also the
-maximum tag length for OCB.
+=back
-=head1 CCM Mode
+SIV mode makes two passes over the input data, thus, only one call to
+EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made
+with B<out> set to a non-B<NULL> value. A call to EVP_Decrypt_Final() or
+EVP_CipherFinal() is not required, but will indicate if the update
+operation succeeded.
-The behaviour of CCM mode ciphers is similar to GCM mode but with a few
-additional requirements and different ctrl values.
+=head2 ChaCha20-Poly1305
-Like GCM and OCB modes any additional authenticated data (AAD) is passed by calling
-EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output
-parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext
-length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or
-EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>)
-set to B<NULL> and the length passed in the B<inl> parameter.
+The following I<ctrl>s are supported for the ChaCha20-Poly1305 AEAD algorithm.
-The following ctrls are supported in CCM mode:
+=over 4
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
-This call is made to set the expected B<CCM> tag value when decrypting or
-the length of the tag (with the B<tag> parameter set to NULL) when encrypting.
-The tag length is often referred to as B<M>. If not set a default value is
-used (12 for AES).
+Sets the nonce length. This call can only be made before specifying the nonce.
+If not called a default nonce length of 12 (i.e. 96 bits) is used. The maximum
+nonce length is 16 (B<CHACHA_CTR_SIZE>, i.e. 128-bits).
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL);
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
-Sets the CCM B<L> value. If not set a default is used (8 for AES).
+Writes C<taglen> bytes of the tag value to the buffer indicated by C<tag>.
+This call can only be made when encrypting data and B<after> all data has been
+processed (e.g. after an EVP_EncryptFinal() call).
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL);
+C<taglen> specified here must be 16 (B<POLY1305_BLOCK_SIZE>, i.e. 128-bits) or
+less.
-Sets the CCM nonce (IV) length: this call can only be made before specifying
-an nonce value. The nonce length is given by B<15 - L> so it is 7 by default
-for AES.
+=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
+
+Sets the expected tag to C<taglen> bytes from C<tag>.
+The tag length can only be set before specifying an IV.
+C<taglen> must be between 1 and 16 (B<POLY1305_BLOCK_SIZE>) inclusive.
+This call is only valid when decrypting data.
+
+=back
=head1 NOTES
=head1 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 interface.
-
-EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with
-default key lengths. If custom ciphers exceed these values the results are
-unpredictable. This is because it has become standard practice to define a
-generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes.
+B<EVP_MAX_KEY_LENGTH> and B<EVP_MAX_IV_LENGTH> only refer to the internal
+ciphers with default key lengths. If custom ciphers exceed these values the
+results are unpredictable. This is because it has become standard practice to
+define a generic key as a fixed unsigned char array containing
+B<EVP_MAX_KEY_LENGTH> bytes.
The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested
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
L<evp(7)>
+Supported ciphers are listed in:
+
+L<EVP_aes(3)>,
+L<EVP_aria(3)>,
+L<EVP_bf(3)>,
+L<EVP_camellia(3)>,
+L<EVP_cast5(3)>,
+L<EVP_chacha20(3)>,
+L<EVP_des(3)>,
+L<EVP_desx(3)>,
+L<EVP_idea(3)>,
+L<EVP_rc2(3)>,
+L<EVP_rc4(3)>,
+L<EVP_rc5(3)>,
+L<EVP_seed(3)>,
+L<EVP_sm4(3)>
+
=head1 HISTORY
Support for OCB mode was added in OpenSSL 1.1.0
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
projects / openssl.git / blobdiff