1.\" $OpenBSD: EVP_EncryptInit.3,v 1.48 2023/08/31 17:27:41 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.\" 6.\" This file is a derived work. 7.\" The changes are covered by the following Copyright and license: 8.\" 9.\" Copyright (c) 2019, 2023 Ingo Schwarze <schwarze@openbsd.org> 10.\" 11.\" Permission to use, copy, modify, and distribute this software for any 12.\" purpose with or without fee is hereby granted, provided that the above 13.\" copyright notice and this permission notice appear in all copies. 14.\" 15.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 16.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 17.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 18.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 19.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 20.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 21.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 22.\" 23.\" The original file was written by Dr. Stephen Henson <steve@openssl.org> 24.\" and Richard Levitte <levitte@openssl.org>. 25.\" Copyright (c) 2000-2002, 2005, 2012-2016 The OpenSSL Project. 26.\" All rights reserved. 27.\" 28.\" Redistribution and use in source and binary forms, with or without 29.\" modification, are permitted provided that the following conditions 30.\" are met: 31.\" 32.\" 1. Redistributions of source code must retain the above copyright 33.\" notice, this list of conditions and the following disclaimer. 34.\" 35.\" 2. Redistributions in binary form must reproduce the above copyright 36.\" notice, this list of conditions and the following disclaimer in 37.\" the documentation and/or other materials provided with the 38.\" distribution. 39.\" 40.\" 3. All advertising materials mentioning features or use of this 41.\" software must display the following acknowledgment: 42.\" "This product includes software developed by the OpenSSL Project 43.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 44.\" 45.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 46.\" endorse or promote products derived from this software without 47.\" prior written permission. For written permission, please contact 48.\" openssl-core@openssl.org. 49.\" 50.\" 5. Products derived from this software may not be called "OpenSSL" 51.\" nor may "OpenSSL" appear in their names without prior written 52.\" permission of the OpenSSL Project. 53.\" 54.\" 6. Redistributions of any form whatsoever must retain the following 55.\" acknowledgment: 56.\" "This product includes software developed by the OpenSSL Project 57.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 58.\" 59.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 60.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 61.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 62.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 63.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 64.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 65.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 66.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 67.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 68.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 69.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 70.\" OF THE POSSIBILITY OF SUCH DAMAGE. 71.\" 72.Dd $Mdocdate: August 31 2023 $ 73.Dt EVP_ENCRYPTINIT 3 74.Os 75.Sh NAME 76.Nm EVP_CIPHER_CTX_new , 77.Nm EVP_CIPHER_CTX_reset , 78.Nm EVP_CIPHER_CTX_cleanup , 79.Nm EVP_CIPHER_CTX_init , 80.Nm EVP_CIPHER_CTX_free , 81.Nm EVP_CIPHER_CTX_copy , 82.Nm EVP_EncryptInit_ex , 83.Nm EVP_EncryptUpdate , 84.Nm EVP_EncryptFinal_ex , 85.Nm EVP_DecryptInit_ex , 86.Nm EVP_DecryptUpdate , 87.Nm EVP_DecryptFinal_ex , 88.Nm EVP_CipherInit_ex , 89.Nm EVP_CipherUpdate , 90.Nm EVP_CipherFinal_ex , 91.Nm EVP_EncryptInit , 92.Nm EVP_EncryptFinal , 93.Nm EVP_DecryptInit , 94.Nm EVP_DecryptFinal , 95.Nm EVP_CipherInit , 96.Nm EVP_CipherFinal , 97.Nm EVP_Cipher , 98.Nm EVP_CIPHER_CTX_encrypting , 99.Nm EVP_get_cipherbyname , 100.Nm EVP_get_cipherbynid , 101.Nm EVP_get_cipherbyobj , 102.Nm EVP_CIPHER_CTX_cipher , 103.Nm EVP_enc_null , 104.Nm EVP_idea_cbc , 105.Nm EVP_idea_ecb , 106.Nm EVP_idea_cfb64 , 107.Nm EVP_idea_cfb , 108.Nm EVP_idea_ofb , 109.Nm EVP_rc2_cbc , 110.Nm EVP_rc2_ecb , 111.Nm EVP_rc2_cfb64 , 112.Nm EVP_rc2_cfb , 113.Nm EVP_rc2_ofb , 114.Nm EVP_rc2_40_cbc , 115.Nm EVP_rc2_64_cbc , 116.Nm EVP_bf_cbc , 117.Nm EVP_bf_ecb , 118.Nm EVP_bf_cfb64 , 119.Nm EVP_bf_cfb , 120.Nm EVP_bf_ofb , 121.Nm EVP_cast5_cbc , 122.Nm EVP_cast5_ecb , 123.Nm EVP_cast5_cfb64 , 124.Nm EVP_cast5_cfb , 125.Nm EVP_cast5_ofb 126.Nd EVP cipher routines 127.Sh SYNOPSIS 128.In openssl/evp.h 129.Ft EVP_CIPHER_CTX * 130.Fn EVP_CIPHER_CTX_new void 131.Ft int 132.Fo EVP_CIPHER_CTX_reset 133.Fa "EVP_CIPHER_CTX *ctx" 134.Fc 135.Ft int 136.Fo EVP_CIPHER_CTX_cleanup 137.Fa "EVP_CIPHER_CTX *ctx" 138.Fc 139.Ft void 140.Fo EVP_CIPHER_CTX_init 141.Fa "EVP_CIPHER_CTX *ctx" 142.Fc 143.Ft void 144.Fo EVP_CIPHER_CTX_free 145.Fa "EVP_CIPHER_CTX *ctx" 146.Fc 147.Ft int 148.Fo EVP_CIPHER_CTX_copy 149.Fa "EVP_CIPHER_CTX *out" 150.Fa "const EVP_CIPHER_CTX *in" 151.Fc 152.Ft int 153.Fo EVP_EncryptInit_ex 154.Fa "EVP_CIPHER_CTX *ctx" 155.Fa "const EVP_CIPHER *type" 156.Fa "ENGINE *impl" 157.Fa "const unsigned char *key" 158.Fa "const unsigned char *iv" 159.Fc 160.Ft int 161.Fo EVP_EncryptUpdate 162.Fa "EVP_CIPHER_CTX *ctx" 163.Fa "unsigned char *out" 164.Fa "int *outl" 165.Fa "const unsigned char *in" 166.Fa "int inl" 167.Fc 168.Ft int 169.Fo EVP_EncryptFinal_ex 170.Fa "EVP_CIPHER_CTX *ctx" 171.Fa "unsigned char *out" 172.Fa "int *outl" 173.Fc 174.Ft int 175.Fo EVP_DecryptInit_ex 176.Fa "EVP_CIPHER_CTX *ctx" 177.Fa "const EVP_CIPHER *type" 178.Fa "ENGINE *impl" 179.Fa "const unsigned char *key" 180.Fa "const unsigned char *iv" 181.Fc 182.Ft int 183.Fo EVP_DecryptUpdate 184.Fa "EVP_CIPHER_CTX *ctx" 185.Fa "unsigned char *out" 186.Fa "int *outl" 187.Fa "const unsigned char *in" 188.Fa "int inl" 189.Fc 190.Ft int 191.Fo EVP_DecryptFinal_ex 192.Fa "EVP_CIPHER_CTX *ctx" 193.Fa "unsigned char *outm" 194.Fa "int *outl" 195.Fc 196.Ft int 197.Fo EVP_CipherInit_ex 198.Fa "EVP_CIPHER_CTX *ctx" 199.Fa "const EVP_CIPHER *type" 200.Fa "ENGINE *impl" 201.Fa "const unsigned char *key" 202.Fa "const unsigned char *iv" 203.Fa "int enc" 204.Fc 205.Ft int 206.Fo EVP_CipherUpdate 207.Fa "EVP_CIPHER_CTX *ctx" 208.Fa "unsigned char *out" 209.Fa "int *outl" 210.Fa "const unsigned char *in" 211.Fa "int inl" 212.Fc 213.Ft int 214.Fo EVP_CipherFinal_ex 215.Fa "EVP_CIPHER_CTX *ctx" 216.Fa "unsigned char *outm" 217.Fa "int *outl" 218.Fc 219.Ft int 220.Fo EVP_EncryptInit 221.Fa "EVP_CIPHER_CTX *ctx" 222.Fa "const EVP_CIPHER *type" 223.Fa "const unsigned char *key" 224.Fa "const unsigned char *iv" 225.Fc 226.Ft int 227.Fo EVP_EncryptFinal 228.Fa "EVP_CIPHER_CTX *ctx" 229.Fa "unsigned char *out" 230.Fa "int *outl" 231.Fc 232.Ft int 233.Fo EVP_DecryptInit 234.Fa "EVP_CIPHER_CTX *ctx" 235.Fa "const EVP_CIPHER *type" 236.Fa "const unsigned char *key" 237.Fa "const unsigned char *iv" 238.Fc 239.Ft int 240.Fo EVP_DecryptFinal 241.Fa "EVP_CIPHER_CTX *ctx" 242.Fa "unsigned char *outm" 243.Fa "int *outl" 244.Fc 245.Ft int 246.Fo EVP_CipherInit 247.Fa "EVP_CIPHER_CTX *ctx" 248.Fa "const EVP_CIPHER *type" 249.Fa "const unsigned char *key" 250.Fa "const unsigned char *iv" 251.Fa "int enc" 252.Fc 253.Ft int 254.Fo EVP_CipherFinal 255.Fa "EVP_CIPHER_CTX *ctx" 256.Fa "unsigned char *outm" 257.Fa "int *outl" 258.Fc 259.Ft int 260.Fo EVP_Cipher 261.Fa "EVP_CIPHER_CTX *ctx" 262.Fa "unsigned char *out" 263.Fa "const unsigned char *in" 264.Fa "unsigned int inl" 265.Fc 266.Ft int 267.Fo EVP_CIPHER_CTX_encrypting 268.Fa "const EVP_CIPHER_CTX *ctx" 269.Fc 270.Ft const EVP_CIPHER * 271.Fo EVP_get_cipherbyname 272.Fa "const char *name" 273.Fc 274.Ft const EVP_CIPHER * 275.Fo EVP_get_cipherbynid 276.Fa "int nid" 277.Fc 278.Ft const EVP_CIPHER * 279.Fo EVP_get_cipherbyobj 280.Fa "const ASN1_OBJECT *a" 281.Fc 282.Ft const EVP_CIPHER * 283.Fo EVP_CIPHER_CTX_cipher 284.Fa "const EVP_CIPHER_CTX *ctx" 285.Fc 286.Sh DESCRIPTION 287The EVP cipher routines are a high level interface to certain symmetric 288ciphers. 289.Pp 290.Fn EVP_CIPHER_CTX_new 291creates a new, empty cipher context. 292.Pp 293.Fn EVP_CIPHER_CTX_reset 294clears all information from 295.Fa ctx 296and frees all allocated memory associated with it, except the 297.Fa ctx 298object itself, such that it can be reused for another series of calls to 299.Fn EVP_CipherInit , 300.Fn EVP_CipherUpdate , 301and 302.Fn EVP_CipherFinal . 303.Fn EVP_CIPHER_CTX_cleanup 304is a deprecated alias for 305.Fn EVP_CIPHER_CTX_reset . 306.Pp 307.Fn EVP_CIPHER_CTX_init 308is a deprecated function to clear a cipher context on the stack 309before use. 310Do not use it on a cipher context returned from 311.Fn EVP_CIPHER_CTX_new 312or one that was already used. 313.Pp 314.Fn EVP_CIPHER_CTX_free 315clears all information from 316.Fa ctx 317and frees all allocated memory associated with it, including 318.Fa ctx 319itself. 320This function should be called after all operations using a cipher 321are complete, so sensitive information does not remain in memory. 322If 323.Fa ctx 324is a 325.Dv NULL 326pointer, no action occurs. 327.Pp 328.Fn EVP_CIPHER_CTX_copy 329calls 330.Fn EVP_CIPHER_CTX_reset 331on 332.Fa out 333and copies all the data from 334.Fa in 335to 336.Fa out , 337except that the 338.Vt EVP_CIPHER 339and 340.Vt ENGINE 341objects used by 342.Fa in 343and any application specific data set with 344.Xr EVP_CIPHER_CTX_set_app_data 3 345are not copied and 346.Fa out 347will point to the same three objects. 348The algorithm- and implementation-specific cipher data described in 349.Xr EVP_CIPHER_CTX_get_cipher_data 3 350is copied with 351.Xr malloc 3 352and 353.Xr memcpy 3 , 354i.e. assuming that it does not contain pointers to any sub-objects. 355If the bit 356.Dv EVP_CIPH_CUSTOM_COPY 357has been set with 358.Xr EVP_CIPHER_meth_set_flags 3 , 359.Xr EVP_CIPHER_CTX_ctrl 3 360is called at the end with arguments 361.Fa in , 362.Dv EVP_CTRL_COPY , 363.No 0 , 364and 365.Fa out 366such that the cipher implementation can perform further algorithm- 367and implementation-specific initializations after the algorithm- 368and implementation-specific cipher data has been copied. 369Among the cipher algorithms built into the library, 370.Dv EVP_CIPH_CUSTOM_COPY 371and 372.Dv EVP_CTRL_COPY 373are used by some of the ciphers documented in the 374.Xr EVP_aes_256_gcm 3 375manual page. 376.Pp 377.Fn EVP_EncryptInit_ex 378sets up the cipher context 379.Fa ctx 380for encryption with cipher 381.Fa type 382from 383.Vt ENGINE 384.Fa impl . 385.Fa type 386is normally supplied by a function such as 387.Xr EVP_aes_256_cbc 3 . 388If 389.Fa impl 390is 391.Dv NULL , 392then the default implementation is used. 393.Fa key 394is the symmetric key to use and 395.Fa iv 396is the IV to use (if necessary). 397The actual number of bytes used for the 398key and IV depends on the cipher. 399It is possible to set all parameters to 400.Dv NULL 401except 402.Fa type 403in an initial call and supply the remaining parameters in subsequent 404calls, all of which have 405.Fa type 406set to 407.Dv NULL . 408This is done when the default cipher parameters are not appropriate. 409.Pp 410.Fn EVP_EncryptUpdate 411encrypts 412.Fa inl 413bytes from the buffer 414.Fa in 415and writes the encrypted version to 416.Fa out . 417This function can be called multiple times to encrypt successive blocks 418of data. 419The amount of data written depends on the block alignment of the 420encrypted data: as a result the amount of data written may be anything 421from zero bytes to (inl + cipher_block_size - 1) so 422.Fa out 423should contain sufficient room. 424The actual number of bytes written is placed in 425.Fa outl . 426.Pp 427If padding is enabled (the default) then 428.Fn EVP_EncryptFinal_ex 429encrypts the "final" data, that is any data that remains in a partial 430block. 431It uses NOTES (aka PKCS padding). 432The encrypted final data is written to 433.Fa out 434which should have sufficient space for one cipher block. 435The number of bytes written is placed in 436.Fa outl . 437After this function is called, the encryption operation is finished and 438no further calls to 439.Fn EVP_EncryptUpdate 440should be made. 441.Pp 442If padding is disabled then 443.Fn EVP_EncryptFinal_ex 444will not encrypt any more data and it will return an error if any data 445remains in a partial block: that is if the total data length is not a 446multiple of the block size. 447.Pp 448.Fn EVP_DecryptInit_ex , 449.Fn EVP_DecryptUpdate , 450and 451.Fn EVP_DecryptFinal_ex 452are the corresponding decryption operations. 453.Fn EVP_DecryptFinal 454will return an error code if padding is enabled and the final block is 455not correctly formatted. 456The parameters and restrictions are identical to the encryption 457operations except that if padding is enabled the decrypted data buffer 458.Fa out 459passed to 460.Fn EVP_DecryptUpdate 461should have sufficient room for (inl + cipher_block_size) bytes 462unless the cipher block size is 1 in which case 463.Fa inl 464bytes is sufficient. 465.Pp 466.Fn EVP_CipherInit_ex , 467.Fn EVP_CipherUpdate , 468and 469.Fn EVP_CipherFinal_ex 470are functions that can be used for decryption or encryption. 471The operation performed depends on the value of the 472.Fa enc 473parameter. 474It should be set to 1 for encryption, 0 for decryption and -1 to leave 475the value unchanged (the actual value of 476.Fa enc 477being supplied in a previous call). 478.Pp 479.Fn EVP_EncryptInit , 480.Fn EVP_DecryptInit , 481and 482.Fn EVP_CipherInit 483are deprecated functions behaving like 484.Fn EVP_EncryptInit_ex , 485.Fn EVP_DecryptInit_ex , 486and 487.Fn EVP_CipherInit_ex 488except that they always use the default cipher implementation 489and that they require 490.Fn EVP_CIPHER_CTX_reset 491before they can be used on a context that was already used. 492.Pp 493.Fn EVP_EncryptFinal , 494.Fn EVP_DecryptFinal , 495and 496.Fn EVP_CipherFinal 497are identical to 498.Fn EVP_EncryptFinal_ex , 499.Fn EVP_DecryptFinal_ex , 500and 501.Fn EVP_CipherFinal_ex . 502In previous releases of OpenSSL, they also used to clean up the 503.Fa ctx , 504but this is no longer done and 505.Fn EVP_CIPHER_CTX_reset 506or 507.Fn EVP_CIPHER_CTX_free 508must be called to free any context resources. 509.Pp 510.Fn EVP_Cipher 511encrypts or decrypts aligned blocks of data 512whose lengths match the cipher block size. 513It requires that the previous encryption or decryption operation 514using the same 515.Fa ctx , 516if there was any, ended exactly on a block boundary and that 517.Fa inl 518is an integer multiple of the cipher block size. 519If either of these conditions is violated, 520.Fn EVP_Cipher 521silently produces incorrect results. 522For that reason, using the function 523.Fn EVP_CipherUpdate 524instead is strongly recommended. 525The latter can safely handle partial blocks, and even if 526.Fa inl 527actually is a multiple of the cipher block size for all calls, 528the overhead incurred by using 529.Fn EVP_CipherUpdate 530is minimal. 531.Pp 532.Fn EVP_get_cipherbyname , 533.Fn EVP_get_cipherbynid , 534and 535.Fn EVP_get_cipherbyobj 536return an 537.Vt EVP_CIPHER 538structure when passed a cipher name, a NID or an 539.Vt ASN1_OBJECT 540structure. 541.Pp 542.Fn EVP_CIPHER_CTX_cipher 543returns the 544.Vt EVP_CIPHER 545structure when passed an 546.Vt EVP_CIPHER_CTX 547structure. 548.Pp 549Where possible the EVP interface to symmetric ciphers should be 550used in preference to the low level interfaces. 551This is because the code then becomes transparent to the cipher used and 552much more flexible. 553.Pp 554PKCS padding works by adding n padding bytes of value n to make the 555total length of the encrypted data a multiple of the block size. 556Padding is always added so if the data is already a multiple of the 557block size n will equal the block size. 558For example if the block size is 8 and 11 bytes are to be encrypted then 5595 padding bytes of value 5 will be added. 560.Pp 561When decrypting, the final block is checked to see if it has the correct 562form. 563.Pp 564Although the decryption operation can produce an error if padding is 565enabled, it is not a strong test that the input data or key is correct. 566A random block has better than 1 in 256 chance of being of the correct 567format and problems with the input data earlier on will not produce a 568final decrypt error. 569.Pp 570If padding is disabled then the decryption operation will always succeed 571if the total amount of data decrypted is a multiple of the block size. 572.Pp 573The functions 574.Fn EVP_EncryptInit , 575.Fn EVP_EncryptFinal , 576.Fn EVP_DecryptInit , 577.Fn EVP_CipherInit , 578and 579.Fn EVP_CipherFinal 580are obsolete but are retained for compatibility with existing code. 581New code should use 582.Fn EVP_EncryptInit_ex , 583.Fn EVP_EncryptFinal_ex , 584.Fn EVP_DecryptInit_ex , 585.Fn EVP_DecryptFinal_ex , 586.Fn EVP_CipherInit_ex , 587and 588.Fn EVP_CipherFinal_ex 589because they can reuse an existing context without allocating and 590freeing it up on each call. 591.Pp 592.Fn EVP_get_cipherbynid 593and 594.Fn EVP_get_cipherbyobj 595are implemented as macros. 596.Sh RETURN VALUES 597.Fn EVP_CIPHER_CTX_new 598returns a pointer to a newly created 599.Vt EVP_CIPHER_CTX 600for success or 601.Dv NULL 602for failure. 603.Pp 604.Fn EVP_CIPHER_CTX_reset , 605.Fn EVP_CIPHER_CTX_cleanup , 606.Fn EVP_CIPHER_CTX_copy , 607.Fn EVP_EncryptInit_ex , 608.Fn EVP_EncryptUpdate , 609.Fn EVP_EncryptFinal_ex , 610.Fn EVP_DecryptInit_ex , 611.Fn EVP_DecryptUpdate , 612.Fn EVP_DecryptFinal_ex , 613.Fn EVP_CipherInit_ex , 614.Fn EVP_CipherUpdate , 615.Fn EVP_CipherFinal_ex , 616.Fn EVP_EncryptInit , 617.Fn EVP_EncryptFinal , 618.Fn EVP_DecryptInit , 619.Fn EVP_DecryptFinal , 620.Fn EVP_CipherInit , 621.Fn EVP_CipherFinal , 622and 623.Fn EVP_Cipher 624return 1 for success or 0 for failure. 625.Pp 626.Fn EVP_CIPHER_CTX_encrypting 627returns 1 if 628.Fa ctx 629is initialized for encryption or 0 otherwise, in which case 630it may be uninitialized or initialized for decryption. 631.Pp 632.Fn EVP_get_cipherbyname , 633.Fn EVP_get_cipherbynid , 634and 635.Fn EVP_get_cipherbyobj 636return an 637.Vt EVP_CIPHER 638structure or 639.Dv NULL 640on error. 641.Pp 642.Fn EVP_CIPHER_CTX_cipher 643returns an 644.Vt EVP_CIPHER 645structure. 646.Sh CIPHER LISTING 647All algorithms have a fixed key length unless otherwise stated. 648.Bl -tag -width Ds 649.It Fn EVP_enc_null 650Null cipher: does nothing. 651.It Xo 652.Fn EVP_idea_cbc , 653.Fn EVP_idea_ecb , 654.Fn EVP_idea_cfb64 , 655.Fn EVP_idea_ofb 656.Xc 657IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 658.Fn EVP_idea_cfb 659is an alias for 660.Fn EVP_idea_cfb64 , 661implemented as a macro. 662.It Xo 663.Fn EVP_rc2_cbc , 664.Fn EVP_rc2_ecb , 665.Fn EVP_rc2_cfb64 , 666.Fn EVP_rc2_ofb 667.Xc 668RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 669This is a variable key length cipher with an additional parameter called 670"effective key bits" or "effective key length". 671By default both are set to 128 bits. 672.Fn EVP_rc2_cfb 673is an alias for 674.Fn EVP_rc2_cfb64 , 675implemented as a macro. 676.It Xo 677.Fn EVP_rc2_40_cbc , 678.Fn EVP_rc2_64_cbc 679.Xc 680RC2 algorithm in CBC mode with a default key length and effective key 681length of 40 and 64 bits. 682These are obsolete and new code should use 683.Fn EVP_rc2_cbc , 684.Xr EVP_CIPHER_CTX_set_key_length 3 , 685and 686.Xr EVP_CIPHER_CTX_ctrl 3 687to set the key length and effective key length. 688.It Xo 689.Fn EVP_bf_cbc , 690.Fn EVP_bf_ecb , 691.Fn EVP_bf_cfb64 , 692.Fn EVP_bf_ofb 693.Xc 694Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes 695respectively. 696This is a variable key length cipher. 697.Fn EVP_bf_cfb 698is an alias for 699.Fn EVP_bf_cfb64 , 700implemented as a macro. 701.It Xo 702.Fn EVP_cast5_cbc , 703.Fn EVP_cast5_ecb , 704.Fn EVP_cast5_cfb64 , 705.Fn EVP_cast5_ofb 706.Xc 707CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 708This is a variable key length cipher. 709.Fn EVP_cast5_cfb 710is an alias for 711.Fn EVP_cast5_cfb64 , 712implemented as a macro. 713.El 714.Pp 715See also 716.Xr EVP_aes_128_cbc 3 , 717.Xr EVP_camellia_128_cbc 3 , 718.Xr EVP_des_cbc 3 , 719.Xr EVP_rc4 3 , 720and 721.Xr EVP_sm4_cbc 3 . 722.Ss GCM mode 723For GCM mode ciphers, the behaviour of the EVP interface 724is subtly altered and several additional ctrl operations are 725supported. 726.Pp 727To specify any additional authenticated data (AAD), a call to 728.Fn EVP_CipherUpdate , 729.Fn EVP_EncryptUpdate , 730or 731.Fn EVP_DecryptUpdate 732should be made with the output parameter out set to 733.Dv NULL . 734.Pp 735When decrypting, the return value of 736.Fn EVP_DecryptFinal 737or 738.Fn EVP_CipherFinal 739indicates if the operation was successful. 740If it does not indicate success, the authentication operation has 741failed and any output data MUST NOT be used as it is corrupted. 742.Pp 743The following ctrls are supported in GCM mode: 744.Bl -tag -width Ds 745.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_IVLEN ivlen NULL 746Sets the IV length: this call can only be made before specifying an IV. 747If not called, a default IV length is used. 748For GCM AES the default is 12, i.e. 96 bits. 749.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_GET_TAG taglen tag 750Writes 751.Fa taglen 752bytes of the tag value to the buffer indicated by 753.Fa tag . 754This call can only be made when encrypting data and after all data has 755been processed, e.g. after an 756.Fn EVP_EncryptFinal 757call. 758.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_TAG taglen tag 759Sets the expected tag to 760.Fa taglen 761bytes from 762.Fa tag . 763This call is only legal when decrypting data and must be made before 764any data is processed, e.g. before any 765.Fa EVP_DecryptUpdate 766call. 767.El 768.Ss CCM mode 769The behaviour of CCM mode ciphers is similar to GCM mode, but with 770a few additional requirements and different ctrl values. 771.Pp 772Like GCM mode any additional authenticated data (AAD) is passed 773by calling 774.Fn EVP_CipherUpdate , 775.Fn EVP_EncryptUpdate , 776or 777.Fn EVP_DecryptUpdate 778with the output parameter out set to 779.Dv NULL . 780Additionally, the total 781plaintext or ciphertext length MUST be passed to 782.Fn EVP_CipherUpdate , 783.Fn EVP_EncryptUpdate , 784or 785.Fn EVP_DecryptUpdate 786with the output and input 787parameters 788.Pq Fa in No and Fa out 789set to 790.Dv NULL 791and the length passed in the 792.Fa inl 793parameter. 794.Pp 795The following ctrls are supported in CCM mode: 796.Bl -tag -width Ds 797.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_TAG taglen tag 798This call is made to set the expected CCM tag value when decrypting or 799the length of the tag (with the 800.Fa tag 801parameter set to 802.Dv NULL ) 803when encrypting. 804The tag length is often referred to as M. 805If not set, a default value is used (12 for AES). 806.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_L ivlen NULL 807Sets the CCM L value. 808If not set, a default is used (8 for AES). 809.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_IVLEN ivlen NULL 810Sets the CCM nonce (IV) length: this call can only be made before 811specifying a nonce value. 812The nonce length is given by 15 - L so it is 7 by default for AES. 813.El 814.Sh EXAMPLES 815Encrypt a string using blowfish: 816.Bd -literal -offset 3n 817int 818do_crypt(char *outfile) 819{ 820 unsigned char outbuf[1024]; 821 int outlen, tmplen; 822 /* 823 * Bogus key and IV: we'd normally set these from 824 * another source. 825 */ 826 unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; 827 unsigned char iv[] = {1,2,3,4,5,6,7,8}; 828 const char intext[] = "Some Crypto Text"; 829 EVP_CIPHER_CTX *ctx; 830 FILE *out; 831 832 ctx = EVP_CIPHER_CTX_new(); 833 EVP_EncryptInit_ex(ctx, EVP_bf_cbc(), NULL, key, iv); 834 835 if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, 836 strlen(intext))) { 837 /* Error */ 838 EVP_CIPHER_CTX_free(ctx); 839 return 0; 840 } 841 /* 842 * Buffer passed to EVP_EncryptFinal() must be after data just 843 * encrypted to avoid overwriting it. 844 */ 845 if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) { 846 /* Error */ 847 EVP_CIPHER_CTX_free(ctx); 848 return 0; 849 } 850 outlen += tmplen; 851 EVP_CIPHER_CTX_free(ctx); 852 /* 853 * Need binary mode for fopen because encrypted data is 854 * binary data. Also cannot use strlen() on it because 855 * it won't be NUL terminated and may contain embedded 856 * NULs. 857 */ 858 out = fopen(outfile, "wb"); 859 if (out == NULL) { 860 /* Error */ 861 return 0; 862 } 863 fwrite(outbuf, 1, outlen, out); 864 fclose(out); 865 return 1; 866} 867.Ed 868.Pp 869The ciphertext from the above example can be decrypted using the 870.Xr openssl 1 871utility with the command line: 872.Bd -literal -offset indent 873openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F \e 874 -iv 0102030405060708 -d 875.Ed 876.Pp 877General encryption, decryption function example using FILE I/O and AES128 878with a 128-bit key: 879.Bd -literal 880int 881do_crypt(FILE *in, FILE *out, int do_encrypt) 882{ 883 /* Allow enough space in output buffer for additional block */ 884 unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; 885 int inlen, outlen; 886 EVP_CIPHER_CTX *ctx; 887 888 /* 889 * Bogus key and IV: we'd normally set these from 890 * another source. 891 */ 892 unsigned char key[] = "0123456789abcdeF"; 893 unsigned char iv[] = "1234567887654321"; 894 895 ctx = EVP_CIPHER_CTX_new(); 896 EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, 897 do_encrypt); 898 EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); 899 900 for (;;) { 901 inlen = fread(inbuf, 1, 1024, in); 902 if (inlen <= 0) 903 break; 904 if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, 905 inlen)) { 906 /* Error */ 907 EVP_CIPHER_CTX_free(ctx); 908 return 0; 909 } 910 fwrite(outbuf, 1, outlen, out); 911 } 912 if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) { 913 /* Error */ 914 EVP_CIPHER_CTX_free(ctx); 915 return 0; 916 } 917 fwrite(outbuf, 1, outlen, out); 918 919 EVP_CIPHER_CTX_free(ctx); 920 return 1; 921} 922.Ed 923.Sh SEE ALSO 924.Xr BIO_f_cipher 3 , 925.Xr evp 3 , 926.Xr EVP_AEAD_CTX_init 3 , 927.Xr EVP_aes_128_cbc 3 , 928.Xr EVP_camellia_128_cbc 3 , 929.Xr EVP_chacha20 3 , 930.Xr EVP_CIPHER_CTX_ctrl 3 , 931.Xr EVP_CIPHER_CTX_get_cipher_data 3 , 932.Xr EVP_CIPHER_CTX_set_flags 3 , 933.Xr EVP_CIPHER_nid 3 , 934.Xr EVP_des_cbc 3 , 935.Xr EVP_OpenInit 3 , 936.Xr EVP_rc4 3 , 937.Xr EVP_SealInit 3 , 938.Xr EVP_sm4_cbc 3 939.Sh HISTORY 940.Fn EVP_EncryptInit , 941.Fn EVP_EncryptUpdate , 942.Fn EVP_EncryptFinal , 943.Fn EVP_DecryptInit , 944.Fn EVP_DecryptUpdate , 945.Fn EVP_DecryptFinal , 946.Fn EVP_CipherInit , 947.Fn EVP_CipherUpdate , 948.Fn EVP_CipherFinal , 949.Fn EVP_get_cipherbyname , 950.Fn EVP_idea_cbc , 951.Fn EVP_idea_ecb , 952.Fn EVP_idea_cfb , 953and 954.Fn EVP_idea_ofb 955first appeared in SSLeay 0.5.1. 956.Fn EVP_rc2_cbc , 957.Fn EVP_rc2_ecb , 958.Fn EVP_rc2_cfb , 959and 960.Fn EVP_rc2_ofb 961first appeared in SSLeay 0.5.2. 962.Fn EVP_Cipher 963first appeared in SSLeay 0.6.5. 964.Fn EVP_bf_cbc , 965.Fn EVP_bf_ecb , 966.Fn EVP_bf_cfb , 967and 968.Fn EVP_bf_ofb 969first appeared in SSLeay 0.6.6. 970.Fn EVP_CIPHER_CTX_cleanup , 971.Fn EVP_get_cipherbyobj , 972.Fn EVP_CIPHER_CTX_cipher , 973and 974.Fn EVP_enc_null 975first appeared in SSLeay 0.8.0. 976.Fn EVP_get_cipherbynid 977first appeared in SSLeay 0.8.1. 978.Fn EVP_CIPHER_CTX_init 979first appeared in SSLeay 0.9.0. 980All these functions have been available since 981.Ox 2.4 . 982.Pp 983.Fn EVP_rc2_40_cbc 984and 985.Fn EVP_rc2_64_cbc 986first appeared in SSLeay 0.9.1 and have been available since 987.Ox 2.6 . 988.Pp 989.Fn EVP_EncryptInit_ex , 990.Fn EVP_EncryptFinal_ex , 991.Fn EVP_DecryptInit_ex , 992.Fn EVP_DecryptFinal_ex , 993.Fn EVP_CipherInit_ex , 994and 995.Fn EVP_CipherFinal_ex 996first appeared in OpenSSL 0.9.7 and have been available since 997.Ox 3.2 . 998.Pp 999.Fn EVP_bf_cfb64 , 1000.Fn EVP_cast5_cfb64 , 1001.Fn EVP_idea_cfb64 , 1002and 1003.Fn EVP_rc2_cfb64 1004first appeared in OpenSSL 0.9.7e and have been available since 1005.Ox 3.8 . 1006.Pp 1007.Fn EVP_CIPHER_CTX_new 1008and 1009.Fn EVP_CIPHER_CTX_free 1010first appeared in OpenSSL 0.9.8b and have been available since 1011.Ox 4.5 . 1012.Pp 1013.Fn EVP_CIPHER_CTX_copy 1014first appeared in OpenSSL 1.0.0 1015and has been available since 1016.Ox 4.9 . 1017.Pp 1018.Fn EVP_CIPHER_CTX_reset 1019first appeared in OpenSSL 1.1.0 and has been available since 1020.Ox 6.3 . 1021.Pp 1022.Fn EVP_CIPHER_CTX_encrypting 1023first appeared in OpenSSL 1.1.0 and has been available since 1024.Ox 6.4 . 1025.Sh BUGS 1026.Fn EVP_CIPHER_CTX_copy 1027may already have cleared the data in 1028.Fa out 1029and copied some new data into it even if it fails and returns 0. 1030