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