]>
Commit | Line | Data |
---|---|---|
3cbe1980 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
25191fff | 5 | EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex, |
52ad5b60 | 6 | EVP_MD_CTX_ctrl, EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex, |
25191fff | 7 | EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type, |
aafbe1cc | 8 | EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, |
474e469b | 9 | EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha1, |
7f572e95 | 10 | EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_mdc2, |
684b1695 | 11 | EVP_ripemd160, EVP_blake2b512, EVP_blake2s256, EVP_get_digestbyname, |
2d0b4412 | 12 | EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines |
3cbe1980 DSH |
13 | |
14 | =head1 SYNOPSIS | |
15 | ||
16 | #include <openssl/evp.h> | |
17 | ||
25191fff RL |
18 | EVP_MD_CTX *EVP_MD_CTX_new(void); |
19 | int EVP_MD_CTX_reset(EVP_MD_CTX *ctx); | |
20 | void EVP_MD_CTX_free(EVP_MD_CTX *ctx); | |
52ad5b60 | 21 | void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2); |
e72d734d DSH |
22 | |
23 | int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); | |
109d3123 | 24 | int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); |
e72d734d DSH |
25 | int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, |
26 | unsigned int *s); | |
27 | ||
aebb9aac | 28 | int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in); |
e72d734d DSH |
29 | |
30 | int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); | |
13588350 | 31 | int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, |
4d524e10 | 32 | unsigned int *s); |
3cbe1980 | 33 | |
aebb9aac | 34 | int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in); |
e72d734d | 35 | |
5a34fcd7 | 36 | int EVP_MD_type(const EVP_MD *md); |
05ea606a | 37 | int EVP_MD_pkey_type(const EVP_MD *md); |
5a34fcd7 DSH |
38 | int EVP_MD_size(const EVP_MD *md); |
39 | int EVP_MD_block_size(const EVP_MD *md); | |
3cbe1980 | 40 | |
5a34fcd7 | 41 | const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); |
25191fff RL |
42 | int EVP_MD_CTX_size(const EVP_MD *ctx); |
43 | int EVP_MD_CTX_block_size(const EVP_MD *ctx); | |
44 | int EVP_MD_CTX_type(const EVP_MD *ctx); | |
3cbe1980 | 45 | |
13588350 DSH |
46 | const EVP_MD *EVP_md_null(void); |
47 | const EVP_MD *EVP_md2(void); | |
48 | const EVP_MD *EVP_md5(void); | |
13588350 | 49 | const EVP_MD *EVP_sha1(void); |
13588350 DSH |
50 | const EVP_MD *EVP_mdc2(void); |
51 | const EVP_MD *EVP_ripemd160(void); | |
684b1695 RS |
52 | const EVP_MD *EVP_blake2b512(void); |
53 | const EVP_MD *EVP_blake2s256(void); | |
3cbe1980 | 54 | |
5a34fcd7 DSH |
55 | const EVP_MD *EVP_sha224(void); |
56 | const EVP_MD *EVP_sha256(void); | |
57 | const EVP_MD *EVP_sha384(void); | |
58 | const EVP_MD *EVP_sha512(void); | |
59 | ||
3cbe1980 | 60 | const EVP_MD *EVP_get_digestbyname(const char *name); |
25191fff RL |
61 | const EVP_MD *EVP_get_digestbynid(int type); |
62 | const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o); | |
3cbe1980 DSH |
63 | |
64 | =head1 DESCRIPTION | |
65 | ||
c7497f34 RS |
66 | The EVP digest routines are a high level interface to message digests, |
67 | and should be used instead of the cipher-specific functions. | |
3cbe1980 | 68 | |
25191fff RL |
69 | EVP_MD_CTX_new() allocates, initializes and returns a digest context. |
70 | ||
71 | EVP_MD_CTX_reset() resets the digest context B<ctx>. This can be used | |
72 | to reuse an already existing context. | |
e72d734d | 73 | |
25191fff RL |
74 | EVP_MD_CTX_free() cleans up digest context B<ctx> and frees up the |
75 | space allocated to it. | |
e72d734d | 76 | |
52ad5b60 TS |
77 | EVP_MD_CTX_ctrl() performs digest-specific control actions on context B<ctx>. |
78 | ||
e72d734d DSH |
79 | EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest |
80 | B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this | |
186bb907 | 81 | function. B<type> will typically be supplied by a function such as EVP_sha1(). |
e72d734d | 82 | If B<impl> is NULL then the default implementation of digest B<type> is used. |
3cbe1980 | 83 | |
4facdbb5 | 84 | EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the |
c8973693 | 85 | digest context B<ctx>. This function can be called several times on the |
3cbe1980 DSH |
86 | same B<ctx> to hash additional data. |
87 | ||
e72d734d | 88 | EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places |
3cbe1980 DSH |
89 | it in B<md>. If the B<s> parameter is not NULL then the number of |
90 | bytes of data written (i.e. the length of the digest) will be written | |
91 | to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. | |
e72d734d DSH |
92 | After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() |
93 | can be made, but EVP_DigestInit_ex() can be called to initialize a new | |
3cbe1980 DSH |
94 | digest operation. |
95 | ||
e72d734d | 96 | EVP_MD_CTX_copy_ex() can be used to copy the message digest state from |
3cbe1980 | 97 | B<in> to B<out>. This is useful if large amounts of data are to be |
e72d734d DSH |
98 | hashed which only differ in the last few bytes. B<out> must be initialized |
99 | before calling this function. | |
100 | ||
101 | EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except | |
102 | the passed context B<ctx> does not have to be initialized, and it always | |
103 | uses the default digest implementation. | |
104 | ||
105 | EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest | |
11c4c02c | 106 | context B<ctx> is automatically cleaned up. |
e72d734d DSH |
107 | |
108 | EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination | |
109 | B<out> does not have to be initialized. | |
3cbe1980 | 110 | |
4facdbb5 | 111 | EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest |
3cbe1980 DSH |
112 | when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the |
113 | hash. | |
114 | ||
4facdbb5 | 115 | EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the |
3cbe1980 DSH |
116 | message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. |
117 | ||
4facdbb5 | 118 | EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER |
3cbe1980 | 119 | representing the given message digest when passed an B<EVP_MD> structure. |
4facdbb5 | 120 | For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is |
3cbe1980 DSH |
121 | normally used when setting ASN1 OIDs. |
122 | ||
72b60351 | 123 | EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed |
3cbe1980 DSH |
124 | B<EVP_MD_CTX>. |
125 | ||
4facdbb5 UM |
126 | EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated |
127 | with this digest. For example EVP_sha1() is associated with RSA so this will | |
5a34fcd7 DSH |
128 | return B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms |
129 | are no longer linked this function is only retained for compatibility | |
130 | reasons. | |
3cbe1980 | 131 | |
474e469b | 132 | EVP_md2(), EVP_md5(), EVP_sha1(), EVP_sha224(), EVP_sha256(), |
684b1695 RS |
133 | EVP_sha384(), EVP_sha512(), EVP_mdc2(), EVP_ripemd160(), EVP_blake2b512(), and |
134 | EVP_blake2s256() return B<EVP_MD> structures for the MD2, MD5, SHA1, SHA224, | |
208527a7 KR |
135 | SHA256, SHA384, SHA512, MDC2, RIPEMD160, BLAKE2b-512, and BLAKE2s-256 digest |
136 | algorithms respectively. | |
3cbe1980 | 137 | |
4facdbb5 | 138 | EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it |
3cbe1980 DSH |
139 | returns is of zero length. |
140 | ||
4facdbb5 | 141 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() |
3cbe1980 | 142 | return an B<EVP_MD> structure when passed a digest name, a digest NID or |
f672aee4 | 143 | an ASN1_OBJECT structure respectively. |
3cbe1980 DSH |
144 | |
145 | =head1 RETURN VALUES | |
146 | ||
e72d734d | 147 | EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for |
13588350 | 148 | success and 0 for failure. |
3cbe1980 | 149 | |
52ad5b60 TS |
150 | EVP_MD_CTX_ctrl() returns 1 if successful or 0 for failure. |
151 | ||
e72d734d | 152 | EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure. |
3cbe1980 DSH |
153 | |
154 | EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the | |
155 | corresponding OBJECT IDENTIFIER or NID_undef if none exists. | |
156 | ||
fa6bb85a MC |
157 | EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and |
158 | EVP_MD_CTX_block_size() return the digest or block size in bytes. | |
3cbe1980 | 159 | |
625a9baf | 160 | EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(), |
684b1695 | 161 | EVP_mdc2(), EVP_ripemd160(), EVP_blake2b512(), and EVP_blake2s256() return |
208527a7 | 162 | pointers to the corresponding EVP_MD structures. |
3cbe1980 | 163 | |
4ec19e20 | 164 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() |
3cbe1980 DSH |
165 | return either an B<EVP_MD> structure or NULL if an error occurs. |
166 | ||
167 | =head1 NOTES | |
168 | ||
169 | The B<EVP> interface to message digests should almost always be used in | |
170 | preference to the low level interfaces. This is because the code then becomes | |
171 | transparent to the digest used and much more flexible. | |
172 | ||
7b3e11c5 | 173 | New applications should use the SHA2 digest algorithms such as SHA256. |
5a34fcd7 | 174 | The other digest algorithms are still in common use. |
3cbe1980 | 175 | |
e72d734d DSH |
176 | For most applications the B<impl> parameter to EVP_DigestInit_ex() will be |
177 | set to NULL to use the default digest implementation. | |
178 | ||
7b3e11c5 | 179 | The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are |
e72d734d | 180 | obsolete but are retained to maintain compatibility with existing code. New |
7b3e11c5 | 181 | applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and |
e72d734d DSH |
182 | EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context |
183 | instead of initializing and cleaning it up on each call and allow non default | |
184 | implementations of digests to be specified. | |
185 | ||
a528d4f0 | 186 | If digest contexts are not cleaned up after use |
7b3e11c5 | 187 | memory leaks will occur. |
13588350 | 188 | |
25191fff RL |
189 | EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), EVP_MD_CTX_type(), |
190 | EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as | |
191 | macros. | |
5a34fcd7 | 192 | |
52ad5b60 TS |
193 | EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration |
194 | or control. | |
5a34fcd7 | 195 | |
3cbe1980 DSH |
196 | =head1 EXAMPLE |
197 | ||
198 | This example digests the data "Test Message\n" and "Hello World\n", using the | |
199 | digest name passed on the command line. | |
200 | ||
201 | #include <stdio.h> | |
202 | #include <openssl/evp.h> | |
203 | ||
204 | main(int argc, char *argv[]) | |
205 | { | |
2947af32 BB |
206 | EVP_MD_CTX *mdctx; |
207 | const EVP_MD *md; | |
208 | char mess1[] = "Test Message\n"; | |
209 | char mess2[] = "Hello World\n"; | |
210 | unsigned char md_value[EVP_MAX_MD_SIZE]; | |
211 | int md_len, i; | |
212 | ||
213 | if (argv[1] == NULL) { | |
214 | printf("Usage: mdtest digestname\n"); | |
215 | exit(1); | |
216 | } | |
217 | ||
218 | md = EVP_get_digestbyname(argv[1]); | |
219 | if (md == NULL) { | |
220 | printf("Unknown message digest %s\n", argv[1]); | |
221 | exit(1); | |
222 | } | |
223 | ||
224 | mdctx = EVP_MD_CTX_new(); | |
225 | EVP_DigestInit_ex(mdctx, md, NULL); | |
226 | EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); | |
227 | EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); | |
228 | EVP_DigestFinal_ex(mdctx, md_value, &md_len); | |
229 | EVP_MD_CTX_free(mdctx); | |
230 | ||
231 | printf("Digest is: "); | |
232 | for (i = 0; i < md_len; i++) | |
233 | printf("%02x", md_value[i]); | |
234 | printf("\n"); | |
235 | ||
236 | exit(0); | |
3cbe1980 DSH |
237 | } |
238 | ||
3cbe1980 DSH |
239 | =head1 SEE ALSO |
240 | ||
9b86974e | 241 | L<dgst(1)>, |
b97fdb57 | 242 | L<evp(7)> |
4facdbb5 | 243 | |
3cbe1980 DSH |
244 | =head1 HISTORY |
245 | ||
25191fff RL |
246 | B<EVP_MD_CTX> became opaque in OpenSSL 1.1. Consequently, stack |
247 | allocated B<EVP_MD_CTX>s are no longer supported. | |
248 | ||
249 | EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to | |
250 | EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1. | |
251 | ||
3fa39ed7 | 252 | The link between digests and signing algorithms was fixed in OpenSSL 1.0 and |
7f572e95 DSH |
253 | later, so now EVP_sha1() can be used with RSA and DSA. The legacy EVP_dss1() |
254 | was removed in OpenSSL 1.1.0 | |
3fa39ed7 | 255 | |
e2f92610 RS |
256 | =head1 COPYRIGHT |
257 | ||
258 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
259 | ||
260 | Licensed under the OpenSSL license (the "License"). You may not use | |
261 | this file except in compliance with the License. You can obtain a copy | |
262 | in the file LICENSE in the source distribution or at | |
263 | L<https://www.openssl.org/source/license.html>. | |
264 | ||
265 | =cut |