diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EVP_EncryptInit.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/EVP_EncryptInit.3 | 1387 |
1 files changed, 1191 insertions, 196 deletions
diff --git a/secure/lib/libcrypto/man/man3/EVP_EncryptInit.3 b/secure/lib/libcrypto/man/man3/EVP_EncryptInit.3 index 7aaae7f60908..773d049ab9b0 100644 --- a/secure/lib/libcrypto/man/man3/EVP_EncryptInit.3 +++ b/secure/lib/libcrypto/man/man3/EVP_EncryptInit.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .rr rF -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ @@ -132,37 +130,142 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "EVP_ENCRYPTINIT 3" -.TH EVP_ENCRYPTINIT 3 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "EVP_ENCRYPTINIT 3ossl" +.TH EVP_ENCRYPTINIT 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free, EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate, EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate, EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_EncryptInit, EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname, EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid, EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, EVP_CIPHER_CTX_set_padding, EVP_enc_null \&\- EVP cipher routines +EVP_CIPHER_fetch, +EVP_CIPHER_up_ref, +EVP_CIPHER_free, +EVP_CIPHER_CTX_new, +EVP_CIPHER_CTX_reset, +EVP_CIPHER_CTX_free, +EVP_EncryptInit_ex, +EVP_EncryptInit_ex2, +EVP_EncryptUpdate, +EVP_EncryptFinal_ex, +EVP_DecryptInit_ex, +EVP_DecryptInit_ex2, +EVP_DecryptUpdate, +EVP_DecryptFinal_ex, +EVP_CipherInit_ex, +EVP_CipherInit_ex2, +EVP_CipherUpdate, +EVP_CipherFinal_ex, +EVP_CIPHER_CTX_set_key_length, +EVP_CIPHER_CTX_ctrl, +EVP_EncryptInit, +EVP_EncryptFinal, +EVP_DecryptInit, +EVP_DecryptFinal, +EVP_CipherInit, +EVP_CipherFinal, +EVP_Cipher, +EVP_get_cipherbyname, +EVP_get_cipherbynid, +EVP_get_cipherbyobj, +EVP_CIPHER_is_a, +EVP_CIPHER_get0_name, +EVP_CIPHER_get0_description, +EVP_CIPHER_names_do_all, +EVP_CIPHER_get0_provider, +EVP_CIPHER_get_nid, +EVP_CIPHER_get_params, +EVP_CIPHER_gettable_params, +EVP_CIPHER_get_block_size, +EVP_CIPHER_get_key_length, +EVP_CIPHER_get_iv_length, +EVP_CIPHER_get_flags, +EVP_CIPHER_get_mode, +EVP_CIPHER_get_type, +EVP_CIPHER_CTX_cipher, +EVP_CIPHER_CTX_get0_cipher, +EVP_CIPHER_CTX_get1_cipher, +EVP_CIPHER_CTX_get0_name, +EVP_CIPHER_CTX_get_nid, +EVP_CIPHER_CTX_get_params, +EVP_CIPHER_gettable_ctx_params, +EVP_CIPHER_CTX_gettable_params, +EVP_CIPHER_CTX_set_params, +EVP_CIPHER_settable_ctx_params, +EVP_CIPHER_CTX_settable_params, +EVP_CIPHER_CTX_get_block_size, +EVP_CIPHER_CTX_get_key_length, +EVP_CIPHER_CTX_get_iv_length, +EVP_CIPHER_CTX_get_tag_length, +EVP_CIPHER_CTX_get_app_data, +EVP_CIPHER_CTX_set_app_data, +EVP_CIPHER_CTX_flags, +EVP_CIPHER_CTX_set_flags, +EVP_CIPHER_CTX_clear_flags, +EVP_CIPHER_CTX_test_flags, +EVP_CIPHER_CTX_get_type, +EVP_CIPHER_CTX_get_mode, +EVP_CIPHER_CTX_get_num, +EVP_CIPHER_CTX_set_num, +EVP_CIPHER_CTX_is_encrypting, +EVP_CIPHER_param_to_asn1, +EVP_CIPHER_asn1_to_param, +EVP_CIPHER_CTX_set_padding, +EVP_enc_null, +EVP_CIPHER_do_all_provided, +EVP_CIPHER_nid, +EVP_CIPHER_name, +EVP_CIPHER_block_size, +EVP_CIPHER_key_length, +EVP_CIPHER_iv_length, +EVP_CIPHER_flags, +EVP_CIPHER_mode, +EVP_CIPHER_type, +EVP_CIPHER_CTX_encrypting, +EVP_CIPHER_CTX_nid, +EVP_CIPHER_CTX_block_size, +EVP_CIPHER_CTX_key_length, +EVP_CIPHER_CTX_iv_length, +EVP_CIPHER_CTX_tag_length, +EVP_CIPHER_CTX_num, +EVP_CIPHER_CTX_type, +EVP_CIPHER_CTX_mode +\&\- EVP cipher routines .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/evp.h> \& +\& EVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, +\& const char *properties); +\& int EVP_CIPHER_up_ref(EVP_CIPHER *cipher); +\& void EVP_CIPHER_free(EVP_CIPHER *cipher); \& EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); \& int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx); \& void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); \& \& int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, \& ENGINE *impl, const unsigned char *key, const unsigned char *iv); +\& int EVP_EncryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& const unsigned char *key, const unsigned char *iv, +\& const OSSL_PARAM params[]); \& int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, \& int *outl, const unsigned char *in, int inl); \& int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); \& \& int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, \& ENGINE *impl, const unsigned char *key, const unsigned char *iv); +\& int EVP_DecryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& const unsigned char *key, const unsigned char *iv, +\& const OSSL_PARAM params[]); \& int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, \& int *outl, const unsigned char *in, int inl); \& int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); \& \& int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, \& ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc); +\& int EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, +\& const unsigned char *key, const unsigned char *iv, +\& int enc, const OSSL_PARAM params[]); \& int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, \& int *outl, const unsigned char *in, int inl); \& int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); @@ -179,185 +282,418 @@ EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free, EVP_EncryptInit_e \& const unsigned char *key, const unsigned char *iv, int enc); \& int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); \& +\& int EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out, +\& const unsigned char *in, unsigned int inl); +\& \& 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); +\& void EVP_CIPHER_CTX_set_flags(EVP_CIPHER_CTX *ctx, int flags); +\& void EVP_CIPHER_CTX_clear_flags(EVP_CIPHER_CTX *ctx, int flags); +\& int EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags); \& \& const EVP_CIPHER *EVP_get_cipherbyname(const char *name); \& const EVP_CIPHER *EVP_get_cipherbynid(int nid); \& const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a); \& -\& int EVP_CIPHER_nid(const EVP_CIPHER *e); -\& int EVP_CIPHER_block_size(const EVP_CIPHER *e); -\& int EVP_CIPHER_key_length(const EVP_CIPHER *e); -\& int EVP_CIPHER_iv_length(const EVP_CIPHER *e); -\& unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e); -\& unsigned long EVP_CIPHER_mode(const EVP_CIPHER *e); -\& int EVP_CIPHER_type(const EVP_CIPHER *ctx); +\& int EVP_CIPHER_get_nid(const EVP_CIPHER *e); +\& int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name); +\& int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher, +\& void (*fn)(const char *name, void *data), +\& void *data); +\& const char *EVP_CIPHER_get0_name(const EVP_CIPHER *cipher); +\& const char *EVP_CIPHER_get0_description(const EVP_CIPHER *cipher); +\& const OSSL_PROVIDER *EVP_CIPHER_get0_provider(const EVP_CIPHER *cipher); +\& int EVP_CIPHER_get_block_size(const EVP_CIPHER *e); +\& int EVP_CIPHER_get_key_length(const EVP_CIPHER *e); +\& int EVP_CIPHER_get_iv_length(const EVP_CIPHER *e); +\& unsigned long EVP_CIPHER_get_flags(const EVP_CIPHER *e); +\& unsigned long EVP_CIPHER_get_mode(const EVP_CIPHER *e); +\& int EVP_CIPHER_get_type(const EVP_CIPHER *cipher); \& -\& const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); -\& int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx); -\& int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx); -\& int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx); -\& int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx); +\& const EVP_CIPHER *EVP_CIPHER_CTX_get0_cipher(const EVP_CIPHER_CTX *ctx); +\& EVP_CIPHER *EVP_CIPHER_CTX_get1_cipher(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_nid(const EVP_CIPHER_CTX *ctx); +\& const char *EVP_CIPHER_CTX_get0_name(const EVP_CIPHER_CTX *ctx); +\& +\& int EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]); +\& int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]); +\& int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]); +\& const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher); +\& const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher); +\& const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher); +\& const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(EVP_CIPHER_CTX *ctx); +\& const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_block_size(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_key_length(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_iv_length(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx); \& void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); \& void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data); -\& int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx); -\& int EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx); +\& int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num); +\& int EVP_CIPHER_CTX_is_encrypting(const EVP_CIPHER_CTX *ctx); \& \& int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); \& int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); +\& +\& void EVP_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx, +\& void (*fn)(EVP_CIPHER *cipher, void *arg), +\& void *arg); +\& +\& #define EVP_CIPHER_nid EVP_CIPHER_get_nid +\& #define EVP_CIPHER_name EVP_CIPHER_get0_name +\& #define EVP_CIPHER_block_size EVP_CIPHER_get_block_size +\& #define EVP_CIPHER_key_length EVP_CIPHER_get_key_length +\& #define EVP_CIPHER_iv_length EVP_CIPHER_get_iv_length +\& #define EVP_CIPHER_flags EVP_CIPHER_get_flags +\& #define EVP_CIPHER_mode EVP_CIPHER_get_mode +\& #define EVP_CIPHER_type EVP_CIPHER_get_type +\& #define EVP_CIPHER_CTX_encrypting EVP_CIPHER_CTX_is_encrypting +\& #define EVP_CIPHER_CTX_nid EVP_CIPHER_CTX_get_nid +\& #define EVP_CIPHER_CTX_block_size EVP_CIPHER_CTX_get_block_size +\& #define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length +\& #define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length +\& #define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length +\& #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num +\& #define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type +\& #define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode +.Ve +.PP +The following function has been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \s-1EVP\s0 cipher routines are a high-level interface to certain symmetric ciphers. .PP -\&\fBEVP_CIPHER_CTX_new()\fR creates a cipher context. -.PP -\&\fBEVP_CIPHER_CTX_free()\fR clears all information from a cipher context -and free up any allocated memory associate with it, including \fBctx\fR -itself. This function should be called after all operations using a -cipher are complete so sensitive information does not remain in -memory. -.PP -\&\fBEVP_EncryptInit_ex()\fR sets up cipher context \fBctx\fR for encryption -with cipher \fBtype\fR from \s-1ENGINE\s0 \fBimpl\fR. \fBctx\fR must be created -before calling this function. \fBtype\fR is normally supplied -by a function such as \fBEVP_aes_256_cbc()\fR. If \fBimpl\fR is \s-1NULL\s0 then the -default implementation is used. \fBkey\fR is the symmetric key to use -and \fBiv\fR is the \s-1IV\s0 to use (if necessary), the actual number of bytes -used for the key and \s-1IV\s0 depends on the cipher. It is possible to set -all parameters to \s-1NULL\s0 except \fBtype\fR in an initial call and supply -the remaining parameters in subsequent calls, all of which have \fBtype\fR -set to \s-1NULL.\s0 This is done when the default cipher parameters are not -appropriate. -.PP -\&\fBEVP_EncryptUpdate()\fR encrypts \fBinl\fR bytes from the buffer \fBin\fR and -writes the encrypted version to \fBout\fR. 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. +The \fB\s-1EVP_CIPHER\s0\fR type is a structure for cipher method implementation. +.IP "\fBEVP_CIPHER_fetch()\fR" 4 +.IX Item "EVP_CIPHER_fetch()" +Fetches the cipher implementation for the given \fIalgorithm\fR from any provider +offering it, within the criteria given by the \fIproperties\fR. +See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for further information. +.Sp +The returned value must eventually be freed with \fBEVP_CIPHER_free()\fR. +.Sp +Fetched \fB\s-1EVP_CIPHER\s0\fR structures are reference counted. +.IP "\fBEVP_CIPHER_up_ref()\fR" 4 +.IX Item "EVP_CIPHER_up_ref()" +Increments the reference count for an \fB\s-1EVP_CIPHER\s0\fR structure. +.IP "\fBEVP_CIPHER_free()\fR" 4 +.IX Item "EVP_CIPHER_free()" +Decrements the reference count for the fetched \fB\s-1EVP_CIPHER\s0\fR structure. +If the reference count drops to 0 then the structure is freed. +.IP "\fBEVP_CIPHER_CTX_new()\fR" 4 +.IX Item "EVP_CIPHER_CTX_new()" +Allocates and returns a cipher context. +.IP "\fBEVP_CIPHER_CTX_free()\fR" 4 +.IX Item "EVP_CIPHER_CTX_free()" +Clears all information from a cipher context and frees any allocated memory +associated with it, including \fIctx\fR itself. This function should be called after +all operations using a cipher are complete so sensitive information does not +remain in memory. +.IP "\fBEVP_CIPHER_CTX_ctrl()\fR" 4 +.IX Item "EVP_CIPHER_CTX_ctrl()" +\&\fIThis is a legacy method.\fR \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR is the mechanism that should be used to set and get +parameters that are used by providers. +.Sp +Performs cipher-specific control actions on context \fIctx\fR. The control command +is indicated in \fIcmd\fR and any additional arguments in \fIp1\fR and \fIp2\fR. +\&\fBEVP_CIPHER_CTX_ctrl()\fR must be called after \fBEVP_CipherInit_ex2()\fR. Other restrictions +may apply depending on the control type and cipher implementation. +.Sp +If this function happens to be used with a fetched \fB\s-1EVP_CIPHER\s0\fR, it will +translate the controls that are known to OpenSSL into \s-1\fBOSSL_PARAM\s0\fR\|(3) +parameters with keys defined by OpenSSL and call \fBEVP_CIPHER_CTX_get_params()\fR or +\&\fBEVP_CIPHER_CTX_set_params()\fR as is appropriate for each control command. +.Sp +See \*(L"\s-1CONTROLS\*(R"\s0 below for more information, including what translations are +being done. +.IP "\fBEVP_CIPHER_get_params()\fR" 4 +.IX Item "EVP_CIPHER_get_params()" +Retrieves the requested list of algorithm \fIparams\fR from a \s-1CIPHER\s0 \fIcipher\fR. +See \*(L"\s-1PARAMETERS\*(R"\s0 below for more information. +.IP "\fBEVP_CIPHER_CTX_get_params()\fR" 4 +.IX Item "EVP_CIPHER_CTX_get_params()" +Retrieves the requested list of \fIparams\fR from \s-1CIPHER\s0 context \fIctx\fR. +See \*(L"\s-1PARAMETERS\*(R"\s0 below for more information. +.IP "\fBEVP_CIPHER_CTX_set_params()\fR" 4 +.IX Item "EVP_CIPHER_CTX_set_params()" +Sets the list of \fIparams\fR into a \s-1CIPHER\s0 context \fIctx\fR. +See \*(L"\s-1PARAMETERS\*(R"\s0 below for more information. +.IP "\fBEVP_CIPHER_gettable_params()\fR" 4 +.IX Item "EVP_CIPHER_gettable_params()" +Get a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the retrievable parameters +that can be used with \fBEVP_CIPHER_get_params()\fR. +.IP "\fBEVP_CIPHER_gettable_ctx_params()\fR and \fBEVP_CIPHER_CTX_gettable_params()\fR" 4 +.IX Item "EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params()" +Get a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the retrievable parameters +that can be used with \fBEVP_CIPHER_CTX_get_params()\fR. +\&\fBEVP_CIPHER_gettable_ctx_params()\fR returns the parameters that can be retrieved +from the algorithm, whereas \fBEVP_CIPHER_CTX_gettable_params()\fR returns the +parameters that can be retrieved in the context's current state. +.IP "\fBEVP_CIPHER_settable_ctx_params()\fR and \fBEVP_CIPHER_CTX_settable_params()\fR" 4 +.IX Item "EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params()" +Get a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the settable parameters +that can be used with \fBEVP_CIPHER_CTX_set_params()\fR. +\&\fBEVP_CIPHER_settable_ctx_params()\fR returns the parameters that can be set from the +algorithm, whereas \fBEVP_CIPHER_CTX_settable_params()\fR returns the parameters that +can be set in the context's current state. +.IP "\fBEVP_EncryptInit_ex2()\fR" 4 +.IX Item "EVP_EncryptInit_ex2()" +Sets up cipher context \fIctx\fR for encryption with cipher \fItype\fR. \fItype\fR is +typically supplied by calling \fBEVP_CIPHER_fetch()\fR. \fItype\fR may also be set +using legacy functions such as \fBEVP_aes_256_cbc()\fR, but this is not recommended +for new applications. \fIkey\fR is the symmetric key to use and \fIiv\fR is the \s-1IV\s0 to +use (if necessary), the actual number of bytes used for the key and \s-1IV\s0 depends +on the cipher. The parameters \fIparams\fR will be set on the context after +initialisation. It is possible to set all parameters to \s-1NULL\s0 except \fItype\fR in +an initial call and supply the remaining parameters in subsequent calls, all of +which have \fItype\fR set to \s-1NULL.\s0 This is done when the default cipher parameters +are not appropriate. +For \fB\s-1EVP_CIPH_GCM_MODE\s0\fR the \s-1IV\s0 will be generated internally if it is not +specified. +.IP "\fBEVP_EncryptInit_ex()\fR" 4 +.IX Item "EVP_EncryptInit_ex()" +This legacy function is similar to \fBEVP_EncryptInit_ex2()\fR when \fIimpl\fR is \s-1NULL.\s0 +The implementation of the \fItype\fR from the \fIimpl\fR engine will be used if it +exists. +.IP "\fBEVP_EncryptUpdate()\fR" 4 +.IX Item "EVP_EncryptUpdate()" +Encrypts \fIinl\fR bytes from the buffer \fIin\fR and writes the encrypted version to +\&\fIout\fR. 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, \fBout\fR should contain sufficient room for the operation being performed. -The actual number of bytes written is placed in \fBoutl\fR. It also -checks if \fBin\fR and \fBout\fR are partially overlapping, and if they are +Thus, \fIout\fR should contain sufficient room for the operation being performed. +The actual number of bytes written is placed in \fIoutl\fR. It also +checks if \fIin\fR and \fIout\fR are partially overlapping, and if they are 0 is returned to indicate failure. -.PP +.Sp If padding is enabled (the default) then \fBEVP_EncryptFinal_ex()\fR encrypts the \*(L"final\*(R" data, that is any data that remains in a partial block. It uses standard block padding (aka \s-1PKCS\s0 padding) as described in the \s-1NOTES\s0 section, below. The encrypted -final data is written to \fBout\fR which should have sufficient space for -one cipher block. The number of bytes written is placed in \fBoutl\fR. After +final data is written to \fIout\fR which should have sufficient space for +one cipher block. The number of bytes written is placed in \fIoutl\fR. After this function is called the encryption operation is finished and no further calls to \fBEVP_EncryptUpdate()\fR should be made. -.PP +.Sp If padding is disabled then \fBEVP_EncryptFinal_ex()\fR 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. -.PP -\&\fBEVP_DecryptInit_ex()\fR, \fBEVP_DecryptUpdate()\fR and \fBEVP_DecryptFinal_ex()\fR are the -corresponding decryption operations. \fBEVP_DecryptFinal()\fR 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 \fBout\fR -passed to \fBEVP_DecryptUpdate()\fR should have sufficient room for -(\fBinl\fR + cipher_block_size) bytes unless the cipher block size is 1 in -which case \fBinl\fR bytes is sufficient. -.PP -\&\fBEVP_CipherInit_ex()\fR, \fBEVP_CipherUpdate()\fR and \fBEVP_CipherFinal_ex()\fR are -functions that can be used for decryption or encryption. The operation -performed depends on the value of the \fBenc\fR parameter. It should be set -to 1 for encryption, 0 for decryption and \-1 to leave the value unchanged +.IP "\fBEVP_DecryptInit_ex2()\fR, \fBEVP_DecryptInit_ex()\fR, \fBEVP_DecryptUpdate()\fR and \fBEVP_DecryptFinal_ex()\fR" 4 +.IX Item "EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex()" +These functions are the corresponding decryption operations. +\&\fBEVP_DecryptFinal()\fR 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 \fIout\fR passed to \fBEVP_DecryptUpdate()\fR should have +sufficient room for (\fIinl\fR + cipher_block_size) bytes unless the cipher block +size is 1 in which case \fIinl\fR bytes is sufficient. +.IP "\fBEVP_CipherInit_ex2()\fR, \fBEVP_CipherInit_ex()\fR, \fBEVP_CipherUpdate()\fR and \fBEVP_CipherFinal_ex()\fR" 4 +.IX Item "EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex()" +These functions can be used for decryption or encryption. The operation +performed depends on the value of the \fIenc\fR 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). -.PP -\&\fBEVP_CIPHER_CTX_reset()\fR clears all information from a cipher context -and free up any allocated memory associate with it, except the \fBctx\fR -itself. This function should be called anytime \fBctx\fR is to be reused -for another \fBEVP_CipherInit()\fR / \fBEVP_CipherUpdate()\fR / \fBEVP_CipherFinal()\fR -series of calls. -.PP -\&\fBEVP_EncryptInit()\fR, \fBEVP_DecryptInit()\fR and \fBEVP_CipherInit()\fR behave in a -similar way to \fBEVP_EncryptInit_ex()\fR, \fBEVP_DecryptInit_ex()\fR and -\&\fBEVP_CipherInit_ex()\fR except they always use the default cipher implementation. -.PP -\&\fBEVP_EncryptFinal()\fR, \fBEVP_DecryptFinal()\fR and \fBEVP_CipherFinal()\fR are -identical to \fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptFinal_ex()\fR and +.IP "\fBEVP_CIPHER_CTX_reset()\fR" 4 +.IX Item "EVP_CIPHER_CTX_reset()" +Clears all information from a cipher context and free up any allocated memory +associated with it, except the \fIctx\fR itself. This function should be called +anytime \fIctx\fR is reused by another +\&\fBEVP_CipherInit()\fR / \fBEVP_CipherUpdate()\fR / \fBEVP_CipherFinal()\fR series of calls. +.IP "\fBEVP_EncryptInit()\fR, \fBEVP_DecryptInit()\fR and \fBEVP_CipherInit()\fR" 4 +.IX Item "EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit()" +Behave in a similar way to \fBEVP_EncryptInit_ex()\fR, \fBEVP_DecryptInit_ex()\fR and +\&\fBEVP_CipherInit_ex()\fR except if the \fItype\fR is not a fetched cipher they use the +default implementation of the \fItype\fR. +.IP "\fBEVP_EncryptFinal()\fR, \fBEVP_DecryptFinal()\fR and \fBEVP_CipherFinal()\fR" 4 +.IX Item "EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal()" +Identical to \fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptFinal_ex()\fR and \&\fBEVP_CipherFinal_ex()\fR. In previous releases they also cleaned up -the \fBctx\fR, but this is no longer done and \fBEVP_CIPHER_CTX_clean()\fR +the \fIctx\fR, but this is no longer done and \fBEVP_CIPHER_CTX_cleanup()\fR must be called to free any context resources. -.PP -\&\fBEVP_get_cipherbyname()\fR, \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR -return an \s-1EVP_CIPHER\s0 structure when passed a cipher name, a \s-1NID\s0 or an -\&\s-1ASN1_OBJECT\s0 structure. -.PP -\&\fBEVP_CIPHER_nid()\fR and \fBEVP_CIPHER_CTX_nid()\fR return the \s-1NID\s0 of a cipher when -passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR structure. The actual \s-1NID\s0 -value is an internal value which may not have a corresponding \s-1OBJECT -IDENTIFIER.\s0 -.PP -\&\fBEVP_CIPHER_CTX_set_padding()\fR enables or disables padding. This -function should be called after the context is set up for encryption -or decryption with \fBEVP_EncryptInit_ex()\fR, \fBEVP_DecryptInit_ex()\fR or -\&\fBEVP_CipherInit_ex()\fR. By default encryption operations are padded using -standard block padding and the padding is checked and removed when -decrypting. If the \fBpad\fR parameter is zero then no padding is +.IP "\fBEVP_Cipher()\fR" 4 +.IX Item "EVP_Cipher()" +Encrypts or decrypts a maximum \fIinl\fR amount of bytes from \fIin\fR and leaves the +result in \fIout\fR. +.Sp +For legacy ciphers \- If the cipher doesn't have the flag +\&\fB\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0\fR set, then \fIinl\fR must be a multiple of +\&\fBEVP_CIPHER_get_block_size()\fR. If it isn't, the result is undefined. If the cipher +has that flag set, then \fIinl\fR can be any size. +.Sp +Due to the constraints of the \s-1API\s0 contract of this function it shouldn't be used +in applications, please consider using \fBEVP_CipherUpdate()\fR and +\&\fBEVP_CipherFinal_ex()\fR instead. +.IP "\fBEVP_get_cipherbyname()\fR, \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR" 4 +.IX Item "EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj()" +Returns an \fB\s-1EVP_CIPHER\s0\fR structure when passed a cipher name, a cipher \fB\s-1NID\s0\fR or +an \fB\s-1ASN1_OBJECT\s0\fR structure respectively. +.Sp +\&\fBEVP_get_cipherbyname()\fR will return \s-1NULL\s0 for algorithms such as \*(L"\s-1AES\-128\-SIV\*(R", +\&\*(L"AES\-128\-CBC\-CTS\*(R"\s0 and \*(L"\s-1CAMELLIA\-128\-CBC\-CTS\*(R"\s0 which were previously only +accessible via low level interfaces. +.Sp +The \fBEVP_get_cipherbyname()\fR function is present for backwards compatibility with +OpenSSL prior to version 3 and is different to the \fBEVP_CIPHER_fetch()\fR function +since it does not attempt to \*(L"fetch\*(R" an implementation of the cipher. +Additionally, it only knows about ciphers that are built-in to OpenSSL and have +an associated \s-1NID.\s0 Similarly \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR +also return objects without an associated implementation. +.Sp +When the cipher objects returned by these functions are used (such as in a call +to \fBEVP_EncryptInit_ex()\fR) an implementation of the cipher will be implicitly +fetched from the loaded providers. This fetch could fail if no suitable +implementation is available. Use \fBEVP_CIPHER_fetch()\fR instead to explicitly fetch +the algorithm and an associated implementation from a provider. +.Sp +See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for more information about fetching. +.Sp +The cipher objects returned from these functions do not need to be freed with +\&\fBEVP_CIPHER_free()\fR. +.IP "\fBEVP_CIPHER_get_nid()\fR and \fBEVP_CIPHER_CTX_get_nid()\fR" 4 +.IX Item "EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid()" +Return the \s-1NID\s0 of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR +structure. The actual \s-1NID\s0 value is an internal value which may not have a +corresponding \s-1OBJECT IDENTIFIER.\s0 +.IP "\fBEVP_CIPHER_CTX_set_flags()\fR, \fBEVP_CIPHER_CTX_clear_flags()\fR and \fBEVP_CIPHER_CTX_test_flags()\fR" 4 +.IX Item "EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags()" +Sets, clears and tests \fIctx\fR flags. See \*(L"\s-1FLAGS\*(R"\s0 below for more information. +.Sp +For provided ciphers \fBEVP_CIPHER_CTX_set_flags()\fR should be called only after the +fetched cipher has been assigned to the \fIctx\fR. It is recommended to use +\&\*(L"\s-1PARAMETERS\*(R"\s0 instead. +.IP "\fBEVP_CIPHER_CTX_set_padding()\fR" 4 +.IX 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 \fBEVP_EncryptInit_ex2()\fR, +\&\fBEVP_DecryptInit_ex2()\fR or \fBEVP_CipherInit_ex2()\fR. By default encryption operations +are padded using standard block padding and the padding is checked and removed +when decrypting. If the \fIpad\fR 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. -.PP -\&\fBEVP_CIPHER_key_length()\fR and \fBEVP_CIPHER_CTX_key_length()\fR return the key -length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR -structure. The constant \fB\s-1EVP_MAX_KEY_LENGTH\s0\fR is the maximum key length -for all ciphers. Note: although \fBEVP_CIPHER_key_length()\fR is fixed for a -given cipher, the value of \fBEVP_CIPHER_CTX_key_length()\fR may be different -for variable key length ciphers. -.PP -\&\fBEVP_CIPHER_CTX_set_key_length()\fR sets the key length of the cipher ctx. +.IP "\fBEVP_CIPHER_get_key_length()\fR and \fBEVP_CIPHER_CTX_get_key_length()\fR" 4 +.IX Item "EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length()" +Return the key length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or +\&\fB\s-1EVP_CIPHER_CTX\s0\fR structure. The constant \fB\s-1EVP_MAX_KEY_LENGTH\s0\fR is the maximum +key length for all ciphers. Note: although \fBEVP_CIPHER_get_key_length()\fR is fixed for +a given cipher, the value of \fBEVP_CIPHER_CTX_get_key_length()\fR may be different for +variable key length ciphers. +.IP "\fBEVP_CIPHER_CTX_set_key_length()\fR" 4 +.IX Item "EVP_CIPHER_CTX_set_key_length()" +Sets the key length of the cipher context. 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. -.PP -\&\fBEVP_CIPHER_iv_length()\fR and \fBEVP_CIPHER_CTX_iv_length()\fR return the \s-1IV\s0 -length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR. -It will return zero if the cipher does not use an \s-1IV.\s0 The constant -\&\fB\s-1EVP_MAX_IV_LENGTH\s0\fR is the maximum \s-1IV\s0 length for all ciphers. -.PP -\&\fBEVP_CIPHER_block_size()\fR and \fBEVP_CIPHER_CTX_block_size()\fR return the block -size of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or \fB\s-1EVP_CIPHER_CTX\s0\fR -structure. The constant \fB\s-1EVP_MAX_BLOCK_LENGTH\s0\fR is also the maximum block -length for all ciphers. -.PP -\&\fBEVP_CIPHER_type()\fR and \fBEVP_CIPHER_CTX_type()\fR return the type of the passed -cipher or context. This \*(L"type\*(R" is the actual \s-1NID\s0 of the cipher \s-1OBJECT -IDENTIFIER\s0 as such it ignores the cipher parameters and 40 bit \s-1RC2\s0 and -128 bit \s-1RC2\s0 have the same \s-1NID.\s0 If the cipher does not have an object -identifier or does not have \s-1ASN1\s0 support this function will return +.IP "\fBEVP_CIPHER_get_iv_length()\fR and \fBEVP_CIPHER_CTX_get_iv_length()\fR" 4 +.IX Item "EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length()" +Return the \s-1IV\s0 length of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or +\&\fB\s-1EVP_CIPHER_CTX\s0\fR. It will return zero if the cipher does not use an \s-1IV.\s0 +The constant \fB\s-1EVP_MAX_IV_LENGTH\s0\fR is the maximum \s-1IV\s0 length for all ciphers. +.IP "\fBEVP_CIPHER_CTX_get_tag_length()\fR" 4 +.IX Item "EVP_CIPHER_CTX_get_tag_length()" +Returns the tag length of an \s-1AEAD\s0 cipher when passed a \fB\s-1EVP_CIPHER_CTX\s0\fR. 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. +.IP "\fBEVP_CIPHER_get_block_size()\fR and \fBEVP_CIPHER_CTX_get_block_size()\fR" 4 +.IX Item "EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size()" +Return the block size of a cipher when passed an \fB\s-1EVP_CIPHER\s0\fR or +\&\fB\s-1EVP_CIPHER_CTX\s0\fR structure. The constant \fB\s-1EVP_MAX_BLOCK_LENGTH\s0\fR is also the +maximum block length for all ciphers. +.IP "\fBEVP_CIPHER_get_type()\fR and \fBEVP_CIPHER_CTX_get_type()\fR" 4 +.IX Item "EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type()" +Return the type of the passed cipher or context. This \*(L"type\*(R" is the actual \s-1NID\s0 +of the cipher \s-1OBJECT IDENTIFIER\s0 and as such it ignores the cipher parameters +(40 bit \s-1RC2\s0 and 128 bit \s-1RC2\s0 have the same \s-1NID\s0). If the cipher does not have an +object identifier or does not have \s-1ASN1\s0 support this function will return \&\fBNID_undef\fR. -.PP -\&\fBEVP_CIPHER_CTX_cipher()\fR returns the \fB\s-1EVP_CIPHER\s0\fR structure when passed -an \fB\s-1EVP_CIPHER_CTX\s0\fR structure. -.PP -\&\fBEVP_CIPHER_mode()\fR and \fBEVP_CIPHER_CTX_mode()\fR return the block cipher mode: +.IP "\fBEVP_CIPHER_is_a()\fR" 4 +.IX Item "EVP_CIPHER_is_a()" +Returns 1 if \fIcipher\fR is an implementation of an algorithm that's identifiable +with \fIname\fR, otherwise 0. If \fIcipher\fR is a legacy cipher (it's the return +value from the likes of \fBEVP_aes128()\fR rather than the result of an +\&\fBEVP_CIPHER_fetch()\fR), only cipher names registered with the default library +context (see \s-1\fBOSSL_LIB_CTX\s0\fR\|(3)) will be considered. +.IP "\fBEVP_CIPHER_get0_name()\fR and \fBEVP_CIPHER_CTX_get0_name()\fR" 4 +.IX Item "EVP_CIPHER_get0_name() and EVP_CIPHER_CTX_get0_name()" +Return the name of the passed cipher or context. For fetched ciphers with +multiple names, only one of them is returned. See also \fBEVP_CIPHER_names_do_all()\fR. +.IP "\fBEVP_CIPHER_names_do_all()\fR" 4 +.IX Item "EVP_CIPHER_names_do_all()" +Traverses all names for the \fIcipher\fR, and calls \fIfn\fR with each name and +\&\fIdata\fR. This is only useful with fetched \fB\s-1EVP_CIPHER\s0\fRs. +.IP "\fBEVP_CIPHER_get0_description()\fR" 4 +.IX Item "EVP_CIPHER_get0_description()" +Returns a description of the cipher, meant for display and human consumption. +The description is at the discretion of the cipher implementation. +.IP "\fBEVP_CIPHER_get0_provider()\fR" 4 +.IX Item "EVP_CIPHER_get0_provider()" +Returns an \fB\s-1OSSL_PROVIDER\s0\fR pointer to the provider that implements the given +\&\fB\s-1EVP_CIPHER\s0\fR. +.IP "\fBEVP_CIPHER_CTX_get0_cipher()\fR" 4 +.IX Item "EVP_CIPHER_CTX_get0_cipher()" +Returns the \fB\s-1EVP_CIPHER\s0\fR structure when passed an \fB\s-1EVP_CIPHER_CTX\s0\fR structure. +\&\fBEVP_CIPHER_CTX_get1_cipher()\fR is the same except the ownership is passed to +the caller. +.IP "\fBEVP_CIPHER_get_mode()\fR and \fBEVP_CIPHER_CTX_get_mode()\fR" 4 +.IX Item "EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode()" +Return the block cipher mode: \&\s-1EVP_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\s0 or \s-1EVP_CIPH_OCB_MODE.\s0 If the cipher is a stream cipher then -\&\s-1EVP_CIPH_STREAM_CIPHER\s0 is returned. -.PP -\&\fBEVP_CIPHER_param_to_asn1()\fR sets the AlgorithmIdentifier \*(L"parameter\*(R" based -on the passed cipher. This will typically include any parameters and an -\&\s-1IV.\s0 The cipher \s-1IV\s0 (if any) must be set when this call is made. This call -should be made before the cipher is actually \*(L"used\*(R" (before any -\&\fBEVP_EncryptUpdate()\fR, \fBEVP_DecryptUpdate()\fR calls for example). This function -may fail if the cipher does not have any \s-1ASN1\s0 support. -.PP -\&\fBEVP_CIPHER_asn1_to_param()\fR sets the cipher parameters based on an \s-1ASN1\s0 -AlgorithmIdentifier \*(L"parameter\*(R". The precise effect depends on the cipher -In the case of \s-1RC2,\s0 for example, it will set the \s-1IV\s0 and effective key length. +EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE\s0 or \s-1EVP_CIPH_SIV_MODE.\s0 +If the cipher is a stream cipher then \s-1EVP_CIPH_STREAM_CIPHER\s0 is returned. +.IP "\fBEVP_CIPHER_get_flags()\fR" 4 +.IX Item "EVP_CIPHER_get_flags()" +Returns any flags associated with the cipher. See \*(L"\s-1FLAGS\*(R"\s0 +for a list of currently defined flags. +.IP "\fBEVP_CIPHER_CTX_get_num()\fR and \fBEVP_CIPHER_CTX_set_num()\fR" 4 +.IX Item "EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num()" +Gets or sets the cipher specific \*(L"num\*(R" parameter for the associated \fIctx\fR. +Built-in ciphers typically use this to track how much of the current underlying block +has been \*(L"used\*(R" already. +.IP "\fBEVP_CIPHER_CTX_is_encrypting()\fR" 4 +.IX Item "EVP_CIPHER_CTX_is_encrypting()" +Reports whether the \fIctx\fR is being used for encryption or decryption. +.IP "\fBEVP_CIPHER_CTX_flags()\fR" 4 +.IX Item "EVP_CIPHER_CTX_flags()" +A deprecated macro calling \f(CW\*(C`EVP_CIPHER_get_flags(EVP_CIPHER_CTX_get0_cipher(ctx))\*(C'\fR. +Do not use. +.IP "\fBEVP_CIPHER_param_to_asn1()\fR" 4 +.IX Item "EVP_CIPHER_param_to_asn1()" +Sets the AlgorithmIdentifier \*(L"parameter\*(R" based on the passed cipher. This will +typically include any parameters and an \s-1IV.\s0 The cipher \s-1IV\s0 (if any) must be set +when this call is made. This call should be made before the cipher is actually +\&\*(L"used\*(R" (before any \fBEVP_EncryptUpdate()\fR, \fBEVP_DecryptUpdate()\fR calls for example). +This function may fail if the cipher does not have any \s-1ASN1\s0 support. +.IP "\fBEVP_CIPHER_asn1_to_param()\fR" 4 +.IX Item "EVP_CIPHER_asn1_to_param()" +Sets the cipher parameters based on an \s-1ASN1\s0 AlgorithmIdentifier \*(L"parameter\*(R". +The precise effect depends on the cipher. In the case of \fB\s-1RC2\s0\fR, for example, +it will set the \s-1IV\s0 and effective key length. This function should be called after the base cipher type is set but before the key is set. For example \fBEVP_CipherInit()\fR will be called with the \s-1IV\s0 and key set to \s-1NULL,\s0 \fBEVP_CIPHER_asn1_to_param()\fR will be called and finally @@ -365,55 +701,569 @@ key set to \s-1NULL,\s0 \fBEVP_CIPHER_asn1_to_param()\fR will be called and fina possible for this function to fail if the cipher does not have any \s-1ASN1\s0 support or the parameters cannot be set (for example the \s-1RC2\s0 effective key length is not supported. +.IP "\fBEVP_CIPHER_CTX_rand_key()\fR" 4 +.IX Item "EVP_CIPHER_CTX_rand_key()" +Generates a random key of the appropriate length based on the cipher context. +The \fB\s-1EVP_CIPHER\s0\fR can provide its own random key generation routine to support +keys of a specific form. \fIkey\fR must point to a buffer at least as big as the +value returned by \fBEVP_CIPHER_CTX_get_key_length()\fR. +.IP "\fBEVP_CIPHER_do_all_provided()\fR" 4 +.IX Item "EVP_CIPHER_do_all_provided()" +Traverses all ciphers implemented by all activated providers in the given +library context \fIlibctx\fR, and for each of the implementations, calls the given +function \fIfn\fR with the implementation method and the given \fIarg\fR as argument. +.SH "PARAMETERS" +.IX Header "PARAMETERS" +See \s-1\fBOSSL_PARAM\s0\fR\|(3) for information about passing parameters. +.SS "Gettable \s-1EVP_CIPHER\s0 parameters" +.IX Subsection "Gettable EVP_CIPHER parameters" +When \fBEVP_CIPHER_fetch()\fR is called it internally calls \fBEVP_CIPHER_get_params()\fR +and caches the results. .PP -\&\fBEVP_CIPHER_CTX_ctrl()\fR allows various cipher specific parameters to be determined -and set. +\&\fBEVP_CIPHER_get_params()\fR can be used with the following \s-1\fBOSSL_PARAM\s0\fR\|(3) keys: +.ie n .IP """mode"" (\fB\s-1OSSL_CIPHER_PARAM_MODE\s0\fR) <unsigned integer>" 4 +.el .IP "``mode'' (\fB\s-1OSSL_CIPHER_PARAM_MODE\s0\fR) <unsigned integer>" 4 +.IX Item "mode (OSSL_CIPHER_PARAM_MODE) <unsigned integer>" +Gets the mode for the associated cipher algorithm \fIcipher\fR. +See \*(L"\fBEVP_CIPHER_get_mode()\fR and \fBEVP_CIPHER_CTX_get_mode()\fR\*(R" for a list of valid modes. +Use \fBEVP_CIPHER_get_mode()\fR to retrieve the cached value. +.ie n .IP """keylen"" (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``keylen'' (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "keylen (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>" +Gets the key length for the associated cipher algorithm \fIcipher\fR. +Use \fBEVP_CIPHER_get_key_length()\fR to retrieve the cached value. +.ie n .IP """ivlen"" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``ivlen'' (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR) <unsigned integer>" 4 +.IX Item "ivlen (OSSL_CIPHER_PARAM_IVLEN) <unsigned integer>" +Gets the \s-1IV\s0 length for the associated cipher algorithm \fIcipher\fR. +Use \fBEVP_CIPHER_get_iv_length()\fR to retrieve the cached value. +.ie n .IP """blocksize"" (\fB\s-1OSSL_CIPHER_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``blocksize'' (\fB\s-1OSSL_CIPHER_PARAM_BLOCK_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "blocksize (OSSL_CIPHER_PARAM_BLOCK_SIZE) <unsigned integer>" +Gets the block size for the associated cipher algorithm \fIcipher\fR. +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 \s-1AES\s0 in \s-1CTR\s0 mode has a block size of 1 (because it operates like a +stream cipher), even though \s-1AES\s0 has a block size of 16. +Use \fBEVP_CIPHER_get_block_size()\fR to retrieve the cached value. +.ie n .IP """aead"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD\s0\fR) <integer>" 4 +.el .IP "``aead'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD\s0\fR) <integer>" 4 +.IX Item "aead (OSSL_CIPHER_PARAM_AEAD) <integer>" +Gets 1 if this is an \s-1AEAD\s0 cipher algorithm, otherwise it gets 0. +Use (EVP_CIPHER_get_flags(cipher) & \s-1EVP_CIPH_FLAG_AEAD_CIPHER\s0) to retrieve the +cached value. +.ie n .IP """custom-iv"" (\fB\s-1OSSL_CIPHER_PARAM_CUSTOM_IV\s0\fR) <integer>" 4 +.el .IP "``custom-iv'' (\fB\s-1OSSL_CIPHER_PARAM_CUSTOM_IV\s0\fR) <integer>" 4 +.IX Item "custom-iv (OSSL_CIPHER_PARAM_CUSTOM_IV) <integer>" +Gets 1 if the cipher algorithm \fIcipher\fR has a custom \s-1IV,\s0 otherwise it gets 0. +Storing and initializing the \s-1IV\s0 is left entirely to the implementation, if a +custom \s-1IV\s0 is used. +Use (EVP_CIPHER_get_flags(cipher) & \s-1EVP_CIPH_CUSTOM_IV\s0) to retrieve the +cached value. +.ie n .IP """cts"" (\fB\s-1OSSL_CIPHER_PARAM_CTS\s0\fR) <integer>" 4 +.el .IP "``cts'' (\fB\s-1OSSL_CIPHER_PARAM_CTS\s0\fR) <integer>" 4 +.IX Item "cts (OSSL_CIPHER_PARAM_CTS) <integer>" +Gets 1 if the cipher algorithm \fIcipher\fR 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 \fBEVP_CipherUpdate()\fR. +Use (EVP_CIPHER_get_flags(cipher) & \s-1EVP_CIPH_FLAG_CTS\s0) to retrieve the +cached value. +.ie n .IP """tls-multi"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK\s0\fR) <integer>" 4 +.el .IP "``tls-multi'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK\s0\fR) <integer>" 4 +.IX Item "tls-multi (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK) <integer>" +Gets 1 if the cipher algorithm \fIcipher\fR supports interleaving of crypto blocks, +otherwise it gets 0. The interleaving is an optimization only applicable to certain +\&\s-1TLS\s0 ciphers. +Use (EVP_CIPHER_get_flags(cipher) & \s-1EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK\s0) to retrieve the +cached value. +.ie n .IP """has-randkey"" (\fB\s-1OSSL_CIPHER_PARAM_HAS_RANDKEY\s0\fR) <integer>" 4 +.el .IP "``has-randkey'' (\fB\s-1OSSL_CIPHER_PARAM_HAS_RANDKEY\s0\fR) <integer>" 4 +.IX Item "has-randkey (OSSL_CIPHER_PARAM_HAS_RANDKEY) <integer>" +Gets 1 if the cipher algorithm \fIcipher\fR supports the gettable \s-1EVP_CIPHER_CTX\s0 +parameter \fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR. Only \s-1DES\s0 and 3DES set this to 1, +all other OpenSSL ciphers return 0. +.SS "Gettable and Settable \s-1EVP_CIPHER_CTX\s0 parameters" +.IX Subsection "Gettable and Settable EVP_CIPHER_CTX parameters" +The following \s-1\fBOSSL_PARAM\s0\fR\|(3) keys can be used with both \fBEVP_CIPHER_CTX_get_params()\fR +and \fBEVP_CIPHER_CTX_set_params()\fR. +.ie n .IP """padding"" (\fB\s-1OSSL_CIPHER_PARAM_PADDING\s0\fR) <unsigned integer>" 4 +.el .IP "``padding'' (\fB\s-1OSSL_CIPHER_PARAM_PADDING\s0\fR) <unsigned integer>" 4 +.IX Item "padding (OSSL_CIPHER_PARAM_PADDING) <unsigned integer>" +Gets or sets the padding mode for the cipher context \fIctx\fR. +Padding is enabled if the value is 1, and disabled if the value is 0. +See also \fBEVP_CIPHER_CTX_set_padding()\fR. +.ie n .IP """num"" (\fB\s-1OSSL_CIPHER_PARAM_NUM\s0\fR) <unsigned integer>" 4 +.el .IP "``num'' (\fB\s-1OSSL_CIPHER_PARAM_NUM\s0\fR) <unsigned integer>" 4 +.IX Item "num (OSSL_CIPHER_PARAM_NUM) <unsigned integer>" +Gets or sets the cipher specific \*(L"num\*(R" parameter for the cipher context \fIctx\fR. +Built-in ciphers typically use this to track how much of the current underlying +block has been \*(L"used\*(R" already. +See also \fBEVP_CIPHER_CTX_get_num()\fR and \fBEVP_CIPHER_CTX_set_num()\fR. +.ie n .IP """keylen"" (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``keylen'' (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR) <unsigned integer>" 4 +.IX Item "keylen (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>" +Gets or sets the key length for the cipher context \fIctx\fR. +The length of the \*(L"keylen\*(R" parameter should not exceed that of a \fBsize_t\fR. +See also \fBEVP_CIPHER_CTX_get_key_length()\fR and \fBEVP_CIPHER_CTX_set_key_length()\fR. +.ie n .IP """tag"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAG\s0\fR) <octet string>" 4 +.el .IP "``tag'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAG\s0\fR) <octet string>" 4 +.IX Item "tag (OSSL_CIPHER_PARAM_AEAD_TAG) <octet string>" +Gets or sets the \s-1AEAD\s0 tag for the associated cipher context \fIctx\fR. +See \*(L"\s-1AEAD\s0 Interface\*(R" in \fBEVP_EncryptInit\fR\|(3). +.ie n .IP """keybits"" (\fB\s-1OSSL_CIPHER_PARAM_RC2_KEYBITS\s0\fR) <unsigned integer>" 4 +.el .IP "``keybits'' (\fB\s-1OSSL_CIPHER_PARAM_RC2_KEYBITS\s0\fR) <unsigned integer>" 4 +.IX Item "keybits (OSSL_CIPHER_PARAM_RC2_KEYBITS) <unsigned integer>" +Gets or sets the effective keybits used for a \s-1RC2\s0 cipher. +The length of the \*(L"keybits\*(R" parameter should not exceed that of a \fBsize_t\fR. +.ie n .IP """rounds"" (\fB\s-1OSSL_CIPHER_PARAM_ROUNDS\s0\fR) <unsigned integer>" 4 +.el .IP "``rounds'' (\fB\s-1OSSL_CIPHER_PARAM_ROUNDS\s0\fR) <unsigned integer>" 4 +.IX Item "rounds (OSSL_CIPHER_PARAM_ROUNDS) <unsigned integer>" +Gets or sets the number of rounds to be used for a cipher. +This is used by the \s-1RC5\s0 cipher. +.ie n .IP """alg_id_param"" (\fB\s-1OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS\s0\fR) <octet string>" 4 +.el .IP "``alg_id_param'' (\fB\s-1OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS\s0\fR) <octet string>" 4 +.IX Item "alg_id_param (OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS) <octet string>" +Used to pass the \s-1DER\s0 encoded AlgorithmIdentifier parameter to or from +the cipher implementation. Functions like \fBEVP_CIPHER_param_to_asn1\fR\|(3) +and \fBEVP_CIPHER_asn1_to_param\fR\|(3) use this parameter for any implementation +that has the flag \fB\s-1EVP_CIPH_FLAG_CUSTOM_ASN1\s0\fR set. +.ie n .IP """cts_mode"" (\fB\s-1OSSL_CIPHER_PARAM_CTS_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.el .IP "``cts_mode'' (\fB\s-1OSSL_CIPHER_PARAM_CTS_MODE\s0\fR) <\s-1UTF8\s0 string>" 4 +.IX Item "cts_mode (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. The input length must be greater than or equal to the +block size. (The block size for \s-1AES\s0 and \s-1CAMELLIA\s0 is 16 bytes). +.Sp +Valid values for the mode are: +.RS 4 +.ie n .IP """\s-1CS1""\s0" 4 +.el .IP "``\s-1CS1''\s0" 4 +.IX Item "CS1" +The \s-1NIST\s0 variant of cipher text stealing. +For input lengths that are multiples of the block size it is equivalent to +using a \*(L"AES-XXX-CBC\*(R" or \*(L"CAMELLIA-XXX-CBC\*(R" cipher otherwise the second last +cipher text block is a partial block. +.ie n .IP """\s-1CS2""\s0" 4 +.el .IP "``\s-1CS2''\s0" 4 +.IX Item "CS2" +For input lengths that are multiples of the block size it is equivalent to +using a \*(L"AES-XXX-CBC\*(R" or \*(L"CAMELLIA-XXX-CBC\*(R" cipher, otherwise it is the same as +\&\*(L"\s-1CS3\*(R"\s0 mode. +.ie n .IP """\s-1CS3""\s0" 4 +.el .IP "``\s-1CS3''\s0" 4 +.IX 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). If the input length is exactly one full block +then this is equivalent to using a \*(L"AES-XXX-CBC\*(R" or \*(L"CAMELLIA-XXX-CBC\*(R" cipher. +.RE +.RS 4 +.Sp +The default is \*(L"\s-1CS1\*(R".\s0 +This is only supported for \*(L"\s-1AES\-128\-CBC\-CTS\*(R", \*(L"AES\-192\-CBC\-CTS\*(R", \*(L"AES\-256\-CBC\-CTS\*(R", +\&\*(L"CAMELLIA\-128\-CBC\-CTS\*(R", \*(L"CAMELLIA\-192\-CBC\-CTS\*(R"\s0 and \*(L"\s-1CAMELLIA\-256\-CBC\-CTS\*(R".\s0 +.RE +.ie n .IP """tls1multi_interleave"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR) <unsigned integer>" 4 +.el .IP "``tls1multi_interleave'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR) <unsigned integer>" 4 +.IX Item "tls1multi_interleave (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). +.SS "Gettable \s-1EVP_CIPHER_CTX\s0 parameters" +.IX Subsection "Gettable EVP_CIPHER_CTX parameters" +The following \s-1\fBOSSL_PARAM\s0\fR\|(3) keys can be used with \fBEVP_CIPHER_CTX_get_params()\fR: +.ie n .IP """ivlen"" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR and <\fB\s-1OSSL_CIPHER_PARAM_AEAD_IVLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``ivlen'' (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR and <\fB\s-1OSSL_CIPHER_PARAM_AEAD_IVLEN\s0\fR) <unsigned integer>" 4 +.IX Item "ivlen (OSSL_CIPHER_PARAM_IVLEN and <OSSL_CIPHER_PARAM_AEAD_IVLEN) <unsigned integer>" +Gets the \s-1IV\s0 length for the cipher context \fIctx\fR. +The length of the \*(L"ivlen\*(R" parameter should not exceed that of a \fBsize_t\fR. +See also \fBEVP_CIPHER_CTX_get_iv_length()\fR. +.ie n .IP """iv"" (\fB\s-1OSSL_CIPHER_PARAM_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4 +.el .IP "``iv'' (\fB\s-1OSSL_CIPHER_PARAM_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4 +.IX Item "iv (OSSL_CIPHER_PARAM_IV) <octet string OR octet ptr>" +Gets the \s-1IV\s0 used to initialize the associated cipher context \fIctx\fR. +See also \fBEVP_CIPHER_CTX_get_original_iv()\fR. +.ie n .IP """updated-iv"" (\fB\s-1OSSL_CIPHER_PARAM_UPDATED_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4 +.el .IP "``updated-iv'' (\fB\s-1OSSL_CIPHER_PARAM_UPDATED_IV\s0\fR) <octet string \s-1OR\s0 octet ptr>" 4 +.IX Item "updated-iv (OSSL_CIPHER_PARAM_UPDATED_IV) <octet string OR octet ptr>" +Gets the updated pseudo-IV state for the associated cipher context, e.g., +the previous ciphertext block for \s-1CBC\s0 mode or the iteratively encrypted \s-1IV\s0 +value for \s-1OFB\s0 mode. Note that octet pointer access is deprecated and is +provided only for backwards compatibility with historical libcrypto APIs. +See also \fBEVP_CIPHER_CTX_get_updated_iv()\fR. +.ie n .IP """randkey"" (\fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR) <octet string>" 4 +.el .IP "``randkey'' (\fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR) <octet string>" 4 +.IX Item "randkey (OSSL_CIPHER_PARAM_RANDOM_KEY) <octet string>" +Gets an implementation specific randomly generated key for the associated +cipher context \fIctx\fR. This is currently only supported by \s-1DES\s0 and 3DES (which set +the key to odd parity). +.ie n .IP """taglen"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAGLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``taglen'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAGLEN\s0\fR) <unsigned integer>" 4 +.IX Item "taglen (OSSL_CIPHER_PARAM_AEAD_TAGLEN) <unsigned integer>" +Gets the tag length to be used for an \s-1AEAD\s0 cipher for the associated cipher +context \fIctx\fR. It gets a default value if it has not been set. +The length of the \*(L"taglen\*(R" parameter should not exceed that of a \fBsize_t\fR. +See also \fBEVP_CIPHER_CTX_get_tag_length()\fR. +.ie n .IP """tlsaadpad"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\s0\fR) <unsigned integer>" 4 +.el .IP "``tlsaadpad'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\s0\fR) <unsigned integer>" 4 +.IX Item "tlsaadpad (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD) <unsigned integer>" +Gets the length of the tag that will be added to a \s-1TLS\s0 record for the \s-1AEAD\s0 +tag for the associated cipher context \fIctx\fR. +The length of the \*(L"tlsaadpad\*(R" parameter should not exceed that of a \fBsize_t\fR. +.ie n .IP """tlsivgen"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\s0\fR) <octet string>" 4 +.el .IP "``tlsivgen'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\s0\fR) <octet string>" 4 +.IX Item "tlsivgen (OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN) <octet string>" +Gets the invocation field generated for encryption. +Can only be called after \*(L"tlsivfixed\*(R" is set. +This is only used for \s-1GCM\s0 mode. +.ie n .IP """tls1multi_enclen"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\s0\fR) <unsigned integer>" 4 +.el .IP "``tls1multi_enclen'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\s0\fR) <unsigned integer>" 4 +.IX Item "tls1multi_enclen (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN) <unsigned integer>" +Get the total length of the record returned from the \*(L"tls1multi_enc\*(R" operation. +.ie n .IP """tls1multi_maxbufsz"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``tls1multi_maxbufsz'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\s0\fR) <unsigned integer>" 4 +.IX Item "tls1multi_maxbufsz (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE) <unsigned integer>" +Gets the maximum record length for a \s-1TLS1\s0 multiblock cipher operation. +The length of the \*(L"tls1multi_maxbufsz\*(R" parameter should not exceed that of a \fBsize_t\fR. +.ie n .IP """tls1multi_aadpacklen"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\s0\fR) <unsigned integer>" 4 +.el .IP "``tls1multi_aadpacklen'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\s0\fR) <unsigned integer>" 4 +.IX Item "tls1multi_aadpacklen (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN) <unsigned integer>" +Gets the result of running the \*(L"tls1multi_aad\*(R" operation. +.ie n .IP """tls-mac"" (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC\s0\fR) <octet ptr>" 4 +.el .IP "``tls-mac'' (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC\s0\fR) <octet ptr>" 4 +.IX Item "tls-mac (OSSL_CIPHER_PARAM_TLS_MAC) <octet ptr>" +Used to pass the \s-1TLS MAC\s0 data. +.SS "Settable \s-1EVP_CIPHER_CTX\s0 parameters" +.IX Subsection "Settable EVP_CIPHER_CTX parameters" +The following \s-1\fBOSSL_PARAM\s0\fR\|(3) keys can be used with \fBEVP_CIPHER_CTX_set_params()\fR: +.ie n .IP """mackey"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_MAC_KEY\s0\fR) <octet string>" 4 +.el .IP "``mackey'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_MAC_KEY\s0\fR) <octet string>" 4 +.IX Item "mackey (OSSL_CIPHER_PARAM_AEAD_MAC_KEY) <octet string>" +Sets the \s-1MAC\s0 key used by composite \s-1AEAD\s0 ciphers such as \s-1AES\-CBC\-HMAC\-SHA256.\s0 +.ie n .IP """speed"" (\fB\s-1OSSL_CIPHER_PARAM_SPEED\s0\fR) <unsigned integer>" 4 +.el .IP "``speed'' (\fB\s-1OSSL_CIPHER_PARAM_SPEED\s0\fR) <unsigned integer>" 4 +.IX Item "speed (OSSL_CIPHER_PARAM_SPEED) <unsigned integer>" +Sets the speed option for the associated cipher context. This is only supported +by \s-1AES SIV\s0 ciphers which disallow multiple operations by default. +Setting \*(L"speed\*(R" to 1 allows another encrypt or decrypt operation to be +performed. This is used for performance testing. +.ie n .IP """use-bits"" (\fB\s-1OSSL_CIPHER_PARAM_USE_BITS\s0\fR) <unsigned integer>" 4 +.el .IP "``use-bits'' (\fB\s-1OSSL_CIPHER_PARAM_USE_BITS\s0\fR) <unsigned integer>" 4 +.IX Item "use-bits (OSSL_CIPHER_PARAM_USE_BITS) <unsigned integer>" +Determines if the input length \fIinl\fR passed to \fBEVP_EncryptUpdate()\fR, +\&\fBEVP_DecryptUpdate()\fR and \fBEVP_CipherUpdate()\fR is the number of bits or number of bytes. +Setting \*(L"use-bits\*(R" to 1 uses bits. The default is in bytes. +This is only used for \fB\s-1CFB1\s0\fR ciphers. +.Sp +This can be set using EVP_CIPHER_CTX_set_flags(ctx, \s-1EVP_CIPH_FLAG_LENGTH_BITS\s0). +.ie n .IP """tls-version"" (\fB\s-1OSSL_CIPHER_PARAM_TLS_VERSION\s0\fR) <integer>" 4 +.el .IP "``tls-version'' (\fB\s-1OSSL_CIPHER_PARAM_TLS_VERSION\s0\fR) <integer>" 4 +.IX Item "tls-version (OSSL_CIPHER_PARAM_TLS_VERSION) <integer>" +Sets the \s-1TLS\s0 version. +.ie n .IP """tls-mac-size"" (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC_SIZE\s0\fR) <unsigned integer>" 4 +.el .IP "``tls-mac-size'' (\fB\s-1OSSL_CIPHER_PARAM_TLS_MAC_SIZE\s0\fR) <unsigned integer>" 4 +.IX Item "tls-mac-size (OSSL_CIPHER_PARAM_TLS_MAC_SIZE) <unsigned integer>" +Set the \s-1TLS MAC\s0 size. +.ie n .IP """tlsaad"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD\s0\fR) <octet string>" 4 +.el .IP "``tlsaad'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD\s0\fR) <octet string>" 4 +.IX Item "tlsaad (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD) <octet string>" +Sets TLSv1.2 \s-1AAD\s0 information for the associated cipher context \fIctx\fR. +TLSv1.2 \s-1AAD\s0 information is always 13 bytes in length and is as defined for the +\&\*(L"additional_data\*(R" field described in section 6.2.3.3 of \s-1RFC5246.\s0 +.ie n .IP """tlsivfixed"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\s0\fR) <octet string>" 4 +.el .IP "``tlsivfixed'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\s0\fR) <octet string>" 4 +.IX Item "tlsivfixed (OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED) <octet string>" +Sets the fixed portion of an \s-1IV\s0 for an \s-1AEAD\s0 cipher used in a \s-1TLS\s0 record +encryption/ decryption for the associated cipher context. +\&\s-1TLS\s0 record encryption/decryption always occurs \*(L"in place\*(R" so that the input and +output buffers are always the same memory location. +\&\s-1AEAD\s0 IVs in TLSv1.2 consist of an implicit \*(L"fixed\*(R" part and an explicit part +that varies with every record. +Setting a \s-1TLS\s0 fixed \s-1IV\s0 changes a cipher to encrypt/decrypt \s-1TLS\s0 records. +\&\s-1TLS\s0 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 \s-1IV\s0 and the final bytes of the input buffer will be the \s-1AEAD\s0 tag. +The length of the explicit part of the \s-1IV\s0 and the tag length will depend on the +cipher in use and will be defined in the \s-1RFC\s0 for the relevant ciphersuite. +In order to allow for \*(L"in place\*(R" 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 \s-1IV.\s0 +.Sp +When encrypting a record the first bytes of the input buffer should be empty to +allow space for the explicit \s-1IV,\s0 as will the final bytes where the tag will +be written. +The length of the input buffer will include the length of the explicit \s-1IV,\s0 the +payload, and the tag bytes. +The cipher implementation should generate the explicit \s-1IV\s0 and write it to the +beginning of the output buffer, do \*(L"in place\*(R" encryption of the payload and +write that to the output buffer, and finally add the tag onto the end of the +output buffer. +.Sp +Whether encrypting or decrypting the value written to \fI*outl\fR in the +OSSL_FUNC_cipher_cipher call should be the length of the payload excluding the explicit +\&\s-1IV\s0 length and the tag length. +.ie n .IP """tlsivinv"" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\s0\fR) <octet string>" 4 +.el .IP "``tlsivinv'' (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\s0\fR) <octet string>" 4 +.IX Item "tlsivinv (OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV) <octet string>" +Sets the invocation field used for decryption. +Can only be called after \*(L"tlsivfixed\*(R" is set. +This is only used for \s-1GCM\s0 mode. +.ie n .IP """tls1multi_enc"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\s0\fR) <octet string>" 4 +.el .IP "``tls1multi_enc'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\s0\fR) <octet string>" 4 +.IX Item "tls1multi_enc (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC) <octet string>" +Triggers a multiblock \s-1TLS1\s0 encrypt operation for a \s-1TLS1\s0 aware cipher that +supports sending 4 or 8 records in one go. +The cipher performs both the \s-1MAC\s0 and encrypt stages and constructs the record +headers itself. +\&\*(L"tls1multi_enc\*(R" supplies the output buffer for the encrypt operation, +\&\*(L"tls1multi_encin\*(R" & \*(L"tls1multi_interleave\*(R" must also be set in order to supply +values to the encrypt operation. +.ie n .IP """tls1multi_encin"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\s0\fR) <octet string>" 4 +.el .IP "``tls1multi_encin'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\s0\fR) <octet string>" 4 +.IX Item "tls1multi_encin (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN) <octet string>" +Supplies the data to encrypt for a \s-1TLS1\s0 multiblock cipher operation. +.ie n .IP """tls1multi_maxsndfrag"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\s0\fR) <unsigned integer>" 4 +.el .IP "``tls1multi_maxsndfrag'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\s0\fR) <unsigned integer>" 4 +.IX Item "tls1multi_maxsndfrag (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT) <unsigned integer>" +Sets the maximum send fragment size for a \s-1TLS1\s0 multiblock cipher operation. +It must be set before using \*(L"tls1multi_maxbufsz\*(R". +The length of the \*(L"tls1multi_maxsndfrag\*(R" parameter should not exceed that of a \fBsize_t\fR. +.ie n .IP """tls1multi_aad"" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\s0\fR) <octet string>" 4 +.el .IP "``tls1multi_aad'' (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\s0\fR) <octet string>" 4 +.IX Item "tls1multi_aad (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD) <octet string>" +Sets the authenticated additional data used by a \s-1TLS1\s0 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) +.Sp +\&\*(L"tls1multi_interleave\*(R" must also be set for this operation. +.SH "CONTROLS" +.IX Header "CONTROLS" +The Mappings from \fBEVP_CIPHER_CTX_ctrl()\fR identifiers to \s-1PARAMETERS\s0 are listed +in the following section. See the \*(L"\s-1PARAMETERS\*(R"\s0 section for more details. .PP -\&\fBEVP_CIPHER_CTX_rand_key()\fR generates a random key of the appropriate length -based on the cipher context. The \s-1EVP_CIPHER\s0 can provide its own random key -generation routine to support keys of a specific form. \fBKey\fR must point to a -buffer at least as big as the value returned by \fBEVP_CIPHER_CTX_key_length()\fR. +\&\fBEVP_CIPHER_CTX_ctrl()\fR can be used to send the following standard controls: +.IP "\s-1EVP_CTRL_AEAD_SET_IVLEN\s0 and \s-1EVP_CTRL_GET_IVLEN\s0" 4 +.IX Item "EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the +key \*(L"ivlen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR). +.IP "\s-1EVP_CTRL_AEAD_SET_IV_FIXED\s0" 4 +.IX Item "EVP_CTRL_AEAD_SET_IV_FIXED" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key \*(L"tlsivfixed\*(R" +(\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED\s0\fR). +.IP "\s-1EVP_CTRL_AEAD_SET_MAC_KEY\s0" 4 +.IX Item "EVP_CTRL_AEAD_SET_MAC_KEY" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key \*(L"mackey\*(R" +(\fB\s-1OSSL_CIPHER_PARAM_AEAD_MAC_KEY\s0\fR). +.IP "\s-1EVP_CTRL_AEAD_SET_TAG\s0 and \s-1EVP_CTRL_AEAD_GET_TAG\s0" 4 +.IX Item "EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the +key \*(L"tag\*(R" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TAG\s0\fR). +.IP "\s-1EVP_CTRL_CCM_SET_L\s0" 4 +.IX Item "EVP_CTRL_CCM_SET_L" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key \*(L"ivlen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_IVLEN\s0\fR) +with a value of (15 \- L) +.IP "\s-1EVP_CTRL_COPY\s0" 4 +.IX Item "EVP_CTRL_COPY" +There is no \s-1OSSL_PARAM\s0 mapping for this. Use \fBEVP_CIPHER_CTX_copy()\fR instead. +.IP "\s-1EVP_CTRL_GCM_SET_IV_INV\s0" 4 +.IX Item "EVP_CTRL_GCM_SET_IV_INV" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key \*(L"tlsivinv\*(R" +(\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV\s0\fR). +.IP "\s-1EVP_CTRL_RAND_KEY\s0" 4 +.IX Item "EVP_CTRL_RAND_KEY" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key \*(L"randkey\*(R" +(\fB\s-1OSSL_CIPHER_PARAM_RANDOM_KEY\s0\fR). +.IP "\s-1EVP_CTRL_SET_KEY_LENGTH\s0" 4 +.IX Item "EVP_CTRL_SET_KEY_LENGTH" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key \*(L"keylen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_KEYLEN\s0\fR). +.IP "\s-1EVP_CTRL_SET_RC2_KEY_BITS\s0 and \s-1EVP_CTRL_GET_RC2_KEY_BITS\s0" 4 +.IX Item "EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the +key \*(L"keybits\*(R" (\fB\s-1OSSL_CIPHER_PARAM_RC2_KEYBITS\s0\fR). +.IP "\s-1EVP_CTRL_SET_RC5_ROUNDS\s0 and \s-1EVP_CTRL_GET_RC5_ROUNDS\s0" 4 +.IX Item "EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR and +\&\fBEVP_CIPHER_CTX_get_params()\fR get called with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the +key \*(L"rounds\*(R" (\fB\s-1OSSL_CIPHER_PARAM_ROUNDS\s0\fR). +.IP "\s-1EVP_CTRL_SET_SPEED\s0" 4 +.IX Item "EVP_CTRL_SET_SPEED" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key \*(L"speed\*(R" (\fB\s-1OSSL_CIPHER_PARAM_SPEED\s0\fR). +.IP "\s-1EVP_CTRL_GCM_IV_GEN\s0" 4 +.IX Item "EVP_CTRL_GCM_IV_GEN" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_get_params()\fR gets called +with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key +\&\*(L"tlsivgen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN\s0\fR). +.IP "\s-1EVP_CTRL_AEAD_TLS1_AAD\s0" 4 +.IX Item "EVP_CTRL_AEAD_TLS1_AAD" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR get called +with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key +\&\*(L"tlsaad\*(R" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD\s0\fR) +followed by \fBEVP_CIPHER_CTX_get_params()\fR with a key of +\&\*(L"tlsaadpad\*(R" (\fB\s-1OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD\s0\fR). +.IP "\s-1EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE\s0" 4 +.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, +\&\fBEVP_CIPHER_CTX_set_params()\fR gets called with an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the +key \s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT\s0 +followed by \fBEVP_CIPHER_CTX_get_params()\fR with a key of +\&\*(L"tls1multi_maxbufsz\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE\s0\fR). +.IP "\s-1EVP_CTRL_TLS1_1_MULTIBLOCK_AAD\s0" 4 +.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_AAD" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with \s-1\fBOSSL_PARAM\s0\fR\|(3) items with the keys +\&\*(L"tls1multi_aad\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD\s0\fR) and +\&\*(L"tls1multi_interleave\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR) +followed by \fBEVP_CIPHER_CTX_get_params()\fR with keys of +\&\*(L"tls1multi_aadpacklen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN\s0\fR) and +\&\*(L"tls1multi_interleave\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR). +.IP "\s-1EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT\s0" 4 +.IX Item "EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT" +When used with a fetched \fB\s-1EVP_CIPHER\s0\fR, \fBEVP_CIPHER_CTX_set_params()\fR gets called +with \s-1\fBOSSL_PARAM\s0\fR\|(3) items with the keys +\&\*(L"tls1multi_enc\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC\s0\fR), +\&\*(L"tls1multi_encin\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN\s0\fR) and +\&\*(L"tls1multi_interleave\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE\s0\fR), +followed by \fBEVP_CIPHER_CTX_get_params()\fR with a key of +\&\*(L"tls1multi_enclen\*(R" (\fB\s-1OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN\s0\fR). +.SH "FLAGS" +.IX Header "FLAGS" +\&\fBEVP_CIPHER_CTX_set_flags()\fR, \fBEVP_CIPHER_CTX_clear_flags()\fR and \fBEVP_CIPHER_CTX_test_flags()\fR. +can be used to manipulate and test these \fB\s-1EVP_CIPHER_CTX\s0\fR flags: +.IP "\s-1EVP_CIPH_NO_PADDING\s0" 4 +.IX Item "EVP_CIPH_NO_PADDING" +Used by \fBEVP_CIPHER_CTX_set_padding()\fR. +.Sp +See also \*(L"Gettable and Settable \s-1EVP_CIPHER_CTX\s0 parameters\*(R" \*(L"padding\*(R" +.IP "\s-1EVP_CIPH_FLAG_LENGTH_BITS\s0" 4 +.IX Item "EVP_CIPH_FLAG_LENGTH_BITS" +See \*(L"Settable \s-1EVP_CIPHER_CTX\s0 parameters\*(R" \*(L"use-bits\*(R". +.IP "\s-1EVP_CIPHER_CTX_FLAG_WRAP_ALLOW\s0" 4 +.IX Item "EVP_CIPHER_CTX_FLAG_WRAP_ALLOW" +Used for Legacy purposes only. This flag needed to be set to indicate the +cipher handled wrapping. +.PP +\&\fBEVP_CIPHER_flags()\fR uses the following flags that +have mappings to \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R": +.IP "\s-1EVP_CIPH_FLAG_AEAD_CIPHER\s0" 4 +.IX Item "EVP_CIPH_FLAG_AEAD_CIPHER" +See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"aead\*(R". +.IP "\s-1EVP_CIPH_CUSTOM_IV\s0" 4 +.IX Item "EVP_CIPH_CUSTOM_IV" +See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"custom-iv\*(R". +.IP "\s-1EVP_CIPH_FLAG_CTS\s0" 4 +.IX Item "EVP_CIPH_FLAG_CTS" +See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"cts\*(R". +.IP "\s-1EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK\s0;" 4 +.IX Item "EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK;" +See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"tls-multi\*(R". +.IP "\s-1EVP_CIPH_RAND_KEY\s0" 4 +.IX Item "EVP_CIPH_RAND_KEY" +See \*(L"Gettable \s-1EVP_CIPHER\s0 parameters\*(R" \*(L"has-randkey\*(R". +.PP +\&\fBEVP_CIPHER_flags()\fR uses the following flags for legacy purposes only: +.IP "\s-1EVP_CIPH_VARIABLE_LENGTH\s0" 4 +.IX Item "EVP_CIPH_VARIABLE_LENGTH" +.PD 0 +.IP "\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0" 4 +.IX Item "EVP_CIPH_FLAG_CUSTOM_CIPHER" +.IP "\s-1EVP_CIPH_ALWAYS_CALL_INIT\s0" 4 +.IX Item "EVP_CIPH_ALWAYS_CALL_INIT" +.IP "\s-1EVP_CIPH_CTRL_INIT\s0" 4 +.IX Item "EVP_CIPH_CTRL_INIT" +.IP "\s-1EVP_CIPH_CUSTOM_KEY_LENGTH\s0" 4 +.IX Item "EVP_CIPH_CUSTOM_KEY_LENGTH" +.IP "\s-1EVP_CIPH_CUSTOM_COPY\s0" 4 +.IX Item "EVP_CIPH_CUSTOM_COPY" +.IP "\s-1EVP_CIPH_FLAG_DEFAULT_ASN1\s0" 4 +.IX Item "EVP_CIPH_FLAG_DEFAULT_ASN1" +.PD +See \fBEVP_CIPHER_meth_set_flags\fR\|(3) for further information related to the above +flags. .SH "RETURN VALUES" .IX Header "RETURN VALUES" +\&\fBEVP_CIPHER_fetch()\fR returns a pointer to a \fB\s-1EVP_CIPHER\s0\fR for success +and \fB\s-1NULL\s0\fR for failure. +.PP +\&\fBEVP_CIPHER_up_ref()\fR returns 1 for success or 0 otherwise. +.PP \&\fBEVP_CIPHER_CTX_new()\fR returns a pointer to a newly created \&\fB\s-1EVP_CIPHER_CTX\s0\fR for success and \fB\s-1NULL\s0\fR for failure. .PP -\&\fBEVP_EncryptInit_ex()\fR, \fBEVP_EncryptUpdate()\fR and \fBEVP_EncryptFinal_ex()\fR +\&\fBEVP_EncryptInit_ex2()\fR, \fBEVP_EncryptUpdate()\fR and \fBEVP_EncryptFinal_ex()\fR return 1 for success and 0 for failure. .PP -\&\fBEVP_DecryptInit_ex()\fR and \fBEVP_DecryptUpdate()\fR return 1 for success and 0 for failure. +\&\fBEVP_DecryptInit_ex2()\fR and \fBEVP_DecryptUpdate()\fR return 1 for success and 0 for failure. \&\fBEVP_DecryptFinal_ex()\fR returns 0 if the decrypt failed or 1 for success. .PP -\&\fBEVP_CipherInit_ex()\fR and \fBEVP_CipherUpdate()\fR return 1 for success and 0 for failure. +\&\fBEVP_CipherInit_ex2()\fR and \fBEVP_CipherUpdate()\fR return 1 for success and 0 for failure. \&\fBEVP_CipherFinal_ex()\fR returns 0 for a decryption failure or 1 for success. .PP +\&\fBEVP_Cipher()\fR returns 1 on success or 0 on failure, if the flag +\&\fB\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0\fR is not set for the cipher. +\&\fBEVP_Cipher()\fR returns the number of bytes written to \fIout\fR for encryption / decryption, or +the number of bytes authenticated in a call specifying \s-1AAD\s0 for an \s-1AEAD\s0 cipher, if the flag +\&\fB\s-1EVP_CIPH_FLAG_CUSTOM_CIPHER\s0\fR is set for the cipher. +.PP \&\fBEVP_CIPHER_CTX_reset()\fR returns 1 for success and 0 for failure. .PP \&\fBEVP_get_cipherbyname()\fR, \fBEVP_get_cipherbynid()\fR and \fBEVP_get_cipherbyobj()\fR return an \fB\s-1EVP_CIPHER\s0\fR structure or \s-1NULL\s0 on error. .PP -\&\fBEVP_CIPHER_nid()\fR and \fBEVP_CIPHER_CTX_nid()\fR return a \s-1NID.\s0 +\&\fBEVP_CIPHER_get_nid()\fR and \fBEVP_CIPHER_CTX_get_nid()\fR return a \s-1NID.\s0 .PP -\&\fBEVP_CIPHER_block_size()\fR and \fBEVP_CIPHER_CTX_block_size()\fR return the block -size. +\&\fBEVP_CIPHER_get_block_size()\fR and \fBEVP_CIPHER_CTX_get_block_size()\fR return the +block size. .PP -\&\fBEVP_CIPHER_key_length()\fR and \fBEVP_CIPHER_CTX_key_length()\fR return the key +\&\fBEVP_CIPHER_get_key_length()\fR and \fBEVP_CIPHER_CTX_get_key_length()\fR return the key length. .PP \&\fBEVP_CIPHER_CTX_set_padding()\fR always returns 1. .PP -\&\fBEVP_CIPHER_iv_length()\fR and \fBEVP_CIPHER_CTX_iv_length()\fR return the \s-1IV\s0 +\&\fBEVP_CIPHER_get_iv_length()\fR and \fBEVP_CIPHER_CTX_get_iv_length()\fR return the \s-1IV\s0 length or zero if the cipher does not use an \s-1IV.\s0 .PP -\&\fBEVP_CIPHER_type()\fR and \fBEVP_CIPHER_CTX_type()\fR return the \s-1NID\s0 of the cipher's -\&\s-1OBJECT IDENTIFIER\s0 or NID_undef if it has no defined \s-1OBJECT IDENTIFIER.\s0 +\&\fBEVP_CIPHER_CTX_get_tag_length()\fR return the tag length or zero if the cipher +does not use a tag. +.PP +\&\fBEVP_CIPHER_get_type()\fR and \fBEVP_CIPHER_CTX_get_type()\fR return the \s-1NID\s0 of the +cipher's \s-1OBJECT IDENTIFIER\s0 or NID_undef if it has no defined +\&\s-1OBJECT IDENTIFIER.\s0 .PP \&\fBEVP_CIPHER_CTX_cipher()\fR returns an \fB\s-1EVP_CIPHER\s0\fR structure. .PP +\&\fBEVP_CIPHER_CTX_get_num()\fR returns a nonnegative num value or +\&\fB\s-1EVP_CTRL_RET_UNSUPPORTED\s0\fR if the implementation does not support the call +or on any other error. +.PP +\&\fBEVP_CIPHER_CTX_set_num()\fR returns 1 on success and 0 if the implementation +does not support the call or on any other error. +.PP +\&\fBEVP_CIPHER_CTX_is_encrypting()\fR returns 1 if the \fIctx\fR is set up for encryption +0 otherwise. +.PP \&\fBEVP_CIPHER_param_to_asn1()\fR and \fBEVP_CIPHER_asn1_to_param()\fR return greater than zero for success and zero or a negative number on failure. .PP -\&\fBEVP_CIPHER_CTX_rand_key()\fR returns 1 for success. +\&\fBEVP_CIPHER_CTX_rand_key()\fR returns 1 for success and zero or a negative number +for failure. +.PP +\&\fBEVP_CIPHER_names_do_all()\fR returns 1 if the callback was called for all names. +A return value of 0 means that the callback was not called for any names. .SH "CIPHER LISTING" .IX Header "CIPHER LISTING" All algorithms have a fixed key length unless otherwise stated. @@ -423,15 +1273,16 @@ interface. .IP "\fBEVP_enc_null()\fR" 4 .IX Item "EVP_enc_null()" Null cipher: does nothing. -.SH "AEAD Interface" -.IX Header "AEAD Interface" +.SH "AEAD INTERFACE" +.IX Header "AEAD INTERFACE" The \s-1EVP\s0 interface for Authenticated Encryption with Associated Data (\s-1AEAD\s0) modes are subtly altered and several additional \fIctrl\fR operations are supported depending on the mode specified. .PP To specify additional authenticated data (\s-1AAD\s0), a call to \fBEVP_CipherUpdate()\fR, \&\fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR should be made with the output -parameter \fBout\fR set to \fB\s-1NULL\s0\fR. +parameter \fIout\fR set to \fB\s-1NULL\s0\fR. In this case, on success, the parameter +\&\fIoutl\fR is set to the number of bytes authenticated. .PP When decrypting, the return value of \fBEVP_DecryptFinal()\fR or \fBEVP_CipherFinal()\fR indicates whether the operation was successful. If it does not indicate success, @@ -481,8 +1332,8 @@ few additional requirements and different \fIctrl\fR values. .PP For \s-1CCM\s0 mode, the total plaintext or ciphertext length \fB\s-1MUST\s0\fR be passed to \&\fBEVP_CipherUpdate()\fR, \fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR with the output -and input parameters (\fBin\fR and \fBout\fR) set to \fB\s-1NULL\s0\fR and the length passed in -the \fBinl\fR parameter. +and input parameters (\fIin\fR and \fIout\fR) set to \fB\s-1NULL\s0\fR and the length passed in +the \fIinl\fR parameter. .PP The following \fIctrl\fRs are supported in \s-1CCM\s0 mode. .IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_TAG,\s0 taglen, tag)" 4 @@ -492,25 +1343,71 @@ the length of the tag (with the \f(CW\*(C`tag\*(C'\fR parameter set to \s-1NULL\ The tag length is often referred to as \fBM\fR. If not set a default value is used (12 for \s-1AES\s0). When decrypting, the tag needs to be set before passing in data to be decrypted, but as in \s-1GCM\s0 and \s-1OCB\s0 mode, it can be set after -passing additional authenticated data (see \*(L"\s-1AEAD\s0 Interface\*(R"). +passing additional authenticated data (see \*(L"\s-1AEAD INTERFACE\*(R"\s0). .IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_CCM_SET_L,\s0 ivlen, \s-1NULL\s0)" 4 .IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)" Sets the \s-1CCM\s0 \fBL\fR value. If not set a default is used (8 for \s-1AES\s0). .IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_IVLEN,\s0 ivlen, \s-1NULL\s0)" 4 .IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" -Sets the \s-1CCM\s0 nonce (\s-1IV\s0) length. This call can only be made before specifying -a nonce value. The nonce length is given by \fB15 \- L\fR so it is 7 by default for +Sets the \s-1CCM\s0 nonce (\s-1IV\s0) length. This call can only be made before specifying a +nonce value. The nonce length is given by \fB15 \- L\fR so it is 7 by default for \&\s-1AES.\s0 +.SS "\s-1SIV\s0 Mode" +.IX Subsection "SIV Mode" +For \s-1SIV\s0 mode ciphers the behaviour of the \s-1EVP\s0 interface is subtly +altered and several additional ctrl operations are supported. +.PP +To specify any additional authenticated data (\s-1AAD\s0) and/or a Nonce, a call to +\&\fBEVP_CipherUpdate()\fR, \fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR should be made +with the output parameter \fIout\fR set to \fB\s-1NULL\s0\fR. +.PP +\&\s-1RFC5297\s0 states that the Nonce is the last piece of \s-1AAD\s0 before the actual +encrypt/decrypt takes place. The \s-1API\s0 does not differentiate the Nonce from +other \s-1AAD.\s0 +.PP +When decrypting the return value of \fBEVP_DecryptFinal()\fR or \fBEVP_CipherFinal()\fR +indicates if the operation was successful. If it does not indicate success +the authentication operation has failed and any output data \fB\s-1MUST NOT\s0\fR +be used as it is corrupted. +.PP +The \s-1API\s0 does not store the the \s-1SIV\s0 (Synthetic Initialization Vector) in +the cipher text. Instead, it is stored as the tag within the \s-1EVP_CIPHER_CTX.\s0 +The \s-1SIV\s0 must be retrieved from the context after encryption, and set into +the context before decryption. +.PP +This differs from \s-1RFC5297\s0 in that the cipher output from encryption, and +the cipher input to decryption, does not contain the \s-1SIV.\s0 This also means +that the plain text and cipher text lengths are identical. +.PP +The following ctrls are supported in \s-1SIV\s0 mode, and are used to get and set +the Synthetic Initialization Vector: +.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_GET_TAG,\s0 taglen, tag);" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);" +Writes \fItaglen\fR bytes of the tag value (the Synthetic Initialization Vector) +to the buffer indicated by \fItag\fR. This call can only be made when encrypting +data and \fBafter\fR all data has been processed (e.g. after an \fBEVP_EncryptFinal()\fR +call). For \s-1SIV\s0 mode the taglen must be 16. +.IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_TAG,\s0 taglen, tag);" 4 +.IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);" +Sets the expected tag (the Synthetic Initialization Vector) to \fItaglen\fR +bytes from \fItag\fR. This call is only legal when decrypting data and must be +made \fBbefore\fR any data is processed (e.g. before any \fBEVP_DecryptUpdate()\fR +calls). For \s-1SIV\s0 mode the taglen must be 16. +.PP +\&\s-1SIV\s0 mode makes two passes over the input data, thus, only one call to +\&\fBEVP_CipherUpdate()\fR, \fBEVP_EncryptUpdate()\fR or \fBEVP_DecryptUpdate()\fR should be made +with \fIout\fR set to a non\-\fB\s-1NULL\s0\fR value. A call to \fBEVP_DecryptFinal()\fR or +\&\fBEVP_CipherFinal()\fR is not required, but will indicate if the update +operation succeeded. .SS "ChaCha20\-Poly1305" .IX Subsection "ChaCha20-Poly1305" The following \fIctrl\fRs are supported for the ChaCha20\-Poly1305 \s-1AEAD\s0 algorithm. .IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_SET_IVLEN,\s0 ivlen, \s-1NULL\s0)" 4 .IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)" -Sets the nonce length. This call can only be made before specifying the nonce. -If not called a default nonce length of 12 (i.e. 96 bits) is used. The maximum -nonce length is 12 bytes (i.e. 96\-bits). If a nonce of less than 12 bytes is set -then the nonce is automatically padded with leading 0 bytes to make it 12 bytes -in length. +Sets the nonce length. This call is now redundant since the only valid value +is the default length of 12 (i.e. 96 bits). +Prior to OpenSSL 3.0 a nonce of less than 12 bytes could be used to automatically +pad the iv with leading 0 bytes to make it 12 bytes in length. .IP "EVP_CIPHER_CTX_ctrl(ctx, \s-1EVP_CTRL_AEAD_GET_TAG,\s0 taglen, tag)" 4 .IX Item "EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)" Writes \f(CW\*(C`taglen\*(C'\fR bytes of the tag value to the buffer indicated by \f(CW\*(C`tag\*(C'\fR. @@ -550,12 +1447,14 @@ 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. .PP -The functions \fBEVP_EncryptInit()\fR, \fBEVP_EncryptFinal()\fR, \fBEVP_DecryptInit()\fR, -\&\fBEVP_CipherInit()\fR and \fBEVP_CipherFinal()\fR are obsolete but are retained for -compatibility with existing code. New code should use \fBEVP_EncryptInit_ex()\fR, -\&\fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptInit_ex()\fR, \fBEVP_DecryptFinal_ex()\fR, -\&\fBEVP_CipherInit_ex()\fR and \fBEVP_CipherFinal_ex()\fR because they can reuse an -existing context without allocating and freeing it up on each call. +The functions \fBEVP_EncryptInit()\fR, \fBEVP_EncryptInit_ex()\fR, +\&\fBEVP_EncryptFinal()\fR, \fBEVP_DecryptInit()\fR, \fBEVP_DecryptInit_ex()\fR, +\&\fBEVP_CipherInit()\fR, \fBEVP_CipherInit_ex()\fR and \fBEVP_CipherFinal()\fR are obsolete +but are retained for compatibility with existing code. New code should +use \fBEVP_EncryptInit_ex2()\fR, \fBEVP_EncryptFinal_ex()\fR, \fBEVP_DecryptInit_ex2()\fR, +\&\fBEVP_DecryptFinal_ex()\fR, \fBEVP_CipherInit_ex2()\fR and \fBEVP_CipherFinal_ex()\fR +because they can reuse an existing context without allocating and freeing +it up on each call. .PP There are some differences between functions \fBEVP_CipherInit()\fR and \&\fBEVP_CipherInit_ex()\fR, significant in some circumstances. \fBEVP_CipherInit()\fR fills @@ -566,6 +1465,12 @@ removed, and it is especially important for the \&\fB\s-1EVP_CIPHER_CTX_FLAG_WRAP_ALLOW\s0\fR flag treated specially in \&\fBEVP_CipherInit_ex()\fR. .PP +Ignoring failure returns of the \fB\s-1EVP_CIPHER_CTX\s0\fR initialization functions can +lead to subsequent undefined behavior when calling the functions that update or +finalize the context. The only valid calls on the \fB\s-1EVP_CIPHER_CTX\s0\fR when +initialization fails are calls that attempt another initialization of the +context or release the context. +.PP \&\fBEVP_get_cipherbynid()\fR, and \fBEVP_get_cipherbyobj()\fR are implemented as macros. .SH "BUGS" .IX Header "BUGS" @@ -597,7 +1502,11 @@ Encrypt a string using \s-1IDEA:\s0 \& FILE *out; \& \& ctx = EVP_CIPHER_CTX_new(); -\& EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv); +\& if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) { +\& /* Error */ +\& EVP_CIPHER_CTX_free(ctx); +\& return 0; +\& } \& \& if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) { \& /* Error */ @@ -659,13 +1568,21 @@ with a 128\-bit key: \& \& /* Don\*(Aqt set key or IV right away; we want to check lengths */ \& ctx = EVP_CIPHER_CTX_new(); -\& EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, -\& do_encrypt); -\& OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16); -\& OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16); +\& if (!EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL, +\& do_encrypt, NULL)) { +\& /* Error */ +\& EVP_CIPHER_CTX_free(ctx); +\& return 0; +\& } +\& OPENSSL_assert(EVP_CIPHER_CTX_get_key_length(ctx) == 16); +\& OPENSSL_assert(EVP_CIPHER_CTX_get_iv_length(ctx) == 16); \& \& /* Now we can set key and IV */ -\& EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); +\& if (!EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL)) { +\& /* Error */ +\& EVP_CIPHER_CTX_free(ctx); +\& return 0; +\& } \& \& for (;;) { \& inlen = fread(inbuf, 1, 1024, in); @@ -689,26 +1606,76 @@ with a 128\-bit key: \& return 1; \& } .Ve +.PP +Encryption using AES-CBC with a 256\-bit key with \*(L"\s-1CS1\*(R"\s0 ciphertext stealing. +.PP +.Vb 10 +\& int encrypt(const unsigned char *key, const unsigned char *iv, +\& const unsigned char *msg, size_t msg_len, unsigned char *out) +\& { +\& /* +\& * This assumes that key size is 32 bytes and the iv is 16 bytes. +\& * For ciphertext stealing mode the length of the ciphertext "out" will be +\& * the same size as the plaintext size "msg_len". +\& * The "msg_len" can be any size >= 16. +\& */ +\& int ret = 0, encrypt = 1, outlen, len; +\& EVP_CIPHER_CTX *ctx = NULL; +\& EVP_CIPHER *cipher = NULL; +\& OSSL_PARAM params[2]; +\& +\& ctx = EVP_CIPHER_CTX_new(); +\& cipher = EVP_CIPHER_fetch(NULL, "AES\-256\-CBC\-CTS", NULL); +\& if (ctx == NULL || cipher == NULL) +\& goto err; +\& +\& /* +\& * The default is "CS1" so this is not really needed, +\& * but would be needed to set either "CS2" or "CS3". +\& */ +\& params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE, +\& "CS1", 0); +\& params[1] = OSSL_PARAM_construct_end(); +\& +\& if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params)) +\& goto err; +\& +\& /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */ +\& if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len)) +\& goto err; +\& if (!EVP_CipherFinal_ex(ctx, out + outlen, &len)) +\& goto err; +\& ret = 1; +\& err: +\& EVP_CIPHER_free(cipher); +\& EVP_CIPHER_CTX_free(ctx); +\& return ret; +\& } +.Ve .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fBevp\fR\|(7) +\&\fBevp\fR\|(7), +\&\fBproperty\fR\|(7), +\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7), +\&\fBprovider\-cipher\fR\|(7), +\&\fBlife_cycle\-cipher\fR\|(7) .PP Supported ciphers are listed in: .PP -\&\fBEVP_aes\fR\|(3), -\&\fBEVP_aria\fR\|(3), -\&\fBEVP_bf\fR\|(3), -\&\fBEVP_camellia\fR\|(3), -\&\fBEVP_cast5\fR\|(3), +\&\fBEVP_aes_128_gcm\fR\|(3), +\&\fBEVP_aria_128_gcm\fR\|(3), +\&\fBEVP_bf_cbc\fR\|(3), +\&\fBEVP_camellia_128_ecb\fR\|(3), +\&\fBEVP_cast5_cbc\fR\|(3), \&\fBEVP_chacha20\fR\|(3), -\&\fBEVP_des\fR\|(3), -\&\fBEVP_desx\fR\|(3), -\&\fBEVP_idea\fR\|(3), -\&\fBEVP_rc2\fR\|(3), +\&\fBEVP_des_cbc\fR\|(3), +\&\fBEVP_desx_cbc\fR\|(3), +\&\fBEVP_idea_cbc\fR\|(3), +\&\fBEVP_rc2_cbc\fR\|(3), \&\fBEVP_rc4\fR\|(3), -\&\fBEVP_rc5\fR\|(3), -\&\fBEVP_seed\fR\|(3), -\&\fBEVP_sm4\fR\|(3) +\&\fBEVP_rc5_32_12_16_cbc\fR\|(3), +\&\fBEVP_seed_cbc\fR\|(3), +\&\fBEVP_sm4_cbc\fR\|(3), .SH "HISTORY" .IX Header "HISTORY" Support for \s-1OCB\s0 mode was added in OpenSSL 1.1.0. @@ -717,11 +1684,39 @@ Support for \s-1OCB\s0 mode was added in OpenSSL 1.1.0. \&\fBEVP_CIPHER_CTX_reset()\fR appeared and \fBEVP_CIPHER_CTX_cleanup()\fR disappeared. \fBEVP_CIPHER_CTX_init()\fR remains as an alias for \&\fBEVP_CIPHER_CTX_reset()\fR. +.PP +The \fBEVP_CIPHER_CTX_cipher()\fR function was deprecated in OpenSSL 3.0; use +\&\fBEVP_CIPHER_CTX_get0_cipher()\fR instead. +.PP +The \fBEVP_EncryptInit_ex2()\fR, \fBEVP_DecryptInit_ex2()\fR, \fBEVP_CipherInit_ex2()\fR, +\&\fBEVP_CIPHER_fetch()\fR, \fBEVP_CIPHER_free()\fR, \fBEVP_CIPHER_up_ref()\fR, +\&\fBEVP_CIPHER_CTX_get0_cipher()\fR, \fBEVP_CIPHER_CTX_get1_cipher()\fR, +\&\fBEVP_CIPHER_get_params()\fR, \fBEVP_CIPHER_CTX_set_params()\fR, +\&\fBEVP_CIPHER_CTX_get_params()\fR, \fBEVP_CIPHER_gettable_params()\fR, +\&\fBEVP_CIPHER_settable_ctx_params()\fR, \fBEVP_CIPHER_gettable_ctx_params()\fR, +\&\fBEVP_CIPHER_CTX_settable_params()\fR and \fBEVP_CIPHER_CTX_gettable_params()\fR +functions were added in 3.0. +.PP +The \fBEVP_CIPHER_nid()\fR, \fBEVP_CIPHER_name()\fR, \fBEVP_CIPHER_block_size()\fR, +\&\fBEVP_CIPHER_key_length()\fR, \fBEVP_CIPHER_iv_length()\fR, \fBEVP_CIPHER_flags()\fR, +\&\fBEVP_CIPHER_mode()\fR, \fBEVP_CIPHER_type()\fR, \fBEVP_CIPHER_CTX_nid()\fR, +\&\fBEVP_CIPHER_CTX_block_size()\fR, \fBEVP_CIPHER_CTX_key_length()\fR, +\&\fBEVP_CIPHER_CTX_iv_length()\fR, \fBEVP_CIPHER_CTX_tag_length()\fR, +\&\fBEVP_CIPHER_CTX_num()\fR, \fBEVP_CIPHER_CTX_type()\fR, and \fBEVP_CIPHER_CTX_mode()\fR +functions were renamed to include \f(CW\*(C`get\*(C'\fR or \f(CW\*(C`get0\*(C'\fR in their names in +OpenSSL 3.0, respectively. The old names are kept as non-deprecated +alias macros. +.PP +The \fBEVP_CIPHER_CTX_encrypting()\fR function was renamed to +\&\fBEVP_CIPHER_CTX_is_encrypting()\fR in OpenSSL 3.0. The old name is kept as +non-deprecated alias macro. +.PP +The \fBEVP_CIPHER_CTX_flags()\fR macro was deprecated in OpenSSL 1.1.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>. |