1.\" $OpenBSD: EVP_EncryptInit.3,v 1.44 2022/08/31 14:27:34 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: August 31 2022 $ 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 . 446.Fn EVP_CIPHER_CTX_cleanup 447is a deprecated alias for 448.Fn EVP_CIPHER_CTX_reset . 449.Pp 450.Fn EVP_CIPHER_CTX_init 451is a deprecated function to clear a cipher context on the stack 452before use. 453Do not use it on a cipher context returned from 454.Fn EVP_CIPHER_CTX_new 455or one that was already used. 456.Pp 457.Fn EVP_CIPHER_CTX_free 458clears all information from 459.Fa ctx 460and frees all allocated memory associated with it, including 461.Fa ctx 462itself. 463This function should be called after all operations using a cipher 464are complete, so sensitive information does not remain in memory. 465If 466.Fa ctx 467is a 468.Dv NULL 469pointer, no action occurs. 470.Pp 471.Fn EVP_EncryptInit_ex 472sets up the cipher context 473.Fa ctx 474for encryption with cipher 475.Fa type 476from 477.Vt ENGINE 478.Fa impl . 479.Fa type 480is normally supplied by a function such as 481.Xr EVP_aes_256_cbc 3 . 482If 483.Fa impl 484is 485.Dv NULL , 486then the default implementation is used. 487.Fa key 488is the symmetric key to use and 489.Fa iv 490is the IV to use (if necessary). 491The actual number of bytes used for the 492key and IV depends on the cipher. 493It is possible to set all parameters to 494.Dv NULL 495except 496.Fa type 497in an initial call and supply the remaining parameters in subsequent 498calls, all of which have 499.Fa type 500set to 501.Dv NULL . 502This is done when the default cipher parameters are not appropriate. 503.Pp 504.Fn EVP_EncryptUpdate 505encrypts 506.Fa inl 507bytes from the buffer 508.Fa in 509and writes the encrypted version to 510.Fa out . 511This function can be called multiple times to encrypt successive blocks 512of data. 513The amount of data written depends on the block alignment of the 514encrypted data: as a result the amount of data written may be anything 515from zero bytes to (inl + cipher_block_size - 1) so 516.Fa out 517should contain sufficient room. 518The actual number of bytes written is placed in 519.Fa outl . 520.Pp 521If padding is enabled (the default) then 522.Fn EVP_EncryptFinal_ex 523encrypts the "final" data, that is any data that remains in a partial 524block. 525It uses NOTES (aka PKCS padding). 526The encrypted final data is written to 527.Fa out 528which should have sufficient space for one cipher block. 529The number of bytes written is placed in 530.Fa outl . 531After this function is called, the encryption operation is finished and 532no further calls to 533.Fn EVP_EncryptUpdate 534should be made. 535.Pp 536If padding is disabled then 537.Fn EVP_EncryptFinal_ex 538will not encrypt any more data and it will return an error if any data 539remains in a partial block: that is if the total data length is not a 540multiple of the block size. 541.Pp 542.Fn EVP_DecryptInit_ex , 543.Fn EVP_DecryptUpdate , 544and 545.Fn EVP_DecryptFinal_ex 546are the corresponding decryption operations. 547.Fn EVP_DecryptFinal 548will return an error code if padding is enabled and the final block is 549not correctly formatted. 550The parameters and restrictions are identical to the encryption 551operations except that if padding is enabled the decrypted data buffer 552.Fa out 553passed to 554.Fn EVP_DecryptUpdate 555should have sufficient room for (inl + cipher_block_size) bytes 556unless the cipher block size is 1 in which case 557.Fa inl 558bytes is sufficient. 559.Pp 560.Fn EVP_CipherInit_ex , 561.Fn EVP_CipherUpdate , 562and 563.Fn EVP_CipherFinal_ex 564are functions that can be used for decryption or encryption. 565The operation performed depends on the value of the 566.Fa enc 567parameter. 568It should be set to 1 for encryption, 0 for decryption and -1 to leave 569the value unchanged (the actual value of 570.Fa enc 571being supplied in a previous call). 572.Pp 573.Fn EVP_EncryptInit , 574.Fn EVP_DecryptInit , 575and 576.Fn EVP_CipherInit 577are deprecated functions behaving like 578.Fn EVP_EncryptInit_ex , 579.Fn EVP_DecryptInit_ex , 580and 581.Fn EVP_CipherInit_ex 582except that they always use the default cipher implementation 583and that they require 584.Fn EVP_CIPHER_CTX_reset 585before they can be used on a context that was already used. 586.Pp 587.Fn EVP_EncryptFinal , 588.Fn EVP_DecryptFinal , 589and 590.Fn EVP_CipherFinal 591are identical to 592.Fn EVP_EncryptFinal_ex , 593.Fn EVP_DecryptFinal_ex , 594and 595.Fn EVP_CipherFinal_ex . 596In previous releases of OpenSSL, they also used to clean up the 597.Fa ctx , 598but this is no longer done and 599.Fn EVP_CIPHER_CTX_reset 600or 601.Fn EVP_CIPHER_CTX_free 602must be called to free any context resources. 603.Pp 604.Fn EVP_Cipher 605encrypts or decrypts aligned blocks of data 606whose lengths match the cipher block size. 607It requires that the previous encryption or decryption operation 608using the same 609.Fa ctx , 610if there was any, ended exactly on a block boundary and that 611.Fa inl 612is an integer multiple of the cipher block size. 613If either of these conditions is violated, 614.Fn EVP_Cipher 615silently produces incorrect results. 616For that reason, using the function 617.Fn EVP_CipherUpdate 618instead is strongly recommended. 619The latter can safely handle partial blocks, and even if 620.Fa inl 621actually is a multiple of the cipher block size for all calls, 622the overhead incurred by using 623.Fn EVP_CipherUpdate 624is minimal. 625.Pp 626.Fn EVP_get_cipherbyname , 627.Fn EVP_get_cipherbynid , 628and 629.Fn EVP_get_cipherbyobj 630return an 631.Vt EVP_CIPHER 632structure when passed a cipher name, a NID or an 633.Vt ASN1_OBJECT 634structure. 635.Pp 636.Fn EVP_CIPHER_nid 637and 638.Fn EVP_CIPHER_CTX_nid 639return the NID of a cipher when passed an 640.Vt EVP_CIPHER 641or 642.Vt EVP_CIPHER_CTX 643structure. 644The actual NID value is an internal value which may not have a 645corresponding OBJECT IDENTIFIER. 646.Pp 647.Fn EVP_CIPHER_CTX_set_flags 648enables the given 649.Fa flags 650in 651.Fa ctx . 652.Fn EVP_CIPHER_CTX_clear_flags 653disables the given 654.Fa flags 655in 656.Fa ctx . 657.Fn EVP_CIPHER_CTX_test_flags 658checks whether any of the given 659.Fa flags 660are currently set in 661.Fa ctx , 662returning the subset of the 663.Fa flags 664that are set, or 0 if none of them are set. 665Currently, the only supported cipher context flag is 666.Dv EVP_CIPHER_CTX_FLAG_WRAP_ALLOW ; 667see 668.Xr EVP_aes_128_wrap 3 669for details. 670.Pp 671.Fn EVP_CIPHER_CTX_set_padding 672enables or disables padding. 673This function should be called after the context is set up for 674encryption or decryption with 675.Fn EVP_EncryptInit_ex , 676.Fn EVP_DecryptInit_ex , 677or 678.Fn EVP_CipherInit_ex . 679By default encryption operations are padded using standard block padding 680and the padding is checked and removed when decrypting. 681If the 682.Fa padding 683parameter is zero, then no padding is performed, the total amount of data 684encrypted or decrypted must then be a multiple of the block size or an 685error will occur. 686.Pp 687.Fn EVP_CIPHER_key_length 688and 689.Fn EVP_CIPHER_CTX_key_length 690return the key length of a cipher when passed an 691.Vt EVP_CIPHER 692or 693.Vt EVP_CIPHER_CTX 694structure. 695The constant 696.Dv EVP_MAX_KEY_LENGTH 697is the maximum key length for all ciphers. 698Note: although 699.Fn EVP_CIPHER_key_length 700is fixed for a given cipher, the value of 701.Fn EVP_CIPHER_CTX_key_length 702may be different for variable key length ciphers. 703.Pp 704.Fn EVP_CIPHER_CTX_set_key_length 705sets the key length of the cipher ctx. 706If the cipher is a fixed length cipher, then attempting to set the key 707length to any value other than the fixed value is an error. 708.Pp 709.Fn EVP_CIPHER_iv_length 710and 711.Fn EVP_CIPHER_CTX_iv_length 712return the IV length of a cipher when passed an 713.Vt EVP_CIPHER 714or 715.Vt EVP_CIPHER_CTX . 716It will return zero if the cipher does not use an IV. 717The constant 718.Dv EVP_MAX_IV_LENGTH 719is the maximum IV length for all ciphers. 720.Pp 721.Fn EVP_CIPHER_CTX_get_iv 722and 723.Fn EVP_CIPHER_CTX_set_iv 724will respectively retrieve and set the IV for an 725.Vt EVP_CIPHER_CTX . 726In both cases, the specified IV length must exactly equal the expected 727IV length for the context as returned by 728.Fn EVP_CIPHER_CTX_iv_length . 729.Pp 730.Fn EVP_CIPHER_block_size 731and 732.Fn EVP_CIPHER_CTX_block_size 733return the block size of a cipher when passed an 734.Vt EVP_CIPHER 735or 736.Vt EVP_CIPHER_CTX 737structure. 738The constant 739.Dv EVP_MAX_BLOCK_LENGTH 740is also the maximum block length for all ciphers. 741.Pp 742.Fn EVP_CIPHER_type 743and 744.Fn EVP_CIPHER_CTX_type 745return the type of the passed cipher or context. 746This "type" is the actual NID of the cipher OBJECT IDENTIFIER as such it 747ignores the cipher parameters and 40-bit RC2 and 128-bit RC2 have the 748same NID. 749If the cipher does not have an object identifier or does not 750have ASN.1 support, this function will return 751.Dv NID_undef . 752.Pp 753.Fn EVP_CIPHER_CTX_cipher 754returns the 755.Vt EVP_CIPHER 756structure when passed an 757.Vt EVP_CIPHER_CTX 758structure. 759.Pp 760.Fn EVP_CIPHER_mode 761and 762.Fn EVP_CIPHER_CTX_mode 763return the block cipher mode: 764.Dv EVP_CIPH_ECB_MODE , 765.Dv EVP_CIPH_CBC_MODE , 766.Dv EVP_CIPH_CFB_MODE , 767.Dv EVP_CIPH_OFB_MODE , 768.Dv EVP_CIPH_CTR_MODE , 769or 770.Dv EVP_CIPH_XTS_MODE . 771If the cipher is a stream cipher then 772.Dv EVP_CIPH_STREAM_CIPHER 773is returned. 774.Pp 775.Fn EVP_CIPHER_param_to_asn1 776sets the ASN.1 777.Vt AlgorithmIdentifier 778parameter based on the passed cipher. 779This will typically include any parameters and an IV. 780The cipher IV (if any) must be set when this call is made. 781This call should be made before the cipher is actually "used" (before any 782.Fn EVP_EncryptUpdate 783or 784.Fn EVP_DecryptUpdate 785calls, for example). 786This function may fail if the cipher does not have any ASN.1 support. 787.Pp 788.Fn EVP_CIPHER_asn1_to_param 789sets the cipher parameters based on an ASN.1 790.Vt AlgorithmIdentifier 791parameter. 792The precise effect depends on the cipher. 793In the case of RC2, for example, it will set the IV and effective 794key length. 795This function should be called after the base cipher type is set but 796before the key is set. 797For example 798.Fn EVP_CipherInit 799will be called with the IV and key set to 800.Dv NULL , 801.Fn EVP_CIPHER_asn1_to_param 802will be called and finally 803.Fn EVP_CipherInit 804again with all parameters except the key set to 805.Dv NULL . 806It is possible for this function to fail if the cipher does not 807have any ASN.1 support or the parameters cannot be set (for example 808the RC2 effective key length is not supported). 809.Pp 810.Fn EVP_CIPHER_CTX_ctrl 811allows various cipher specific parameters to be determined and set. 812Currently only the RC2 effective key length can be set. 813.Pp 814.Fn EVP_CIPHER_CTX_rand_key 815generates a random key of the appropriate length based on the cipher 816context. 817The 818.Vt EVP_CIPHER 819can provide its own random key generation routine to support keys 820of a specific form. 821The 822.Fa key 823argument must point to a buffer at least as big as the value returned by 824.Fn EVP_CIPHER_CTX_key_length . 825.Pp 826Where possible the EVP interface to symmetric ciphers should be 827used in preference to the low level interfaces. 828This is because the code then becomes transparent to the cipher used and 829much more flexible. 830.Pp 831PKCS padding works by adding n padding bytes of value n to make the 832total length of the encrypted data a multiple of the block size. 833Padding is always added so if the data is already a multiple of the 834block size n will equal the block size. 835For example if the block size is 8 and 11 bytes are to be encrypted then 8365 padding bytes of value 5 will be added. 837.Pp 838When decrypting, the final block is checked to see if it has the correct 839form. 840.Pp 841Although the decryption operation can produce an error if padding is 842enabled, it is not a strong test that the input data or key is correct. 843A random block has better than 1 in 256 chance of being of the correct 844format and problems with the input data earlier on will not produce a 845final decrypt error. 846.Pp 847If padding is disabled then the decryption operation will always succeed 848if the total amount of data decrypted is a multiple of the block size. 849.Pp 850The functions 851.Fn EVP_EncryptInit , 852.Fn EVP_EncryptFinal , 853.Fn EVP_DecryptInit , 854.Fn EVP_CipherInit , 855and 856.Fn EVP_CipherFinal 857are obsolete but are retained for compatibility with existing code. 858New code should use 859.Fn EVP_EncryptInit_ex , 860.Fn EVP_EncryptFinal_ex , 861.Fn EVP_DecryptInit_ex , 862.Fn EVP_DecryptFinal_ex , 863.Fn EVP_CipherInit_ex , 864and 865.Fn EVP_CipherFinal_ex 866because they can reuse an existing context without allocating and 867freeing it up on each call. 868.Pp 869.Fn EVP_get_cipherbynid 870and 871.Fn EVP_get_cipherbyobj 872are implemented as macros. 873.Sh RETURN VALUES 874.Fn EVP_CIPHER_CTX_new 875returns a pointer to a newly created 876.Vt EVP_CIPHER_CTX 877for success or 878.Dv NULL 879for failure. 880.Pp 881.Fn EVP_CIPHER_CTX_reset , 882.Fn EVP_CIPHER_CTX_cleanup , 883.Fn EVP_CIPHER_CTX_get_iv , 884.Fn EVP_CIPHER_CTX_set_iv , 885.Fn EVP_EncryptInit_ex , 886.Fn EVP_EncryptUpdate , 887.Fn EVP_EncryptFinal_ex , 888.Fn EVP_DecryptInit_ex , 889.Fn EVP_DecryptUpdate , 890.Fn EVP_DecryptFinal_ex , 891.Fn EVP_CipherInit_ex , 892.Fn EVP_CipherUpdate , 893.Fn EVP_CipherFinal_ex , 894.Fn EVP_EncryptInit , 895.Fn EVP_EncryptFinal , 896.Fn EVP_DecryptInit , 897.Fn EVP_DecryptFinal , 898.Fn EVP_CipherInit , 899.Fn EVP_CipherFinal , 900.Fn EVP_Cipher , 901.Fn EVP_CIPHER_CTX_set_key_length , 902and 903.Fn EVP_CIPHER_CTX_rand_key 904return 1 for success or 0 for failure. 905.Pp 906.Fn EVP_CIPHER_CTX_set_padding 907always returns 1. 908.Pp 909.Fn EVP_get_cipherbyname , 910.Fn EVP_get_cipherbynid , 911and 912.Fn EVP_get_cipherbyobj 913return an 914.Vt EVP_CIPHER 915structure or 916.Dv NULL 917on error. 918.Pp 919.Fn EVP_CIPHER_nid 920and 921.Fn EVP_CIPHER_CTX_nid 922return a NID. 923.Pp 924.Fn EVP_CIPHER_block_size 925and 926.Fn EVP_CIPHER_CTX_block_size 927return the block size. 928.Pp 929.Fn EVP_CIPHER_key_length 930and 931.Fn EVP_CIPHER_CTX_key_length 932return the key length. 933.Pp 934.Fn EVP_CIPHER_iv_length 935and 936.Fn EVP_CIPHER_CTX_iv_length 937return the IV length or zero if the cipher does not use an IV. 938.Pp 939.Fn EVP_CIPHER_type 940and 941.Fn EVP_CIPHER_CTX_type 942return the NID of the cipher's OBJECT IDENTIFIER or 943.Dv NID_undef 944if it has no defined OBJECT IDENTIFIER. 945.Pp 946.Fn EVP_CIPHER_CTX_cipher 947returns an 948.Vt EVP_CIPHER 949structure. 950.Pp 951.Fn EVP_CIPHER_param_to_asn1 952and 953.Fn EVP_CIPHER_asn1_to_param 954return greater than zero for success and zero or a negative number 955for failure. 956.Sh CIPHER LISTING 957All algorithms have a fixed key length unless otherwise stated. 958.Bl -tag -width Ds 959.It Fn EVP_enc_null 960Null cipher: does nothing. 961.It Xo 962.Fn EVP_idea_cbc , 963.Fn EVP_idea_ecb , 964.Fn EVP_idea_cfb64 , 965.Fn EVP_idea_ofb 966.Xc 967IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 968.Fn EVP_idea_cfb 969is an alias for 970.Fn EVP_idea_cfb64 , 971implemented as a macro. 972.It Xo 973.Fn EVP_rc2_cbc , 974.Fn EVP_rc2_ecb , 975.Fn EVP_rc2_cfb64 , 976.Fn EVP_rc2_ofb 977.Xc 978RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 979This is a variable key length cipher with an additional parameter called 980"effective key bits" or "effective key length". 981By default both are set to 128 bits. 982.Fn EVP_rc2_cfb 983is an alias for 984.Fn EVP_rc2_cfb64 , 985implemented as a macro. 986.It Xo 987.Fn EVP_rc2_40_cbc , 988.Fn EVP_rc2_64_cbc 989.Xc 990RC2 algorithm in CBC mode with a default key length and effective key 991length of 40 and 64 bits. 992These are obsolete and new code should use 993.Fn EVP_rc2_cbc , 994.Fn EVP_CIPHER_CTX_set_key_length , 995and 996.Fn EVP_CIPHER_CTX_ctrl 997to set the key length and effective key length. 998.It Xo 999.Fn EVP_bf_cbc , 1000.Fn EVP_bf_ecb , 1001.Fn EVP_bf_cfb64 , 1002.Fn EVP_bf_ofb 1003.Xc 1004Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes 1005respectively. 1006This is a variable key length cipher. 1007.Fn EVP_bf_cfb 1008is an alias for 1009.Fn EVP_bf_cfb64 , 1010implemented as a macro. 1011.It Xo 1012.Fn EVP_cast5_cbc , 1013.Fn EVP_cast5_ecb , 1014.Fn EVP_cast5_cfb64 , 1015.Fn EVP_cast5_ofb 1016.Xc 1017CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 1018This is a variable key length cipher. 1019.Fn EVP_cast5_cfb 1020is an alias for 1021.Fn EVP_cast5_cfb64 , 1022implemented as a macro. 1023.It Fn EVP_chacha20 1024The ChaCha20 stream cipher. 1025The key length is 256 bits. 1026The first 32 bits of the 128-bit IV are used as a counter, 1027and the remaining 96 bits as a nonce. 1028.El 1029.Pp 1030See also 1031.Xr EVP_aes_128_cbc 3 , 1032.Xr EVP_camellia_128_cbc 3 , 1033.Xr EVP_des_cbc 3 , 1034.Xr EVP_rc4 3 , 1035and 1036.Xr EVP_sm4_cbc 3 . 1037.Ss GCM mode 1038For GCM mode ciphers, the behaviour of the EVP interface 1039is subtly altered and several additional ctrl operations are 1040supported. 1041.Pp 1042To specify any additional authenticated data (AAD), a call to 1043.Fn EVP_CipherUpdate , 1044.Fn EVP_EncryptUpdate , 1045or 1046.Fn EVP_DecryptUpdate 1047should be made with the output parameter out set to 1048.Dv NULL . 1049.Pp 1050When decrypting, the return value of 1051.Fn EVP_DecryptFinal 1052or 1053.Fn EVP_CipherFinal 1054indicates if the operation was successful. 1055If it does not indicate success, the authentication operation has 1056failed and any output data MUST NOT be used as it is corrupted. 1057.Pp 1058The following ctrls are supported in GCM mode: 1059.Bl -tag -width Ds 1060.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_IVLEN ivlen NULL 1061Sets the IV length: this call can only be made before specifying an IV. 1062If not called, a default IV length is used. 1063For GCM AES the default is 12, i.e. 96 bits. 1064.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_GET_TAG taglen tag 1065Writes 1066.Fa taglen 1067bytes of the tag value to the buffer indicated by 1068.Fa tag . 1069This call can only be made when encrypting data and after all data has 1070been processed, e.g. after an 1071.Fn EVP_EncryptFinal 1072call. 1073.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_TAG taglen tag 1074Sets the expected tag to 1075.Fa taglen 1076bytes from 1077.Fa tag . 1078This call is only legal when decrypting data and must be made before 1079any data is processed, e.g. before any 1080.Fa EVP_DecryptUpdate 1081call. 1082.El 1083.Ss CCM mode 1084The behaviour of CCM mode ciphers is similar to GCM mode, but with 1085a few additional requirements and different ctrl values. 1086.Pp 1087Like GCM mode any additional authenticated data (AAD) is passed 1088by calling 1089.Fn EVP_CipherUpdate , 1090.Fn EVP_EncryptUpdate , 1091or 1092.Fn EVP_DecryptUpdate 1093with the output parameter out set to 1094.Dv NULL . 1095Additionally, the total 1096plaintext or ciphertext length MUST be passed to 1097.Fn EVP_CipherUpdate , 1098.Fn EVP_EncryptUpdate , 1099or 1100.Fn EVP_DecryptUpdate 1101with the output and input 1102parameters 1103.Pq Fa in No and Fa out 1104set to 1105.Dv NULL 1106and the length passed in the 1107.Fa inl 1108parameter. 1109.Pp 1110The following ctrls are supported in CCM mode: 1111.Bl -tag -width Ds 1112.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_TAG taglen tag 1113This call is made to set the expected CCM tag value when decrypting or 1114the length of the tag (with the 1115.Fa tag 1116parameter set to 1117.Dv NULL ) 1118when encrypting. 1119The tag length is often referred to as M. 1120If not set, a default value is used (12 for AES). 1121.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_L ivlen NULL 1122Sets the CCM L value. 1123If not set, a default is used (8 for AES). 1124.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_IVLEN ivlen NULL 1125Sets the CCM nonce (IV) length: this call can only be made before 1126specifying a nonce value. 1127The nonce length is given by 15 - L so it is 7 by default for AES. 1128.El 1129.Sh EXAMPLES 1130Encrypt a string using blowfish: 1131.Bd -literal -offset 3n 1132int 1133do_crypt(char *outfile) 1134{ 1135 unsigned char outbuf[1024]; 1136 int outlen, tmplen; 1137 /* 1138 * Bogus key and IV: we'd normally set these from 1139 * another source. 1140 */ 1141 unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; 1142 unsigned char iv[] = {1,2,3,4,5,6,7,8}; 1143 const char intext[] = "Some Crypto Text"; 1144 EVP_CIPHER_CTX *ctx; 1145 FILE *out; 1146 1147 ctx = EVP_CIPHER_CTX_new(); 1148 EVP_EncryptInit_ex(ctx, EVP_bf_cbc(), NULL, key, iv); 1149 1150 if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, 1151 strlen(intext))) { 1152 /* Error */ 1153 EVP_CIPHER_CTX_free(ctx); 1154 return 0; 1155 } 1156 /* 1157 * Buffer passed to EVP_EncryptFinal() must be after data just 1158 * encrypted to avoid overwriting it. 1159 */ 1160 if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) { 1161 /* Error */ 1162 EVP_CIPHER_CTX_free(ctx); 1163 return 0; 1164 } 1165 outlen += tmplen; 1166 EVP_CIPHER_CTX_free(ctx); 1167 /* 1168 * Need binary mode for fopen because encrypted data is 1169 * binary data. Also cannot use strlen() on it because 1170 * it won't be NUL terminated and may contain embedded 1171 * NULs. 1172 */ 1173 out = fopen(outfile, "wb"); 1174 if (out == NULL) { 1175 /* Error */ 1176 return 0; 1177 } 1178 fwrite(outbuf, 1, outlen, out); 1179 fclose(out); 1180 return 1; 1181} 1182.Ed 1183.Pp 1184The ciphertext from the above example can be decrypted using the 1185.Xr openssl 1 1186utility with the command line: 1187.Bd -literal -offset indent 1188openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F \e 1189 -iv 0102030405060708 -d 1190.Ed 1191.Pp 1192General encryption, decryption function example using FILE I/O and AES128 1193with a 128-bit key: 1194.Bd -literal 1195int 1196do_crypt(FILE *in, FILE *out, int do_encrypt) 1197{ 1198 /* Allow enough space in output buffer for additional block */ 1199 unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; 1200 int inlen, outlen; 1201 EVP_CIPHER_CTX *ctx; 1202 1203 /* 1204 * Bogus key and IV: we'd normally set these from 1205 * another source. 1206 */ 1207 unsigned char key[] = "0123456789abcdeF"; 1208 unsigned char iv[] = "1234567887654321"; 1209 1210 ctx = EVP_CIPHER_CTX_new(); 1211 EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, 1212 do_encrypt); 1213 EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); 1214 1215 for (;;) { 1216 inlen = fread(inbuf, 1, 1024, in); 1217 if (inlen <= 0) 1218 break; 1219 if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, 1220 inlen)) { 1221 /* Error */ 1222 EVP_CIPHER_CTX_free(ctx); 1223 return 0; 1224 } 1225 fwrite(outbuf, 1, outlen, out); 1226 } 1227 if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) { 1228 /* Error */ 1229 EVP_CIPHER_CTX_free(ctx); 1230 return 0; 1231 } 1232 fwrite(outbuf, 1, outlen, out); 1233 1234 EVP_CIPHER_CTX_free(ctx); 1235 return 1; 1236} 1237.Ed 1238.Sh SEE ALSO 1239.Xr BIO_f_cipher 3 , 1240.Xr evp 3 , 1241.Xr EVP_AEAD_CTX_init 3 , 1242.Xr EVP_aes_128_cbc 3 , 1243.Xr EVP_camellia_128_cbc 3 , 1244.Xr EVP_des_cbc 3 , 1245.Xr EVP_OpenInit 3 , 1246.Xr EVP_rc4 3 , 1247.Xr EVP_SealInit 3 , 1248.Xr EVP_sm4_cbc 3 1249.Sh HISTORY 1250.Fn EVP_EncryptInit , 1251.Fn EVP_EncryptUpdate , 1252.Fn EVP_EncryptFinal , 1253.Fn EVP_DecryptInit , 1254.Fn EVP_DecryptUpdate , 1255.Fn EVP_DecryptFinal , 1256.Fn EVP_CipherInit , 1257.Fn EVP_CipherUpdate , 1258.Fn EVP_CipherFinal , 1259.Fn EVP_get_cipherbyname , 1260.Fn EVP_idea_cbc , 1261.Fn EVP_idea_ecb , 1262.Fn EVP_idea_cfb , 1263and 1264.Fn EVP_idea_ofb 1265first appeared in SSLeay 0.5.1. 1266.Fn EVP_rc2_cbc , 1267.Fn EVP_rc2_ecb , 1268.Fn EVP_rc2_cfb , 1269and 1270.Fn EVP_rc2_ofb 1271first appeared in SSLeay 0.5.2. 1272.Fn EVP_Cipher , 1273.Fn EVP_CIPHER_block_size , 1274.Fn EVP_CIPHER_key_length , 1275.Fn EVP_CIPHER_iv_length , 1276.Fn EVP_CIPHER_type , 1277.Fn EVP_CIPHER_CTX_block_size , 1278.Fn EVP_CIPHER_CTX_key_length , 1279.Fn EVP_CIPHER_CTX_iv_length , 1280and 1281.Fn EVP_CIPHER_CTX_type 1282first appeared in SSLeay 0.6.5. 1283.Fn EVP_bf_cbc , 1284.Fn EVP_bf_ecb , 1285.Fn EVP_bf_cfb , 1286and 1287.Fn EVP_bf_ofb 1288first appeared in SSLeay 0.6.6. 1289.Fn EVP_CIPHER_CTX_cleanup , 1290.Fn EVP_get_cipherbyobj , 1291.Fn EVP_CIPHER_nid , 1292.Fn EVP_CIPHER_CTX_cipher , 1293.Fn EVP_CIPHER_CTX_nid , 1294.Fn EVP_CIPHER_CTX_get_app_data , 1295.Fn EVP_CIPHER_CTX_set_app_data , 1296and 1297.Fn EVP_enc_null 1298first appeared in SSLeay 0.8.0. 1299.Fn EVP_get_cipherbynid 1300first appeared in SSLeay 0.8.1. 1301.Fn EVP_CIPHER_CTX_init , 1302.Fn EVP_CIPHER_param_to_asn1 , 1303and 1304.Fn EVP_CIPHER_asn1_to_param 1305first appeared in SSLeay 0.9.0. 1306All these functions have been available since 1307.Ox 2.4 . 1308.Pp 1309.Fn EVP_rc2_40_cbc 1310and 1311.Fn EVP_rc2_64_cbc 1312first appeared in SSL_eay 0.9.1. 1313.Fn EVP_CIPHER_CTX_type 1314first appeared in OpenSSL 0.9.3. 1315These functions have been available since 1316.Ox 2.6 . 1317.Pp 1318.Fn EVP_CIPHER_CTX_set_key_length , 1319.Fn EVP_CIPHER_CTX_ctrl , 1320.Fn EVP_CIPHER_flags , 1321.Fn EVP_CIPHER_mode , 1322.Fn EVP_CIPHER_CTX_flags , 1323and 1324.Fn EVP_CIPHER_CTX_mode 1325first appeared in OpenSSL 0.9.6 and have been available since 1326.Ox 2.9 . 1327.Pp 1328.Fn EVP_EncryptInit_ex , 1329.Fn EVP_EncryptFinal_ex , 1330.Fn EVP_DecryptInit_ex , 1331.Fn EVP_DecryptFinal_ex , 1332.Fn EVP_CipherInit_ex , 1333.Fn EVP_CipherFinal_ex , 1334and 1335.Fn EVP_CIPHER_CTX_set_padding 1336first appeared in OpenSSL 0.9.7 and have been available since 1337.Ox 3.2 . 1338.Pp 1339.Fn EVP_bf_cfb64 , 1340.Fn EVP_cast5_cfb64 , 1341.Fn EVP_idea_cfb64 , 1342and 1343.Fn EVP_rc2_cfb64 1344first appeared in OpenSSL 0.9.7e and have been available since 1345.Ox 3.8 . 1346.Pp 1347.Fn EVP_CIPHER_CTX_rand_key 1348first appeared in OpenSSL 0.9.8. 1349.Fn EVP_CIPHER_CTX_new 1350and 1351.Fn EVP_CIPHER_CTX_free 1352first appeared in OpenSSL 0.9.8b. 1353These functions have been available since 1354.Ox 4.5 . 1355.Pp 1356.Fn EVP_CIPHER_CTX_reset 1357first appeared in OpenSSL 1.1.0 and has been available since 1358.Ox 6.3 . 1359.Pp 1360.Fn EVP_CIPHER_CTX_get_iv 1361and 1362.Fn EVP_CIPHER_CTX_set_iv 1363first appeared in LibreSSL 2.8.1 and has been available since 1364.Ox 6.4 . 1365.Sh BUGS 1366.Dv EVP_MAX_KEY_LENGTH 1367and 1368.Dv EVP_MAX_IV_LENGTH 1369only refer to the internal ciphers with default key lengths. 1370If custom ciphers exceed these values, the results are unpredictable. 1371This is because it has become standard practice to define a generic key 1372as a fixed unsigned char array containing 1373.Dv EVP_MAX_KEY_LENGTH 1374bytes. 1375.Pp 1376The ASN.1 code is incomplete (and sometimes inaccurate). 1377It has only been tested for certain common S/MIME ciphers 1378(RC2, DES, triple DES) in CBC mode. 1379