summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EVP_EncryptInit.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/EVP_EncryptInit.3')
-rw-r--r--src/lib/libcrypto/man/EVP_EncryptInit.3813
1 files changed, 0 insertions, 813 deletions
diff --git a/src/lib/libcrypto/man/EVP_EncryptInit.3 b/src/lib/libcrypto/man/EVP_EncryptInit.3
deleted file mode 100644
index 7765be2ca6..0000000000
--- a/src/lib/libcrypto/man/EVP_EncryptInit.3
+++ /dev/null
@@ -1,813 +0,0 @@
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.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 15:49:26 +0000