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