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