summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EVP_DigestInit.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/EVP_DigestInit.3606
1 files changed, 0 insertions, 606 deletions
diff --git a/src/lib/libcrypto/man/EVP_DigestInit.3 b/src/lib/libcrypto/man/EVP_DigestInit.3
deleted file mode 100644
index 668c189bc1..0000000000
--- a/src/lib/libcrypto/man/EVP_DigestInit.3
+++ /dev/null
@@ -1,606 +0,0 @@
1.\" $OpenBSD: EVP_DigestInit.3,v 1.37 2024/12/06 15:01:01 schwarze Exp $
2.\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000
3.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
4.\"
5.\" This file is a derived work.
6.\" The changes are covered by the following Copyright and license:
7.\"
8.\" Copyright (c) 2019, 2023 Ingo Schwarze <schwarze@openbsd.org>
9.\"
10.\" Permission to use, copy, modify, and distribute this software for any
11.\" purpose with or without fee is hereby granted, provided that the above
12.\" copyright notice and this permission notice appear in all copies.
13.\"
14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21.\"
22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>,
23.\" Richard Levitte <levitte@openssl.org>,
24.\" Paul Yang <yang.yang@baishancloud.com>, and
25.\" Antoine Salon <asalon@vmware.com>.
26.\" Copyright (c) 2000-2004, 2009, 2012-2016, 2018, 2019 The OpenSSL Project.
27.\" All rights reserved.
28.\"
29.\" Redistribution and use in source and binary forms, with or without
30.\" modification, are permitted provided that the following conditions
31.\" are met:
32.\"
33.\" 1. Redistributions of source code must retain the above copyright
34.\" notice, this list of conditions and the following disclaimer.
35.\"
36.\" 2. Redistributions in binary form must reproduce the above copyright
37.\" notice, this list of conditions and the following disclaimer in
38.\" the documentation and/or other materials provided with the
39.\" distribution.
40.\"
41.\" 3. All advertising materials mentioning features or use of this
42.\" software must display the following acknowledgment:
43.\" "This product includes software developed by the OpenSSL Project
44.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
45.\"
46.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
47.\" endorse or promote products derived from this software without
48.\" prior written permission. For written permission, please contact
49.\" openssl-core@openssl.org.
50.\"
51.\" 5. Products derived from this software may not be called "OpenSSL"
52.\" nor may "OpenSSL" appear in their names without prior written
53.\" permission of the OpenSSL Project.
54.\"
55.\" 6. Redistributions of any form whatsoever must retain the following
56.\" acknowledgment:
57.\" "This product includes software developed by the OpenSSL Project
58.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
59.\"
60.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
61.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
62.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
63.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
64.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
65.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
66.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
67.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
68.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
69.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
70.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
71.\" OF THE POSSIBILITY OF SUCH DAMAGE.
72.\"
73.Dd $Mdocdate: December 6 2024 $
74.Dt EVP_DIGESTINIT 3
75.Os
76.Sh NAME
77.Nm EVP_MD_CTX_new ,
78.Nm EVP_MD_CTX_reset ,
79.Nm EVP_MD_CTX_free ,
80.Nm EVP_MD_CTX_init ,
81.Nm EVP_MD_CTX_create ,
82.Nm EVP_MD_CTX_cleanup ,
83.Nm EVP_MD_CTX_destroy ,
84.Nm EVP_DigestInit_ex ,
85.Nm EVP_DigestUpdate ,
86.Nm EVP_DigestFinal_ex ,
87.Nm EVP_Digest ,
88.Nm EVP_MD_CTX_copy_ex ,
89.Nm EVP_DigestInit ,
90.Nm EVP_DigestFinal ,
91.Nm EVP_MD_CTX_copy ,
92.Nm EVP_MD_CTX_md ,
93.Nm EVP_md_null ,
94.Nm EVP_sha224 ,
95.Nm EVP_sha256 ,
96.Nm EVP_sha384 ,
97.Nm EVP_sha512 ,
98.Nm EVP_sha512_224 ,
99.Nm EVP_sha512_256 ,
100.Nm EVP_ripemd160 ,
101.Nm EVP_get_digestbyname ,
102.Nm EVP_get_digestbynid ,
103.Nm EVP_get_digestbyobj
104.Nd EVP digest routines
105.Sh SYNOPSIS
106.In openssl/evp.h
107.Ft EVP_MD_CTX *
108.Fn EVP_MD_CTX_new void
109.Ft int
110.Fo EVP_MD_CTX_reset
111.Fa "EVP_MD_CTX *ctx"
112.Fc
113.Ft void
114.Fo EVP_MD_CTX_free
115.Fa "EVP_MD_CTX *ctx"
116.Fc
117.Ft int
118.Fo EVP_MD_CTX_init
119.Fa "EVP_MD_CTX *ctx"
120.Fc
121.Ft EVP_MD_CTX *
122.Fn EVP_MD_CTX_create void
123.Ft int
124.Fo EVP_MD_CTX_cleanup
125.Fa "EVP_MD_CTX *ctx"
126.Fc
127.Ft void
128.Fo EVP_MD_CTX_destroy
129.Fa "EVP_MD_CTX *ctx"
130.Fc
131.Ft int
132.Fo EVP_DigestInit_ex
133.Fa "EVP_MD_CTX *ctx"
134.Fa "const EVP_MD *type"
135.Fa "ENGINE *engine"
136.Fc
137.Ft int
138.Fo EVP_DigestUpdate
139.Fa "EVP_MD_CTX *ctx"
140.Fa "const void *d"
141.Fa "size_t cnt"
142.Fc
143.Ft int
144.Fo EVP_DigestFinal_ex
145.Fa "EVP_MD_CTX *ctx"
146.Fa "unsigned char *md"
147.Fa "unsigned int *s"
148.Fc
149.Ft int
150.Fo EVP_Digest
151.Fa "const void *d"
152.Fa "size_t cnt"
153.Fa "unsigned char *md"
154.Fa "unsigned int *s"
155.Fa "const EVP_MD *type"
156.Fa "ENGINE *engine"
157.Fc
158.Ft int
159.Fo EVP_MD_CTX_copy_ex
160.Fa "EVP_MD_CTX *out"
161.Fa "const EVP_MD_CTX *in"
162.Fc
163.Ft int
164.Fo EVP_DigestInit
165.Fa "EVP_MD_CTX *ctx"
166.Fa "const EVP_MD *type"
167.Fc
168.Ft int
169.Fo EVP_DigestFinal
170.Fa "EVP_MD_CTX *ctx"
171.Fa "unsigned char *md"
172.Fa "unsigned int *s"
173.Fc
174.Ft int
175.Fo EVP_MD_CTX_copy
176.Fa "EVP_MD_CTX *out"
177.Fa "EVP_MD_CTX *in"
178.Fc
179.Ft const EVP_MD *
180.Fo EVP_MD_CTX_md
181.Fa "const EVP_MD_CTX *ctx"
182.Fc
183.Ft const EVP_MD *
184.Fn EVP_md_null void
185.Ft const EVP_MD *
186.Fn EVP_sha224 void
187.Ft const EVP_MD *
188.Fn EVP_sha256 void
189.Ft const EVP_MD *
190.Fn EVP_sha384 void
191.Ft const EVP_MD *
192.Fn EVP_sha512 void
193.Ft const EVP_MD *
194.Fn EVP_sha512_224 void
195.Ft const EVP_MD *
196.Fn EVP_sha512_256 void
197.Ft const EVP_MD *
198.Fn EVP_ripemd160 void
199.Ft const EVP_MD *
200.Fo EVP_get_digestbyname
201.Fa "const char *name"
202.Fc
203.Ft const EVP_MD *
204.Fo EVP_get_digestbynid
205.Fa "int type"
206.Fc
207.Ft const EVP_MD *
208.Fo EVP_get_digestbyobj
209.Fa "const ASN1_OBJECT *o"
210.Fc
211.Sh DESCRIPTION
212The EVP digest routines are a high-level interface to message digests
213and should be used instead of the cipher-specific functions.
214.Pp
215.Fn EVP_MD_CTX_new
216allocates a new, empty digest context.
217.Pp
218.Fn EVP_MD_CTX_reset
219cleans up
220.Fa ctx
221and resets it to the state it had after
222.Fn EVP_MD_CTX_new ,
223such that it can be reused.
224.Pp
225.Fn EVP_MD_CTX_free
226cleans up
227.Fa ctx
228and frees the space allocated to it.
229.Pp
230.Fn EVP_MD_CTX_init
231is a deprecated function to clear a digest context on the stack
232before use.
233Do not use it on a digest context returned from
234.Fn EVP_MD_CTX_new
235or one that was already used.
236.Pp
237.Fn EVP_MD_CTX_create ,
238.Fn EVP_MD_CTX_cleanup ,
239and
240.Fn EVP_MD_CTX_destroy
241are deprecated aliases for
242.Fn EVP_MD_CTX_new ,
243.Fn EVP_MD_CTX_reset ,
244and
245.Fn EVP_MD_CTX_free ,
246respectively.
247.Pp
248.Fn EVP_DigestInit_ex
249sets up the digest context
250.Fa ctx
251to use a digest
252.Fa type .
253The
254.Fa type
255will typically be supplied by a function such as
256.Fn EVP_sha512 .
257The
258.Fa ENGINE *engine
259argument is always ignored and passing
260.Dv NULL
261is recommended.
262.Pp
263.Fn EVP_DigestUpdate
264hashes
265.Fa cnt
266bytes of data at
267.Fa d
268into the digest context
269.Fa ctx .
270This function can be called several times on the same
271.Fa ctx
272to hash additional data.
273.Pp
274.Fn EVP_DigestFinal_ex
275retrieves the digest value from
276.Fa ctx
277and places it in
278.Fa md .
279If the
280.Fa s
281parameter is not
282.Dv NULL ,
283then the number of bytes of data written (i.e. the length of the
284digest) will be written to the integer at
285.Fa s ;
286at most
287.Dv EVP_MAX_MD_SIZE
288bytes will be written.
289After calling
290.Fn EVP_DigestFinal_ex ,
291no additional calls to
292.Fn EVP_DigestUpdate
293can be made, but
294.Fn EVP_DigestInit_ex
295can be called to initialize a new digest operation.
296.Pp
297.Fn EVP_Digest
298is a simple wrapper function to hash
299.Fa cnt
300bytes of data at
301.Fa d
302using the digest
303.Fa type
304in a one-shot operation and place the digest value into
305.Fa md ,
306and, unless
307.Fa s
308is
309.Dv NULL ,
310the length of the digest in bytes into
311.Pf * Fa s .
312This wrapper uses a temporary digest context and passes its arguments to
313.Fn EVP_DigestInit_ex ,
314.Fn EVP_DigestUpdate ,
315and
316.Fn EVP_DigestFinal_ex
317internally.
318The
319.Fa ENGINE *engine
320argument is always ignored and passing
321.Dv NULL
322is recommended.
323.Pp
324.Fn EVP_MD_CTX_copy_ex
325can be used to copy the message digest state from
326.Fa in
327to
328.Fa out .
329This is useful if large amounts of data are to be hashed which only
330differ in the last few bytes.
331.Pp
332.Fn EVP_DigestInit
333is a deprecated function behaving like
334.Fn EVP_DigestInit_ex
335except that it requires
336.Fn EVP_MD_CTX_reset
337before it can be used on a context that was already used.
338.Pp
339.Fn EVP_DigestFinal
340is a deprecated function behaving like
341.Fn EVP_DigestFinal_ex
342except that the digest context
343.Fa ctx
344is automatically cleaned up after use by calling
345.Fn EVP_MD_CTX_reset
346internally.
347.Pp
348.Fn EVP_MD_CTX_copy
349is a deprecated function behaving like
350.Fn EVP_MD_CTX_copy_ex
351except that it requires
352.Fn EVP_MD_CTX_reset
353before a context that was already used can be passed as
354.Fa out .
355.Pp
356.Fn EVP_sha224 ,
357.Fn EVP_sha256 ,
358.Fn EVP_sha384 ,
359.Fn EVP_sha512 ,
360and
361.Fn EVP_ripemd160
362return
363.Vt EVP_MD
364structures for the SHA224, SHA256, SHA384, SHA512 and
365RIPEMD160 digest algorithms respectively.
366.Pp
367.Fn EVP_sha512_224
368and
369.Fn EVP_sha512_256
370return an
371.Vt EVP_MD
372structure that provides the truncated SHA512 variants SHA512/224 and SHA512/256,
373respectively.
374.Pp
375.Fn EVP_md_null
376is a "null" message digest that does nothing:
377i.e. the hash it returns is of zero length.
378.Pp
379.Fn EVP_get_digestbyname ,
380.Fn EVP_get_digestbynid ,
381and
382.Fn EVP_get_digestbyobj
383return an
384.Vt EVP_MD
385structure when passed a digest name, a digest NID, or an ASN1_OBJECT
386structure respectively.
387.Pp
388.Fn EVP_get_digestbynid
389and
390.Fn EVP_get_digestbyobj
391are implemented as macros.
392.Pp
393The EVP interface to message digests should almost always be used
394in preference to the low-level interfaces.
395This is because the code then becomes transparent to the digest used and
396much more flexible.
397.Pp
398The
399.Fa ENGINE *engine
400argument is always ignored and passing
401.Dv NULL
402is recommended.
403.Pp
404The functions
405.Fn EVP_DigestInit ,
406.Fn EVP_DigestFinal ,
407and
408.Fn EVP_MD_CTX_copy
409are obsolete but are retained to maintain compatibility with existing
410code.
411New applications should use
412.Fn EVP_DigestInit_ex ,
413.Fn EVP_DigestFinal_ex ,
414and
415.Fn EVP_MD_CTX_copy_ex
416because they can efficiently reuse a digest context instead of
417initializing and cleaning it up on each call.
418.Pp
419If digest contexts are not cleaned up after use, memory leaks will occur.
420.Sh RETURN VALUES
421.Fn EVP_MD_CTX_new
422and
423.Fn EVP_MD_CTX_create
424return the new
425.Vt EVP_MD_CTX
426object or
427.Dv NULL
428for failure.
429.Pp
430.Fn EVP_MD_CTX_reset ,
431.Fn EVP_MD_CTX_init ,
432and
433.Fn EVP_MD_CTX_cleanup
434always return 1.
435.Pp
436.Fn EVP_DigestInit_ex ,
437.Fn EVP_DigestUpdate ,
438.Fn EVP_DigestFinal_ex ,
439.Fn EVP_Digest ,
440.Fn EVP_MD_CTX_copy_ex ,
441.Fn EVP_DigestInit ,
442.Fn EVP_DigestFinal ,
443and
444.Fn EVP_MD_CTX_copy
445return 1 for success or 0 for failure.
446.Pp
447.Fn EVP_MD_CTX_md
448returns the
449.Vt EVP_MD
450object used by
451.Fa ctx ,
452or
453.Dv NULL
454if
455.Fa ctx
456is
457.Dv NULL
458or does not have any message digest algorithm assigned yet.
459.Pp
460.Fn EVP_md_null ,
461.Fn EVP_sha224 ,
462.Fn EVP_sha256 ,
463.Fn EVP_sha384 ,
464.Fn EVP_sha512 ,
465.Fn EVP_sha512_224 ,
466.Fn EVP_sha512_256 ,
467and
468.Fn EVP_ripemd160
469return pointers to constant static objects owned by the library.
470.Pp
471.Fn EVP_get_digestbyname ,
472.Fn EVP_get_digestbynid ,
473and
474.Fn EVP_get_digestbyobj
475return either an
476.Vt EVP_MD
477structure or
478.Dv NULL
479if an error occurs.
480.Sh EXAMPLES
481This example digests the data "Test Message\en" and "Hello World\en",
482using the digest name passed on the command line.
483.Bd -literal -offset indent
484#include <stdio.h>
485#include <string.h>
486#include <openssl/evp.h>
487
488int
489main(int argc, char *argv[])
490{
491 EVP_MD_CTX *mdctx;
492 const EVP_MD *md;
493 const char mess1[] = "Test Message\en";
494 const char mess2[] = "Hello World\en";
495 unsigned char md_value[EVP_MAX_MD_SIZE];
496 unsigned int md_len, i;
497
498 if (argc <= 1) {
499 printf("Usage: mdtest digestname\en");
500 exit(1);
501 }
502
503 md = EVP_get_digestbyname(argv[1]);
504 if (md == NULL) {
505 printf("Unknown message digest %s\en", argv[1]);
506 exit(1);
507 }
508
509 mdctx = EVP_MD_CTX_new();
510 EVP_DigestInit_ex(mdctx, md, NULL);
511 EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
512 EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
513 EVP_DigestFinal_ex(mdctx, md_value, &md_len);
514 EVP_MD_CTX_free(mdctx);
515
516 printf("Digest is: ");
517 for(i = 0; i < md_len; i++)
518 printf("%02x", md_value[i]);
519 printf("\en");
520
521 return 0;
522}
523.Ed
524.Sh SEE ALSO
525.Xr BIO_f_md 3 ,
526.Xr CMAC_Init 3 ,
527.Xr evp 3 ,
528.Xr EVP_BytesToKey 3 ,
529.Xr EVP_DigestSignInit 3 ,
530.Xr EVP_DigestVerifyInit 3 ,
531.Xr EVP_MD_CTX_ctrl 3 ,
532.Xr EVP_MD_nid 3 ,
533.Xr EVP_PKEY_CTX_set_signature_md 3 ,
534.Xr EVP_sha1 3 ,
535.Xr EVP_sha3_224 3 ,
536.Xr EVP_SignInit 3 ,
537.Xr EVP_sm3 3 ,
538.Xr EVP_VerifyInit 3 ,
539.Xr HMAC 3 ,
540.Xr OCSP_basic_sign 3 ,
541.Xr OCSP_request_sign 3 ,
542.Xr PKCS5_PBKDF2_HMAC 3 ,
543.Xr PKCS7_sign_add_signer 3 ,
544.Xr X509_ALGOR_set0 3 ,
545.Xr X509_digest 3 ,
546.Xr X509_sign 3
547.Sh HISTORY
548.Fn EVP_DigestInit ,
549.Fn EVP_DigestUpdate ,
550and
551.Fn EVP_DigestFinal
552first appeared in SSLeay 0.5.1.
553.Fn EVP_md_null
554and
555.Fn EVP_get_digestbyname
556first appeared in SSLeay 0.8.0.
557.Fn EVP_get_digestbynid
558and
559.Fn EVP_get_digestbyobj
560first appeared in SSLeay 0.8.1.
561.Fn EVP_ripemd160
562first appeared in SSLeay 0.9.0.
563All these functions have been available since
564.Ox 2.4 .
565.Pp
566.Fn EVP_MD_CTX_copy
567first appeared in OpenSSL 0.9.2b and has been available since
568.Ox 2.6 .
569.Pp
570.Fn EVP_MD_CTX_md
571first appeared in OpenSSL 0.9.5 and has been available since
572.Ox 2.7 .
573.Pp
574.Fn EVP_MD_CTX_init ,
575.Fn EVP_MD_CTX_create ,
576.Fn EVP_MD_CTX_cleanup ,
577.Fn EVP_MD_CTX_destroy ,
578.Fn EVP_DigestInit_ex ,
579.Fn EVP_DigestFinal_ex ,
580.Fn EVP_Digest ,
581and
582.Fn EVP_MD_CTX_copy_ex
583first appeared in OpenSSL 0.9.7 and have been available since
584.Ox 3.2 .
585.Pp
586.Fn EVP_sha224 ,
587.Fn EVP_sha256 ,
588.Fn EVP_sha384 ,
589and
590.Fn EVP_sha512
591first appeared in OpenSSL 0.9.7h and 0.9.8a
592and have been available since
593.Ox 4.0 .
594.Pp
595.Fn EVP_MD_CTX_new ,
596.Fn EVP_MD_CTX_reset ,
597and
598.Fn EVP_MD_CTX_free
599first appeared in OpenSSL 1.1.0 and have been available since
600.Ox 6.3 .
601.Pp
602.Fn EVP_sha512_224
603and
604.Fn EVP_sha512_256
605first appeared in OpenSSL 1.1.1 and have been available since
606.Ox 7.4 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 23:04:17 +0000