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