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