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