mirror of
https://github.com/openssl/openssl.git
synced 2025-01-30 14:01:55 +08:00
EVP_CIPHER Documentation updates
EVP_EncryptInit.pod now follows the pattern used in EVP_DigestInit.pod. i.e. '=item' is used for methods PARAMETERS and CONTROLS sections have been added. The PARAMETERS list has been moved from provider-cipher.pod (this file just has a link now). Missing fields were updated. The CONTROLS shows the mappings to OSSL_PARAM keys. Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/15416)
This commit is contained in:
Shane Lontis
Tomas Mraz
parent
29253e1e87
commit
97aede6846
@ -132,7 +132,7 @@ EVP_CIPHER_do_all_provided
|
||||
|
||||
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);
|
||||
@ -197,70 +197,132 @@ symmetric ciphers.
|
||||
|
||||
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.
|
||||
|
||||
EVP_CIPHER_free() decrements the reference count for the B<EVP_CIPHER>
|
||||
structure.
|
||||
=item EVP_CIPHER_up_ref()
|
||||
|
||||
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()
|
||||
|
||||
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.
|
||||
Allocates and returns a cipher context.
|
||||
|
||||
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_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()
|
||||
|
||||
Retrieves the requested list of algorithm I<params> from a CIPHER I<cipher>.
|
||||
See L</PARAMETERS> below for more information.
|
||||
|
||||
=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
|
||||
@ -276,41 +338,48 @@ If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more
|
||||
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.
|
||||
=item EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate()
|
||||
and EVP_DecryptFinal_ex()
|
||||
|
||||
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).
|
||||
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.
|
||||
|
||||
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.
|
||||
=item EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and
|
||||
EVP_CipherFinal_ex()
|
||||
|
||||
EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
|
||||
similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and
|
||||
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>
|
||||
@ -318,138 +387,133 @@ can be any size.
|
||||
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.
|
||||
=item EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid()
|
||||
|
||||
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
|
||||
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>.
|
||||
=item EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length()
|
||||
|
||||
EVP_CIPHER_CTX_set_params() Sets the list of operation B<params> into a CIPHER
|
||||
context B<ctx>.
|
||||
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_get_params() retrieves the requested list of operation
|
||||
B<params> from CIPHER context B<ctx>.
|
||||
=item EVP_CIPHER_CTX_set_key_length()
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx.
|
||||
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.
|
||||
=item EVP_CIPHER_CTX_tag_length()
|
||||
|
||||
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
|
||||
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()
|
||||
|
||||
EVP_CIPHER_number() returns the internal dynamic number assigned to
|
||||
the I<cipher>. This is only useful with fetched B<EVP_CIPHER>s.
|
||||
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.
|
||||
|
||||
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_number()
|
||||
|
||||
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.
|
||||
Returns the internal dynamic number assigned to the I<cipher>. 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_name() and EVP_CIPHER_CTX_name()
|
||||
|
||||
EVP_CIPHER_provider() returns an B<OSSL_PROVIDER> pointer to the provider
|
||||
that implements the given B<EVP_CIPHER>.
|
||||
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_CTX_get0_cipher() returns the B<EVP_CIPHER> structure when passed
|
||||
an B<EVP_CIPHER_CTX> structure.
|
||||
=item 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.
|
||||
|
||||
=item 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_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_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.
|
||||
=item EVP_CIPHER_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.
|
||||
Returns any flags associated with the cipher. See EVP_CIPHER_meth_set_flags()
|
||||
for a list of currently defined flags.
|
||||
|
||||
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.
|
||||
=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
|
||||
@ -458,18 +522,472 @@ possible for this function to fail if the cipher does not have any ASN1 support
|
||||
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()
|
||||
|
||||
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().
|
||||
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().
|
||||
|
||||
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.
|
||||
=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.
|
||||
|
||||
=item "cts_mode" (B<OSSL_CIPHER_PARAM_CTS_MODE>) <UTF8 string>
|
||||
|
||||
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
|
||||
|
||||
@ -737,9 +1255,9 @@ the input data earlier on will not produce a final decrypt error.
|
||||
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()
|
||||
|
||||
@ -202,272 +202,9 @@ with the provider side context I<cctx> in its current state if it is
|
||||
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
|
||||
|
||||
@ -485,7 +222,8 @@ array, or NULL if none is offered.
|
||||
|
||||
=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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user