EVP_CIPHER_CTX_new,
EVP_CIPHER_CTX_reset,
EVP_CIPHER_CTX_free,
+EVP_CIPHER_CTX_dup,
+EVP_CIPHER_CTX_copy,
EVP_EncryptInit_ex,
EVP_EncryptInit_ex2,
EVP_EncryptUpdate,
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);
+ EVP_CIPHER_CTX *EVP_CIPHER_CTX_dup(const EVP_CIPHER_CTX *in);
+ int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in);
int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
ENGINE *impl, const unsigned char *key, const unsigned char *iv);
all operations using a cipher are complete so sensitive information does not
remain in memory.
+=item EVP_CIPHER_CTX_dup()
+
+Can be used to duplicate the cipher state from I<in>. This is useful
+to avoid multiple EVP_CIPHER_fetch() calls or if large amounts of data are to be
+fed which only differ in the last few bytes.
+
+=item EVP_CIPHER_CTX_copy()
+
+Can be used to copy the cipher state from I<in> to I<out>.
+
=item EVP_CIPHER_CTX_ctrl()
I<This is a legacy method.> EVP_CIPHER_CTX_set_params() and
=item EVP_CIPHER_gettable_params()
-Get a constant B<OSSL_PARAM> array that describes the retrievable parameters
-that can be used with EVP_CIPHER_get_params(). See L<OSSL_PARAM(3)> for the
-use of B<OSSL_PARAM> as a parameter descriptor.
+Get a constant L<OSSL_PARAM(3)> array that describes the retrievable parameters
+that can be used with EVP_CIPHER_get_params().
=item EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params()
-Get a constant B<OSSL_PARAM> array that describes the retrievable parameters
+Get a constant L<OSSL_PARAM(3)> array that describes the retrievable parameters
that can be used with EVP_CIPHER_CTX_get_params().
EVP_CIPHER_gettable_ctx_params() returns the parameters that can be retrieved
from the algorithm, whereas EVP_CIPHER_CTX_gettable_params() returns the
parameters that can be retrieved in the context's current state.
-See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
=item EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params()
-Get a constant B<OSSL_PARAM> array that describes the settable parameters
+Get a constant L<OSSL_PARAM(3)> array that describes the settable parameters
that can be used with EVP_CIPHER_CTX_set_params().
EVP_CIPHER_settable_ctx_params() returns the parameters that can be set from the
algorithm, whereas EVP_CIPHER_CTX_settable_params() returns the parameters that
can be set in the context's current state.
-See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
=item EVP_EncryptInit_ex2()
=item EVP_EncryptUpdate()
Encrypts I<inl> bytes from the buffer I<in> and writes the encrypted version to
-I<out>. This function can be called multiple times to encrypt successive blocks
+I<out>. The pointers I<out> and I<in> may point to the same location, in which
+case the encryption will be done in-place. If I<out> and I<in> point to different
+locations, the two buffers must be disjoint, otherwise the operation might fail
+or the outcome might be undefined.
+
+This function can be called multiple times to encrypt successive blocks
of data. The amount of data written depends on the block alignment of the
encrypted data.
For most ciphers and modes, the amount of data written can be anything
from zero bytes to (inl + cipher_block_size) bytes.
For stream ciphers, the amount of data written can be anything from zero
bytes to inl bytes.
-Thus, I<out> should contain sufficient room for the operation being performed.
-The actual number of bytes written is placed in I<outl>. It also
-checks if I<in> and I<out> are partially overlapping, and if they are
-0 is returned to indicate failure.
+Thus, the buffer pointed to by I<out> must contain sufficient room for the
+operation being performed.
+The actual number of bytes written is placed in I<outl>.
If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
the "final" data, that is any data that remains in a partial block.
Return the NID of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
structure. The actual NID value is an internal value which may not have a
-corresponding OBJECT IDENTIFIER.
+corresponding OBJECT IDENTIFIER. NID_undef is returned in the event that the
+nid is unknown or if the cipher has not been properly initialized via a call to
+B<EVP_CipherInit>.
=item EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags()
=item EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length()
Return the IV length of a cipher when passed an B<EVP_CIPHER> or
-B<EVP_CIPHER_CTX>. It will return zero if the cipher does not use an IV.
-The constant B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers.
+B<EVP_CIPHER_CTX>. It will return zero if the cipher does not use an IV, if
+the cipher has not yet been initialized within the B<EVP_CIPHER_CTX>, or if the
+passed cipher is NULL. The constant B<EVP_MAX_IV_LENGTH> is the maximum IV
+length for all ciphers.
=item EVP_CIPHER_CTX_get_tag_length()
Return the block size of a cipher when passed an B<EVP_CIPHER> or
B<EVP_CIPHER_CTX> structure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the
-maximum block length for all ciphers.
+maximum block length for all ciphers. A value of 0 is returned if the cipher
+has not been properly initialized with a call to B<EVP_CipherInit>.
=item EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type()
Returns the B<EVP_CIPHER> structure when passed an B<EVP_CIPHER_CTX> structure.
EVP_CIPHER_CTX_get1_cipher() is the same except the ownership is passed to
-the caller.
+the caller. Both functions return NULL on error.
=item EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode()
typically include any parameters and an IV. The cipher IV (if any) must be set
when this call is made. This call should be made before the cipher is actually
"used" (before any EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example).
-This function may fail if the cipher does not have any ASN1 support.
+This function may fail if the cipher does not have any ASN1 support, or if an
+uninitialized cipher is passed to it.
=item EVP_CIPHER_asn1_to_param()
When EVP_CIPHER_fetch() is called it internally calls EVP_CIPHER_get_params()
and caches the results.
-EVP_CIPHER_get_params() can be used with the following B<OSSL_PARAM> keys:
+EVP_CIPHER_get_params() can be used with the following L<OSSL_PARAM(3)> keys:
=over 4
=head2 Gettable and Settable EVP_CIPHER_CTX parameters
-The following B<OSSL_PARAM> keys can be used with both EVP_CIPHER_CTX_get_params()
+The following L<OSSL_PARAM(3)> keys can be used with both EVP_CIPHER_CTX_get_params()
and EVP_CIPHER_CTX_set_params().
=over 4
=head2 Gettable EVP_CIPHER_CTX parameters
-The following B<OSSL_PARAM> keys can be used with EVP_CIPHER_CTX_get_params():
+The following L<OSSL_PARAM(3)> keys can be used with EVP_CIPHER_CTX_get_params():
=over 4
=head2 Settable EVP_CIPHER_CTX parameters
-The following B<OSSL_PARAM> keys can be used with EVP_CIPHER_CTX_set_params():
+The following L<OSSL_PARAM(3)> keys can be used with EVP_CIPHER_CTX_set_params():
=over 4
"tls1multi_interleave" must also be set for this operation.
+=item "xts_standard" (B<OSSL_CIPHER_PARAM_XTS_STANDARD>) <UTF8 string>
+
+Sets the XTS standard to use with SM4-XTS algorithm. XTS mode has two
+implementations, one is standardized in IEEE Std. 1619-2007 and has
+been widely used (e.g., XTS AES), the other is proposed recently
+(GB/T 17964-2021 implemented in May 2022) and is currently only used
+in SM4.
+
+The main difference between them is the multiplication by the
+primitive element E<alpha> to calculate the tweak values. The IEEE
+Std 1619-2007 noted that the multiplication "is a left shift of each
+byte by one bit with carry propagating from one byte to the next
+one", which means that in each byte, the leftmost bit is the most
+significant bit. But in GB/T 17964-2021, the rightmost bit is the
+most significant bit, thus the multiplication becomes a right shift
+of each byte by one bit with carry propagating from one byte to the
+next one.
+
+Valid values for the mode are:
+
+=over 4
+
+=item "GB"
+
+The GB/T 17964-2021 variant of SM4-XTS algorithm.
+
+=item "IEEE"
+
+The IEEE Std. 1619-2007 variant of SM4-XTS algorithm.
+
+=back
+
+The default value is "GB".
+
=back
=head1 CONTROLS
When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() get called
with an L<OSSL_PARAM(3)> item with the key
-"tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD>)
+"tlsaad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD>)
followed by EVP_CIPHER_CTX_get_params() with a key of
"tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD>).
EVP_CIPHER_CTX_new() returns a pointer to a newly created
B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
+EVP_CIPHER_CTX_dup() returns a new EVP_CIPHER_CTX if successful or NULL on failure.
+
+EVP_CIPHER_CTX_copy() returns 1 if successful or 0 for failure.
+
EVP_EncryptInit_ex2(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex()
return 1 for success and 0 for failure.
EVP_CipherInit_ex2() 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() returns the amount of encrypted / decrypted bytes, or -1
-on failure if the flag B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is set for the
-cipher. EVP_Cipher() returns 1 on success or 0 on failure, if the flag
-B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is not set for the cipher.
+EVP_Cipher() returns 1 on success and <= 0 on failure, if the flag
+B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is not set for the cipher, or if the cipher has
+not been initialized via a call to B<EVP_CipherInit_ex2>.
+EVP_Cipher() returns the number of bytes written to I<out> for encryption / decryption, or
+the number of bytes authenticated in a call specifying AAD for an AEAD cipher, if the flag
+B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is set for the cipher.
EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure.
EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid() return a NID.
EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size() return the
-block size.
+block size, or 0 on error.
EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length() return the key
length.
EVP_CIPHER_CTX_set_padding() always returns 1.
EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length() return the IV
-length or zero if the cipher does not use an IV.
+length, zero if the cipher does not use an IV and a negative value on error.
EVP_CIPHER_CTX_get_tag_length() return the tag length or zero if the cipher
does not use a tag.
EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater
than zero for success and zero or a negative number on failure.
-EVP_CIPHER_CTX_rand_key() returns 1 for success.
+EVP_CIPHER_CTX_rand_key() returns 1 for success and zero or a negative number
+for failure.
EVP_CIPHER_names_do_all() returns 1 if the callback was called for all names.
A return value of 0 means that the callback was not called for any names.
To specify additional authenticated data (AAD), a call to EVP_CipherUpdate(),
EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
-parameter I<out> set to B<NULL>.
+parameter I<out> set to B<NULL>. In this case, on success, the parameter
+I<outl> is set to the number of bytes authenticated.
When decrypting, the return value of EVP_DecryptFinal() or EVP_CipherFinal()
indicates whether the operation was successful. If it does not indicate success,
=head2 SIV Mode
+Both the AES-SIV and AES-GCM-SIV ciphers fall under this mode.
+
For SIV mode ciphers the behaviour of the EVP interface is subtly
altered and several additional ctrl operations are supported.
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 SIV modes.
+The API does not store the SIV (Synthetic Initialization Vector) in
+the cipher text. Instead, it is stored as the tag within the EVP_CIPHER_CTX.
+The SIV must be retrieved from the context after encryption, and set into
+the context before decryption.
+
+This differs from RFC5297 in that the cipher output from encryption, and
+the cipher input to decryption, does not contain the SIV. This also means
+that the plain text and cipher text lengths are identical.
+
+The following ctrls are supported in SIV mode, and are used to get and set
+the Synthetic Initialization Vector:
=over 4
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
-Writes I<taglen> bytes of the tag value to the buffer indicated by I<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 SIV mode the taglen must
-be 16.
+Writes I<taglen> bytes of the tag value (the Synthetic Initialization Vector)
+to the buffer indicated by I<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 SIV mode the taglen must be 16.
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
-Sets the expected tag to I<taglen> bytes from I<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 SIV mode the taglen must be 16.
+Sets the expected tag (the Synthetic Initialization Vector) to I<taglen>
+bytes from I<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()
+calls). For SIV mode the taglen must be 16.
=back
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 I<out> set to a non-B<NULL> value. A call to EVP_Decrypt_Final() or
+with I<out> set to a non-B<NULL> value. A call to EVP_DecryptFinal() or
EVP_CipherFinal() is not required, but will indicate if the update
operation succeeded.
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
-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 12 bytes (i.e. 96-bits). If a nonce of less than 12 bytes is set
-then the nonce is automatically padded with leading 0 bytes to make it 12 bytes
-in length.
+Sets the nonce length. This call is now redundant since the only valid value
+is the default length of 12 (i.e. 96 bits).
+Prior to OpenSSL 3.0 a nonce of less than 12 bytes could be used to automatically
+pad the iv with leading 0 bytes to make it 12 bytes in length.
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
B<EVP_CIPHER_CTX_FLAG_WRAP_ALLOW> flag treated specially in
EVP_CipherInit_ex().
+Ignoring failure returns of the B<EVP_CIPHER_CTX> initialization functions can
+lead to subsequent undefined behavior when calling the functions that update or
+finalize the context. The only valid calls on the B<EVP_CIPHER_CTX> when
+initialization fails are calls that attempt another initialization of the
+context or release the context.
+
EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros.
=head1 BUGS
FILE *out;
ctx = EVP_CIPHER_CTX_new();
- EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL);
+ if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) {
+ /* Error */
+ EVP_CIPHER_CTX_free(ctx);
+ return 0;
+ }
if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) {
/* Error */
/* Don't set key or IV right away; we want to check lengths */
ctx = EVP_CIPHER_CTX_new();
- EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL,
- do_encrypt, NULL);
+ if (!EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL,
+ do_encrypt, NULL)) {
+ /* Error */
+ EVP_CIPHER_CTX_free(ctx);
+ return 0;
+ }
OPENSSL_assert(EVP_CIPHER_CTX_get_key_length(ctx) == 16);
OPENSSL_assert(EVP_CIPHER_CTX_get_iv_length(ctx) == 16);
/* Now we can set key and IV */
- EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL);
+ if (!EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL)) {
+ /* Error */
+ EVP_CIPHER_CTX_free(ctx);
+ return 0;
+ }
for (;;) {
inlen = fread(inbuf, 1, 1024, in);
goto err;
/* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */
- if (!EVP_CipherUpdate(ctx, encrypted, &outlen, msg, msglen))
+ if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len))
goto err;
- if (!EVP_CipherFinal_ex(ctx, encrypted + outlen, &len))
+ if (!EVP_CipherFinal_ex(ctx, out + outlen, &len))
goto err;
ret = 1;
err:
The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.0.
+EVP_CIPHER_CTX_dup() was added in OpenSSL 3.2.
+
=head1 COPYRIGHT
-Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
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
projects / openssl.git / blobdiff