=item EVP_CIPHER_CTX_dup()
Can be used to duplicate the cipher state from I<in>. This is useful
-to avoid multiple EVP_MD_fetch() calls or if large amounts of data are to be
-hashed which only differ in the last few bytes.
+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()
=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 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_MD_CTX if successful or NULL on 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_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.
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,
the authentication operation has failed and any output data B<MUST NOT>
be used as it is corrupted.
-The API does not store the the SIV (Synthetic Initialization Vector) in
+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.
=head1 COPYRIGHT
-Copyright 2000-2022 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