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