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_ctrl(EVP_CIPHER_CTX *ctx, int cmd, int p1, void *p2);
int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key);
const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
The B<EVP_CIPHER> type is a structure for cipher method implementation.
-EVP_CIPHER_fetch() fetches the cipher implementation for the given
-B<algorithm> from any provider offering it, within the criteria given
-by the B<properties>.
+=over 4
+
+=item EVP_CIPHER_fetch()
+
+Fetches the cipher implementation for the given B<algorithm> from any provider
+offering it, within the criteria given by the B<properties>.
See L<crypto(7)/ALGORITHM FETCHING> for further information.
The returned value must eventually be freed with EVP_CIPHER_free().
-EVP_CIPHER_up_ref() increments the reference count for an B<EVP_CIPHER>
-structure.
+Fetched B<EVP_CIPHER> structures are reference counted.
+
+=item EVP_CIPHER_up_ref()
-EVP_CIPHER_free() decrements the reference count for the B<EVP_CIPHER>
-structure.
+Increments the reference count for an B<EVP_CIPHER> structure.
+
+=item EVP_CIPHER_free()
+
+Decrements the reference count for the fetched B<EVP_CIPHER> structure.
If the reference count drops to 0 then the structure is freed.
-EVP_CIPHER_CTX_new() creates a cipher context.
+=item EVP_CIPHER_CTX_new()
+
+Allocates and returns a cipher context.
+
+=item 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.
+
+=item EVP_CIPHER_CTX_ctrl()
+
+I<This is a legacy method. EVP_CIPHER_CTX_set_params() and
+EVP_CIPHER_CTX_get_params() is the mechanism that should be used to set and get
+parameters that are used by providers.>
+
+Performs cipher-specific control actions on context I<ctx>. The control command
+is indicated in I<cmd> and any additional arguments in I<p1> and I<p2>.
+EVP_CIPHER_CTX_ctrl() must be called after EVP_CipherInit_ex2(). Other restrictions
+may apply depending on the control type and cipher implementation.
+
+If this function happens to be used with a fetched B<EVP_CIPHER>, it will
+translate the controls that are known to OpenSSL into L<OSSL_PARAM(3)>
+parameters with keys defined by OpenSSL and call EVP_CIPHER_CTX_get_params() or
+EVP_CIPHER_CTX_set_params() as is appropriate for each control command.
+
+See L</CONTROLS> below for more information, including what translations are
+being done.
+
+=item EVP_CIPHER_get_params()
-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.
+Retrieves the requested list of algorithm I<params> from a CIPHER I<cipher>.
+See L</PARAMETERS> below for more information.
-EVP_EncryptInit_ex2() sets up cipher context B<ctx> for encryption
-with cipher B<type>. B<type> is typically supplied by a function such
-as EVP_aes_256_cbc(), or a value explicitly fetched with
-EVP_CIPHER_fetch(). B<key> is the symmetric key to use
-and B<iv> is the IV to use (if necessary), the actual number of bytes
-used for the key and IV depends on the cipher. The parameters B<params> will
+=item EVP_CIPHER_CTX_get_params()
+
+Retrieves the requested list of I<params> from CIPHER context I<ctx>.
+See L</PARAMETERS> below for more information.
+
+=item EVP_CIPHER_CTX_set_params()
+
+Sets the list of I<params> into a CIPHER context I<ctx>.
+See L</PARAMETERS> below for more information.
+
+=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.
+
+=item EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params()
+
+Get a constant B<OSSL_PARAM> 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
+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()
+
+Sets up cipher context I<ctx> for encryption with cipher I<type>. I<type> is
+typically supplied by a function such as EVP_aes_256_cbc(), or a value
+explicitly fetched with EVP_CIPHER_fetch(). I<key> is the symmetric key to use
+and I<iv> is the IV to use (if necessary), the actual number of bytes
+used for the key and IV depends on the cipher. The parameters I<params> will
be set on the context after initialisation. It is possible to set
-all parameters to NULL except B<type> in an initial call and supply
-the remaining parameters in subsequent calls, all of which have B<type>
+all parameters to NULL except I<type> in an initial call and supply
+the remaining parameters in subsequent calls, all of which have I<type>
set to NULL. This is done when the default cipher parameters are not
appropriate.
-For EVP_CIPH_GCM_MODE the IV will be generated internally if it is not
+For B<EVP_CIPH_GCM_MODE> the IV will be generated internally if it is not
specified.
-EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
-with cipher B<type>. B<type> is typically supplied by a function such
-as EVP_aes_256_cbc(), or a value explicitly fetched with
-EVP_CIPHER_fetch(). If B<impl> is non-NULL, its implementation of the
-cipher B<type> is used if there is one, and if not, the default
-implementation is used. B<key> is the symmetric key to use
-and B<iv> is the IV to use (if necessary), the actual number of bytes
-used for the key and IV depends on the cipher. It is possible to set
-all parameters to NULL except B<type> in an initial call and supply
-the remaining parameters in subsequent calls, all of which have B<type>
-set to NULL. This is done when the default cipher parameters are not
-appropriate.
-For EVP_CIPH_GCM_MODE the IV will be generated internally if it is not
-specified.
+=item EVP_EncryptInit_ex()
-EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and
-writes the encrypted version to B<out>. 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.
+Is a legacy function similiar to EVP_EncryptInit_ex2() except If I<impl>
+is non-NULL, its implementation of the cipher B<type> is used if there is one,
+and if not, the default implementation is used.
+
+=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
+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 - 1) bytes.
For wrap cipher 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, B<out> should contain sufficient room for the operation being performed.
-The actual number of bytes written is placed in B<outl>. It also
-checks if B<in> and B<out> are partially overlapping, and if they are
+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.
If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
data and it will return an error if any data remains in a partial block:
that is if the total data length is not a multiple of the block size.
-EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate()
-and EVP_DecryptFinal_ex() are the corresponding decryption
-operations. EVP_DecryptFinal() will return an error code if padding is
-enabled and the final block is not correctly formatted. The parameters
-and restrictions are identical to the encryption operations except
-that if padding is enabled the decrypted data buffer B<out> passed
-to EVP_DecryptUpdate() should have sufficient room for (B<inl> +
-cipher_block_size) bytes unless the cipher block size is 1 in which case
-B<inl> bytes is sufficient.
-
-EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and
-EVP_CipherFinal_ex() are functions that can be used for decryption or
-encryption. The operation 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_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
+=item EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate()
+and EVP_DecryptFinal_ex()
+
+These functions are the corresponding decryption operations.
+EVP_DecryptFinal() will return an error code if padding is enabled and the
+final block is not correctly formatted. The parameters and restrictions are
+identical to the encryption operations except that if padding is enabled the
+decrypted data buffer I<out> passed to EVP_DecryptUpdate() should have
+sufficient room for (I<inl> + cipher_block_size) bytes unless the cipher block
+size is 1 in which case I<inl> bytes is sufficient.
+
+=item EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and
+EVP_CipherFinal_ex()
+
+These functions that can be used for decryption or encryption. The operation
+performed depends on the value of the I<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).
+
+=item EVP_CIPHER_CTX_reset()
+
+Clears all information from a cipher context and free up any allocated memory
+associated with it, except the I<ctx> itself. This function should be called
+anytime I<ctx> is to be reused for another
+EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal() series of calls.
+
+=item EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit()
+
+Behave in a similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and
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
+=item EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal()
+
+Identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
EVP_CipherFinal_ex(). In previous releases they also cleaned up
-the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean()
+the I<ctx>, but this is no longer done and EVP_CIPHER_CTX_cleanup()
must be called to free any context resources.
-EVP_Cipher() encrypts or decrypts a maximum I<inl> amount of bytes from
-I<in> and leaves the result in I<out>.
+=item EVP_Cipher()
+
+Encrypts or decrypts a maximum I<inl> amount of bytes from I<in> and leaves the
+result in I<out>.
If the cipher doesn't have the flag B<EVP_CIPH_FLAG_CUSTOM_CIPHER> set,
then I<inl> must be a multiple of EVP_CIPHER_block_size(). If it isn't,
the result is undefined. If the cipher has that flag set, then I<inl>
This function is historic and shouldn't be used in an application, please
consider using EVP_CipherUpdate() and EVP_CipherFinal_ex instead.
-EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
-return an EVP_CIPHER structure when passed a cipher name, a NID or an
+=item EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()
+
+Return an EVP_CIPHER structure when passed a cipher name, a NID or an
ASN1_OBJECT structure.
-EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() 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.
-
-EVP_CIPHER_CTX_set_padding() enables or disables padding. This
-function should be called after the context is set up for encryption
-or decryption with EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2() or
-EVP_CipherInit_ex2(). By default encryption operations are padded using
-standard block padding and the padding is checked and removed when
-decrypting. If the B<pad> parameter is zero then no padding is
+=item EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid()
+
+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.
+
+=item EVP_CIPHER_CTX_set_padding()
+
+Enables or disables padding. This function should be called after the context
+is set up for encryption or decryption with EVP_EncryptInit_ex2(),
+EVP_DecryptInit_ex2() or EVP_CipherInit_ex2(). By default encryption operations
+are padded using standard block padding and the padding is checked and removed
+when decrypting. If the B<pad> parameter is zero then no padding is
performed, the total amount of data encrypted or decrypted must then
be a multiple of the block size or an error will occur.
-EVP_CIPHER_get_params() retrieves the requested list of algorithm
-B<params> from a B<cipher>.
-
-EVP_CIPHER_CTX_set_params() Sets the list of operation B<params> into a CIPHER
-context B<ctx>.
-
-EVP_CIPHER_CTX_get_params() retrieves the requested list of operation
-B<params> from CIPHER context B<ctx>.
-
-EVP_CIPHER_gettable_params() returns an B<OSSL_PARAM> array that describes
-the retrievable and settable parameters. EVP_CIPHER_gettable_params()
-returns 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.
-
-EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params()
-return constant B<OSSL_PARAM> arrays that describe 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.
-
-EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params()
-return constant B<OSSL_PARAM> arrays that describe the settable
-parameters that can be used with EVP_CIPHER_CTX_set_params().
-EVP_CIPHER_settable_ctx_params() returns the parameters that can be
-retrieved from the algorithm, whereas EVP_CIPHER_CTX_settable_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_key_length() and EVP_CIPHER_CTX_key_length()
-EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key
-length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>
-structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length
-for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a
-given cipher, the value of EVP_CIPHER_CTX_key_length() may be different
-for variable key length ciphers.
+Return the key length of a cipher when passed an B<EVP_CIPHER> or
+B<EVP_CIPHER_CTX> structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum
+key length for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for
+a given cipher, the value of EVP_CIPHER_CTX_key_length() may be different for
+variable key length ciphers.
-EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
+=item EVP_CIPHER_CTX_set_key_length()
+
+Sets the key length of the cipher ctx.
If the cipher is a fixed length cipher then attempting to set the key
length to any value other than the fixed value is an error.
-EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_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.
+=item EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length()
-EVP_CIPHER_CTX_tag_length() returns the tag length of a AEAD cipher when passed
-a B<EVP_CIPHER_CTX>. It will return zero if the cipher does not support a tag.
-It returns a default value if the tag length has not been set.
+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.
-EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() 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.
-
-EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed
-cipher or context. This "type" is the actual NID of the cipher OBJECT
-IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and
-128 bit RC2 have the same NID. If the cipher does not have an object
-identifier or does not have ASN1 support this function will return
+=item EVP_CIPHER_CTX_tag_length()
+
+Returns the tag length of a AEAD cipher when passed a B<EVP_CIPHER_CTX>. It will
+return zero if the cipher does not support a tag. It returns a default value if
+the tag length has not been set.
+
+=item EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size()
+
+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.
+
+=item EVP_CIPHER_type() and EVP_CIPHER_CTX_type()
+
+Return the type of the passed cipher or context. This "type" is the actual NID
+of the cipher OBJECT IDENTIFIER as such it ignores the cipher parameters and
+40 bit RC2 and 128 bit RC2 have the same NID. If the cipher does not have an
+object identifier or does not have ASN1 support this function will return
B<NID_undef>.
-EVP_CIPHER_is_a() returns 1 if I<cipher> is an implementation of an
-algorithm that's identifiable with I<name>, otherwise 0.
-If I<cipher> is a legacy cipher (it's the return value from the likes
-of EVP_aes128() rather than the result of an EVP_CIPHER_fetch()), only
-cipher names registered with the default library context (see
-L<OSSL_LIB_CTX(3)>) will be considered.
+=item EVP_CIPHER_is_a()
+
+Returns 1 if I<cipher> is an implementation of an algorithm that's identifiable
+with I<name>, otherwise 0. If I<cipher> is a legacy cipher (it's the return
+value from the likes of EVP_aes128() rather than the result of an
+EVP_CIPHER_fetch()), only cipher names registered with the default library
+context (see L<OSSL_LIB_CTX(3)>) will be considered.
+
+=item EVP_CIPHER_number()
+
+Returns the internal dynamic number assigned to the I<cipher>. This is only
+useful with fetched B<EVP_CIPHER>s.
+
+=item EVP_CIPHER_name() and EVP_CIPHER_CTX_name()
-EVP_CIPHER_number() returns the internal dynamic number assigned to
-the I<cipher>. This is only useful with fetched B<EVP_CIPHER>s.
+Return the name of the passed cipher or context. For fetched ciphers with
+multiple names, only one of them is returned; it's recommended to use
+EVP_CIPHER_names_do_all() instead.
-EVP_CIPHER_name() and EVP_CIPHER_CTX_name() return the name of the passed
-cipher or context. For fetched ciphers with multiple names, only one
-of them is returned; it's recommended to use EVP_CIPHER_names_do_all()
-instead.
+=item EVP_CIPHER_names_do_all()
-EVP_CIPHER_names_do_all() traverses all names for the I<cipher>, and
-calls I<fn> with each name and I<data>. This is only useful with
-fetched B<EVP_CIPHER>s.
+Traverses all names for the I<cipher>, and calls I<fn> with each name and
+I<data>. This is only useful with fetched B<EVP_CIPHER>s.
-EVP_CIPHER_description() returns a description of the cipher, meant for
-display and human consumption. The description is at the discretion of the
-cipher implementation.
+=item EVP_CIPHER_description()
-EVP_CIPHER_provider() returns an B<OSSL_PROVIDER> pointer to the provider
-that implements the given B<EVP_CIPHER>.
+Returns a description of the cipher, meant for display and human consumption.
+The description is at the discretion of the cipher implementation.
-EVP_CIPHER_CTX_get0_cipher() returns the B<EVP_CIPHER> structure when passed
-an B<EVP_CIPHER_CTX> structure.
+=item EVP_CIPHER_provider()
+
+Returns an B<OSSL_PROVIDER> pointer to the provider that implements the given
+B<EVP_CIPHER>.
+
+=item EVP_CIPHER_CTX_get0_cipher()
+
+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.
-EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode:
+=item 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, EVP_CIPH_OFB_MODE,
EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE,
-EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE or EVP_CIPH_SIV_MODE. If the cipher is a
-stream cipher then EVP_CIPH_STREAM_CIPHER is returned.
-
-EVP_CIPHER_flags() returns any flags associated with the cipher. See
-EVP_CIPHER_meth_set_flags() for a list of currently defined flags.
-
-EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based
-on the passed cipher. This will 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.
-
-EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1
-AlgorithmIdentifier "parameter". The precise effect depends on the cipher
-In the case of RC2, for example, it will set the IV and effective key length.
+EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE or EVP_CIPH_SIV_MODE.
+If the cipher is a stream cipher then EVP_CIPH_STREAM_CIPHER is returned.
+
+=item EVP_CIPHER_flags()
+
+Returns any flags associated with the cipher. See EVP_CIPHER_meth_set_flags()
+for a list of currently defined flags.
+
+=item EVP_CIPHER_param_to_asn1()
+
+Sets the AlgorithmIdentifier "parameter" based on the passed cipher. This will
+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.
+
+=item EVP_CIPHER_asn1_to_param()
+
+Sets the cipher parameters based on an ASN1 AlgorithmIdentifier "parameter".
+The precise effect depends on the cipher. In the case of B<RC2>, for example,
+it will set the IV and effective key length.
This function should be called after the base cipher type is set but before
the key is set. For example EVP_CipherInit() will be called with the IV and
key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally
or the parameters cannot be set (for example the RC2 effective key length
is not supported.
-EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
-and set.
+=item EVP_CIPHER_CTX_rand_key()
+
+Generates a random key of the appropriate length based on the cipher context.
+The B<EVP_CIPHER> can provide its own random key generation routine to support
+keys of a specific form. I<Key> must point to a buffer at least as big as the
+value returned by EVP_CIPHER_CTX_key_length().
+
+=item EVP_CIPHER_do_all_provided()
+
+Traverses all ciphers implemented by all activated providers in the given
+library context I<libctx>, and for each of the implementations, calls the given
+function I<fn> with the implementation method and the given I<arg> as argument.
+
+=back
+
+=head1 PARAMETERS
+
+See L<OSSL_PARAM(3)> for information about passing parameters.
+
+=head2 Gettable EVP_CIPHER parameters
+
+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:
+
+=over 4
+
+=item "mode" (B<OSSL_CIPHER_PARAM_MODE>) <unsigned integer>
+
+Gets the mode for the associated cipher algorithm I<cipher>.
+See L</EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode()> for a list of valid modes.
+Use EVP_CIPHER_mode() to retrieve the cached value.
+
+=item "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>) <unsigned integer>
+
+Gets the key length for the associated cipher algorithm I<cipher>.
+Use EVP_CIPHER_key_length() to retrieve the cached value.
+
+=item "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>) <unsigned integer>
+
+Gets the IV length for the associated cipher algorithm I<cipher>.
+Use EVP_CIPHER_iv_length() to retrieve the cached value.
+
+=item "blocksize" (B<OSSL_CIPHER_PARAM_BLOCK_SIZE>) <unsigned integer>
+
+Gets the block size for the associated cipher algorithm I<cipher>.
+The block size should be 1 for stream ciphers.
+Note that the block size for a cipher may be different to the block size for
+the underlying encryption/decryption primitive.
+For example AES in CTR mode has a block size of 1 (because it operates like a
+stream cipher), even though AES has a block size of 16.
+Use EVP_CIPHER_block_size() to retreive the cached value.
+
+=item "aead" (B<OSSL_CIPHER_PARAM_AEAD>) <integer>
+
+Gets 1 if this is an AEAD cipher algorithm, otherwise it gets 0.
+Use (EVP_CIPHER_flags(cipher) & EVP_CIPH_FLAG_AEAD_CIPHER) to retrieve the
+cached value.
+
+=item "custom-iv" (B<OSSL_CIPHER_PARAM_CUSTOM_IV>) <integer>
+
+Gets 1 if the cipher algorithm I<cipher> has a custom IV, otherwise it gets 0.
+Storing and initializing the IV is left entirely to the implementation, if a
+custom IV is used.
+Use (EVP_CIPHER_flags(cipher) & EVP_CIPH_CUSTOM_IV) to retrieve the
+cached value.
+
+=item "cts" (B<OSSL_CIPHER_PARAM_CTS>) <integer>
+
+Gets 1 if the cipher algorithm I<cipher> uses ciphertext stealing,
+otherwise it gets 0.
+This is currently used to indicate that the cipher is a one shot that only
+allows a single call to EVP_CipherUpdate().
+Use (EVP_CIPHER_flags(cipher) & EVP_CIPH_FLAG_CTS) to retrieve the
+cached value.
+
+=item "tls-multi" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK>) <integer>
+
+Gets 1 if the cipher algorithm I<cipher> supports interleaving of crypto blocks,
+otherwise it gets 0. The interleaving is an optimization only applicable to certain
+TLS ciphers.
+Use (EVP_CIPHER_flags(cipher) & EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK) to retrieve the
+cached value.
+
+=back
+
+=head2 Gettable and Settable EVP_CIPHER_CTX parameters
+
+The following OSSL_PARAM keys can be used with both EVP_CIPHER_CTX_get_params()
+and EVP_CIPHER_CTX_set_params().
+
+=over 4
+
+=item "padding" (B<OSSL_CIPHER_PARAM_PADDING>) <unsigned integer>
+
+Gets or sets the padding mode for the cipher context I<ctx>.
+Padding is enabled if the value is 1, and disabled if the value is 0.
+See also EVP_CIPHER_CTX_set_padding().
+
+=item "num" (B<OSSL_CIPHER_PARAM_NUM>) <unsigned integer>
+
+Gets or sets the cipher specific "num" parameter for the cipher context I<ctx>.
+Built-in ciphers typically use this to track how much of the current underlying
+block has been "used" already.
+See also EVP_CIPHER_CTX_num() and EVP_CIPHER_CTX_set_num().
+
+=item "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>) <unsigned integer>
+
+Gets or sets the key length for the cipher context I<ctx>.
+The length of the "keylen" parameter should not exceed that of a B<size_t>.
+See also EVP_CIPHER_CTX_key_length() and EVP_CIPHER_CTX_set_key_length().
+
+=item "tag" (B<OSSL_CIPHER_PARAM_AEAD_TAG>) <octet string>
+
+Gets or sets the AEAD tag for the associated cipher context I<ctx>.
+See L<EVP_EncryptInit(3)/AEAD Interface>.
+
+=item "keybits" (B<OSSL_CIPHER_PARAM_RC2_KEYBITS>) <unsigned integer>
+
+Gets or sets the effective keybits used for a RC2 cipher.
+The length of the "keybits" parameter should not exceed that of a B<size_t>.
+
+=item "rounds" (B<OSSL_CIPHER_PARAM_ROUNDS>) <unsigned integer>
+
+Gets or sets the number of rounds to be used for a cipher.
+This is used by the RC5 cipher.
+
+=item "alg_id_param" (B<OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS>) <octet string>
+
+Used to pass the DER encoded AlgorithmIdentifier parameter to or from
+the cipher implementation. Functions like L<EVP_CIPHER_param_to_asn1(3)>
+and L<EVP_CIPHER_asn1_to_param(3)> use this parameter for any implementation
+that has the flag B<EVP_CIPH_FLAG_CUSTOM_ASN1> 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().
+=item "cts_mode" (B<OSSL_CIPHER_PARAM_CTS_MODE>) <UTF8 string>
-EVP_CIPHER_do_all_provided() traverses all ciphers implemented by all activated
-providers in the given library context I<libctx>, and for each of the
-implementations, calls the given function I<fn> with the implementation method
-and the given I<arg> as argument.
+Gets or sets the cipher text stealing mode. For all modes the output size is the
+same as the input size.
+
+Valid values for the mode are:
+
+=over 4
+
+=item "CS1"
+
+The NIST variant of cipher text stealing.
+For message lengths that are multiples of the block size it is equivalent to
+using a "AES-CBC" cipher otherwise the second last cipher text block is a
+partial block.
+
+=item "CS2"
+
+For message lengths that are multiples of the block size it is equivalent to
+using a "AES-CBC" cipher, otherwise it is the same as "CS3".
+
+=item "CS3"
+
+The Kerberos5 variant of cipher text stealing which always swaps the last
+cipher text block with the previous block (which may be a partial or full block
+depending on the input length).
+
+=back
+
+The default is "CS1".
+This is only supported for "AES-128-CBC-CTS", "AES-192-CBC-CTS" and "AES-256-CBC-CTS".
+
+=item "tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>) <unsigned integer>
+
+Sets or gets the number of records being sent in one go for a tls1 multiblock
+cipher operation (either 4 or 8 records).
+
+=back
+
+=head2 Gettable EVP_CIPHER_CTX parameters
+
+The following OSSL_PARAM keys can be used with EVP_CIPHER_CTX_get_params():
+
+=over 4
+
+=item "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN> and <B<OSSL_CIPHER_PARAM_AEAD_IVLEN>) <unsigned integer>
+
+Gets the IV length for the cipher context I<ctx>.
+The length of the "ivlen" parameter should not exceed that of a B<size_t>.
+See also EVP_CIPHER_CTX_iv_length().
+
+=item "iv" (B<OSSL_CIPHER_PARAM_IV>) <octet string OR octet ptr>
+
+Gets the IV used to initialize the associated cipher context I<ctx>.
+See also EVP_CIPHER_CTX_get_original_iv().
+
+=item "updated-iv" (B<OSSL_CIPHER_PARAM_UPDATED_IV>) <octet string OR octet ptr>
+
+Gets the updated pseudo-IV state for the associated cipher ctx, e.g.,
+the previous ciphertext block for CBC mode or the iteratively encrypted IV
+value for OFB mode. Note that octet pointer access is deprecated and is
+provided only for backwards compatibility with historical libcrypto APIs.
+See also EVP_CIPHER_CTX_get_updated_iv().
+
+=item "randkey" (B<OSSL_CIPHER_PARAM_RANDOM_KEY>) <octet string>
+
+Gets a implementation specific randomly generated key for the associated
+cipher ctx I(ctx>. This is currently only supported by 3DES (which sets the key to
+odd parity).
+
+=item "taglen" (B<OSSL_CIPHER_PARAM_AEAD_TAGLEN>) <unsigned integer>
+
+Gets the tag length to be used for an AEAD cipher for the associated cipher ctx
+I<ctx>. It gets a default value if it has not been set.
+The length of the "taglen" parameter should not exceed that of a B<size_t>.
+See also EVP_CIPHER_CTX_tag_length().
+
+=item "tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD>) <unsigned integer>
+
+Gets the length of the tag that will be added to a TLS record for the AEAD
+tag for the associated cipher ctx I<ctx>.
+The length of the "tlsaadpad" parameter should not exceed that of a B<size_t>.
+
+=item "tlsivgen" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN>) <octet string>
+
+Gets the invocation field generated for encryption.
+Can only be called after "tlsivfixed" is set.
+This is only used for GCM mode.
+
+=item "tls1multi_enclen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN>) <unsigned integer>
+
+Get the total length of the record returned from the "tls1multi_enc" operation.
+
+=item "tls1multi_maxbufsz" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE>) <unsigned integer>
+
+Gets the maximum record length for a tls1 multiblock cipher operation.
+The length of the "tls1multi_maxbufsz" parameter should not exceed that of a B<size_t>.
+
+=item "tls1multi_aadpacklen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN>) <unsigned integer>
+
+Gets the result of running the "tls1multi_aad" operation.
+
+=item "tls-mac" (B<OSSL_CIPHER_PARAM_TLS_MAC>) <octet ptr>
+
+Used to pass the tls mac data.
+
+=back
+
+=head2 Settable EVP_CIPHER_CTX parameters
+
+The following OSSL_PARAM keys can be used with EVP_CIPHER_CTX_set_params():
+
+=over 4
+
+=item "mackey" (B<OSSL_CIPHER_PARAM_AEAD_MAC_KEY>) <octet string>
+
+Sets the MAC key used by composite AEAD ciphers such as AES-CBC-HMAC-SHA256.
+
+=item "speed" (B<OSSL_CIPHER_PARAM_SPEED>) <unsigned integer>
+
+Sets the speed option for the associated cipher ctx. This is only supported
+by AES SIV ciphers which disallow multiple operations by default.
+Setting "speed" to 1 allows another encrypt or decrypt operation to be
+performed. This is used for performance testing.
+
+=item "tls-version" (B<OSSL_CIPHER_PARAM_TLS_VERSION>) <integer>
+
+Sets the tls-version.
+
+=item "tls-mac-size" (B<OSSL_CIPHER_PARAM_TLS_MAC_SIZE>) <unsigned integer>
+
+Set the tls mac size.
+
+=item "tlsaad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD>) <octet string>
+
+Sets TLSv1.2 AAD information for the associated cipher ctx I<ctx>.
+TLSv1.2 AAD information is always 13 bytes in length and is as defined for the
+"additional_data" field described in section 6.2.3.3 of RFC5246.
+
+=item "tlsivfixed" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED>) <octet string>
+
+Sets the fixed portion of an IV for an AEAD cipher used in a TLS record
+encryption/ decryption for the associated cipher ctx.
+TLS record encryption/decryption always occurs "in place" so that the input and
+output buffers are always the same memory location.
+AEAD IVs in TLSv1.2 consist of an implicit "fixed" part and an explicit part
+that varies with every record.
+Setting a TLS fixed IV changes a cipher to encrypt/decrypt TLS records.
+TLS records are encrypted/decrypted using a single OSSL_FUNC_cipher_cipher call per
+record.
+For a record decryption the first bytes of the input buffer will be the explicit
+part of the IV and the final bytes of the input buffer will be the AEAD tag.
+The length of the explicit part of the IV and the tag length will depend on the
+cipher in use and will be defined in the RFC for the relevant ciphersuite.
+In order to allow for "in place" decryption the plaintext output should be
+written to the same location in the output buffer that the ciphertext payload
+was read from, i.e. immediately after the explicit IV.
+
+When encrypting a record the first bytes of the input buffer will be empty to
+allow space for the explicit IV, as will the final bytes where the tag will
+be written.
+The length of the input buffer will include the length of the explicit IV, the
+payload, and the tag bytes.
+The cipher implementation should generate the explicit IV and write it to the
+beginning of the output buffer, do "in place" encryption of the payload and
+write that to the output buffer, and finally add the tag onto the end of the
+output buffer.
+
+Whether encrypting or decrypting the value written to I<*outl> in the
+OSSL_FUNC_cipher_cipher call should be the length of the payload excluding the explicit
+IV length and the tag length.
+
+=item "tlsivinv" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV>) <octet string>
+
+Sets the invocation field used for decryption.
+Can only be called after "tlsivfixed" is set.
+This is only used for GCM mode.
+
+=item "tls1multi_enc" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC>) <octet string>
+
+Triggers a multiblock tls1 encrypt operation for a tls1 aware cipher that supports
+sending 4 or 8 records in one go.
+The cipher performs both the MAC and encrypt stages and constructs the record
+headers itself.
+"tls1multi_enc" supplies the output buffer for the encrypt operation,
+"tls1multi_encin" & "tls1multi_interleave" must also be set in order to supply
+values to the encrypt operation.
+
+=item "tls1multi_encin" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN>) <octet string>
+
+Supplies the data to encrypt for a tls1 multiblock cipher operation.
+
+=item "tls1multi_maxsndfrag" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT>) <unsigned integer>
+
+Sets the maximum send fragment size for a tls1 multiblock cipher operation.
+It must be set before using "tls1multi_maxbufsz".
+The length of the "tls1multi_maxsndfrag" parameter should not exceed that of a B<size_t>.
+
+=item "tls1multi_aad" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD>) <octet string>
+
+Sets the authenticated additional data used by a tls1 multiblock cipher operation.
+The supplied data consists of 13 bytes of record data containing:
+Bytes 0-7: The sequence number of the first record
+Byte 8: The record type
+Byte 9-10: The protocol version
+Byte 11-12: Input length (Always 0)
+
+"tls1multi_interleave" must also be set for this operation.
+
+=back
+
+=head1 CONTROLS
+
+The Mappings from EVP_CIPHER_CTX_ctrl() identifiers to PARAMETERS are listed
+in the following section. See the L</PARAMETERS> section for more details.
+
+EVP_CIPHER_CTX_ctrl() can be used to send the following standard controls:
+
+=over 4
+
+=item EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and
+EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the
+key "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>).
+
+=item EVP_CTRL_AEAD_SET_IV_FIXED
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called
+with an L<OSSL_PARAM(3)> item with the key "tlsivfixed"
+(B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED>).
+
+=item EVP_CTRL_AEAD_SET_MAC_KEY
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called
+with an L<OSSL_PARAM(3)> item with the key "mackey"
+(B<OSSL_CIPHER_PARAM_AEAD_MAC_KEY>).
+
+=item EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and
+EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the
+key "tag" (B<OSSL_CIPHER_PARAM_AEAD_TAG>).
+
+=item EVP_CTRL_CCM_SET_L
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called
+with an L<OSSL_PARAM(3)> item with the key "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>)
+with a value of (15 - L)
+
+=item EVP_CTRL_COPY
+
+There is no OSSL_PARAM mapping for this. Use EVP_CIPHER_CTX_copy() instead.
+
+=item EVP_CTRL_GCM_SET_IV_INV
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called
+with an L<OSSL_PARAM(3)> item with the key "tlsivinv"
+(B<OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV>).
+
+=item EVP_CTRL_RAND_KEY
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called
+with an L<OSSL_PARAM(3)> item with the key "randkey"
+(B<OSSL_CIPHER_PARAM_RANDOM_KEY>).
+
+=item EVP_CTRL_SET_KEY_LENGTH
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called
+with an L<OSSL_PARAM(3)> item with the key "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>).
+
+=item EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and
+EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the
+key "keybits" (B<OSSL_CIPHER_PARAM_RC2_KEYBITS>).
+
+=item EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and
+EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the
+key "rounds" (B<OSSL_CIPHER_PARAM_ROUNDS>).
+
+=item EVP_CTRL_SET_SPEED
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called
+with an L<OSSL_PARAM(3)> item with the key "speed" (B<OSSL_CIPHER_PARAM_SPEED>).
+
+=item EVP_CTRL_GCM_IV_GEN
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_get_params() gets called
+with an L<OSSL_PARAM(3)> item with the key
+"tlsivgen" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN>).
+
+=item EVP_CTRL_AEAD_TLS1_AAD
+
+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>)
+followed by EVP_CIPHER_CTX_get_params() with a key of
+"tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD>).
+
+=item EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE
+
+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 OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT
+followed by EVP_CIPHER_CTX_get_params() with a key of
+"tls1multi_maxbufsz" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE>).
+
+=item EVP_CTRL_TLS1_1_MULTIBLOCK_AAD
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() get called
+with L<OSSL_PARAM(3)> items with the keys
+"tls1multi_aad" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD>) and
+"tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>)
+followed by EVP_CIPHER_CTX_get_params() with keys of
+"tls1multi_aadpacklen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN>) and
+"tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>).
+
+=item EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT
+
+When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() get called
+with L<OSSL_PARAM(3)> items with the keys
+"tls1multi_enc" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC>),
+"tls1multi_encin" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN>) and
+"tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>),
+followed by EVP_CIPHER_CTX_get_params() with a key of
+"tls1multi_enclen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN>).
+
+=back
=head1 RETURN VALUES
If padding is disabled then the decryption operation will always succeed if
the total amount of data decrypted is a multiple of the block size.
-The functions EVP_EncryptInit(), EVP_EncryptInit_ex1(),
-EVP_EncryptFinal(), EVP_DecryptInit(), EVP_DecryptInit_ex1(),
-EVP_CipherInit(), EVP_CipherInit_ex1() and EVP_CipherFinal() are obsolete
+The functions EVP_EncryptInit(), EVP_EncryptInit_ex(),
+EVP_EncryptFinal(), EVP_DecryptInit(), EVP_DecryptInit_ex(),
+EVP_CipherInit(), EVP_CipherInit_ex() and EVP_CipherFinal() are obsolete
but are retained for compatibility with existing code. New code should
use EVP_EncryptInit_ex2(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex2(),
EVP_DecryptFinal_ex(), EVP_CipherInit_ex2() and EVP_CipherFinal_ex()
not NULL. Otherwise, they return the parameters associated with the
provider side algorithm I<provctx>.
-Parameters currently recognised by built-in ciphers are as follows. Not all
-parameters are relevant to, or are understood by all ciphers:
-
-=over 4
-
-=item "padding" (B<OSSL_CIPHER_PARAM_PADDING>) <unsigned integer>
-
-Sets the padding mode for the associated cipher ctx.
-Setting a value of 1 will turn padding on.
-Setting a value of 0 will turn padding off.
-
-=item "mode" (B<OSSL_CIPHER_PARAM_MODE>) <unsigned integer>
-
-Gets the mode for the associated cipher algorithm.
-See L<EVP_CIPHER_mode(3)> for a list of valid modes.
-
-=item "blocksize" (B<OSSL_CIPHER_PARAM_BLOCK_SIZE>) <unsigned integer>
-
-Gets the block size for the associated cipher algorithm.
-The block size should be 1 for stream ciphers.
-Note that the block size for a cipher may be different to the block size for
-the underlying encryption/decryption primitive.
-For example AES in CTR mode has a block size of 1 (because it operates like a
-stream cipher), even though AES has a block size of 16.
-The length of the "blocksize" parameter should not exceed that of a B<size_t>.
-
-=item "aead" (B<OSSL_CIPHER_PARAM_AEAD>) <integer>
-
-Gets 1 if this is an AEAD cipher algorithm, otherwise it gets 0.
-
-=item "custom-iv" (B<OSSL_CIPHER_PARAM_CUSTOM_IV>) <integer>
-
-Gets 1 if the cipher algorithm has a custom IV, otherwise it gets 0.
-Storing and initializing the IV is left entirely to the implementation, if a
-custom IV is used.
-
-=item "cts" (B<OSSL_CIPHER_PARAM_CTS>) <integer>
-
-Gets 1 if the cipher algorithm uses ciphertext stealing, otherwise it gets 0.
-This is currently used to indicate that the cipher is a one shot that only
-allows a single call to EVP_CipherUpdate().
-
-=item "tls-multi" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK>) <integer>
-
-Gets 1 if the cipher algorithm supports interleaving of crypto blocks, otherwise
-it gets 0. The interleaving is an optimization only applicable to certain
-TLS ciphers.
-
-=item "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>) <unsigned integer>
-
-Gets the key length for the associated cipher algorithm.
-This can also be used to get or set the key length for the associated cipher
-ctx.
-The length of the "keylen" parameter should not exceed that of a B<size_t>.
-
-=item "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>) <unsigned integer>
-
-Gets the IV length for the associated cipher algorithm.
-The length of the "ivlen" parameter should not exceed that of a B<size_t>.
-
-=item "iv" (B<OSSL_CIPHER_PARAM_IV>) <octet string OR octet ptr>
-
-Gets the IV used to initialize the associated cipher ctx.
-
-=item "updated-iv" (B<OSSL_CIPHER_PARAM_UPDATED_IV>) <octet string OR octet ptr>
-
-Gets the updated pseudo-IV state for the associated cipher ctx, e.g.,
-the previous ciphertext block for CBC mode or the iteratively encrypted IV
-value for OFB mode. Note that octet pointer access is deprecated and is
-provided only for backwards compatibility with historical libcrypto APIs.
-
-=item "num" (B<OSSL_CIPHER_PARAM_NUM>) <unsigned integer>
-
-Gets or sets the cipher specific "num" parameter for the associated cipher ctx.
-Built-in ciphers typically use this to track how much of the current underlying
-block has been "used" already.
-
-=item "tag" (B<OSSL_CIPHER_PARAM_AEAD_TAG>) <octet string>
-
-Gets or sets the AEAD tag for the associated cipher ctx.
-See L<EVP_EncryptInit(3)/AEAD Interface>.
-
-=item "taglen" (B<OSSL_CIPHER_PARAM_AEAD_TAGLEN>) <unsigned integer>
-
-Gets the tag length to be used for an AEAD cipher for the associated cipher ctx.
-It gets a default value if it has not been set.
-The length of the "taglen" parameter should not exceed that of a B<size_t>.
-
-=item "tlsaad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD>) <octet string>
-
-Sets TLSv1.2 AAD information for the associated cipher ctx.
-TLSv1.2 AAD information is always 13 bytes in length and is as defined for the
-"additional_data" field described in section 6.2.3.3 of RFC5246.
-
-=item "tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD>) <unsigned integer>
-
-Gets the length of the tag that will be added to a TLS record for the AEAD
-tag for the associated cipher ctx.
-The length of the "tlsaadpad" parameter should not exceed that of a B<size_t>.
-
-=item "tlsivfixed" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED>) <octet string>
-
-Sets the fixed portion of an IV for an AEAD cipher used in a TLS record
-encryption/ decryption for the associated cipher ctx.
-TLS record encryption/decryption always occurs "in place" so that the input and
-output buffers are always the same memory location.
-AEAD IVs in TLSv1.2 consist of an implicit "fixed" part and an explicit part
-that varies with every record.
-Setting a TLS fixed IV changes a cipher to encrypt/decrypt TLS records.
-TLS records are encrypted/decrypted using a single OSSL_FUNC_cipher_cipher call per
-record.
-For a record decryption the first bytes of the input buffer will be the explicit
-part of the IV and the final bytes of the input buffer will be the AEAD tag.
-The length of the explicit part of the IV and the tag length will depend on the
-cipher in use and will be defined in the RFC for the relevant ciphersuite.
-In order to allow for "in place" decryption the plaintext output should be
-written to the same location in the output buffer that the ciphertext payload
-was read from, i.e. immediately after the explicit IV.
-
-When encrypting a record the first bytes of the input buffer will be empty to
-allow space for the explicit IV, as will the final bytes where the tag will
-be written.
-The length of the input buffer will include the length of the explicit IV, the
-payload, and the tag bytes.
-The cipher implementation should generate the explicit IV and write it to the
-beginning of the output buffer, do "in place" encryption of the payload and
-write that to the output buffer, and finally add the tag onto the end of the
-output buffer.
-
-Whether encrypting or decrypting the value written to I<*outl> in the
-OSSL_FUNC_cipher_cipher call should be the length of the payload excluding the explicit
-IV length and the tag length.
-
-=item "ivlen" (B<OSSL_CIPHER_PARAM_AEAD_IVLEN>) <unsigned integer>
-
-Sets the IV length to be used for an AEAD cipher for the associated cipher ctx.
-The length of the "ivlen" parameter should not exceed that of a B<size_t>.
-
-=item "mackey" (B<OSSL_CIPHER_PARAM_AEAD_MAC_KEY>) <octet string>
-
-Sets the MAC key used by composite AEAD ciphers such as AES-CBC-HMAC-SHA256.
-
-=item "randkey" (B<OSSL_CIPHER_PARAM_RANDOM_KEY>) <octet string>
-
-Gets a implementation specific randomly generated key for the associated
-cipher ctx. This is currently only supported by 3DES (which sets the key to
-odd parity).
-
-=item "alg_id_param" (B<OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS>) <octet string>
-
-Used to pass the DER encoded AlgorithmIdentifier parameter to or from
-the cipher implementation. Functions like L<EVP_CIPHER_param_to_asn1(3)>
-and L<EVP_CIPHER_asn1_to_param(3)> use this parameter for any implementation
-that has the flag B<EVP_CIPH_FLAG_CUSTOM_ASN1> set.
-
-=item "rounds" (B<OSSL_CIPHER_PARAM_ROUNDS>) <unsigned integer>
-
-Sets or gets the number of rounds to be used for a cipher.
-This is used by the RC5 cipher.
-
-=item "keybits" (B<OSSL_CIPHER_PARAM_RC2_KEYBITS>) <unsigned integer>
-
-Gets or sets the effective keybits used for a RC2 cipher.
-The length of the "keybits" parameter should not exceed that of a B<size_t>.
-
-=item "speed" (B<OSSL_CIPHER_PARAM_SPEED>) <unsigned integer>
-
-Sets the speed option for the associated cipher ctx. This is only supported
-by AES SIV ciphers which disallow multiple operations by default.
-Setting "speed" to 1 allows another encrypt or decrypt operation to be
-performed. This is used for performance testing.
-
-=item "tlsivgen" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN>) <octet string>
-
-Gets the invocation field generated for encryption.
-Can only be called after "tlsivfixed" is set.
-This is only used for GCM mode.
-
-=item "tlsivinv" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV>) <octet string>
-
-Sets the invocation field used for decryption.
-Can only be called after "tlsivfixed" is set.
-This is only used for GCM mode.
-
-=item "tls1multi_enc" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC>) <octet string>
-
-Triggers a multiblock tls1 encrypt operation for a tls1 aware cipher that supports
-sending 4 or 8 records in one go.
-The cipher performs both the MAC and encrypt stages and constructs the record
-headers itself.
-"tls1multi_enc" supplies the output buffer for the encrypt operation,
-"tls1multi_encin" & "tls1multi_interleave" must also be set in order to supply
-values to the encrypt operation.
-
-=item "tls1multi_enclen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN>) <unsigned integer>
-
-Get the total length of the record returned from the "tls1multi_enc" operation.
-
-=item "tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>) <unsigned integer>
-
-Sets or gets the number of records being sent in one go for a tls1 multiblock
-cipher operation (either 4 or 8 records).
-
-=item "tls1multi_encin" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN>) <octet string>
-
-Supplies the data to encrypt for a tls1 multiblock cipher operation.
-
-=item "tls1multi_maxsndfrag" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT>) <unsigned integer>
-
-Sets the maximum send fragment size for a tls1 multiblock cipher operation.
-It must be set before using "tls1multi_maxbufsz".
-The length of the "tls1multi_maxsndfrag" parameter should not exceed that of a B<size_t>.
-
-=item "tls1multi_maxbufsz" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE>) <unsigned integer>
-
-Gets the maximum record length for a tls1 multiblock cipher operation.
-The length of the "tls1multi_maxbufsz" parameter should not exceed that of a B<size_t>.
-
-=item "tls1multi_aad" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD>) <octet string>
-
-Sets the authenticated additional data used by a tls1 multiblock cipher operation.
-The supplied data consists of 13 bytes of record data containing:
-Bytes 0-7: The sequence number of the first record
-Byte 8: The record type
-Byte 9-10: The protocol version
-Byte 11-12: Input length (Always 0)
-
-"tls1multi_interleave" must also be set for this operation.
-
-=item "tls1multi_aadpacklen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN>) <unsigned integer>
-
-Gets the result of running the "tls1multi_aad" operation.
-
-=item "cts_mode" (B<OSSL_CIPHER_PARAM_CTS_MODE>) <UTF8 string>
-
-Sets the cipher text stealing mode. For all modes the output size is the same as
-the input size.
-
-Valid values for the mode are:
-
-=over 4
-
-=item "CS1"
-
-The NIST variant of cipher text stealing.
-For message lengths that are multiples of the block size it is equivalent to
-using a "AES-CBC" cipher otherwise the second last cipher text block is a
-partial block.
-
-=item "CS2"
-
-For message lengths that are multiples of the block size it is equivalent to
-using a "AES-CBC" cipher, otherwise it is the same as "CS3".
-
-=item "CS3"
-
-The Kerberos5 variant of cipher text stealing which always swaps the last
-cipher text block with the previous block (which may be a partial or full block
-depending on the input length).
-
-=back
-
-The default is "CS1".
-This is only supported for "AES-128-CBC-CTS", "AES-192-CBC-CTS" and "AES-256-CBC-CTS".
-
-=back
+Parameters currently recognised by built-in ciphers are listed in
+L<EVP_EncryptInit(3)/PARAMETERS>.
+Not all parameters are relevant to, or are understood by all ciphers:
=head1 RETURN VALUES
=head1 SEE ALSO
-L<provider(7)>
+L<provider(7)>, L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-default(7)>,
+L<OSSL_PROVIDER-legacy(7)>
=head1 HISTORY
projects / openssl.git / commitdiff