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