1.\" $OpenBSD: EVP_EncryptInit.3,v 1.42 2021/10/14 00:45:02 tb Exp $ 2.\" full merge up to: OpenSSL 5211e094 Nov 11 14:39:11 2014 -0800 3.\" EVP_bf_cbc.pod EVP_cast5_cbc.pod EVP_idea_cbc.pod EVP_rc2_cbc.pod 4.\" 7c6d372a Nov 20 13:20:01 2018 +0000 5.\" selective merge up to: OpenSSL 16cfc2c9 Mar 8 22:30:28 2018 +0100 6.\" EVP_chacha20.pod 8fa4d95e Oct 21 11:59:09 2017 +0900 7.\" 8.\" This file is a derived work. 9.\" The changes are covered by the following Copyright and license: 10.\" 11.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 12.\" 13.\" Permission to use, copy, modify, and distribute this software for any 14.\" purpose with or without fee is hereby granted, provided that the above 15.\" copyright notice and this permission notice appear in all copies. 16.\" 17.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 18.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 19.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 20.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 21.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 22.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 23.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 24.\" 25.\" The original file was written by Dr. Stephen Henson <steve@openssl.org> 26.\" and Richard Levitte <levitte@openssl.org>. 27.\" Copyright (c) 2000-2002, 2005, 2012-2016 The OpenSSL Project. 28.\" All rights reserved. 29.\" 30.\" Redistribution and use in source and binary forms, with or without 31.\" modification, are permitted provided that the following conditions 32.\" are met: 33.\" 34.\" 1. Redistributions of source code must retain the above copyright 35.\" notice, this list of conditions and the following disclaimer. 36.\" 37.\" 2. Redistributions in binary form must reproduce the above copyright 38.\" notice, this list of conditions and the following disclaimer in 39.\" the documentation and/or other materials provided with the 40.\" distribution. 41.\" 42.\" 3. All advertising materials mentioning features or use of this 43.\" software must display the following acknowledgment: 44.\" "This product includes software developed by the OpenSSL Project 45.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 46.\" 47.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 48.\" endorse or promote products derived from this software without 49.\" prior written permission. For written permission, please contact 50.\" openssl-core@openssl.org. 51.\" 52.\" 5. Products derived from this software may not be called "OpenSSL" 53.\" nor may "OpenSSL" appear in their names without prior written 54.\" permission of the OpenSSL Project. 55.\" 56.\" 6. Redistributions of any form whatsoever must retain the following 57.\" acknowledgment: 58.\" "This product includes software developed by the OpenSSL Project 59.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 60.\" 61.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 62.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 63.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 64.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 65.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 66.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 67.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 68.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 69.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 70.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 71.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 72.\" OF THE POSSIBILITY OF SUCH DAMAGE. 73.\" 74.Dd $Mdocdate: October 14 2021 $ 75.Dt EVP_ENCRYPTINIT 3 76.Os 77.Sh NAME 78.Nm EVP_CIPHER_CTX_new , 79.Nm EVP_CIPHER_CTX_reset , 80.Nm EVP_CIPHER_CTX_cleanup , 81.Nm EVP_CIPHER_CTX_init , 82.Nm EVP_CIPHER_CTX_free , 83.Nm EVP_EncryptInit_ex , 84.Nm EVP_EncryptUpdate , 85.Nm EVP_EncryptFinal_ex , 86.Nm EVP_DecryptInit_ex , 87.Nm EVP_DecryptUpdate , 88.Nm EVP_DecryptFinal_ex , 89.Nm EVP_CipherInit_ex , 90.Nm EVP_CipherUpdate , 91.Nm EVP_CipherFinal_ex , 92.Nm EVP_EncryptInit , 93.Nm EVP_EncryptFinal , 94.Nm EVP_DecryptInit , 95.Nm EVP_DecryptFinal , 96.Nm EVP_CipherInit , 97.Nm EVP_CipherFinal , 98.Nm EVP_Cipher , 99.Nm EVP_CIPHER_CTX_set_flags , 100.Nm EVP_CIPHER_CTX_clear_flags , 101.Nm EVP_CIPHER_CTX_test_flags , 102.Nm EVP_CIPHER_CTX_set_padding , 103.Nm EVP_CIPHER_CTX_set_key_length , 104.Nm EVP_CIPHER_CTX_ctrl , 105.Nm EVP_CIPHER_CTX_rand_key , 106.Nm EVP_get_cipherbyname , 107.Nm EVP_get_cipherbynid , 108.Nm EVP_get_cipherbyobj , 109.Nm EVP_CIPHER_nid , 110.Nm EVP_CIPHER_block_size , 111.Nm EVP_CIPHER_key_length , 112.Nm EVP_CIPHER_iv_length , 113.Nm EVP_CIPHER_flags , 114.Nm EVP_CIPHER_mode , 115.Nm EVP_CIPHER_type , 116.Nm EVP_CIPHER_CTX_cipher , 117.Nm EVP_CIPHER_CTX_nid , 118.Nm EVP_CIPHER_CTX_block_size , 119.Nm EVP_CIPHER_CTX_key_length , 120.Nm EVP_CIPHER_CTX_iv_length , 121.Nm EVP_CIPHER_CTX_get_iv , 122.Nm EVP_CIPHER_CTX_set_iv , 123.Nm EVP_CIPHER_CTX_get_app_data , 124.Nm EVP_CIPHER_CTX_set_app_data , 125.Nm EVP_CIPHER_CTX_type , 126.Nm EVP_CIPHER_CTX_flags , 127.Nm EVP_CIPHER_CTX_mode , 128.Nm EVP_CIPHER_param_to_asn1 , 129.Nm EVP_CIPHER_asn1_to_param , 130.Nm EVP_enc_null , 131.Nm EVP_idea_cbc , 132.Nm EVP_idea_ecb , 133.Nm EVP_idea_cfb64 , 134.Nm EVP_idea_cfb , 135.Nm EVP_idea_ofb , 136.Nm EVP_rc2_cbc , 137.Nm EVP_rc2_ecb , 138.Nm EVP_rc2_cfb64 , 139.Nm EVP_rc2_cfb , 140.Nm EVP_rc2_ofb , 141.Nm EVP_rc2_40_cbc , 142.Nm EVP_rc2_64_cbc , 143.Nm EVP_bf_cbc , 144.Nm EVP_bf_ecb , 145.Nm EVP_bf_cfb64 , 146.Nm EVP_bf_cfb , 147.Nm EVP_bf_ofb , 148.Nm EVP_cast5_cbc , 149.Nm EVP_cast5_ecb , 150.Nm EVP_cast5_cfb64 , 151.Nm EVP_cast5_cfb , 152.Nm EVP_cast5_ofb , 153.Nm EVP_chacha20 154.Nd EVP cipher routines 155.Sh SYNOPSIS 156.In openssl/evp.h 157.Ft EVP_CIPHER_CTX * 158.Fn EVP_CIPHER_CTX_new void 159.Ft int 160.Fo EVP_CIPHER_CTX_reset 161.Fa "EVP_CIPHER_CTX *ctx" 162.Fc 163.Ft int 164.Fo EVP_CIPHER_CTX_cleanup 165.Fa "EVP_CIPHER_CTX *ctx" 166.Fc 167.Ft void 168.Fo EVP_CIPHER_CTX_init 169.Fa "EVP_CIPHER_CTX *ctx" 170.Fc 171.Ft void 172.Fo EVP_CIPHER_CTX_free 173.Fa "EVP_CIPHER_CTX *ctx" 174.Fc 175.Ft int 176.Fo EVP_EncryptInit_ex 177.Fa "EVP_CIPHER_CTX *ctx" 178.Fa "const EVP_CIPHER *type" 179.Fa "ENGINE *impl" 180.Fa "const unsigned char *key" 181.Fa "const unsigned char *iv" 182.Fc 183.Ft int 184.Fo EVP_EncryptUpdate 185.Fa "EVP_CIPHER_CTX *ctx" 186.Fa "unsigned char *out" 187.Fa "int *outl" 188.Fa "const unsigned char *in" 189.Fa "int inl" 190.Fc 191.Ft int 192.Fo EVP_EncryptFinal_ex 193.Fa "EVP_CIPHER_CTX *ctx" 194.Fa "unsigned char *out" 195.Fa "int *outl" 196.Fc 197.Ft int 198.Fo EVP_DecryptInit_ex 199.Fa "EVP_CIPHER_CTX *ctx" 200.Fa "const EVP_CIPHER *type" 201.Fa "ENGINE *impl" 202.Fa "const unsigned char *key" 203.Fa "const unsigned char *iv" 204.Fc 205.Ft int 206.Fo EVP_DecryptUpdate 207.Fa "EVP_CIPHER_CTX *ctx" 208.Fa "unsigned char *out" 209.Fa "int *outl" 210.Fa "const unsigned char *in" 211.Fa "int inl" 212.Fc 213.Ft int 214.Fo EVP_DecryptFinal_ex 215.Fa "EVP_CIPHER_CTX *ctx" 216.Fa "unsigned char *outm" 217.Fa "int *outl" 218.Fc 219.Ft int 220.Fo EVP_CipherInit_ex 221.Fa "EVP_CIPHER_CTX *ctx" 222.Fa "const EVP_CIPHER *type" 223.Fa "ENGINE *impl" 224.Fa "const unsigned char *key" 225.Fa "const unsigned char *iv" 226.Fa "int enc" 227.Fc 228.Ft int 229.Fo EVP_CipherUpdate 230.Fa "EVP_CIPHER_CTX *ctx" 231.Fa "unsigned char *out" 232.Fa "int *outl" 233.Fa "const unsigned char *in" 234.Fa "int inl" 235.Fc 236.Ft int 237.Fo EVP_CipherFinal_ex 238.Fa "EVP_CIPHER_CTX *ctx" 239.Fa "unsigned char *outm" 240.Fa "int *outl" 241.Fc 242.Ft int 243.Fo EVP_EncryptInit 244.Fa "EVP_CIPHER_CTX *ctx" 245.Fa "const EVP_CIPHER *type" 246.Fa "const unsigned char *key" 247.Fa "const unsigned char *iv" 248.Fc 249.Ft int 250.Fo EVP_EncryptFinal 251.Fa "EVP_CIPHER_CTX *ctx" 252.Fa "unsigned char *out" 253.Fa "int *outl" 254.Fc 255.Ft int 256.Fo EVP_DecryptInit 257.Fa "EVP_CIPHER_CTX *ctx" 258.Fa "const EVP_CIPHER *type" 259.Fa "const unsigned char *key" 260.Fa "const unsigned char *iv" 261.Fc 262.Ft int 263.Fo EVP_DecryptFinal 264.Fa "EVP_CIPHER_CTX *ctx" 265.Fa "unsigned char *outm" 266.Fa "int *outl" 267.Fc 268.Ft int 269.Fo EVP_CipherInit 270.Fa "EVP_CIPHER_CTX *ctx" 271.Fa "const EVP_CIPHER *type" 272.Fa "const unsigned char *key" 273.Fa "const unsigned char *iv" 274.Fa "int enc" 275.Fc 276.Ft int 277.Fo EVP_CipherFinal 278.Fa "EVP_CIPHER_CTX *ctx" 279.Fa "unsigned char *outm" 280.Fa "int *outl" 281.Fc 282.Ft int 283.Fo EVP_Cipher 284.Fa "EVP_CIPHER_CTX *ctx" 285.Fa "unsigned char *out" 286.Fa "const unsigned char *in" 287.Fa "unsigned int inl" 288.Fc 289.Ft void 290.Fo EVP_CIPHER_CTX_set_flags 291.Fa "EVP_CIPHER_CTX *ctx" 292.Fa "int flags" 293.Fc 294.Ft void 295.Fo EVP_CIPHER_CTX_clear_flags 296.Fa "EVP_CIPHER_CTX *ctx" 297.Fa "int flags" 298.Fc 299.Ft int 300.Fo EVP_CIPHER_CTX_test_flags 301.Fa "EVP_CIPHER_CTX *ctx" 302.Fa "int flags" 303.Fc 304.Ft int 305.Fo EVP_CIPHER_CTX_set_padding 306.Fa "EVP_CIPHER_CTX *x" 307.Fa "int padding" 308.Fc 309.Ft int 310.Fo EVP_CIPHER_CTX_set_key_length 311.Fa "EVP_CIPHER_CTX *x" 312.Fa "int keylen" 313.Fc 314.Ft int 315.Fo EVP_CIPHER_CTX_ctrl 316.Fa "EVP_CIPHER_CTX *ctx" 317.Fa "int type" 318.Fa "int arg" 319.Fa "void *ptr" 320.Fc 321.Ft int 322.Fo EVP_CIPHER_CTX_rand_key 323.Fa "EVP_CIPHER_CTX *ctx" 324.Fa "unsigned char *key" 325.Fc 326.Ft const EVP_CIPHER * 327.Fo EVP_get_cipherbyname 328.Fa "const char *name" 329.Fc 330.Ft const EVP_CIPHER * 331.Fo EVP_get_cipherbynid 332.Fa "int nid" 333.Fc 334.Ft const EVP_CIPHER * 335.Fo EVP_get_cipherbyobj 336.Fa "const ASN1_OBJECT *a" 337.Fc 338.Ft int 339.Fo EVP_CIPHER_nid 340.Fa "const EVP_CIPHER *e" 341.Fc 342.Ft int 343.Fo EVP_CIPHER_block_size 344.Fa "const EVP_CIPHER *e" 345.Fc 346.Ft int 347.Fo EVP_CIPHER_key_length 348.Fa "const EVP_CIPHER *e" 349.Fc 350.Ft int 351.Fo EVP_CIPHER_iv_length 352.Fa "const EVP_CIPHER *e" 353.Fc 354.Ft unsigned long 355.Fo EVP_CIPHER_flags 356.Fa "const EVP_CIPHER *e" 357.Fc 358.Ft unsigned long 359.Fo EVP_CIPHER_mode 360.Fa "const EVP_CIPHER *e" 361.Fc 362.Ft int 363.Fo EVP_CIPHER_type 364.Fa "const EVP_CIPHER *ctx" 365.Fc 366.Ft const EVP_CIPHER * 367.Fo EVP_CIPHER_CTX_cipher 368.Fa "const EVP_CIPHER_CTX *ctx" 369.Fc 370.Ft int 371.Fo EVP_CIPHER_CTX_nid 372.Fa "const EVP_CIPHER_CTX *ctx" 373.Fc 374.Ft int 375.Fo EVP_CIPHER_CTX_block_size 376.Fa "const EVP_CIPHER_CTX *ctx" 377.Fc 378.Ft int 379.Fo EVP_CIPHER_CTX_key_length 380.Fa "const EVP_CIPHER_CTX *ctx" 381.Fc 382.Ft int 383.Fo EVP_CIPHER_CTX_iv_length 384.Fa "const EVP_CIPHER_CTX *ctx" 385.Fc 386.Ft int 387.Fo EVP_CIPHER_CTX_get_iv 388.Fa "const EVP_CIPHER_CTX *ctx" 389.Fa "unsigned char *iv" 390.Fa "size_t len" 391.Fc 392.Ft int 393.Fo EVP_CIPHER_CTX_set_iv 394.Fa "EVP_CIPHER_CTX *ctx" 395.Fa "const unsigned char *iv" 396.Fa "size_t len" 397.Fc 398.Ft void * 399.Fo EVP_CIPHER_CTX_get_app_data 400.Fa "const EVP_CIPHER_CTX *ctx" 401.Fc 402.Ft void 403.Fo EVP_CIPHER_CTX_set_app_data 404.Fa "const EVP_CIPHER_CTX *ctx" 405.Fa "void *data" 406.Fc 407.Ft int 408.Fo EVP_CIPHER_CTX_type 409.Fa "const EVP_CIPHER_CTX *ctx" 410.Fc 411.Ft unsigned long 412.Fo EVP_CIPHER_CTX_flags 413.Fa "const EVP_CIPHER_CTX *ctx" 414.Fc 415.Ft unsigned long 416.Fo EVP_CIPHER_CTX_mode 417.Fa "const EVP_CIPHER_CTX *ctx" 418.Fc 419.Ft int 420.Fo EVP_CIPHER_param_to_asn1 421.Fa "EVP_CIPHER_CTX *c" 422.Fa "ASN1_TYPE *type" 423.Fc 424.Ft int 425.Fo EVP_CIPHER_asn1_to_param 426.Fa "EVP_CIPHER_CTX *c" 427.Fa "ASN1_TYPE *type" 428.Fc 429.Sh DESCRIPTION 430The EVP cipher routines are a high level interface to certain symmetric 431ciphers. 432.Pp 433.Fn EVP_CIPHER_CTX_new 434creates a new, empty cipher context. 435.Pp 436.Fn EVP_CIPHER_CTX_reset 437clears all information from 438.Fa ctx 439and frees all allocated memory associated with it, except the 440.Fa ctx 441object itself, such that it can be reused for another series of calls to 442.Fn EVP_CipherInit , 443.Fn EVP_CipherUpdate , 444and 445.Fn EVP_CipherFinal . 446It is also suitable for cipher contexts on the stack that were used 447and are no longer needed. 448.Fn EVP_CIPHER_CTX_cleanup 449is a deprecated alias for 450.Fn EVP_CIPHER_CTX_reset . 451.Pp 452.Fn EVP_CIPHER_CTX_init 453is a deprecated function to clear a cipher context on the stack 454before use. 455Do not use it on a cipher context returned from 456.Fn EVP_CIPHER_CTX_new 457or one that was already used. 458.Pp 459.Fn EVP_CIPHER_CTX_free 460clears all information from 461.Fa ctx 462and frees all allocated memory associated with it, including 463.Fa ctx 464itself. 465This function should be called after all operations using a cipher 466are complete, so sensitive information does not remain in memory. 467If 468.Fa ctx 469is a 470.Dv NULL 471pointer, no action occurs. 472.Pp 473.Fn EVP_EncryptInit_ex 474sets up the cipher context 475.Fa ctx 476for encryption with cipher 477.Fa type 478from 479.Vt ENGINE 480.Fa impl . 481If 482.Fa ctx 483points to an unused object on the stack, it must be initialized with 484.Fn EVP_MD_CTX_init 485before calling this function. 486.Fa type 487is normally supplied by a function such as 488.Xr EVP_aes_256_cbc 3 . 489If 490.Fa impl 491is 492.Dv NULL , 493then the default implementation is used. 494.Fa key 495is the symmetric key to use and 496.Fa iv 497is the IV to use (if necessary). 498The actual number of bytes used for the 499key and IV depends on the cipher. 500It is possible to set all parameters to 501.Dv NULL 502except 503.Fa type 504in an initial call and supply the remaining parameters in subsequent 505calls, all of which have 506.Fa type 507set to 508.Dv NULL . 509This is done when the default cipher parameters are not appropriate. 510.Pp 511.Fn EVP_EncryptUpdate 512encrypts 513.Fa inl 514bytes from the buffer 515.Fa in 516and writes the encrypted version to 517.Fa out . 518This function can be called multiple times to encrypt successive blocks 519of data. 520The amount of data written depends on the block alignment of the 521encrypted data: as a result the amount of data written may be anything 522from zero bytes to (inl + cipher_block_size - 1) so 523.Fa out 524should contain sufficient room. 525The actual number of bytes written is placed in 526.Fa outl . 527.Pp 528If padding is enabled (the default) then 529.Fn EVP_EncryptFinal_ex 530encrypts the "final" data, that is any data that remains in a partial 531block. 532It uses NOTES (aka PKCS padding). 533The encrypted final data is written to 534.Fa out 535which should have sufficient space for one cipher block. 536The number of bytes written is placed in 537.Fa outl . 538After this function is called the encryption operation is finished and 539no further calls to 540.Fn EVP_EncryptUpdate 541should be made. 542.Pp 543If padding is disabled then 544.Fn EVP_EncryptFinal_ex 545will not encrypt any more data and it will return an error if any data 546remains in a partial block: that is if the total data length is not a 547multiple of the block size. 548.Pp 549.Fn EVP_DecryptInit_ex , 550.Fn EVP_DecryptUpdate , 551and 552.Fn EVP_DecryptFinal_ex 553are the corresponding decryption operations. 554.Fn EVP_DecryptFinal 555will return an error code if padding is enabled and the final block is 556not correctly formatted. 557The parameters and restrictions are identical to the encryption 558operations except that if padding is enabled the decrypted data buffer 559.Fa out 560passed to 561.Fn EVP_DecryptUpdate 562should have sufficient room for (inl + cipher_block_size) bytes 563unless the cipher block size is 1 in which case 564.Fa inl 565bytes is sufficient. 566.Pp 567.Fn EVP_CipherInit_ex , 568.Fn EVP_CipherUpdate , 569and 570.Fn EVP_CipherFinal_ex 571are functions that can be used for decryption or encryption. 572The operation performed depends on the value of the 573.Fa enc 574parameter. 575It should be set to 1 for encryption, 0 for decryption and -1 to leave 576the value unchanged (the actual value of 577.Fa enc 578being supplied in a previous call). 579.Pp 580.Fn EVP_EncryptInit , 581.Fn EVP_DecryptInit , 582and 583.Fn EVP_CipherInit 584are deprecated functions behaving like 585.Fn EVP_EncryptInit_ex , 586.Fn EVP_DecryptInit_ex , 587and 588.Fn EVP_CipherInit_ex 589except that they always use the default cipher implementation 590and that they require 591.Fn EVP_CIPHER_CTX_reset 592before they can be used on a context that was already used. 593.Pp 594.Fn EVP_EncryptFinal , 595.Fn EVP_DecryptFinal , 596and 597.Fn EVP_CipherFinal 598are identical to 599.Fn EVP_EncryptFinal_ex , 600.Fn EVP_DecryptFinal_ex , 601and 602.Fn EVP_CipherFinal_ex . 603In previous releases of OpenSSL, they also used to clean up the 604.Fa ctx , 605but this is no longer done and 606.Fn EVP_CIPHER_CTX_reset 607or 608.Fn EVP_CIPHER_CTX_free 609must be called to free any context resources. 610.Pp 611.Fn EVP_Cipher 612encrypts or decrypts aligned blocks of data 613whose lengths match the cipher block size. 614It requires that the previous encryption or decryption operation 615using the same 616.Fa ctx , 617if there was any, ended exactly on a block boundary and that 618.Fa inl 619is an integer multiple of the cipher block size. 620If either of these conditions is violated, 621.Fn EVP_Cipher 622silently produces incorrect results. 623For that reason, using the function 624.Fn EVP_CipherUpdate 625instead is strongly recommended. 626The latter can safely handle partial blocks, and even if 627.Fa inl 628actually is a multiple of the cipher block size for all calls, 629the overhead incurred by using 630.Fn EVP_CipherUpdate 631is minimal. 632.Pp 633.Fn EVP_get_cipherbyname , 634.Fn EVP_get_cipherbynid , 635and 636.Fn EVP_get_cipherbyobj 637return an 638.Vt EVP_CIPHER 639structure when passed a cipher name, a NID or an 640.Vt ASN1_OBJECT 641structure. 642.Pp 643.Fn EVP_CIPHER_nid 644and 645.Fn EVP_CIPHER_CTX_nid 646return the NID of a cipher when passed an 647.Vt EVP_CIPHER 648or 649.Vt EVP_CIPHER_CTX 650structure. 651The actual NID value is an internal value which may not have a 652corresponding OBJECT IDENTIFIER. 653.Pp 654.Fn EVP_CIPHER_CTX_set_flags 655enables the given 656.Fa flags 657in 658.Fa ctx . 659.Fn EVP_CIPHER_CTX_clear_flags 660disables the given 661.Fa flags 662in 663.Fa ctx . 664.Fn EVP_CIPHER_CTX_test_flags 665checks whether any of the given 666.Fa flags 667are currently set in 668.Fa ctx , 669returning the subset of the 670.Fa flags 671that are set, or 0 if none of them are set. 672Currently, the only supported cipher context flag is 673.Dv EVP_CIPHER_CTX_FLAG_WRAP_ALLOW ; 674see 675.Xr EVP_aes_128_wrap 3 676for details. 677.Pp 678.Fn EVP_CIPHER_CTX_set_padding 679enables or disables padding. 680This function should be called after the context is set up for 681encryption or decryption with 682.Fn EVP_EncryptInit_ex , 683.Fn EVP_DecryptInit_ex , 684or 685.Fn EVP_CipherInit_ex . 686By default encryption operations are padded using standard block padding 687and the padding is checked and removed when decrypting. 688If the 689.Fa padding 690parameter is zero, then no padding is performed, the total amount of data 691encrypted or decrypted must then be a multiple of the block size or an 692error will occur. 693.Pp 694.Fn EVP_CIPHER_key_length 695and 696.Fn EVP_CIPHER_CTX_key_length 697return the key length of a cipher when passed an 698.Vt EVP_CIPHER 699or 700.Vt EVP_CIPHER_CTX 701structure. 702The constant 703.Dv EVP_MAX_KEY_LENGTH 704is the maximum key length for all ciphers. 705Note: although 706.Fn EVP_CIPHER_key_length 707is fixed for a given cipher, the value of 708.Fn EVP_CIPHER_CTX_key_length 709may be different for variable key length ciphers. 710.Pp 711.Fn EVP_CIPHER_CTX_set_key_length 712sets the key length of the cipher ctx. 713If the cipher is a fixed length cipher, then attempting to set the key 714length to any value other than the fixed value is an error. 715.Pp 716.Fn EVP_CIPHER_iv_length 717and 718.Fn EVP_CIPHER_CTX_iv_length 719return the IV length of a cipher when passed an 720.Vt EVP_CIPHER 721or 722.Vt EVP_CIPHER_CTX . 723It will return zero if the cipher does not use an IV. 724The constant 725.Dv EVP_MAX_IV_LENGTH 726is the maximum IV length for all ciphers. 727.Pp 728.Fn EVP_CIPHER_CTX_get_iv 729and 730.Fn EVP_CIPHER_CTX_set_iv 731will respectively retrieve and set the IV for an 732.Vt EVP_CIPHER_CTX . 733In both cases, the specified IV length must exactly equal the expected 734IV length for the context as returned by 735.Fn EVP_CIPHER_CTX_iv_length . 736.Pp 737.Fn EVP_CIPHER_block_size 738and 739.Fn EVP_CIPHER_CTX_block_size 740return the block size of a cipher when passed an 741.Vt EVP_CIPHER 742or 743.Vt EVP_CIPHER_CTX 744structure. 745The constant 746.Dv EVP_MAX_BLOCK_LENGTH 747is also the maximum block length for all ciphers. 748.Pp 749.Fn EVP_CIPHER_type 750and 751.Fn EVP_CIPHER_CTX_type 752return the type of the passed cipher or context. 753This "type" is the actual NID of the cipher OBJECT IDENTIFIER as such it 754ignores the cipher parameters and 40-bit RC2 and 128-bit RC2 have the 755same NID. 756If the cipher does not have an object identifier or does not 757have ASN.1 support this function will return 758.Dv NID_undef . 759.Pp 760.Fn EVP_CIPHER_CTX_cipher 761returns the 762.Vt EVP_CIPHER 763structure when passed an 764.Vt EVP_CIPHER_CTX 765structure. 766.Pp 767.Fn EVP_CIPHER_mode 768and 769.Fn EVP_CIPHER_CTX_mode 770return the block cipher mode: 771.Dv EVP_CIPH_ECB_MODE , 772.Dv EVP_CIPH_CBC_MODE , 773.Dv EVP_CIPH_CFB_MODE , 774.Dv EVP_CIPH_OFB_MODE , 775.Dv EVP_CIPH_CTR_MODE , 776or 777.Dv EVP_CIPH_XTS_MODE . 778If the cipher is a stream cipher then 779.Dv EVP_CIPH_STREAM_CIPHER 780is returned. 781.Pp 782.Fn EVP_CIPHER_param_to_asn1 783sets the ASN.1 784.Vt AlgorithmIdentifier 785parameter based on the passed cipher. 786This will typically include any parameters and an IV. 787The cipher IV (if any) must be set when this call is made. 788This call should be made before the cipher is actually "used" (before any 789.Fn EVP_EncryptUpdate 790or 791.Fn EVP_DecryptUpdate 792calls, for example). 793This function may fail if the cipher does not have any ASN.1 support. 794.Pp 795.Fn EVP_CIPHER_asn1_to_param 796sets the cipher parameters based on an ASN.1 797.Vt AlgorithmIdentifier 798parameter. 799The precise effect depends on the cipher. 800In the case of RC2, for example, it will set the IV and effective 801key length. 802This function should be called after the base cipher type is set but 803before the key is set. 804For example 805.Fn EVP_CipherInit 806will be called with the IV and key set to 807.Dv NULL , 808.Fn EVP_CIPHER_asn1_to_param 809will be called and finally 810.Fn EVP_CipherInit 811again with all parameters except the key set to 812.Dv NULL . 813It is possible for this function to fail if the cipher does not 814have any ASN.1 support or the parameters cannot be set (for example 815the RC2 effective key length is not supported). 816.Pp 817.Fn EVP_CIPHER_CTX_ctrl 818allows various cipher specific parameters to be determined and set. 819Currently only the RC2 effective key length can be set. 820.Pp 821.Fn EVP_CIPHER_CTX_rand_key 822generates a random key of the appropriate length based on the cipher 823context. 824The 825.Vt EVP_CIPHER 826can provide its own random key generation routine to support keys 827of a specific form. 828The 829.Fa key 830argument must point to a buffer at least as big as the value returned by 831.Fn EVP_CIPHER_CTX_key_length . 832.Pp 833Where possible the EVP interface to symmetric ciphers should be 834used in preference to the low level interfaces. 835This is because the code then becomes transparent to the cipher used and 836much more flexible. 837.Pp 838PKCS padding works by adding n padding bytes of value n to make the 839total length of the encrypted data a multiple of the block size. 840Padding is always added so if the data is already a multiple of the 841block size n will equal the block size. 842For example if the block size is 8 and 11 bytes are to be encrypted then 8435 padding bytes of value 5 will be added. 844.Pp 845When decrypting the final block is checked to see if it has the correct 846form. 847.Pp 848Although the decryption operation can produce an error if padding is 849enabled, it is not a strong test that the input data or key is correct. 850A random block has better than 1 in 256 chance of being of the correct 851format and problems with the input data earlier on will not produce a 852final decrypt error. 853.Pp 854If padding is disabled then the decryption operation will always succeed 855if the total amount of data decrypted is a multiple of the block size. 856.Pp 857The functions 858.Fn EVP_EncryptInit , 859.Fn EVP_EncryptFinal , 860.Fn EVP_DecryptInit , 861.Fn EVP_CipherInit , 862and 863.Fn EVP_CipherFinal 864are obsolete but are retained for compatibility with existing code. 865New code should use 866.Fn EVP_EncryptInit_ex , 867.Fn EVP_EncryptFinal_ex , 868.Fn EVP_DecryptInit_ex , 869.Fn EVP_DecryptFinal_ex , 870.Fn EVP_CipherInit_ex , 871and 872.Fn EVP_CipherFinal_ex 873because they can reuse an existing context without allocating and 874freeing it up on each call. 875.Pp 876.Fn EVP_get_cipherbynid 877and 878.Fn EVP_get_cipherbyobj 879are implemented as macros. 880.Sh RETURN VALUES 881.Fn EVP_CIPHER_CTX_new 882returns a pointer to a newly created 883.Vt EVP_CIPHER_CTX 884for success or 885.Dv NULL 886for failure. 887.Pp 888.Fn EVP_CIPHER_CTX_reset , 889.Fn EVP_CIPHER_CTX_cleanup , 890.Fn EVP_CIPHER_CTX_get_iv , 891.Fn EVP_CIPHER_CTX_set_iv , 892.Fn EVP_EncryptInit_ex , 893.Fn EVP_EncryptUpdate , 894.Fn EVP_EncryptFinal_ex , 895.Fn EVP_DecryptInit_ex , 896.Fn EVP_DecryptUpdate , 897.Fn EVP_DecryptFinal_ex , 898.Fn EVP_CipherInit_ex , 899.Fn EVP_CipherUpdate , 900.Fn EVP_CipherFinal_ex , 901.Fn EVP_EncryptInit , 902.Fn EVP_EncryptFinal , 903.Fn EVP_DecryptInit , 904.Fn EVP_DecryptFinal , 905.Fn EVP_CipherInit , 906.Fn EVP_CipherFinal , 907.Fn EVP_Cipher , 908.Fn EVP_CIPHER_CTX_set_key_length , 909and 910.Fn EVP_CIPHER_CTX_rand_key 911return 1 for success or 0 for failure. 912.Pp 913.Fn EVP_CIPHER_CTX_set_padding 914always returns 1. 915.Pp 916.Fn EVP_get_cipherbyname , 917.Fn EVP_get_cipherbynid , 918and 919.Fn EVP_get_cipherbyobj 920return an 921.Vt EVP_CIPHER 922structure or 923.Dv NULL 924on error. 925.Pp 926.Fn EVP_CIPHER_nid 927and 928.Fn EVP_CIPHER_CTX_nid 929return a NID. 930.Pp 931.Fn EVP_CIPHER_block_size 932and 933.Fn EVP_CIPHER_CTX_block_size 934return the block size. 935.Pp 936.Fn EVP_CIPHER_key_length 937and 938.Fn EVP_CIPHER_CTX_key_length 939return the key length. 940.Pp 941.Fn EVP_CIPHER_iv_length 942and 943.Fn EVP_CIPHER_CTX_iv_length 944return the IV length or zero if the cipher does not use an IV. 945.Pp 946.Fn EVP_CIPHER_type 947and 948.Fn EVP_CIPHER_CTX_type 949return the NID of the cipher's OBJECT IDENTIFIER or 950.Dv NID_undef 951if it has no defined OBJECT IDENTIFIER. 952.Pp 953.Fn EVP_CIPHER_CTX_cipher 954returns an 955.Vt EVP_CIPHER 956structure. 957.Pp 958.Fn EVP_CIPHER_param_to_asn1 959and 960.Fn EVP_CIPHER_asn1_to_param 961return greater than zero for success and zero or a negative number 962for failure. 963.Sh CIPHER LISTING 964All algorithms have a fixed key length unless otherwise stated. 965.Bl -tag -width Ds 966.It Fn EVP_enc_null 967Null cipher: does nothing. 968.It Xo 969.Fn EVP_idea_cbc , 970.Fn EVP_idea_ecb , 971.Fn EVP_idea_cfb64 , 972.Fn EVP_idea_ofb 973.Xc 974IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 975.Fn EVP_idea_cfb 976is an alias for 977.Fn EVP_idea_cfb64 , 978implemented as a macro. 979.It Xo 980.Fn EVP_rc2_cbc , 981.Fn EVP_rc2_ecb , 982.Fn EVP_rc2_cfb64 , 983.Fn EVP_rc2_ofb 984.Xc 985RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 986This is a variable key length cipher with an additional parameter called 987"effective key bits" or "effective key length". 988By default both are set to 128 bits. 989.Fn EVP_rc2_cfb 990is an alias for 991.Fn EVP_rc2_cfb64 , 992implemented as a macro. 993.It Xo 994.Fn EVP_rc2_40_cbc , 995.Fn EVP_rc2_64_cbc 996.Xc 997RC2 algorithm in CBC mode with a default key length and effective key 998length of 40 and 64 bits. 999These are obsolete and new code should use 1000.Fn EVP_rc2_cbc , 1001.Fn EVP_CIPHER_CTX_set_key_length , 1002and 1003.Fn EVP_CIPHER_CTX_ctrl 1004to set the key length and effective key length. 1005.It Xo 1006.Fn EVP_bf_cbc , 1007.Fn EVP_bf_ecb , 1008.Fn EVP_bf_cfb64 , 1009.Fn EVP_bf_ofb 1010.Xc 1011Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes 1012respectively. 1013This is a variable key length cipher. 1014.Fn EVP_bf_cfb 1015is an alias for 1016.Fn EVP_bf_cfb64 , 1017implemented as a macro. 1018.It Xo 1019.Fn EVP_cast5_cbc , 1020.Fn EVP_cast5_ecb , 1021.Fn EVP_cast5_cfb64 , 1022.Fn EVP_cast5_ofb 1023.Xc 1024CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 1025This is a variable key length cipher. 1026.Fn EVP_cast5_cfb 1027is an alias for 1028.Fn EVP_cast5_cfb64 , 1029implemented as a macro. 1030.It Fn EVP_chacha20 1031The ChaCha20 stream cipher. 1032The key length is 256 bits. 1033The first 32 bits of the 128-bit IV are used as a counter, 1034and the remaining 96 bits as a nonce. 1035.El 1036.Pp 1037See also 1038.Xr EVP_aes_128_cbc 3 , 1039.Xr EVP_camellia_128_cbc 3 , 1040.Xr EVP_des_cbc 3 , 1041.Xr EVP_rc4 3 , 1042and 1043.Xr EVP_sm4_cbc 3 . 1044.Ss GCM mode 1045For GCM mode ciphers, the behaviour of the EVP interface 1046is subtly altered and several additional ctrl operations are 1047supported. 1048.Pp 1049To specify any additional authenticated data (AAD), a call to 1050.Fn EVP_CipherUpdate , 1051.Fn EVP_EncryptUpdate , 1052or 1053.Fn EVP_DecryptUpdate 1054should be made with the output parameter out set to 1055.Dv NULL . 1056.Pp 1057When decrypting, the return value of 1058.Fn EVP_DecryptFinal 1059or 1060.Fn EVP_CipherFinal 1061indicates if the operation was successful. 1062If it does not indicate success, the authentication operation has 1063failed and any output data MUST NOT be used as it is corrupted. 1064.Pp 1065The following ctrls are supported in GCM mode: 1066.Bl -tag -width Ds 1067.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_IVLEN ivlen NULL 1068Sets the IV length: this call can only be made before specifying an IV. 1069If not called, a default IV length is used. 1070For GCM AES the default is 12, i.e. 96 bits. 1071.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_GET_TAG taglen tag 1072Writes 1073.Fa taglen 1074bytes of the tag value to the buffer indicated by 1075.Fa tag . 1076This call can only be made when encrypting data and after all data has 1077been processed, e.g. after an 1078.Fn EVP_EncryptFinal 1079call. 1080.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_TAG taglen tag 1081Sets the expected tag to 1082.Fa taglen 1083bytes from 1084.Fa tag . 1085This call is only legal when decrypting data and must be made before 1086any data is processed, e.g. before any 1087.Fa EVP_DecryptUpdate 1088call. 1089.El 1090.Ss CCM mode 1091The behaviour of CCM mode ciphers is similar to GCM mode, but with 1092a few additional requirements and different ctrl values. 1093.Pp 1094Like GCM mode any additional authenticated data (AAD) is passed 1095by calling 1096.Fn EVP_CipherUpdate , 1097.Fn EVP_EncryptUpdate , 1098or 1099.Fn EVP_DecryptUpdate 1100with the output parameter out set to 1101.Dv NULL . 1102Additionally, the total 1103plaintext or ciphertext length MUST be passed to 1104.Fn EVP_CipherUpdate , 1105.Fn EVP_EncryptUpdate , 1106or 1107.Fn EVP_DecryptUpdate 1108with the output and input 1109parameters 1110.Pq Fa in No and Fa out 1111set to 1112.Dv NULL 1113and the length passed in the 1114.Fa inl 1115parameter. 1116.Pp 1117The following ctrls are supported in CCM mode: 1118.Bl -tag -width Ds 1119.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_TAG taglen tag 1120This call is made to set the expected CCM tag value when decrypting or 1121the length of the tag (with the 1122.Fa tag 1123parameter set to 1124.Dv NULL ) 1125when encrypting. 1126The tag length is often referred to as M. 1127If not set, a default value is used (12 for AES). 1128.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_L ivlen NULL 1129Sets the CCM L value. 1130If not set, a default is used (8 for AES). 1131.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_IVLEN ivlen NULL 1132Sets the CCM nonce (IV) length: this call can only be made before 1133specifying a nonce value. 1134The nonce length is given by 15 - L so it is 7 by default for AES. 1135.El 1136.Sh EXAMPLES 1137Encrypt a string using blowfish: 1138.Bd -literal -offset 3n 1139int 1140do_crypt(char *outfile) 1141{ 1142 unsigned char outbuf[1024]; 1143 int outlen, tmplen; 1144 /* 1145 * Bogus key and IV: we'd normally set these from 1146 * another source. 1147 */ 1148 unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; 1149 unsigned char iv[] = {1,2,3,4,5,6,7,8}; 1150 const char intext[] = "Some Crypto Text"; 1151 EVP_CIPHER_CTX *ctx; 1152 FILE *out; 1153 1154 ctx = EVP_CIPHER_CTX_new(); 1155 EVP_EncryptInit_ex(ctx, EVP_bf_cbc(), NULL, key, iv); 1156 1157 if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, 1158 strlen(intext))) { 1159 /* Error */ 1160 EVP_CIPHER_CTX_free(ctx); 1161 return 0; 1162 } 1163 /* 1164 * Buffer passed to EVP_EncryptFinal() must be after data just 1165 * encrypted to avoid overwriting it. 1166 */ 1167 if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) { 1168 /* Error */ 1169 EVP_CIPHER_CTX_free(ctx); 1170 return 0; 1171 } 1172 outlen += tmplen; 1173 EVP_CIPHER_CTX_free(ctx); 1174 /* 1175 * Need binary mode for fopen because encrypted data is 1176 * binary data. Also cannot use strlen() on it because 1177 * it won't be NUL terminated and may contain embedded 1178 * NULs. 1179 */ 1180 out = fopen(outfile, "wb"); 1181 if (out == NULL) { 1182 /* Error */ 1183 return 0; 1184 } 1185 fwrite(outbuf, 1, outlen, out); 1186 fclose(out); 1187 return 1; 1188} 1189.Ed 1190.Pp 1191The ciphertext from the above example can be decrypted using the 1192.Xr openssl 1 1193utility with the command line: 1194.Bd -literal -offset indent 1195openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F \e 1196 -iv 0102030405060708 -d 1197.Ed 1198.Pp 1199General encryption, decryption function example using FILE I/O and AES128 1200with a 128-bit key: 1201.Bd -literal 1202int 1203do_crypt(FILE *in, FILE *out, int do_encrypt) 1204{ 1205 /* Allow enough space in output buffer for additional block */ 1206 unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; 1207 int inlen, outlen; 1208 EVP_CIPHER_CTX *ctx; 1209 1210 /* 1211 * Bogus key and IV: we'd normally set these from 1212 * another source. 1213 */ 1214 unsigned char key[] = "0123456789abcdeF"; 1215 unsigned char iv[] = "1234567887654321"; 1216 1217 ctx = EVP_CIPHER_CTX_new(); 1218 EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, 1219 do_encrypt); 1220 EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); 1221 1222 for (;;) { 1223 inlen = fread(inbuf, 1, 1024, in); 1224 if (inlen <= 0) 1225 break; 1226 if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, 1227 inlen)) { 1228 /* Error */ 1229 EVP_CIPHER_CTX_free(ctx); 1230 return 0; 1231 } 1232 fwrite(outbuf, 1, outlen, out); 1233 } 1234 if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) { 1235 /* Error */ 1236 EVP_CIPHER_CTX_free(ctx); 1237 return 0; 1238 } 1239 fwrite(outbuf, 1, outlen, out); 1240 1241 EVP_CIPHER_CTX_free(ctx); 1242 return 1; 1243} 1244.Ed 1245.Sh SEE ALSO 1246.Xr BIO_f_cipher 3 , 1247.Xr evp 3 , 1248.Xr EVP_AEAD_CTX_init 3 , 1249.Xr EVP_aes_128_cbc 3 , 1250.Xr EVP_camellia_128_cbc 3 , 1251.Xr EVP_des_cbc 3 , 1252.Xr EVP_OpenInit 3 , 1253.Xr EVP_rc4 3 , 1254.Xr EVP_SealInit 3 , 1255.Xr EVP_sm4_cbc 3 1256.Sh HISTORY 1257.Fn EVP_EncryptInit , 1258.Fn EVP_EncryptUpdate , 1259.Fn EVP_EncryptFinal , 1260.Fn EVP_DecryptInit , 1261.Fn EVP_DecryptUpdate , 1262.Fn EVP_DecryptFinal , 1263.Fn EVP_CipherInit , 1264.Fn EVP_CipherUpdate , 1265.Fn EVP_CipherFinal , 1266.Fn EVP_get_cipherbyname , 1267.Fn EVP_idea_cbc , 1268.Fn EVP_idea_ecb , 1269.Fn EVP_idea_cfb , 1270and 1271.Fn EVP_idea_ofb 1272first appeared in SSLeay 0.5.1. 1273.Fn EVP_rc2_cbc , 1274.Fn EVP_rc2_ecb , 1275.Fn EVP_rc2_cfb , 1276and 1277.Fn EVP_rc2_ofb 1278first appeared in SSLeay 0.5.2. 1279.Fn EVP_Cipher , 1280.Fn EVP_CIPHER_block_size , 1281.Fn EVP_CIPHER_key_length , 1282.Fn EVP_CIPHER_iv_length , 1283.Fn EVP_CIPHER_type , 1284.Fn EVP_CIPHER_CTX_block_size , 1285.Fn EVP_CIPHER_CTX_key_length , 1286.Fn EVP_CIPHER_CTX_iv_length , 1287and 1288.Fn EVP_CIPHER_CTX_type 1289first appeared in SSLeay 0.6.5. 1290.Fn EVP_bf_cbc , 1291.Fn EVP_bf_ecb , 1292.Fn EVP_bf_cfb , 1293and 1294.Fn EVP_bf_ofb 1295first appeared in SSLeay 0.6.6. 1296.Fn EVP_CIPHER_CTX_cleanup , 1297.Fn EVP_get_cipherbyobj , 1298.Fn EVP_CIPHER_nid , 1299.Fn EVP_CIPHER_CTX_cipher , 1300.Fn EVP_CIPHER_CTX_nid , 1301.Fn EVP_CIPHER_CTX_get_app_data , 1302.Fn EVP_CIPHER_CTX_set_app_data , 1303and 1304.Fn EVP_enc_null 1305first appeared in SSLeay 0.8.0. 1306.Fn EVP_get_cipherbynid 1307first appeared in SSLeay 0.8.1. 1308.Fn EVP_CIPHER_CTX_init , 1309.Fn EVP_CIPHER_param_to_asn1 , 1310and 1311.Fn EVP_CIPHER_asn1_to_param 1312first appeared in SSLeay 0.9.0. 1313All these functions have been available since 1314.Ox 2.4 . 1315.Pp 1316.Fn EVP_rc2_40_cbc 1317and 1318.Fn EVP_rc2_64_cbc 1319first appeared in SSL_eay 0.9.1. 1320.Fn EVP_CIPHER_CTX_type 1321first appeared in OpenSSL 0.9.3. 1322These functions have been available since 1323.Ox 2.6 . 1324.Pp 1325.Fn EVP_CIPHER_CTX_set_key_length , 1326.Fn EVP_CIPHER_CTX_ctrl , 1327.Fn EVP_CIPHER_flags , 1328.Fn EVP_CIPHER_mode , 1329.Fn EVP_CIPHER_CTX_flags , 1330and 1331.Fn EVP_CIPHER_CTX_mode 1332first appeared in OpenSSL 0.9.6 and have been available since 1333.Ox 2.9 . 1334.Pp 1335.Fn EVP_EncryptInit_ex , 1336.Fn EVP_EncryptFinal_ex , 1337.Fn EVP_DecryptInit_ex , 1338.Fn EVP_DecryptFinal_ex , 1339.Fn EVP_CipherInit_ex , 1340.Fn EVP_CipherFinal_ex , 1341and 1342.Fn EVP_CIPHER_CTX_set_padding 1343first appeared in OpenSSL 0.9.7 and have been available since 1344.Ox 3.2 . 1345.Pp 1346.Fn EVP_bf_cfb64 , 1347.Fn EVP_cast5_cfb64 , 1348.Fn EVP_idea_cfb64 , 1349and 1350.Fn EVP_rc2_cfb64 1351first appeared in OpenSSL 0.9.7e and have been available since 1352.Ox 3.8 . 1353.Pp 1354.Fn EVP_CIPHER_CTX_rand_key 1355first appeared in OpenSSL 0.9.8. 1356.Fn EVP_CIPHER_CTX_new 1357and 1358.Fn EVP_CIPHER_CTX_free 1359first appeared in OpenSSL 0.9.8b. 1360These functions have been available since 1361.Ox 4.5 . 1362.Pp 1363.Fn EVP_CIPHER_CTX_reset 1364first appeared in OpenSSL 1.1.0 and has been available since 1365.Ox 6.3 . 1366.Pp 1367.Fn EVP_CIPHER_CTX_get_iv 1368and 1369.Fn EVP_CIPHER_CTX_set_iv 1370first appeared in LibreSSL 2.8.1 and has been available since 1371.Ox 6.4 . 1372.Sh BUGS 1373.Dv EVP_MAX_KEY_LENGTH 1374and 1375.Dv EVP_MAX_IV_LENGTH 1376only refer to the internal ciphers with default key lengths. 1377If custom ciphers exceed these values the results are unpredictable. 1378This is because it has become standard practice to define a generic key 1379as a fixed unsigned char array containing 1380.Dv EVP_MAX_KEY_LENGTH 1381bytes. 1382.Pp 1383The ASN.1 code is incomplete (and sometimes inaccurate). 1384It has only been tested for certain common S/MIME ciphers 1385(RC2, DES, triple DES) in CBC mode. 1386