1=pod 2 3=head1 NAME 4 5EVP_CIPHER_fetch, 6EVP_CIPHER_up_ref, 7EVP_CIPHER_free, 8EVP_CIPHER_CTX_new, 9EVP_CIPHER_CTX_reset, 10EVP_CIPHER_CTX_free, 11EVP_EncryptInit_ex, 12EVP_EncryptInit_ex2, 13EVP_EncryptUpdate, 14EVP_EncryptFinal_ex, 15EVP_DecryptInit_ex, 16EVP_DecryptInit_ex2, 17EVP_DecryptUpdate, 18EVP_DecryptFinal_ex, 19EVP_CipherInit_ex, 20EVP_CipherInit_ex2, 21EVP_CipherUpdate, 22EVP_CipherFinal_ex, 23EVP_CIPHER_CTX_set_key_length, 24EVP_CIPHER_CTX_ctrl, 25EVP_EncryptInit, 26EVP_EncryptFinal, 27EVP_DecryptInit, 28EVP_DecryptFinal, 29EVP_CipherInit, 30EVP_CipherFinal, 31EVP_Cipher, 32EVP_get_cipherbyname, 33EVP_get_cipherbynid, 34EVP_get_cipherbyobj, 35EVP_CIPHER_is_a, 36EVP_CIPHER_get0_name, 37EVP_CIPHER_get0_description, 38EVP_CIPHER_names_do_all, 39EVP_CIPHER_get0_provider, 40EVP_CIPHER_get_nid, 41EVP_CIPHER_get_params, 42EVP_CIPHER_gettable_params, 43EVP_CIPHER_get_block_size, 44EVP_CIPHER_get_key_length, 45EVP_CIPHER_get_iv_length, 46EVP_CIPHER_get_flags, 47EVP_CIPHER_get_mode, 48EVP_CIPHER_get_type, 49EVP_CIPHER_CTX_cipher, 50EVP_CIPHER_CTX_get0_cipher, 51EVP_CIPHER_CTX_get1_cipher, 52EVP_CIPHER_CTX_get0_name, 53EVP_CIPHER_CTX_get_nid, 54EVP_CIPHER_CTX_get_params, 55EVP_CIPHER_gettable_ctx_params, 56EVP_CIPHER_CTX_gettable_params, 57EVP_CIPHER_CTX_set_params, 58EVP_CIPHER_settable_ctx_params, 59EVP_CIPHER_CTX_settable_params, 60EVP_CIPHER_CTX_get_block_size, 61EVP_CIPHER_CTX_get_key_length, 62EVP_CIPHER_CTX_get_iv_length, 63EVP_CIPHER_CTX_get_tag_length, 64EVP_CIPHER_CTX_get_app_data, 65EVP_CIPHER_CTX_set_app_data, 66EVP_CIPHER_CTX_flags, 67EVP_CIPHER_CTX_set_flags, 68EVP_CIPHER_CTX_clear_flags, 69EVP_CIPHER_CTX_test_flags, 70EVP_CIPHER_CTX_get_type, 71EVP_CIPHER_CTX_get_mode, 72EVP_CIPHER_CTX_get_num, 73EVP_CIPHER_CTX_set_num, 74EVP_CIPHER_CTX_is_encrypting, 75EVP_CIPHER_param_to_asn1, 76EVP_CIPHER_asn1_to_param, 77EVP_CIPHER_CTX_set_padding, 78EVP_enc_null, 79EVP_CIPHER_do_all_provided, 80EVP_CIPHER_nid, 81EVP_CIPHER_name, 82EVP_CIPHER_block_size, 83EVP_CIPHER_key_length, 84EVP_CIPHER_iv_length, 85EVP_CIPHER_flags, 86EVP_CIPHER_mode, 87EVP_CIPHER_type, 88EVP_CIPHER_CTX_encrypting, 89EVP_CIPHER_CTX_nid, 90EVP_CIPHER_CTX_block_size, 91EVP_CIPHER_CTX_key_length, 92EVP_CIPHER_CTX_iv_length, 93EVP_CIPHER_CTX_tag_length, 94EVP_CIPHER_CTX_num, 95EVP_CIPHER_CTX_type, 96EVP_CIPHER_CTX_mode 97- EVP cipher routines 98 99=head1 SYNOPSIS 100 101=for openssl generic 102 103 #include <openssl/evp.h> 104 105 EVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, 106 const char *properties); 107 int EVP_CIPHER_up_ref(EVP_CIPHER *cipher); 108 void EVP_CIPHER_free(EVP_CIPHER *cipher); 109 EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); 110 int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx); 111 void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); 112 113 int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 114 ENGINE *impl, const unsigned char *key, const unsigned char *iv); 115 int EVP_EncryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 116 const unsigned char *key, const unsigned char *iv, 117 const OSSL_PARAM params[]); 118 int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, 119 int *outl, const unsigned char *in, int inl); 120 int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); 121 122 int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 123 ENGINE *impl, const unsigned char *key, const unsigned char *iv); 124 int EVP_DecryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 125 const unsigned char *key, const unsigned char *iv, 126 const OSSL_PARAM params[]); 127 int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, 128 int *outl, const unsigned char *in, int inl); 129 int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); 130 131 int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 132 ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc); 133 int EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 134 const unsigned char *key, const unsigned char *iv, 135 int enc, const OSSL_PARAM params[]); 136 int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, 137 int *outl, const unsigned char *in, int inl); 138 int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); 139 140 int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 141 const unsigned char *key, const unsigned char *iv); 142 int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl); 143 144 int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 145 const unsigned char *key, const unsigned char *iv); 146 int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); 147 148 int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, 149 const unsigned char *key, const unsigned char *iv, int enc); 150 int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl); 151 152 int EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out, 153 const unsigned char *in, unsigned int inl); 154 155 int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); 156 int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); 157 int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int cmd, int p1, void *p2); 158 int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key); 159 void EVP_CIPHER_CTX_set_flags(EVP_CIPHER_CTX *ctx, int flags); 160 void EVP_CIPHER_CTX_clear_flags(EVP_CIPHER_CTX *ctx, int flags); 161 int EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags); 162 163 const EVP_CIPHER *EVP_get_cipherbyname(const char *name); 164 const EVP_CIPHER *EVP_get_cipherbynid(int nid); 165 const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a); 166 167 int EVP_CIPHER_get_nid(const EVP_CIPHER *e); 168 int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name); 169 int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher, 170 void (*fn)(const char *name, void *data), 171 void *data); 172 const char *EVP_CIPHER_get0_name(const EVP_CIPHER *cipher); 173 const char *EVP_CIPHER_get0_description(const EVP_CIPHER *cipher); 174 const OSSL_PROVIDER *EVP_CIPHER_get0_provider(const EVP_CIPHER *cipher); 175 int EVP_CIPHER_get_block_size(const EVP_CIPHER *e); 176 int EVP_CIPHER_get_key_length(const EVP_CIPHER *e); 177 int EVP_CIPHER_get_iv_length(const EVP_CIPHER *e); 178 unsigned long EVP_CIPHER_get_flags(const EVP_CIPHER *e); 179 unsigned long EVP_CIPHER_get_mode(const EVP_CIPHER *e); 180 int EVP_CIPHER_get_type(const EVP_CIPHER *cipher); 181 182 const EVP_CIPHER *EVP_CIPHER_CTX_get0_cipher(const EVP_CIPHER_CTX *ctx); 183 EVP_CIPHER *EVP_CIPHER_CTX_get1_cipher(const EVP_CIPHER_CTX *ctx); 184 int EVP_CIPHER_CTX_get_nid(const EVP_CIPHER_CTX *ctx); 185 const char *EVP_CIPHER_CTX_get0_name(const EVP_CIPHER_CTX *ctx); 186 187 int EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]); 188 int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]); 189 int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]); 190 const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher); 191 const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher); 192 const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher); 193 const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(EVP_CIPHER_CTX *ctx); 194 const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(EVP_CIPHER_CTX *ctx); 195 int EVP_CIPHER_CTX_get_block_size(const EVP_CIPHER_CTX *ctx); 196 int EVP_CIPHER_CTX_get_key_length(const EVP_CIPHER_CTX *ctx); 197 int EVP_CIPHER_CTX_get_iv_length(const EVP_CIPHER_CTX *ctx); 198 int EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx); 199 void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); 200 void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data); 201 int EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx); 202 int EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx); 203 int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx); 204 int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num); 205 int EVP_CIPHER_CTX_is_encrypting(const EVP_CIPHER_CTX *ctx); 206 207 int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); 208 int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); 209 210 void EVP_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx, 211 void (*fn)(EVP_CIPHER *cipher, void *arg), 212 void *arg); 213 214 #define EVP_CIPHER_nid EVP_CIPHER_get_nid 215 #define EVP_CIPHER_name EVP_CIPHER_get0_name 216 #define EVP_CIPHER_block_size EVP_CIPHER_get_block_size 217 #define EVP_CIPHER_key_length EVP_CIPHER_get_key_length 218 #define EVP_CIPHER_iv_length EVP_CIPHER_get_iv_length 219 #define EVP_CIPHER_flags EVP_CIPHER_get_flags 220 #define EVP_CIPHER_mode EVP_CIPHER_get_mode 221 #define EVP_CIPHER_type EVP_CIPHER_get_type 222 #define EVP_CIPHER_CTX_encrypting EVP_CIPHER_CTX_is_encrypting 223 #define EVP_CIPHER_CTX_nid EVP_CIPHER_CTX_get_nid 224 #define EVP_CIPHER_CTX_block_size EVP_CIPHER_CTX_get_block_size 225 #define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length 226 #define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length 227 #define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length 228 #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num 229 #define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type 230 #define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode 231 232The following function has been deprecated since OpenSSL 3.0, and can be 233hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 234see L<openssl_user_macros(7)>: 235 236 const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); 237 238The following function has been deprecated since OpenSSL 1.1.0, and can be 239hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 240see L<openssl_user_macros(7)>: 241 242 int EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx); 243 244=head1 DESCRIPTION 245 246The EVP cipher routines are a high-level interface to certain 247symmetric ciphers. 248 249The B<EVP_CIPHER> type is a structure for cipher method implementation. 250 251=over 4 252 253=item EVP_CIPHER_fetch() 254 255Fetches the cipher implementation for the given I<algorithm> from any provider 256offering it, within the criteria given by the I<properties>. 257See L<crypto(7)/ALGORITHM FETCHING> for further information. 258 259The returned value must eventually be freed with EVP_CIPHER_free(). 260 261Fetched B<EVP_CIPHER> structures are reference counted. 262 263=item EVP_CIPHER_up_ref() 264 265Increments the reference count for an B<EVP_CIPHER> structure. 266 267=item EVP_CIPHER_free() 268 269Decrements the reference count for the fetched B<EVP_CIPHER> structure. 270If the reference count drops to 0 then the structure is freed. 271 272=item EVP_CIPHER_CTX_new() 273 274Allocates and returns a cipher context. 275 276=item EVP_CIPHER_CTX_free() 277 278Clears all information from a cipher context and frees any allocated memory 279associated with it, including I<ctx> itself. This function should be called after 280all operations using a cipher are complete so sensitive information does not 281remain in memory. 282 283=item EVP_CIPHER_CTX_ctrl() 284 285I<This is a legacy method.> EVP_CIPHER_CTX_set_params() and 286EVP_CIPHER_CTX_get_params() is the mechanism that should be used to set and get 287parameters that are used by providers. 288 289Performs cipher-specific control actions on context I<ctx>. The control command 290is indicated in I<cmd> and any additional arguments in I<p1> and I<p2>. 291EVP_CIPHER_CTX_ctrl() must be called after EVP_CipherInit_ex2(). Other restrictions 292may apply depending on the control type and cipher implementation. 293 294If this function happens to be used with a fetched B<EVP_CIPHER>, it will 295translate the controls that are known to OpenSSL into L<OSSL_PARAM(3)> 296parameters with keys defined by OpenSSL and call EVP_CIPHER_CTX_get_params() or 297EVP_CIPHER_CTX_set_params() as is appropriate for each control command. 298 299See L</CONTROLS> below for more information, including what translations are 300being done. 301 302=item EVP_CIPHER_get_params() 303 304Retrieves the requested list of algorithm I<params> from a CIPHER I<cipher>. 305See L</PARAMETERS> below for more information. 306 307=item EVP_CIPHER_CTX_get_params() 308 309Retrieves the requested list of I<params> from CIPHER context I<ctx>. 310See L</PARAMETERS> below for more information. 311 312=item EVP_CIPHER_CTX_set_params() 313 314Sets the list of I<params> into a CIPHER context I<ctx>. 315See L</PARAMETERS> below for more information. 316 317=item EVP_CIPHER_gettable_params() 318 319Get a constant L<OSSL_PARAM(3)> array that describes the retrievable parameters 320that can be used with EVP_CIPHER_get_params(). 321 322=item EVP_CIPHER_gettable_ctx_params() and EVP_CIPHER_CTX_gettable_params() 323 324Get a constant L<OSSL_PARAM(3)> array that describes the retrievable parameters 325that can be used with EVP_CIPHER_CTX_get_params(). 326EVP_CIPHER_gettable_ctx_params() returns the parameters that can be retrieved 327from the algorithm, whereas EVP_CIPHER_CTX_gettable_params() returns the 328parameters that can be retrieved in the context's current state. 329 330=item EVP_CIPHER_settable_ctx_params() and EVP_CIPHER_CTX_settable_params() 331 332Get a constant L<OSSL_PARAM(3)> array that describes the settable parameters 333that can be used with EVP_CIPHER_CTX_set_params(). 334EVP_CIPHER_settable_ctx_params() returns the parameters that can be set from the 335algorithm, whereas EVP_CIPHER_CTX_settable_params() returns the parameters that 336can be set in the context's current state. 337 338=item EVP_EncryptInit_ex2() 339 340Sets up cipher context I<ctx> for encryption with cipher I<type>. I<type> is 341typically supplied by calling EVP_CIPHER_fetch(). I<type> may also be set 342using legacy functions such as EVP_aes_256_cbc(), but this is not recommended 343for new applications. I<key> is the symmetric key to use and I<iv> is the IV to 344use (if necessary), the actual number of bytes used for the key and IV depends 345on the cipher. The parameters I<params> will be set on the context after 346initialisation. It is possible to set all parameters to NULL except I<type> in 347an initial call and supply the remaining parameters in subsequent calls, all of 348which have I<type> set to NULL. This is done when the default cipher parameters 349are not appropriate. 350For B<EVP_CIPH_GCM_MODE> the IV will be generated internally if it is not 351specified. 352 353=item EVP_EncryptInit_ex() 354 355This legacy function is similar to EVP_EncryptInit_ex2() when I<impl> is NULL. 356The implementation of the I<type> from the I<impl> engine will be used if it 357exists. 358 359=item EVP_EncryptUpdate() 360 361Encrypts I<inl> bytes from the buffer I<in> and writes the encrypted version to 362I<out>. The pointers I<out> and I<in> may point to the same location, in which 363case the encryption will be done in-place. If I<out> and I<in> point to different 364locations, the two buffers must be disjoint, otherwise the operation might fail 365or the outcome might be undefined. 366 367This function can be called multiple times to encrypt successive blocks 368of data. The amount of data written depends on the block alignment of the 369encrypted data. 370For most ciphers and modes, the amount of data written can be anything 371from zero bytes to (inl + cipher_block_size - 1) bytes. 372For wrap cipher modes, the amount of data written can be anything 373from zero bytes to (inl + cipher_block_size) bytes. 374For stream ciphers, the amount of data written can be anything from zero 375bytes to inl bytes. 376Thus, the buffer pointed to by I<out> must contain sufficient room for the 377operation being performed. 378The actual number of bytes written is placed in I<outl>. 379 380If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts 381the "final" data, that is any data that remains in a partial block. 382It uses standard block padding (aka PKCS padding) as described in 383the NOTES section, below. The encrypted 384final data is written to I<out> which should have sufficient space for 385one cipher block. The number of bytes written is placed in I<outl>. After 386this function is called the encryption operation is finished and no further 387calls to EVP_EncryptUpdate() should be made. 388 389If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more 390data and it will return an error if any data remains in a partial block: 391that is if the total data length is not a multiple of the block size. 392 393=item EVP_DecryptInit_ex2(), EVP_DecryptInit_ex(), EVP_DecryptUpdate() 394and EVP_DecryptFinal_ex() 395 396These functions are the corresponding decryption operations. 397EVP_DecryptFinal() will return an error code if padding is enabled and the 398final block is not correctly formatted. The parameters and restrictions are 399identical to the encryption operations except that if padding is enabled the 400decrypted data buffer I<out> passed to EVP_DecryptUpdate() should have 401sufficient room for (I<inl> + cipher_block_size) bytes unless the cipher block 402size is 1 in which case I<inl> bytes is sufficient. 403 404=item EVP_CipherInit_ex2(), EVP_CipherInit_ex(), EVP_CipherUpdate() and 405EVP_CipherFinal_ex() 406 407These functions can be used for decryption or encryption. The operation 408performed depends on the value of the I<enc> parameter. It should be set to 1 409for encryption, 0 for decryption and -1 to leave the value unchanged 410(the actual value of 'enc' being supplied in a previous call). 411 412=item EVP_CIPHER_CTX_reset() 413 414Clears all information from a cipher context and free up any allocated memory 415associated with it, except the I<ctx> itself. This function should be called 416anytime I<ctx> is reused by another 417EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal() series of calls. 418 419=item EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() 420 421Behave in a similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and 422EVP_CipherInit_ex() except if the I<type> is not a fetched cipher they use the 423default implementation of the I<type>. 424 425=item EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() 426 427Identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and 428EVP_CipherFinal_ex(). In previous releases they also cleaned up 429the I<ctx>, but this is no longer done and EVP_CIPHER_CTX_cleanup() 430must be called to free any context resources. 431 432=item EVP_Cipher() 433 434Encrypts or decrypts a maximum I<inl> amount of bytes from I<in> and leaves the 435result in I<out>. 436 437For legacy ciphers - If the cipher doesn't have the flag 438B<EVP_CIPH_FLAG_CUSTOM_CIPHER> set, then I<inl> must be a multiple of 439EVP_CIPHER_get_block_size(). If it isn't, the result is undefined. If the cipher 440has that flag set, then I<inl> can be any size. 441 442Due to the constraints of the API contract of this function it shouldn't be used 443in applications, please consider using EVP_CipherUpdate() and 444EVP_CipherFinal_ex() instead. 445 446=item EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() 447 448Returns an B<EVP_CIPHER> structure when passed a cipher name, a cipher B<NID> or 449an B<ASN1_OBJECT> structure respectively. 450 451EVP_get_cipherbyname() will return NULL for algorithms such as "AES-128-SIV", 452"AES-128-CBC-CTS" and "CAMELLIA-128-CBC-CTS" which were previously only 453accessible via low level interfaces. 454 455The EVP_get_cipherbyname() function is present for backwards compatibility with 456OpenSSL prior to version 3 and is different to the EVP_CIPHER_fetch() function 457since it does not attempt to "fetch" an implementation of the cipher. 458Additionally, it only knows about ciphers that are built-in to OpenSSL and have 459an associated NID. Similarly EVP_get_cipherbynid() and EVP_get_cipherbyobj() 460also return objects without an associated implementation. 461 462When the cipher objects returned by these functions are used (such as in a call 463to EVP_EncryptInit_ex()) an implementation of the cipher will be implicitly 464fetched from the loaded providers. This fetch could fail if no suitable 465implementation is available. Use EVP_CIPHER_fetch() instead to explicitly fetch 466the algorithm and an associated implementation from a provider. 467 468See L<crypto(7)/ALGORITHM FETCHING> for more information about fetching. 469 470The cipher objects returned from these functions do not need to be freed with 471EVP_CIPHER_free(). 472 473=item EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid() 474 475Return the NID of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> 476structure. The actual NID value is an internal value which may not have a 477corresponding OBJECT IDENTIFIER. 478 479=item EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags() 480 481Sets, clears and tests I<ctx> flags. See L</FLAGS> below for more information. 482 483For provided ciphers EVP_CIPHER_CTX_set_flags() should be called only after the 484fetched cipher has been assigned to the I<ctx>. It is recommended to use 485L</PARAMETERS> instead. 486 487=item EVP_CIPHER_CTX_set_padding() 488 489Enables or disables padding. This function should be called after the context 490is set up for encryption or decryption with EVP_EncryptInit_ex2(), 491EVP_DecryptInit_ex2() or EVP_CipherInit_ex2(). By default encryption operations 492are padded using standard block padding and the padding is checked and removed 493when decrypting. If the I<pad> parameter is zero then no padding is 494performed, the total amount of data encrypted or decrypted must then 495be a multiple of the block size or an error will occur. 496 497=item EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length() 498 499Return the key length of a cipher when passed an B<EVP_CIPHER> or 500B<EVP_CIPHER_CTX> structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum 501key length for all ciphers. Note: although EVP_CIPHER_get_key_length() is fixed for 502a given cipher, the value of EVP_CIPHER_CTX_get_key_length() may be different for 503variable key length ciphers. 504 505=item EVP_CIPHER_CTX_set_key_length() 506 507Sets the key length of the cipher context. 508If the cipher is a fixed length cipher then attempting to set the key 509length to any value other than the fixed value is an error. 510 511=item EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length() 512 513Return the IV length of a cipher when passed an B<EVP_CIPHER> or 514B<EVP_CIPHER_CTX>. It will return zero if the cipher does not use an IV. 515The constant B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers. 516 517=item EVP_CIPHER_CTX_get_tag_length() 518 519Returns the tag length of an AEAD cipher when passed a B<EVP_CIPHER_CTX>. It will 520return zero if the cipher does not support a tag. It returns a default value if 521the tag length has not been set. 522 523=item EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size() 524 525Return the block size of a cipher when passed an B<EVP_CIPHER> or 526B<EVP_CIPHER_CTX> structure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the 527maximum block length for all ciphers. 528 529=item EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type() 530 531Return the type of the passed cipher or context. This "type" is the actual NID 532of the cipher OBJECT IDENTIFIER and as such it ignores the cipher parameters 533(40 bit RC2 and 128 bit RC2 have the same NID). If the cipher does not have an 534object identifier or does not have ASN1 support this function will return 535B<NID_undef>. 536 537=item EVP_CIPHER_is_a() 538 539Returns 1 if I<cipher> is an implementation of an algorithm that's identifiable 540with I<name>, otherwise 0. If I<cipher> is a legacy cipher (it's the return 541value from the likes of EVP_aes128() rather than the result of an 542EVP_CIPHER_fetch()), only cipher names registered with the default library 543context (see L<OSSL_LIB_CTX(3)>) will be considered. 544 545=item EVP_CIPHER_get0_name() and EVP_CIPHER_CTX_get0_name() 546 547Return the name of the passed cipher or context. For fetched ciphers with 548multiple names, only one of them is returned. See also EVP_CIPHER_names_do_all(). 549 550=item EVP_CIPHER_names_do_all() 551 552Traverses all names for the I<cipher>, and calls I<fn> with each name and 553I<data>. This is only useful with fetched B<EVP_CIPHER>s. 554 555=item EVP_CIPHER_get0_description() 556 557Returns a description of the cipher, meant for display and human consumption. 558The description is at the discretion of the cipher implementation. 559 560=item EVP_CIPHER_get0_provider() 561 562Returns an B<OSSL_PROVIDER> pointer to the provider that implements the given 563B<EVP_CIPHER>. 564 565=item EVP_CIPHER_CTX_get0_cipher() 566 567Returns the B<EVP_CIPHER> structure when passed an B<EVP_CIPHER_CTX> structure. 568EVP_CIPHER_CTX_get1_cipher() is the same except the ownership is passed to 569the caller. 570 571=item EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode() 572 573Return the block cipher mode: 574EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, 575EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, 576EVP_CIPH_WRAP_MODE, EVP_CIPH_OCB_MODE or EVP_CIPH_SIV_MODE. 577If the cipher is a stream cipher then EVP_CIPH_STREAM_CIPHER is returned. 578 579=item EVP_CIPHER_get_flags() 580 581Returns any flags associated with the cipher. See L</FLAGS> 582for a list of currently defined flags. 583 584=item EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num() 585 586Gets or sets the cipher specific "num" parameter for the associated I<ctx>. 587Built-in ciphers typically use this to track how much of the current underlying block 588has been "used" already. 589 590=item EVP_CIPHER_CTX_is_encrypting() 591 592Reports whether the I<ctx> is being used for encryption or decryption. 593 594=item EVP_CIPHER_CTX_flags() 595 596A deprecated macro calling C<EVP_CIPHER_get_flags(EVP_CIPHER_CTX_get0_cipher(ctx))>. 597Do not use. 598 599=item EVP_CIPHER_param_to_asn1() 600 601Sets the AlgorithmIdentifier "parameter" based on the passed cipher. This will 602typically include any parameters and an IV. The cipher IV (if any) must be set 603when this call is made. This call should be made before the cipher is actually 604"used" (before any EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). 605This function may fail if the cipher does not have any ASN1 support. 606 607=item EVP_CIPHER_asn1_to_param() 608 609Sets the cipher parameters based on an ASN1 AlgorithmIdentifier "parameter". 610The precise effect depends on the cipher. In the case of B<RC2>, for example, 611it will set the IV and effective key length. 612This function should be called after the base cipher type is set but before 613the key is set. For example EVP_CipherInit() will be called with the IV and 614key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally 615EVP_CipherInit() again with all parameters except the key set to NULL. It is 616possible for this function to fail if the cipher does not have any ASN1 support 617or the parameters cannot be set (for example the RC2 effective key length 618is not supported. 619 620=item EVP_CIPHER_CTX_rand_key() 621 622Generates a random key of the appropriate length based on the cipher context. 623The B<EVP_CIPHER> can provide its own random key generation routine to support 624keys of a specific form. I<key> must point to a buffer at least as big as the 625value returned by EVP_CIPHER_CTX_get_key_length(). 626 627=item EVP_CIPHER_do_all_provided() 628 629Traverses all ciphers implemented by all activated providers in the given 630library context I<libctx>, and for each of the implementations, calls the given 631function I<fn> with the implementation method and the given I<arg> as argument. 632 633=back 634 635=head1 PARAMETERS 636 637See L<OSSL_PARAM(3)> for information about passing parameters. 638 639=head2 Gettable EVP_CIPHER parameters 640 641When EVP_CIPHER_fetch() is called it internally calls EVP_CIPHER_get_params() 642and caches the results. 643 644EVP_CIPHER_get_params() can be used with the following L<OSSL_PARAM(3)> keys: 645 646=over 4 647 648=item "mode" (B<OSSL_CIPHER_PARAM_MODE>) <unsigned integer> 649 650Gets the mode for the associated cipher algorithm I<cipher>. 651See L</EVP_CIPHER_get_mode() and EVP_CIPHER_CTX_get_mode()> for a list of valid modes. 652Use EVP_CIPHER_get_mode() to retrieve the cached value. 653 654=item "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>) <unsigned integer> 655 656Gets the key length for the associated cipher algorithm I<cipher>. 657Use EVP_CIPHER_get_key_length() to retrieve the cached value. 658 659=item "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>) <unsigned integer> 660 661Gets the IV length for the associated cipher algorithm I<cipher>. 662Use EVP_CIPHER_get_iv_length() to retrieve the cached value. 663 664=item "blocksize" (B<OSSL_CIPHER_PARAM_BLOCK_SIZE>) <unsigned integer> 665 666Gets the block size for the associated cipher algorithm I<cipher>. 667The block size should be 1 for stream ciphers. 668Note that the block size for a cipher may be different to the block size for 669the underlying encryption/decryption primitive. 670For example AES in CTR mode has a block size of 1 (because it operates like a 671stream cipher), even though AES has a block size of 16. 672Use EVP_CIPHER_get_block_size() to retrieve the cached value. 673 674=item "aead" (B<OSSL_CIPHER_PARAM_AEAD>) <integer> 675 676Gets 1 if this is an AEAD cipher algorithm, otherwise it gets 0. 677Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_AEAD_CIPHER) to retrieve the 678cached value. 679 680=item "custom-iv" (B<OSSL_CIPHER_PARAM_CUSTOM_IV>) <integer> 681 682Gets 1 if the cipher algorithm I<cipher> has a custom IV, otherwise it gets 0. 683Storing and initializing the IV is left entirely to the implementation, if a 684custom IV is used. 685Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_CUSTOM_IV) to retrieve the 686cached value. 687 688=item "cts" (B<OSSL_CIPHER_PARAM_CTS>) <integer> 689 690Gets 1 if the cipher algorithm I<cipher> uses ciphertext stealing, 691otherwise it gets 0. 692This is currently used to indicate that the cipher is a one shot that only 693allows a single call to EVP_CipherUpdate(). 694Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_CTS) to retrieve the 695cached value. 696 697=item "tls-multi" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK>) <integer> 698 699Gets 1 if the cipher algorithm I<cipher> supports interleaving of crypto blocks, 700otherwise it gets 0. The interleaving is an optimization only applicable to certain 701TLS ciphers. 702Use (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK) to retrieve the 703cached value. 704 705=item "has-randkey" (B<OSSL_CIPHER_PARAM_HAS_RANDKEY>) <integer> 706 707Gets 1 if the cipher algorithm I<cipher> supports the gettable EVP_CIPHER_CTX 708parameter B<OSSL_CIPHER_PARAM_RANDOM_KEY>. Only DES and 3DES set this to 1, 709all other OpenSSL ciphers return 0. 710 711=back 712 713=head2 Gettable and Settable EVP_CIPHER_CTX parameters 714 715The following L<OSSL_PARAM(3)> keys can be used with both EVP_CIPHER_CTX_get_params() 716and EVP_CIPHER_CTX_set_params(). 717 718=over 4 719 720=item "padding" (B<OSSL_CIPHER_PARAM_PADDING>) <unsigned integer> 721 722Gets or sets the padding mode for the cipher context I<ctx>. 723Padding is enabled if the value is 1, and disabled if the value is 0. 724See also EVP_CIPHER_CTX_set_padding(). 725 726=item "num" (B<OSSL_CIPHER_PARAM_NUM>) <unsigned integer> 727 728Gets or sets the cipher specific "num" parameter for the cipher context I<ctx>. 729Built-in ciphers typically use this to track how much of the current underlying 730block has been "used" already. 731See also EVP_CIPHER_CTX_get_num() and EVP_CIPHER_CTX_set_num(). 732 733=item "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>) <unsigned integer> 734 735Gets or sets the key length for the cipher context I<ctx>. 736The length of the "keylen" parameter should not exceed that of a B<size_t>. 737See also EVP_CIPHER_CTX_get_key_length() and EVP_CIPHER_CTX_set_key_length(). 738 739=item "tag" (B<OSSL_CIPHER_PARAM_AEAD_TAG>) <octet string> 740 741Gets or sets the AEAD tag for the associated cipher context I<ctx>. 742See L<EVP_EncryptInit(3)/AEAD Interface>. 743 744=item "keybits" (B<OSSL_CIPHER_PARAM_RC2_KEYBITS>) <unsigned integer> 745 746Gets or sets the effective keybits used for a RC2 cipher. 747The length of the "keybits" parameter should not exceed that of a B<size_t>. 748 749=item "rounds" (B<OSSL_CIPHER_PARAM_ROUNDS>) <unsigned integer> 750 751Gets or sets the number of rounds to be used for a cipher. 752This is used by the RC5 cipher. 753 754=item "alg_id_param" (B<OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS>) <octet string> 755 756Used to pass the DER encoded AlgorithmIdentifier parameter to or from 757the cipher implementation. Functions like L<EVP_CIPHER_param_to_asn1(3)> 758and L<EVP_CIPHER_asn1_to_param(3)> use this parameter for any implementation 759that has the flag B<EVP_CIPH_FLAG_CUSTOM_ASN1> set. 760 761=item "cts_mode" (B<OSSL_CIPHER_PARAM_CTS_MODE>) <UTF8 string> 762 763Gets or sets the cipher text stealing mode. For all modes the output size is the 764same as the input size. The input length must be greater than or equal to the 765block size. (The block size for AES and CAMELLIA is 16 bytes). 766 767Valid values for the mode are: 768 769=over 4 770 771=item "CS1" 772 773The NIST variant of cipher text stealing. 774For input lengths that are multiples of the block size it is equivalent to 775using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher otherwise the second last 776cipher text block is a partial block. 777 778=item "CS2" 779 780For input lengths that are multiples of the block size it is equivalent to 781using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher, otherwise it is the same as 782"CS3" mode. 783 784=item "CS3" 785 786The Kerberos5 variant of cipher text stealing which always swaps the last 787cipher text block with the previous block (which may be a partial or full block 788depending on the input length). If the input length is exactly one full block 789then this is equivalent to using a "AES-XXX-CBC" or "CAMELLIA-XXX-CBC" cipher. 790 791=back 792 793The default is "CS1". 794This is only supported for "AES-128-CBC-CTS", "AES-192-CBC-CTS", "AES-256-CBC-CTS", 795"CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS" and "CAMELLIA-256-CBC-CTS". 796 797=item "tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>) <unsigned integer> 798 799Sets or gets the number of records being sent in one go for a tls1 multiblock 800cipher operation (either 4 or 8 records). 801 802=back 803 804=head2 Gettable EVP_CIPHER_CTX parameters 805 806The following L<OSSL_PARAM(3)> keys can be used with EVP_CIPHER_CTX_get_params(): 807 808=over 4 809 810=item "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN> and <B<OSSL_CIPHER_PARAM_AEAD_IVLEN>) <unsigned integer> 811 812Gets the IV length for the cipher context I<ctx>. 813The length of the "ivlen" parameter should not exceed that of a B<size_t>. 814See also EVP_CIPHER_CTX_get_iv_length(). 815 816=item "iv" (B<OSSL_CIPHER_PARAM_IV>) <octet string OR octet ptr> 817 818Gets the IV used to initialize the associated cipher context I<ctx>. 819See also EVP_CIPHER_CTX_get_original_iv(). 820 821=item "updated-iv" (B<OSSL_CIPHER_PARAM_UPDATED_IV>) <octet string OR octet ptr> 822 823Gets the updated pseudo-IV state for the associated cipher context, e.g., 824the previous ciphertext block for CBC mode or the iteratively encrypted IV 825value for OFB mode. Note that octet pointer access is deprecated and is 826provided only for backwards compatibility with historical libcrypto APIs. 827See also EVP_CIPHER_CTX_get_updated_iv(). 828 829=item "randkey" (B<OSSL_CIPHER_PARAM_RANDOM_KEY>) <octet string> 830 831Gets an implementation specific randomly generated key for the associated 832cipher context I<ctx>. This is currently only supported by DES and 3DES (which set 833the key to odd parity). 834 835=item "taglen" (B<OSSL_CIPHER_PARAM_AEAD_TAGLEN>) <unsigned integer> 836 837Gets the tag length to be used for an AEAD cipher for the associated cipher 838context I<ctx>. It gets a default value if it has not been set. 839The length of the "taglen" parameter should not exceed that of a B<size_t>. 840See also EVP_CIPHER_CTX_get_tag_length(). 841 842=item "tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD>) <unsigned integer> 843 844Gets the length of the tag that will be added to a TLS record for the AEAD 845tag for the associated cipher context I<ctx>. 846The length of the "tlsaadpad" parameter should not exceed that of a B<size_t>. 847 848=item "tlsivgen" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN>) <octet string> 849 850Gets the invocation field generated for encryption. 851Can only be called after "tlsivfixed" is set. 852This is only used for GCM mode. 853 854=item "tls1multi_enclen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN>) <unsigned integer> 855 856Get the total length of the record returned from the "tls1multi_enc" operation. 857 858=item "tls1multi_maxbufsz" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE>) <unsigned integer> 859 860Gets the maximum record length for a TLS1 multiblock cipher operation. 861The length of the "tls1multi_maxbufsz" parameter should not exceed that of a B<size_t>. 862 863=item "tls1multi_aadpacklen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN>) <unsigned integer> 864 865Gets the result of running the "tls1multi_aad" operation. 866 867=item "tls-mac" (B<OSSL_CIPHER_PARAM_TLS_MAC>) <octet ptr> 868 869Used to pass the TLS MAC data. 870 871=back 872 873=head2 Settable EVP_CIPHER_CTX parameters 874 875The following L<OSSL_PARAM(3)> keys can be used with EVP_CIPHER_CTX_set_params(): 876 877=over 4 878 879=item "mackey" (B<OSSL_CIPHER_PARAM_AEAD_MAC_KEY>) <octet string> 880 881Sets the MAC key used by composite AEAD ciphers such as AES-CBC-HMAC-SHA256. 882 883=item "speed" (B<OSSL_CIPHER_PARAM_SPEED>) <unsigned integer> 884 885Sets the speed option for the associated cipher context. This is only supported 886by AES SIV ciphers which disallow multiple operations by default. 887Setting "speed" to 1 allows another encrypt or decrypt operation to be 888performed. This is used for performance testing. 889 890=item "use-bits" (B<OSSL_CIPHER_PARAM_USE_BITS>) <unsigned integer> 891 892Determines if the input length I<inl> passed to EVP_EncryptUpdate(), 893EVP_DecryptUpdate() and EVP_CipherUpdate() is the number of bits or number of bytes. 894Setting "use-bits" to 1 uses bits. The default is in bytes. 895This is only used for B<CFB1> ciphers. 896 897This can be set using EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPH_FLAG_LENGTH_BITS). 898 899=item "tls-version" (B<OSSL_CIPHER_PARAM_TLS_VERSION>) <integer> 900 901Sets the TLS version. 902 903=item "tls-mac-size" (B<OSSL_CIPHER_PARAM_TLS_MAC_SIZE>) <unsigned integer> 904 905Set the TLS MAC size. 906 907=item "tlsaad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD>) <octet string> 908 909Sets TLSv1.2 AAD information for the associated cipher context I<ctx>. 910TLSv1.2 AAD information is always 13 bytes in length and is as defined for the 911"additional_data" field described in section 6.2.3.3 of RFC5246. 912 913=item "tlsivfixed" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED>) <octet string> 914 915Sets the fixed portion of an IV for an AEAD cipher used in a TLS record 916encryption/ decryption for the associated cipher context. 917TLS record encryption/decryption always occurs "in place" so that the input and 918output buffers are always the same memory location. 919AEAD IVs in TLSv1.2 consist of an implicit "fixed" part and an explicit part 920that varies with every record. 921Setting a TLS fixed IV changes a cipher to encrypt/decrypt TLS records. 922TLS records are encrypted/decrypted using a single OSSL_FUNC_cipher_cipher call per 923record. 924For a record decryption the first bytes of the input buffer will be the explicit 925part of the IV and the final bytes of the input buffer will be the AEAD tag. 926The length of the explicit part of the IV and the tag length will depend on the 927cipher in use and will be defined in the RFC for the relevant ciphersuite. 928In order to allow for "in place" decryption the plaintext output should be 929written to the same location in the output buffer that the ciphertext payload 930was read from, i.e. immediately after the explicit IV. 931 932When encrypting a record the first bytes of the input buffer should be empty to 933allow space for the explicit IV, as will the final bytes where the tag will 934be written. 935The length of the input buffer will include the length of the explicit IV, the 936payload, and the tag bytes. 937The cipher implementation should generate the explicit IV and write it to the 938beginning of the output buffer, do "in place" encryption of the payload and 939write that to the output buffer, and finally add the tag onto the end of the 940output buffer. 941 942Whether encrypting or decrypting the value written to I<*outl> in the 943OSSL_FUNC_cipher_cipher call should be the length of the payload excluding the explicit 944IV length and the tag length. 945 946=item "tlsivinv" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV>) <octet string> 947 948Sets the invocation field used for decryption. 949Can only be called after "tlsivfixed" is set. 950This is only used for GCM mode. 951 952=item "tls1multi_enc" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC>) <octet string> 953 954Triggers a multiblock TLS1 encrypt operation for a TLS1 aware cipher that 955supports sending 4 or 8 records in one go. 956The cipher performs both the MAC and encrypt stages and constructs the record 957headers itself. 958"tls1multi_enc" supplies the output buffer for the encrypt operation, 959"tls1multi_encin" & "tls1multi_interleave" must also be set in order to supply 960values to the encrypt operation. 961 962=item "tls1multi_encin" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN>) <octet string> 963 964Supplies the data to encrypt for a TLS1 multiblock cipher operation. 965 966=item "tls1multi_maxsndfrag" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT>) <unsigned integer> 967 968Sets the maximum send fragment size for a TLS1 multiblock cipher operation. 969It must be set before using "tls1multi_maxbufsz". 970The length of the "tls1multi_maxsndfrag" parameter should not exceed that of a B<size_t>. 971 972=item "tls1multi_aad" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD>) <octet string> 973 974Sets the authenticated additional data used by a TLS1 multiblock cipher operation. 975The supplied data consists of 13 bytes of record data containing: 976Bytes 0-7: The sequence number of the first record 977Byte 8: The record type 978Byte 9-10: The protocol version 979Byte 11-12: Input length (Always 0) 980 981"tls1multi_interleave" must also be set for this operation. 982 983=back 984 985=head1 CONTROLS 986 987The Mappings from EVP_CIPHER_CTX_ctrl() identifiers to PARAMETERS are listed 988in the following section. See the L</PARAMETERS> section for more details. 989 990EVP_CIPHER_CTX_ctrl() can be used to send the following standard controls: 991 992=over 4 993 994=item EVP_CTRL_AEAD_SET_IVLEN and EVP_CTRL_GET_IVLEN 995 996When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and 997EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the 998key "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>). 999 1000=item EVP_CTRL_AEAD_SET_IV_FIXED 1001 1002When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called 1003with an L<OSSL_PARAM(3)> item with the key "tlsivfixed" 1004(B<OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED>). 1005 1006=item EVP_CTRL_AEAD_SET_MAC_KEY 1007 1008When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called 1009with an L<OSSL_PARAM(3)> item with the key "mackey" 1010(B<OSSL_CIPHER_PARAM_AEAD_MAC_KEY>). 1011 1012=item EVP_CTRL_AEAD_SET_TAG and EVP_CTRL_AEAD_GET_TAG 1013 1014When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and 1015EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the 1016key "tag" (B<OSSL_CIPHER_PARAM_AEAD_TAG>). 1017 1018=item EVP_CTRL_CCM_SET_L 1019 1020When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called 1021with an L<OSSL_PARAM(3)> item with the key "ivlen" (B<OSSL_CIPHER_PARAM_IVLEN>) 1022with a value of (15 - L) 1023 1024=item EVP_CTRL_COPY 1025 1026There is no OSSL_PARAM mapping for this. Use EVP_CIPHER_CTX_copy() instead. 1027 1028=item EVP_CTRL_GCM_SET_IV_INV 1029 1030When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called 1031with an L<OSSL_PARAM(3)> item with the key "tlsivinv" 1032(B<OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV>). 1033 1034=item EVP_CTRL_RAND_KEY 1035 1036When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called 1037with an L<OSSL_PARAM(3)> item with the key "randkey" 1038(B<OSSL_CIPHER_PARAM_RANDOM_KEY>). 1039 1040=item EVP_CTRL_SET_KEY_LENGTH 1041 1042When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called 1043with an L<OSSL_PARAM(3)> item with the key "keylen" (B<OSSL_CIPHER_PARAM_KEYLEN>). 1044 1045=item EVP_CTRL_SET_RC2_KEY_BITS and EVP_CTRL_GET_RC2_KEY_BITS 1046 1047When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and 1048EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the 1049key "keybits" (B<OSSL_CIPHER_PARAM_RC2_KEYBITS>). 1050 1051=item EVP_CTRL_SET_RC5_ROUNDS and EVP_CTRL_GET_RC5_ROUNDS 1052 1053When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() and 1054EVP_CIPHER_CTX_get_params() get called with an L<OSSL_PARAM(3)> item with the 1055key "rounds" (B<OSSL_CIPHER_PARAM_ROUNDS>). 1056 1057=item EVP_CTRL_SET_SPEED 1058 1059When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called 1060with an L<OSSL_PARAM(3)> item with the key "speed" (B<OSSL_CIPHER_PARAM_SPEED>). 1061 1062=item EVP_CTRL_GCM_IV_GEN 1063 1064When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_get_params() gets called 1065with an L<OSSL_PARAM(3)> item with the key 1066"tlsivgen" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN>). 1067 1068=item EVP_CTRL_AEAD_TLS1_AAD 1069 1070When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() get called 1071with an L<OSSL_PARAM(3)> item with the key 1072"tlsaad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD>) 1073followed by EVP_CIPHER_CTX_get_params() with a key of 1074"tlsaadpad" (B<OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD>). 1075 1076=item EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE 1077 1078When used with a fetched B<EVP_CIPHER>, 1079EVP_CIPHER_CTX_set_params() gets called with an L<OSSL_PARAM(3)> item with the 1080key OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT 1081followed by EVP_CIPHER_CTX_get_params() with a key of 1082"tls1multi_maxbufsz" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE>). 1083 1084=item EVP_CTRL_TLS1_1_MULTIBLOCK_AAD 1085 1086When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called 1087with L<OSSL_PARAM(3)> items with the keys 1088"tls1multi_aad" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD>) and 1089"tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>) 1090followed by EVP_CIPHER_CTX_get_params() with keys of 1091"tls1multi_aadpacklen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN>) and 1092"tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>). 1093 1094=item EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT 1095 1096When used with a fetched B<EVP_CIPHER>, EVP_CIPHER_CTX_set_params() gets called 1097with L<OSSL_PARAM(3)> items with the keys 1098"tls1multi_enc" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC>), 1099"tls1multi_encin" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN>) and 1100"tls1multi_interleave" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE>), 1101followed by EVP_CIPHER_CTX_get_params() with a key of 1102"tls1multi_enclen" (B<OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN>). 1103 1104=back 1105 1106=head1 FLAGS 1107 1108EVP_CIPHER_CTX_set_flags(), EVP_CIPHER_CTX_clear_flags() and EVP_CIPHER_CTX_test_flags(). 1109can be used to manipulate and test these B<EVP_CIPHER_CTX> flags: 1110 1111=over 4 1112 1113=item EVP_CIPH_NO_PADDING 1114 1115Used by EVP_CIPHER_CTX_set_padding(). 1116 1117See also L</Gettable and Settable EVP_CIPHER_CTX parameters> "padding" 1118 1119=item EVP_CIPH_FLAG_LENGTH_BITS 1120 1121See L</Settable EVP_CIPHER_CTX parameters> "use-bits". 1122 1123=item EVP_CIPHER_CTX_FLAG_WRAP_ALLOW 1124 1125Used for Legacy purposes only. This flag needed to be set to indicate the 1126cipher handled wrapping. 1127 1128=back 1129 1130EVP_CIPHER_flags() uses the following flags that 1131have mappings to L</Gettable EVP_CIPHER parameters>: 1132 1133=over 4 1134 1135=item EVP_CIPH_FLAG_AEAD_CIPHER 1136 1137See L</Gettable EVP_CIPHER parameters> "aead". 1138 1139=item EVP_CIPH_CUSTOM_IV 1140 1141See L</Gettable EVP_CIPHER parameters> "custom-iv". 1142 1143=item EVP_CIPH_FLAG_CTS 1144 1145See L</Gettable EVP_CIPHER parameters> "cts". 1146 1147=item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK; 1148 1149See L</Gettable EVP_CIPHER parameters> "tls-multi". 1150 1151=item EVP_CIPH_RAND_KEY 1152 1153See L</Gettable EVP_CIPHER parameters> "has-randkey". 1154 1155=back 1156 1157EVP_CIPHER_flags() uses the following flags for legacy purposes only: 1158 1159=over 4 1160 1161=item EVP_CIPH_VARIABLE_LENGTH 1162 1163=item EVP_CIPH_FLAG_CUSTOM_CIPHER 1164 1165=item EVP_CIPH_ALWAYS_CALL_INIT 1166 1167=item EVP_CIPH_CTRL_INIT 1168 1169=item EVP_CIPH_CUSTOM_KEY_LENGTH 1170 1171=item EVP_CIPH_CUSTOM_COPY 1172 1173=item EVP_CIPH_FLAG_DEFAULT_ASN1 1174 1175See L<EVP_CIPHER_meth_set_flags(3)> for further information related to the above 1176flags. 1177 1178=back 1179 1180=head1 RETURN VALUES 1181 1182EVP_CIPHER_fetch() returns a pointer to a B<EVP_CIPHER> for success 1183and B<NULL> for failure. 1184 1185EVP_CIPHER_up_ref() returns 1 for success or 0 otherwise. 1186 1187EVP_CIPHER_CTX_new() returns a pointer to a newly created 1188B<EVP_CIPHER_CTX> for success and B<NULL> for failure. 1189 1190EVP_EncryptInit_ex2(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex() 1191return 1 for success and 0 for failure. 1192 1193EVP_DecryptInit_ex2() and EVP_DecryptUpdate() return 1 for success and 0 for failure. 1194EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success. 1195 1196EVP_CipherInit_ex2() and EVP_CipherUpdate() return 1 for success and 0 for failure. 1197EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success. 1198 1199EVP_Cipher() returns 1 on success or 0 on failure, if the flag 1200B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is not set for the cipher. 1201EVP_Cipher() returns the number of bytes written to I<out> for encryption / decryption, or 1202the number of bytes authenticated in a call specifying AAD for an AEAD cipher, if the flag 1203B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is set for the cipher. 1204 1205EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure. 1206 1207EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() 1208return an B<EVP_CIPHER> structure or NULL on error. 1209 1210EVP_CIPHER_get_nid() and EVP_CIPHER_CTX_get_nid() return a NID. 1211 1212EVP_CIPHER_get_block_size() and EVP_CIPHER_CTX_get_block_size() return the 1213block size. 1214 1215EVP_CIPHER_get_key_length() and EVP_CIPHER_CTX_get_key_length() return the key 1216length. 1217 1218EVP_CIPHER_CTX_set_padding() always returns 1. 1219 1220EVP_CIPHER_get_iv_length() and EVP_CIPHER_CTX_get_iv_length() return the IV 1221length or zero if the cipher does not use an IV. 1222 1223EVP_CIPHER_CTX_get_tag_length() return the tag length or zero if the cipher 1224does not use a tag. 1225 1226EVP_CIPHER_get_type() and EVP_CIPHER_CTX_get_type() return the NID of the 1227cipher's OBJECT IDENTIFIER or NID_undef if it has no defined 1228OBJECT IDENTIFIER. 1229 1230EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure. 1231 1232EVP_CIPHER_CTX_get_num() returns a nonnegative num value or 1233B<EVP_CTRL_RET_UNSUPPORTED> if the implementation does not support the call 1234or on any other error. 1235 1236EVP_CIPHER_CTX_set_num() returns 1 on success and 0 if the implementation 1237does not support the call or on any other error. 1238 1239EVP_CIPHER_CTX_is_encrypting() returns 1 if the I<ctx> is set up for encryption 12400 otherwise. 1241 1242EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater 1243than zero for success and zero or a negative number on failure. 1244 1245EVP_CIPHER_CTX_rand_key() returns 1 for success and zero or a negative number 1246for failure. 1247 1248EVP_CIPHER_names_do_all() returns 1 if the callback was called for all names. 1249A return value of 0 means that the callback was not called for any names. 1250 1251=head1 CIPHER LISTING 1252 1253All algorithms have a fixed key length unless otherwise stated. 1254 1255Refer to L</SEE ALSO> for the full list of ciphers available through the EVP 1256interface. 1257 1258=over 4 1259 1260=item EVP_enc_null() 1261 1262Null cipher: does nothing. 1263 1264=back 1265 1266=head1 AEAD INTERFACE 1267 1268The EVP interface for Authenticated Encryption with Associated Data (AEAD) 1269modes are subtly altered and several additional I<ctrl> operations are supported 1270depending on the mode specified. 1271 1272To specify additional authenticated data (AAD), a call to EVP_CipherUpdate(), 1273EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output 1274parameter I<out> set to B<NULL>. In this case, on success, the parameter 1275I<outl> is set to the number of bytes authenticated. 1276 1277When decrypting, the return value of EVP_DecryptFinal() or EVP_CipherFinal() 1278indicates whether the operation was successful. If it does not indicate success, 1279the authentication operation has failed and any output data B<MUST NOT> be used 1280as it is corrupted. 1281 1282=head2 GCM and OCB Modes 1283 1284The following I<ctrl>s are supported in GCM and OCB modes. 1285 1286=over 4 1287 1288=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL) 1289 1290Sets the IV length. This call can only be made before specifying an IV. If 1291not called a default IV length is used. 1292 1293For GCM AES and OCB AES the default is 12 (i.e. 96 bits). For OCB mode the 1294maximum is 15. 1295 1296=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag) 1297 1298Writes C<taglen> bytes of the tag value to the buffer indicated by C<tag>. 1299This call can only be made when encrypting data and B<after> all data has been 1300processed (e.g. after an EVP_EncryptFinal() call). 1301 1302For OCB, C<taglen> must either be 16 or the value previously set via 1303B<EVP_CTRL_AEAD_SET_TAG>. 1304 1305=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag) 1306 1307When decrypting, this call sets the expected tag to C<taglen> bytes from C<tag>. 1308C<taglen> must be between 1 and 16 inclusive. 1309The tag must be set prior to any call to EVP_DecryptFinal() or 1310EVP_DecryptFinal_ex(). 1311 1312For GCM, this call is only valid when decrypting data. 1313 1314For OCB, this call is valid when decrypting data to set the expected tag, 1315and when encrypting to set the desired tag length. 1316 1317In OCB mode, calling this when encrypting with C<tag> set to C<NULL> sets the 1318tag length. The tag length can only be set before specifying an IV. If this is 1319not called prior to setting the IV during encryption, then a default tag length 1320is used. 1321 1322For OCB AES, the default tag length is 16 (i.e. 128 bits). It is also the 1323maximum tag length for OCB. 1324 1325=back 1326 1327=head2 CCM Mode 1328 1329The EVP interface for CCM mode is similar to that of the GCM mode but with a 1330few additional requirements and different I<ctrl> values. 1331 1332For CCM mode, the total plaintext or ciphertext length B<MUST> be passed to 1333EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output 1334and input parameters (I<in> and I<out>) set to B<NULL> and the length passed in 1335the I<inl> parameter. 1336 1337The following I<ctrl>s are supported in CCM mode. 1338 1339=over 4 1340 1341=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag) 1342 1343This call is made to set the expected B<CCM> tag value when decrypting or 1344the length of the tag (with the C<tag> parameter set to NULL) when encrypting. 1345The tag length is often referred to as B<M>. If not set a default value is 1346used (12 for AES). When decrypting, the tag needs to be set before passing 1347in data to be decrypted, but as in GCM and OCB mode, it can be set after 1348passing additional authenticated data (see L</AEAD INTERFACE>). 1349 1350=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL) 1351 1352Sets the CCM B<L> value. If not set a default is used (8 for AES). 1353 1354=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL) 1355 1356Sets the CCM nonce (IV) length. This call can only be made before specifying a 1357nonce value. The nonce length is given by B<15 - L> so it is 7 by default for 1358AES. 1359 1360=back 1361 1362=head2 SIV Mode 1363 1364For SIV mode ciphers the behaviour of the EVP interface is subtly 1365altered and several additional ctrl operations are supported. 1366 1367To specify any additional authenticated data (AAD) and/or a Nonce, a call to 1368EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made 1369with the output parameter I<out> set to B<NULL>. 1370 1371RFC5297 states that the Nonce is the last piece of AAD before the actual 1372encrypt/decrypt takes place. The API does not differentiate the Nonce from 1373other AAD. 1374 1375When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal() 1376indicates if the operation was successful. If it does not indicate success 1377the authentication operation has failed and any output data B<MUST NOT> 1378be used as it is corrupted. 1379 1380The API does not store the the SIV (Synthetic Initialization Vector) in 1381the cipher text. Instead, it is stored as the tag within the EVP_CIPHER_CTX. 1382The SIV must be retrieved from the context after encryption, and set into 1383the context before decryption. 1384 1385This differs from RFC5297 in that the cipher output from encryption, and 1386the cipher input to decryption, does not contain the SIV. This also means 1387that the plain text and cipher text lengths are identical. 1388 1389The following ctrls are supported in SIV mode, and are used to get and set 1390the Synthetic Initialization Vector: 1391 1392=over 4 1393 1394=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag); 1395 1396Writes I<taglen> bytes of the tag value (the Synthetic Initialization Vector) 1397to the buffer indicated by I<tag>. This call can only be made when encrypting 1398data and B<after> all data has been processed (e.g. after an EVP_EncryptFinal() 1399call). For SIV mode the taglen must be 16. 1400 1401=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag); 1402 1403Sets the expected tag (the Synthetic Initialization Vector) to I<taglen> 1404bytes from I<tag>. This call is only legal when decrypting data and must be 1405made B<before> any data is processed (e.g. before any EVP_DecryptUpdate() 1406calls). For SIV mode the taglen must be 16. 1407 1408=back 1409 1410SIV mode makes two passes over the input data, thus, only one call to 1411EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made 1412with I<out> set to a non-B<NULL> value. A call to EVP_DecryptFinal() or 1413EVP_CipherFinal() is not required, but will indicate if the update 1414operation succeeded. 1415 1416=head2 ChaCha20-Poly1305 1417 1418The following I<ctrl>s are supported for the ChaCha20-Poly1305 AEAD algorithm. 1419 1420=over 4 1421 1422=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL) 1423 1424Sets the nonce length. This call is now redundant since the only valid value 1425is the default length of 12 (i.e. 96 bits). 1426Prior to OpenSSL 3.0 a nonce of less than 12 bytes could be used to automatically 1427pad the iv with leading 0 bytes to make it 12 bytes in length. 1428 1429=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag) 1430 1431Writes C<taglen> bytes of the tag value to the buffer indicated by C<tag>. 1432This call can only be made when encrypting data and B<after> all data has been 1433processed (e.g. after an EVP_EncryptFinal() call). 1434 1435C<taglen> specified here must be 16 (B<POLY1305_BLOCK_SIZE>, i.e. 128-bits) or 1436less. 1437 1438=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag) 1439 1440Sets the expected tag to C<taglen> bytes from C<tag>. 1441The tag length can only be set before specifying an IV. 1442C<taglen> must be between 1 and 16 (B<POLY1305_BLOCK_SIZE>) inclusive. 1443This call is only valid when decrypting data. 1444 1445=back 1446 1447=head1 NOTES 1448 1449Where possible the B<EVP> interface to symmetric ciphers should be used in 1450preference to the low-level interfaces. This is because the code then becomes 1451transparent to the cipher used and much more flexible. Additionally, the 1452B<EVP> interface will ensure the use of platform specific cryptographic 1453acceleration such as AES-NI (the low-level interfaces do not provide the 1454guarantee). 1455 1456PKCS padding works by adding B<n> padding bytes of value B<n> to make the total 1457length of the encrypted data a multiple of the block size. Padding is always 1458added so if the data is already a multiple of the block size B<n> will equal 1459the block size. For example if the block size is 8 and 11 bytes are to be 1460encrypted then 5 padding bytes of value 5 will be added. 1461 1462When decrypting the final block is checked to see if it has the correct form. 1463 1464Although the decryption operation can produce an error if padding is enabled, 1465it is not a strong test that the input data or key is correct. A random block 1466has better than 1 in 256 chance of being of the correct format and problems with 1467the input data earlier on will not produce a final decrypt error. 1468 1469If padding is disabled then the decryption operation will always succeed if 1470the total amount of data decrypted is a multiple of the block size. 1471 1472The functions EVP_EncryptInit(), EVP_EncryptInit_ex(), 1473EVP_EncryptFinal(), EVP_DecryptInit(), EVP_DecryptInit_ex(), 1474EVP_CipherInit(), EVP_CipherInit_ex() and EVP_CipherFinal() are obsolete 1475but are retained for compatibility with existing code. New code should 1476use EVP_EncryptInit_ex2(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex2(), 1477EVP_DecryptFinal_ex(), EVP_CipherInit_ex2() and EVP_CipherFinal_ex() 1478because they can reuse an existing context without allocating and freeing 1479it up on each call. 1480 1481There are some differences between functions EVP_CipherInit() and 1482EVP_CipherInit_ex(), significant in some circumstances. EVP_CipherInit() fills 1483the passed context object with zeros. As a consequence, EVP_CipherInit() does 1484not allow step-by-step initialization of the ctx when the I<key> and I<iv> are 1485passed in separate calls. It also means that the flags set for the CTX are 1486removed, and it is especially important for the 1487B<EVP_CIPHER_CTX_FLAG_WRAP_ALLOW> flag treated specially in 1488EVP_CipherInit_ex(). 1489 1490Ignoring failure returns of the B<EVP_CIPHER_CTX> initialization functions can 1491lead to subsequent undefined behavior when calling the functions that update or 1492finalize the context. The only valid calls on the B<EVP_CIPHER_CTX> when 1493initialization fails are calls that attempt another initialization of the 1494context or release the context. 1495 1496EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros. 1497 1498=head1 BUGS 1499 1500B<EVP_MAX_KEY_LENGTH> and B<EVP_MAX_IV_LENGTH> only refer to the internal 1501ciphers with default key lengths. If custom ciphers exceed these values the 1502results are unpredictable. This is because it has become standard practice to 1503define a generic key as a fixed unsigned char array containing 1504B<EVP_MAX_KEY_LENGTH> bytes. 1505 1506The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested 1507for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. 1508 1509=head1 EXAMPLES 1510 1511Encrypt a string using IDEA: 1512 1513 int do_crypt(char *outfile) 1514 { 1515 unsigned char outbuf[1024]; 1516 int outlen, tmplen; 1517 /* 1518 * Bogus key and IV: we'd normally set these from 1519 * another source. 1520 */ 1521 unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; 1522 unsigned char iv[] = {1,2,3,4,5,6,7,8}; 1523 char intext[] = "Some Crypto Text"; 1524 EVP_CIPHER_CTX *ctx; 1525 FILE *out; 1526 1527 ctx = EVP_CIPHER_CTX_new(); 1528 if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) { 1529 /* Error */ 1530 EVP_CIPHER_CTX_free(ctx); 1531 return 0; 1532 } 1533 1534 if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) { 1535 /* Error */ 1536 EVP_CIPHER_CTX_free(ctx); 1537 return 0; 1538 } 1539 /* 1540 * Buffer passed to EVP_EncryptFinal() must be after data just 1541 * encrypted to avoid overwriting it. 1542 */ 1543 if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) { 1544 /* Error */ 1545 EVP_CIPHER_CTX_free(ctx); 1546 return 0; 1547 } 1548 outlen += tmplen; 1549 EVP_CIPHER_CTX_free(ctx); 1550 /* 1551 * Need binary mode for fopen because encrypted data is 1552 * binary data. Also cannot use strlen() on it because 1553 * it won't be NUL terminated and may contain embedded 1554 * NULs. 1555 */ 1556 out = fopen(outfile, "wb"); 1557 if (out == NULL) { 1558 /* Error */ 1559 return 0; 1560 } 1561 fwrite(outbuf, 1, outlen, out); 1562 fclose(out); 1563 return 1; 1564 } 1565 1566The ciphertext from the above example can be decrypted using the B<openssl> 1567utility with the command line (shown on two lines for clarity): 1568 1569 openssl idea -d \ 1570 -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 <filename 1571 1572General encryption and decryption function example using FILE I/O and AES128 1573with a 128-bit key: 1574 1575 int do_crypt(FILE *in, FILE *out, int do_encrypt) 1576 { 1577 /* Allow enough space in output buffer for additional block */ 1578 unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; 1579 int inlen, outlen; 1580 EVP_CIPHER_CTX *ctx; 1581 /* 1582 * Bogus key and IV: we'd normally set these from 1583 * another source. 1584 */ 1585 unsigned char key[] = "0123456789abcdeF"; 1586 unsigned char iv[] = "1234567887654321"; 1587 1588 /* Don't set key or IV right away; we want to check lengths */ 1589 ctx = EVP_CIPHER_CTX_new(); 1590 if (!EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL, 1591 do_encrypt, NULL)) { 1592 /* Error */ 1593 EVP_CIPHER_CTX_free(ctx); 1594 return 0; 1595 } 1596 OPENSSL_assert(EVP_CIPHER_CTX_get_key_length(ctx) == 16); 1597 OPENSSL_assert(EVP_CIPHER_CTX_get_iv_length(ctx) == 16); 1598 1599 /* Now we can set key and IV */ 1600 if (!EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL)) { 1601 /* Error */ 1602 EVP_CIPHER_CTX_free(ctx); 1603 return 0; 1604 } 1605 1606 for (;;) { 1607 inlen = fread(inbuf, 1, 1024, in); 1608 if (inlen <= 0) 1609 break; 1610 if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) { 1611 /* Error */ 1612 EVP_CIPHER_CTX_free(ctx); 1613 return 0; 1614 } 1615 fwrite(outbuf, 1, outlen, out); 1616 } 1617 if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) { 1618 /* Error */ 1619 EVP_CIPHER_CTX_free(ctx); 1620 return 0; 1621 } 1622 fwrite(outbuf, 1, outlen, out); 1623 1624 EVP_CIPHER_CTX_free(ctx); 1625 return 1; 1626 } 1627 1628Encryption using AES-CBC with a 256-bit key with "CS1" ciphertext stealing. 1629 1630 int encrypt(const unsigned char *key, const unsigned char *iv, 1631 const unsigned char *msg, size_t msg_len, unsigned char *out) 1632 { 1633 /* 1634 * This assumes that key size is 32 bytes and the iv is 16 bytes. 1635 * For ciphertext stealing mode the length of the ciphertext "out" will be 1636 * the same size as the plaintext size "msg_len". 1637 * The "msg_len" can be any size >= 16. 1638 */ 1639 int ret = 0, encrypt = 1, outlen, len; 1640 EVP_CIPHER_CTX *ctx = NULL; 1641 EVP_CIPHER *cipher = NULL; 1642 OSSL_PARAM params[2]; 1643 1644 ctx = EVP_CIPHER_CTX_new(); 1645 cipher = EVP_CIPHER_fetch(NULL, "AES-256-CBC-CTS", NULL); 1646 if (ctx == NULL || cipher == NULL) 1647 goto err; 1648 1649 /* 1650 * The default is "CS1" so this is not really needed, 1651 * but would be needed to set either "CS2" or "CS3". 1652 */ 1653 params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE, 1654 "CS1", 0); 1655 params[1] = OSSL_PARAM_construct_end(); 1656 1657 if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params)) 1658 goto err; 1659 1660 /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */ 1661 if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len)) 1662 goto err; 1663 if (!EVP_CipherFinal_ex(ctx, out + outlen, &len)) 1664 goto err; 1665 ret = 1; 1666 err: 1667 EVP_CIPHER_free(cipher); 1668 EVP_CIPHER_CTX_free(ctx); 1669 return ret; 1670 } 1671 1672=head1 SEE ALSO 1673 1674L<evp(7)>, 1675L<property(7)>, 1676L<crypto(7)/ALGORITHM FETCHING>, 1677L<provider-cipher(7)>, 1678L<life_cycle-cipher(7)> 1679 1680Supported ciphers are listed in: 1681 1682L<EVP_aes_128_gcm(3)>, 1683L<EVP_aria_128_gcm(3)>, 1684L<EVP_bf_cbc(3)>, 1685L<EVP_camellia_128_ecb(3)>, 1686L<EVP_cast5_cbc(3)>, 1687L<EVP_chacha20(3)>, 1688L<EVP_des_cbc(3)>, 1689L<EVP_desx_cbc(3)>, 1690L<EVP_idea_cbc(3)>, 1691L<EVP_rc2_cbc(3)>, 1692L<EVP_rc4(3)>, 1693L<EVP_rc5_32_12_16_cbc(3)>, 1694L<EVP_seed_cbc(3)>, 1695L<EVP_sm4_cbc(3)>, 1696 1697=head1 HISTORY 1698 1699Support for OCB mode was added in OpenSSL 1.1.0. 1700 1701B<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0. As a result, 1702EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup() 1703disappeared. EVP_CIPHER_CTX_init() remains as an alias for 1704EVP_CIPHER_CTX_reset(). 1705 1706The EVP_CIPHER_CTX_cipher() function was deprecated in OpenSSL 3.0; use 1707EVP_CIPHER_CTX_get0_cipher() instead. 1708 1709The EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2(), EVP_CipherInit_ex2(), 1710EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(), 1711EVP_CIPHER_CTX_get0_cipher(), EVP_CIPHER_CTX_get1_cipher(), 1712EVP_CIPHER_get_params(), EVP_CIPHER_CTX_set_params(), 1713EVP_CIPHER_CTX_get_params(), EVP_CIPHER_gettable_params(), 1714EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(), 1715EVP_CIPHER_CTX_settable_params() and EVP_CIPHER_CTX_gettable_params() 1716functions were added in 3.0. 1717 1718The EVP_CIPHER_nid(), EVP_CIPHER_name(), EVP_CIPHER_block_size(), 1719EVP_CIPHER_key_length(), EVP_CIPHER_iv_length(), EVP_CIPHER_flags(), 1720EVP_CIPHER_mode(), EVP_CIPHER_type(), EVP_CIPHER_CTX_nid(), 1721EVP_CIPHER_CTX_block_size(), EVP_CIPHER_CTX_key_length(), 1722EVP_CIPHER_CTX_iv_length(), EVP_CIPHER_CTX_tag_length(), 1723EVP_CIPHER_CTX_num(), EVP_CIPHER_CTX_type(), and EVP_CIPHER_CTX_mode() 1724functions were renamed to include C<get> or C<get0> in their names in 1725OpenSSL 3.0, respectively. The old names are kept as non-deprecated 1726alias macros. 1727 1728The EVP_CIPHER_CTX_encrypting() function was renamed to 1729EVP_CIPHER_CTX_is_encrypting() in OpenSSL 3.0. The old name is kept as 1730non-deprecated alias macro. 1731 1732The EVP_CIPHER_CTX_flags() macro was deprecated in OpenSSL 1.1.0. 1733 1734=head1 COPYRIGHT 1735 1736Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 1737 1738Licensed under the Apache License 2.0 (the "License"). You may not use 1739this file except in compliance with the License. You can obtain a copy 1740in the file LICENSE in the source distribution or at 1741L<https://www.openssl.org/source/license.html>. 1742 1743=cut 1744