1.\" $OpenBSD: EVP_EncryptInit.3,v 1.52 2024/07/21 08:36:43 tb 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: July 21 2024 $ 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_free , 79.Nm EVP_CIPHER_CTX_copy , 80.Nm EVP_EncryptInit_ex , 81.Nm EVP_EncryptUpdate , 82.Nm EVP_EncryptFinal_ex , 83.Nm EVP_DecryptInit_ex , 84.Nm EVP_DecryptUpdate , 85.Nm EVP_DecryptFinal_ex , 86.Nm EVP_CipherInit_ex , 87.Nm EVP_CipherUpdate , 88.Nm EVP_CipherFinal_ex , 89.Nm EVP_EncryptInit , 90.Nm EVP_EncryptFinal , 91.Nm EVP_DecryptInit , 92.Nm EVP_DecryptFinal , 93.Nm EVP_CipherInit , 94.Nm EVP_CipherFinal , 95.Nm EVP_CIPHER_CTX_encrypting , 96.Nm EVP_get_cipherbyname , 97.Nm EVP_get_cipherbynid , 98.Nm EVP_get_cipherbyobj , 99.Nm EVP_CIPHER_CTX_cipher , 100.Nm EVP_enc_null , 101.Nm EVP_idea_cbc , 102.Nm EVP_idea_ecb , 103.Nm EVP_idea_cfb64 , 104.Nm EVP_idea_cfb , 105.Nm EVP_idea_ofb , 106.Nm EVP_rc2_cbc , 107.Nm EVP_rc2_ecb , 108.Nm EVP_rc2_cfb64 , 109.Nm EVP_rc2_cfb , 110.Nm EVP_rc2_ofb , 111.Nm EVP_rc2_40_cbc , 112.Nm EVP_rc2_64_cbc , 113.Nm EVP_bf_cbc , 114.Nm EVP_bf_ecb , 115.Nm EVP_bf_cfb64 , 116.Nm EVP_bf_cfb , 117.Nm EVP_bf_ofb , 118.Nm EVP_cast5_cbc , 119.Nm EVP_cast5_ecb , 120.Nm EVP_cast5_cfb64 , 121.Nm EVP_cast5_cfb , 122.Nm EVP_cast5_ofb 123.Nd EVP cipher routines 124.Sh SYNOPSIS 125.In openssl/evp.h 126.Ft EVP_CIPHER_CTX * 127.Fn EVP_CIPHER_CTX_new void 128.Ft int 129.Fo EVP_CIPHER_CTX_reset 130.Fa "EVP_CIPHER_CTX *ctx" 131.Fc 132.Ft void 133.Fo EVP_CIPHER_CTX_free 134.Fa "EVP_CIPHER_CTX *ctx" 135.Fc 136.Ft int 137.Fo EVP_CIPHER_CTX_copy 138.Fa "EVP_CIPHER_CTX *out" 139.Fa "const EVP_CIPHER_CTX *in" 140.Fc 141.Ft int 142.Fo EVP_EncryptInit_ex 143.Fa "EVP_CIPHER_CTX *ctx" 144.Fa "const EVP_CIPHER *type" 145.Fa "ENGINE *engine" 146.Fa "const unsigned char *key" 147.Fa "const unsigned char *iv" 148.Fc 149.Ft int 150.Fo EVP_EncryptUpdate 151.Fa "EVP_CIPHER_CTX *ctx" 152.Fa "unsigned char *out" 153.Fa "int *out_len" 154.Fa "const unsigned char *in" 155.Fa "int in_len" 156.Fc 157.Ft int 158.Fo EVP_EncryptFinal_ex 159.Fa "EVP_CIPHER_CTX *ctx" 160.Fa "unsigned char *out" 161.Fa "int *out_len" 162.Fc 163.Ft int 164.Fo EVP_DecryptInit_ex 165.Fa "EVP_CIPHER_CTX *ctx" 166.Fa "const EVP_CIPHER *type" 167.Fa "ENGINE *engine" 168.Fa "const unsigned char *key" 169.Fa "const unsigned char *iv" 170.Fc 171.Ft int 172.Fo EVP_DecryptUpdate 173.Fa "EVP_CIPHER_CTX *ctx" 174.Fa "unsigned char *out" 175.Fa "int *out_len" 176.Fa "const unsigned char *in" 177.Fa "int in_len" 178.Fc 179.Ft int 180.Fo EVP_DecryptFinal_ex 181.Fa "EVP_CIPHER_CTX *ctx" 182.Fa "unsigned char *out" 183.Fa "int *out_len" 184.Fc 185.Ft int 186.Fo EVP_CipherInit_ex 187.Fa "EVP_CIPHER_CTX *ctx" 188.Fa "const EVP_CIPHER *type" 189.Fa "ENGINE *engine" 190.Fa "const unsigned char *key" 191.Fa "const unsigned char *iv" 192.Fa "int enc" 193.Fc 194.Ft int 195.Fo EVP_CipherUpdate 196.Fa "EVP_CIPHER_CTX *ctx" 197.Fa "unsigned char *out" 198.Fa "int *out_len" 199.Fa "const unsigned char *in" 200.Fa "int in_len" 201.Fc 202.Ft int 203.Fo EVP_CipherFinal_ex 204.Fa "EVP_CIPHER_CTX *ctx" 205.Fa "unsigned char *out" 206.Fa "int *out_len" 207.Fc 208.Ft int 209.Fo EVP_EncryptInit 210.Fa "EVP_CIPHER_CTX *ctx" 211.Fa "const EVP_CIPHER *type" 212.Fa "const unsigned char *key" 213.Fa "const unsigned char *iv" 214.Fc 215.Ft int 216.Fo EVP_EncryptFinal 217.Fa "EVP_CIPHER_CTX *ctx" 218.Fa "unsigned char *out" 219.Fa "int *out_len" 220.Fc 221.Ft int 222.Fo EVP_DecryptInit 223.Fa "EVP_CIPHER_CTX *ctx" 224.Fa "const EVP_CIPHER *type" 225.Fa "const unsigned char *key" 226.Fa "const unsigned char *iv" 227.Fc 228.Ft int 229.Fo EVP_DecryptFinal 230.Fa "EVP_CIPHER_CTX *ctx" 231.Fa "unsigned char *out" 232.Fa "int *out_len" 233.Fc 234.Ft int 235.Fo EVP_CipherInit 236.Fa "EVP_CIPHER_CTX *ctx" 237.Fa "const EVP_CIPHER *type" 238.Fa "const unsigned char *key" 239.Fa "const unsigned char *iv" 240.Fa "int enc" 241.Fc 242.Ft int 243.Fo EVP_CipherFinal 244.Fa "EVP_CIPHER_CTX *ctx" 245.Fa "unsigned char *out" 246.Fa "int *out_len" 247.Fc 248.Ft int 249.Fo EVP_CIPHER_CTX_encrypting 250.Fa "const EVP_CIPHER_CTX *ctx" 251.Fc 252.Ft const EVP_CIPHER * 253.Fo EVP_get_cipherbyname 254.Fa "const char *name" 255.Fc 256.Ft const EVP_CIPHER * 257.Fo EVP_get_cipherbynid 258.Fa "int nid" 259.Fc 260.Ft const EVP_CIPHER * 261.Fo EVP_get_cipherbyobj 262.Fa "const ASN1_OBJECT *a" 263.Fc 264.Ft const EVP_CIPHER * 265.Fo EVP_CIPHER_CTX_cipher 266.Fa "const EVP_CIPHER_CTX *ctx" 267.Fc 268.Sh DESCRIPTION 269The EVP cipher routines are a high level interface to certain symmetric 270ciphers. 271.Pp 272.Fn EVP_CIPHER_CTX_new 273creates a new, empty cipher context. 274.Pp 275.Fn EVP_CIPHER_CTX_reset 276clears all information from 277.Fa ctx 278and frees all allocated memory associated with it, except the 279.Fa ctx 280object itself, such that it can be reused for another series of calls to 281.Fn EVP_CipherInit , 282.Fn EVP_CipherUpdate , 283and 284.Fn EVP_CipherFinal . 285.Pp 286.Fn EVP_CIPHER_CTX_free 287clears all information from 288.Fa ctx 289and frees all allocated memory associated with it, including 290.Fa ctx 291itself. 292This function should be called after all operations using a cipher 293are complete, so sensitive information does not remain in memory. 294If 295.Fa ctx 296is a 297.Dv NULL 298pointer, no action occurs. 299.Pp 300.Fn EVP_CIPHER_CTX_copy 301calls 302.Fn EVP_CIPHER_CTX_reset 303on 304.Fa out 305and copies all the data from 306.Fa in 307to 308.Fa out , 309except that the 310.Vt EVP_CIPHER 311object used by 312.Fa in 313and any application specific data set with 314.Xr EVP_CIPHER_CTX_set_app_data 3 315are not copied and 316.Fa out 317will point to the same two objects. 318The algorithm- and implementation-specific cipher data described in 319.Xr EVP_CIPHER_CTX_get_cipher_data 3 320is copied with 321.Xr malloc 3 322and 323.Xr memcpy 3 , 324i.e. assuming that it does not contain pointers to any sub-objects. 325If the bit 326.Dv EVP_CIPH_CUSTOM_COPY 327has been set with 328.Xr EVP_CIPHER_meth_set_flags 3 , 329.Xr EVP_CIPHER_CTX_ctrl 3 330is called at the end with arguments 331.Fa in , 332.Dv EVP_CTRL_COPY , 333.No 0 , 334and 335.Fa out 336such that the cipher implementation can perform further algorithm- 337and implementation-specific initializations after the algorithm- 338and implementation-specific cipher data has been copied. 339Among the cipher algorithms built into the library, 340.Dv EVP_CIPH_CUSTOM_COPY 341and 342.Dv EVP_CTRL_COPY 343are used by some of the ciphers documented in the 344.Xr EVP_aes_256_gcm 3 345manual page. 346.Pp 347.Fn EVP_EncryptInit 348and 349.Fn EVP_EncryptInit_ex 350set up the cipher context 351.Fa ctx 352for encryption with cipher 353.Fa type . 354.Fa type 355is normally supplied by a function such as 356.Xr EVP_aes_256_cbc 3 . 357.Fa key 358is the symmetric key to use and 359.Fa iv 360is the IV to use (if necessary). 361The actual number of bytes used for the 362key and IV depends on the cipher. 363The 364.Fa ENGINE *engine 365argument is always ignored and passing 366.Dv NULL 367is recommended. 368It is possible to set all parameters to 369.Dv NULL 370except 371.Fa type 372in an initial call and supply the remaining parameters in subsequent 373calls, all of which have 374.Fa type 375set to 376.Dv NULL . 377This is done when the default cipher parameters are not appropriate. 378.Pp 379.Fn EVP_EncryptUpdate 380encrypts 381.Fa in_len 382bytes from the buffer 383.Fa in 384and writes the encrypted version to 385.Fa out . 386This function can be called multiple times to encrypt successive blocks 387of data. 388The amount of data written depends on the block alignment of the 389encrypted data: as a result the amount of data written may be anything 390from zero bytes to 391.Pq Fa in_len No + cipher_block_size - 1 392so 393.Fa out 394should contain sufficient room. 395The actual number of bytes written is placed in 396.Pf * Fa out_len . 397.Pp 398If padding is enabled (the default) then 399.Fn EVP_EncryptFinal 400and 401.Fn EVP_EncryptFinal_ex , 402which behave identically, 403encrypt the "final" data, that is any data that remains in a partial 404block. 405It uses NOTES (aka PKCS padding). 406The encrypted final data is written to 407.Fa out 408which should have sufficient space for one cipher block. 409The number of bytes written is placed in 410.Pf * Fa out_len . 411After this function is called, the encryption operation is finished and 412no further calls to 413.Fn EVP_EncryptUpdate 414should be made. 415.Pp 416If padding is disabled then 417.Fn EVP_EncryptFinal 418and 419.Fn EVP_EncryptFinal_ex 420do not encrypt any more data and return an error if any data 421remains in a partial block: that is if the total data length is not a 422multiple of the block size. 423.Pp 424.Fn EVP_DecryptInit , 425.Fn EVP_DecryptInit_ex , 426.Fn EVP_DecryptUpdate , 427.Fn EVP_DecryptFinal , 428and 429.Fn EVP_DecryptFinal_ex 430are the corresponding decryption operations. 431.Fn EVP_DecryptFinal 432and 433.Fn EVP_DecryptFinal_ex 434return an error code if padding is enabled and the final block is 435not correctly formatted. 436The parameters and restrictions are identical to the encryption 437operations except that if padding is enabled the decrypted data buffer 438.Fa out 439passed to 440.Fn EVP_DecryptUpdate 441should have sufficient room for 442.Pq Fa in_len No + cipher_block_size 443bytes unless the cipher block size is 1 in which case 444.Fa in_len 445bytes is sufficient. 446.Pp 447.Fn EVP_CipherInit , 448.Fn EVP_CipherInit_ex , 449.Fn EVP_CipherUpdate , 450.Fn EVP_CipherFinal , 451and 452.Fn EVP_CipherFinal_ex 453are functions that can be used for decryption or encryption. 454The operation performed depends on the value of the 455.Fa enc 456parameter. 457It should be set to 1 for encryption, 0 for decryption and -1 to leave 458the value unchanged (the actual value of 459.Fa enc 460being supplied in a previous call). 461.Pp 462.Fn EVP_get_cipherbyname , 463.Fn EVP_get_cipherbynid , 464and 465.Fn EVP_get_cipherbyobj 466return an 467.Vt EVP_CIPHER 468structure when passed a cipher name, a NID or an 469.Vt ASN1_OBJECT 470structure. 471.Pp 472.Fn EVP_CIPHER_CTX_cipher 473returns the 474.Vt EVP_CIPHER 475structure when passed an 476.Vt EVP_CIPHER_CTX 477structure. 478.Pp 479Where possible the EVP interface to symmetric ciphers should be 480used in preference to the low level interfaces. 481This is because the code then becomes transparent to the cipher used and 482much more flexible. 483.Pp 484PKCS padding works by adding n padding bytes of value n to make the 485total length of the encrypted data a multiple of the block size. 486Padding is always added so if the data is already a multiple of the 487block size n will equal the block size. 488For example if the block size is 8 and 11 bytes are to be encrypted then 4895 padding bytes of value 5 will be added. 490.Pp 491When decrypting, the final block is checked to see if it has the correct 492form. 493.Pp 494Although the decryption operation can produce an error if padding is 495enabled, it is not a strong test that the input data or key is correct. 496A random block has better than 1 in 256 chance of being of the correct 497format and problems with the input data earlier on will not produce a 498final decrypt error. 499.Pp 500If padding is disabled then the decryption operation will always succeed 501if the total amount of data decrypted is a multiple of the block size. 502.Pp 503.Fn EVP_get_cipherbynid 504and 505.Fn EVP_get_cipherbyobj 506are implemented as macros. 507.Sh RETURN VALUES 508.Fn EVP_CIPHER_CTX_new 509returns a pointer to a newly created 510.Vt EVP_CIPHER_CTX 511for success or 512.Dv NULL 513for failure. 514.Pp 515.Fn EVP_CIPHER_CTX_reset , 516.Fn EVP_CIPHER_CTX_copy , 517.Fn EVP_EncryptInit_ex , 518.Fn EVP_EncryptUpdate , 519.Fn EVP_EncryptFinal_ex , 520.Fn EVP_DecryptInit_ex , 521.Fn EVP_DecryptUpdate , 522.Fn EVP_DecryptFinal_ex , 523.Fn EVP_CipherInit_ex , 524.Fn EVP_CipherUpdate , 525.Fn EVP_CipherFinal_ex , 526.Fn EVP_EncryptInit , 527.Fn EVP_EncryptFinal , 528.Fn EVP_DecryptInit , 529.Fn EVP_DecryptFinal , 530.Fn EVP_CipherInit , 531and 532.Fn EVP_CipherFinal 533return 1 for success or 0 for failure. 534.Pp 535.Fn EVP_CIPHER_CTX_encrypting 536returns 1 if 537.Fa ctx 538is initialized for encryption or 0 otherwise, in which case 539it may be uninitialized or initialized for decryption. 540.Pp 541.Fn EVP_get_cipherbyname , 542.Fn EVP_get_cipherbynid , 543and 544.Fn EVP_get_cipherbyobj 545return an 546.Vt EVP_CIPHER 547structure or 548.Dv NULL 549on error. 550.Pp 551.Fn EVP_CIPHER_CTX_cipher 552returns an 553.Vt EVP_CIPHER 554structure. 555.Sh CIPHER LISTING 556All algorithms have a fixed key length unless otherwise stated. 557.Bl -tag -width Ds 558.It Fn EVP_enc_null 559Null cipher: does nothing. 560.It Xo 561.Fn EVP_idea_cbc , 562.Fn EVP_idea_ecb , 563.Fn EVP_idea_cfb64 , 564.Fn EVP_idea_ofb 565.Xc 566IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 567.Fn EVP_idea_cfb 568is an alias for 569.Fn EVP_idea_cfb64 , 570implemented as a macro. 571.It Xo 572.Fn EVP_rc2_cbc , 573.Fn EVP_rc2_ecb , 574.Fn EVP_rc2_cfb64 , 575.Fn EVP_rc2_ofb 576.Xc 577RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 578This is a variable key length cipher with an additional parameter called 579"effective key bits" or "effective key length". 580By default both are set to 128 bits. 581.Fn EVP_rc2_cfb 582is an alias for 583.Fn EVP_rc2_cfb64 , 584implemented as a macro. 585.It Xo 586.Fn EVP_rc2_40_cbc , 587.Fn EVP_rc2_64_cbc 588.Xc 589RC2 algorithm in CBC mode with a default key length and effective key 590length of 40 and 64 bits. 591These are obsolete and new code should use 592.Fn EVP_rc2_cbc , 593.Xr EVP_CIPHER_CTX_set_key_length 3 , 594and 595.Xr EVP_CIPHER_CTX_ctrl 3 596to set the key length and effective key length. 597.It Xo 598.Fn EVP_bf_cbc , 599.Fn EVP_bf_ecb , 600.Fn EVP_bf_cfb64 , 601.Fn EVP_bf_ofb 602.Xc 603Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes 604respectively. 605This is a variable key length cipher. 606.Fn EVP_bf_cfb 607is an alias for 608.Fn EVP_bf_cfb64 , 609implemented as a macro. 610.It Xo 611.Fn EVP_cast5_cbc , 612.Fn EVP_cast5_ecb , 613.Fn EVP_cast5_cfb64 , 614.Fn EVP_cast5_ofb 615.Xc 616CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. 617This is a variable key length cipher. 618.Fn EVP_cast5_cfb 619is an alias for 620.Fn EVP_cast5_cfb64 , 621implemented as a macro. 622.El 623.Pp 624See also 625.Xr EVP_aes_128_cbc 3 , 626.Xr EVP_camellia_128_cbc 3 , 627.Xr EVP_des_cbc 3 , 628.Xr EVP_rc4 3 , 629and 630.Xr EVP_sm4_cbc 3 . 631.Ss GCM mode 632For GCM mode ciphers, the behaviour of the EVP interface 633is subtly altered and several additional ctrl operations are 634supported. 635.Pp 636To specify any additional authenticated data (AAD), a call to 637.Fn EVP_CipherUpdate , 638.Fn EVP_EncryptUpdate , 639or 640.Fn EVP_DecryptUpdate 641should be made with the output parameter 642.Fa out 643set to 644.Dv NULL . 645.Pp 646When decrypting, the return value of 647.Fn EVP_DecryptFinal , 648.Fn EVP_DecryptFinal_ex , 649.Fn EVP_CipherFinal , 650or 651.Fn EVP_CipherFinal_ex 652indicates if the operation was successful. 653If it does not indicate success, the authentication operation has 654failed and any output data MUST NOT be used as it is corrupted. 655.Pp 656The following ctrls are supported in GCM mode: 657.Bl -tag -width Ds 658.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_IVLEN ivlen NULL 659Sets the IV length: this call can only be made before specifying an IV. 660If not called, a default IV length is used. 661For GCM AES the default is 12, i.e. 96 bits. 662.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_GET_TAG taglen tag 663Writes 664.Fa taglen 665bytes of the tag value to the buffer indicated by 666.Fa tag . 667This call can only be made when encrypting data and after all data has 668been processed, e.g. after an 669.Fn EVP_EncryptFinal 670or 671.Fn EVP_EncryptFinal_ex 672call. 673.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_GCM_SET_TAG taglen tag 674Sets the expected tag to 675.Fa taglen 676bytes from 677.Fa tag . 678This call is only legal when decrypting data and must be made before 679any data is processed, e.g. before any 680.Fa EVP_DecryptUpdate 681call. 682.El 683.Ss CCM mode 684The behaviour of CCM mode ciphers is similar to GCM mode, but with 685a few additional requirements and different ctrl values. 686.Pp 687Like GCM mode any additional authenticated data (AAD) is passed 688by calling 689.Fn EVP_CipherUpdate , 690.Fn EVP_EncryptUpdate , 691or 692.Fn EVP_DecryptUpdate 693with the output parameter 694.Fa out 695set to 696.Dv NULL . 697Additionally, the total 698plaintext or ciphertext length MUST be passed to 699.Fn EVP_CipherUpdate , 700.Fn EVP_EncryptUpdate , 701or 702.Fn EVP_DecryptUpdate 703with the output and input 704parameters 705.Pq Fa in No and Fa out 706set to 707.Dv NULL 708and the length passed in the 709.Fa in_len 710parameter. 711.Pp 712The following ctrls are supported in CCM mode: 713.Bl -tag -width Ds 714.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_TAG taglen tag 715This call is made to set the expected CCM tag value when decrypting or 716the length of the tag (with the 717.Fa tag 718parameter set to 719.Dv NULL ) 720when encrypting. 721The tag length is often referred to as M. 722If not set, a default value is used (12 for AES). 723.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_L ivlen NULL 724Sets the CCM L value. 725If not set, a default is used (8 for AES). 726.It Fn EVP_CIPHER_CTX_ctrl ctx EVP_CTRL_CCM_SET_IVLEN ivlen NULL 727Sets the CCM nonce (IV) length: this call can only be made before 728specifying a nonce value. 729The nonce length is given by 15 - L so it is 7 by default for AES. 730.El 731.Sh EXAMPLES 732Encrypt a string using blowfish: 733.Bd -literal -offset 3n 734int 735do_crypt(char *out_filename) 736{ 737 unsigned char out_buf[1024]; 738 int out_len, tmp_len; 739 /* 740 * Bogus key and IV: we'd normally set these from 741 * another source. 742 */ 743 unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; 744 unsigned char iv[] = {1,2,3,4,5,6,7,8}; 745 const char in_text[] = "Some Crypto Text"; 746 EVP_CIPHER_CTX *ctx; 747 FILE *out_fileptr; 748 749 ctx = EVP_CIPHER_CTX_new(); 750 EVP_EncryptInit_ex(ctx, EVP_bf_cbc(), NULL, key, iv); 751 752 if (!EVP_EncryptUpdate(ctx, out_buf, &out_len, in_text, 753 strlen(in_text))) { 754 /* Error */ 755 EVP_CIPHER_CTX_free(ctx); 756 return 0; 757 } 758 /* 759 * Buffer passed to EVP_EncryptFinal() must be after data just 760 * encrypted to avoid overwriting it. 761 */ 762 if (!EVP_EncryptFinal_ex(ctx, out_buf + out_len, &tmp_len)) { 763 /* Error */ 764 EVP_CIPHER_CTX_free(ctx); 765 return 0; 766 } 767 out_len += tmp_len; 768 EVP_CIPHER_CTX_free(ctx); 769 /* 770 * Need binary mode for fopen because encrypted data is 771 * binary data. Also cannot use strlen() on it because 772 * it won't be NUL terminated and may contain embedded 773 * NULs. 774 */ 775 out_fileptr = fopen(out_filename, "wb"); 776 if (out_fileptr == NULL) { 777 /* Error */ 778 return 0; 779 } 780 fwrite(out_buf, 1, out_len, out_fileptr); 781 fclose(out_fileptr); 782 return 1; 783} 784.Ed 785.Pp 786The ciphertext from the above example can be decrypted using the 787.Xr openssl 1 788utility with the command line: 789.Bd -literal -offset indent 790openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F \e 791 -iv 0102030405060708 -d 792.Ed 793.Pp 794General encryption, decryption function example using FILE I/O and AES128 795with a 128-bit key: 796.Bd -literal 797int 798do_crypt(FILE *in_fileptr, FILE *out_fileptr, int do_encrypt) 799{ 800 /* Allow enough space in output buffer for additional block */ 801 unsigned char in_buf[1024], out_buf[1024 + EVP_MAX_BLOCK_LENGTH]; 802 int in_len, out_len; 803 EVP_CIPHER_CTX *ctx; 804 805 /* 806 * Bogus key and IV: we'd normally set these from 807 * another source. 808 */ 809 unsigned char key[] = "0123456789abcdeF"; 810 unsigned char iv[] = "1234567887654321"; 811 812 ctx = EVP_CIPHER_CTX_new(); 813 EVP_CipherInit_ex(ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, 814 do_encrypt); 815 EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); 816 817 for (;;) { 818 in_len = fread(in_buf, 1, 1024, in_fileptr); 819 if (in_len <= 0) 820 break; 821 if (!EVP_CipherUpdate(ctx, out_buf, &out_len, in_buf, 822 in_len)) { 823 /* Error */ 824 EVP_CIPHER_CTX_free(ctx); 825 return 0; 826 } 827 fwrite(out_buf, 1, out_len, out_fileptr); 828 } 829 if (!EVP_CipherFinal_ex(ctx, out_buf, &out_len)) { 830 /* Error */ 831 EVP_CIPHER_CTX_free(ctx); 832 return 0; 833 } 834 fwrite(out_buf, 1, out_len, out_fileptr); 835 836 EVP_CIPHER_CTX_free(ctx); 837 return 1; 838} 839.Ed 840.Sh SEE ALSO 841.Xr BIO_f_cipher 3 , 842.Xr evp 3 , 843.Xr EVP_AEAD_CTX_init 3 , 844.Xr EVP_aes_128_cbc 3 , 845.Xr EVP_camellia_128_cbc 3 , 846.Xr EVP_chacha20 3 , 847.Xr EVP_CIPHER_CTX_ctrl 3 , 848.Xr EVP_CIPHER_CTX_get_cipher_data 3 , 849.Xr EVP_CIPHER_CTX_init 3 , 850.Xr EVP_CIPHER_CTX_set_flags 3 , 851.Xr EVP_CIPHER_nid 3 , 852.Xr EVP_des_cbc 3 , 853.Xr EVP_OpenInit 3 , 854.Xr EVP_rc4 3 , 855.Xr EVP_SealInit 3 , 856.Xr EVP_sm4_cbc 3 857.Sh HISTORY 858.Fn EVP_EncryptInit , 859.Fn EVP_EncryptUpdate , 860.Fn EVP_EncryptFinal , 861.Fn EVP_DecryptInit , 862.Fn EVP_DecryptUpdate , 863.Fn EVP_DecryptFinal , 864.Fn EVP_CipherInit , 865.Fn EVP_CipherUpdate , 866.Fn EVP_CipherFinal , 867.Fn EVP_get_cipherbyname , 868.Fn EVP_idea_cbc , 869.Fn EVP_idea_ecb , 870.Fn EVP_idea_cfb , 871and 872.Fn EVP_idea_ofb 873first appeared in SSLeay 0.5.1. 874.Fn EVP_rc2_cbc , 875.Fn EVP_rc2_ecb , 876.Fn EVP_rc2_cfb , 877and 878.Fn EVP_rc2_ofb 879first appeared in SSLeay 0.5.2. 880.Fn EVP_bf_cbc , 881.Fn EVP_bf_ecb , 882.Fn EVP_bf_cfb , 883and 884.Fn EVP_bf_ofb 885first appeared in SSLeay 0.6.6. 886.Fn EVP_get_cipherbyobj , 887.Fn EVP_CIPHER_CTX_cipher , 888and 889.Fn EVP_enc_null 890first appeared in SSLeay 0.8.0. 891.Fn EVP_get_cipherbynid 892first appeared in SSLeay 0.8.1. 893All these functions have been available since 894.Ox 2.4 . 895.Pp 896.Fn EVP_rc2_40_cbc 897and 898.Fn EVP_rc2_64_cbc 899first appeared in SSLeay 0.9.1 and have been available since 900.Ox 2.6 . 901.Pp 902.Fn EVP_EncryptInit_ex , 903.Fn EVP_EncryptFinal_ex , 904.Fn EVP_DecryptInit_ex , 905.Fn EVP_DecryptFinal_ex , 906.Fn EVP_CipherInit_ex , 907and 908.Fn EVP_CipherFinal_ex 909first appeared in OpenSSL 0.9.7 and have been available since 910.Ox 3.2 . 911.Pp 912.Fn EVP_bf_cfb64 , 913.Fn EVP_cast5_cfb64 , 914.Fn EVP_idea_cfb64 , 915and 916.Fn EVP_rc2_cfb64 917first appeared in OpenSSL 0.9.7e and have been available since 918.Ox 3.8 . 919.Pp 920.Fn EVP_CIPHER_CTX_new 921and 922.Fn EVP_CIPHER_CTX_free 923first appeared in OpenSSL 0.9.8b and have been available since 924.Ox 4.5 . 925.Pp 926.Fn EVP_CIPHER_CTX_copy 927first appeared in OpenSSL 1.0.0 928and has been available since 929.Ox 4.9 . 930.Pp 931.Fn EVP_CIPHER_CTX_reset 932first appeared in OpenSSL 1.1.0 and has been available since 933.Ox 6.3 . 934.Pp 935.Fn EVP_CIPHER_CTX_encrypting 936first appeared in OpenSSL 1.1.0 and has been available since 937.Ox 6.4 . 938.Sh BUGS 939.Fn EVP_CIPHER_CTX_copy 940may already have cleared the data in 941.Fa out 942and copied some new data into it even if it fails and returns 0. 943