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