diff options
Diffstat (limited to 'src/lib/libcrypto/doc/EVP_DigestInit.pod')
-rw-r--r-- | src/lib/libcrypto/doc/EVP_DigestInit.pod | 202 |
1 files changed, 0 insertions, 202 deletions
diff --git a/src/lib/libcrypto/doc/EVP_DigestInit.pod b/src/lib/libcrypto/doc/EVP_DigestInit.pod deleted file mode 100644 index fefc858f7e..0000000000 --- a/src/lib/libcrypto/doc/EVP_DigestInit.pod +++ /dev/null | |||
@@ -1,202 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal, EVP_MAX_MD_SIZE, | ||
6 | EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, | ||
7 | EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, | ||
8 | EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2, | ||
9 | EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - | ||
10 | EVP digest routines | ||
11 | |||
12 | =head1 SYNOPSIS | ||
13 | |||
14 | #include <openssl/evp.h> | ||
15 | |||
16 | void EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); | ||
17 | void EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); | ||
18 | void EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, | ||
19 | unsigned int *s); | ||
20 | |||
21 | #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ | ||
22 | |||
23 | int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); | ||
24 | |||
25 | #define EVP_MD_type(e) ((e)->type) | ||
26 | #define EVP_MD_pkey_type(e) ((e)->pkey_type) | ||
27 | #define EVP_MD_size(e) ((e)->md_size) | ||
28 | #define EVP_MD_block_size(e) ((e)->block_size) | ||
29 | |||
30 | #define EVP_MD_CTX_md(e) (e)->digest) | ||
31 | #define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest) | ||
32 | #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) | ||
33 | #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) | ||
34 | |||
35 | EVP_MD *EVP_md_null(void); | ||
36 | EVP_MD *EVP_md2(void); | ||
37 | EVP_MD *EVP_md5(void); | ||
38 | EVP_MD *EVP_sha(void); | ||
39 | EVP_MD *EVP_sha1(void); | ||
40 | EVP_MD *EVP_dss(void); | ||
41 | EVP_MD *EVP_dss1(void); | ||
42 | EVP_MD *EVP_mdc2(void); | ||
43 | EVP_MD *EVP_ripemd160(void); | ||
44 | |||
45 | const EVP_MD *EVP_get_digestbyname(const char *name); | ||
46 | #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) | ||
47 | #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) | ||
48 | |||
49 | =head1 DESCRIPTION | ||
50 | |||
51 | The EVP digest routines are a high level interface to message digests. | ||
52 | |||
53 | EVP_DigestInit() initializes a digest context B<ctx> to use a digest | ||
54 | B<type>: this will typically be supplied by a function such as | ||
55 | EVP_sha1(). | ||
56 | |||
57 | EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the | ||
58 | digest context B<ctx>. This function can be called several times on the | ||
59 | same B<ctx> to hash additional data. | ||
60 | |||
61 | EVP_DigestFinal() retrieves the digest value from B<ctx> and places | ||
62 | it in B<md>. If the B<s> parameter is not NULL then the number of | ||
63 | bytes of data written (i.e. the length of the digest) will be written | ||
64 | to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. | ||
65 | After calling EVP_DigestFinal() no additional calls to EVP_DigestUpdate() | ||
66 | can be made, but EVP_DigestInit() can be called to initialize a new | ||
67 | digest operation. | ||
68 | |||
69 | EVP_MD_CTX_copy() can be used to copy the message digest state from | ||
70 | B<in> to B<out>. This is useful if large amounts of data are to be | ||
71 | hashed which only differ in the last few bytes. | ||
72 | |||
73 | EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest | ||
74 | when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the | ||
75 | hash. | ||
76 | |||
77 | EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the | ||
78 | message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. | ||
79 | |||
80 | EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER | ||
81 | representing the given message digest when passed an B<EVP_MD> structure. | ||
82 | For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is | ||
83 | normally used when setting ASN1 OIDs. | ||
84 | |||
85 | EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed | ||
86 | B<EVP_MD_CTX>. | ||
87 | |||
88 | EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated | ||
89 | with this digest. For example EVP_sha1() is associated with RSA so this will | ||
90 | return B<NID_sha1WithRSAEncryption>. This "link" between digests and signature | ||
91 | algorithms may not be retained in future versions of OpenSSL. | ||
92 | |||
93 | EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160() | ||
94 | return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest | ||
95 | algorithms respectively. The associated signature algorithm is RSA in each case. | ||
96 | |||
97 | EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest | ||
98 | algorithms but using DSS (DSA) for the signature algorithm. | ||
99 | |||
100 | EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it | ||
101 | returns is of zero length. | ||
102 | |||
103 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() | ||
104 | return an B<EVP_MD> structure when passed a digest name, a digest NID or | ||
105 | an ASN1_OBJECT structure respectively. The digest table must be initialized | ||
106 | using, for example, OpenSSL_add_all_digests() for these functions to work. | ||
107 | |||
108 | =head1 RETURN VALUES | ||
109 | |||
110 | EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() do not return values. | ||
111 | |||
112 | EVP_MD_CTX_copy() returns 1 if successful or 0 for failure. | ||
113 | |||
114 | EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the | ||
115 | corresponding OBJECT IDENTIFIER or NID_undef if none exists. | ||
116 | |||
117 | EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(), | ||
118 | EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block | ||
119 | size in bytes. | ||
120 | |||
121 | EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), | ||
122 | EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the | ||
123 | corresponding EVP_MD structures. | ||
124 | |||
125 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() | ||
126 | return either an B<EVP_MD> structure or NULL if an error occurs. | ||
127 | |||
128 | =head1 NOTES | ||
129 | |||
130 | The B<EVP> interface to message digests should almost always be used in | ||
131 | preference to the low level interfaces. This is because the code then becomes | ||
132 | transparent to the digest used and much more flexible. | ||
133 | |||
134 | SHA1 is the digest of choice for new applications. The other digest algorithms | ||
135 | are still in common use. | ||
136 | |||
137 | =head1 EXAMPLE | ||
138 | |||
139 | This example digests the data "Test Message\n" and "Hello World\n", using the | ||
140 | digest name passed on the command line. | ||
141 | |||
142 | #include <stdio.h> | ||
143 | #include <openssl/evp.h> | ||
144 | |||
145 | main(int argc, char *argv[]) | ||
146 | { | ||
147 | EVP_MD_CTX mdctx; | ||
148 | const EVP_MD *md; | ||
149 | char mess1[] = "Test Message\n"; | ||
150 | char mess2[] = "Hello World\n"; | ||
151 | unsigned char md_value[EVP_MAX_MD_SIZE]; | ||
152 | int md_len, i; | ||
153 | |||
154 | OpenSSL_add_all_digests(); | ||
155 | |||
156 | if(!argv[1]) { | ||
157 | printf("Usage: mdtest digestname\n"); | ||
158 | exit(1); | ||
159 | } | ||
160 | |||
161 | md = EVP_get_digestbyname(argv[1]); | ||
162 | |||
163 | if(!md) { | ||
164 | printf("Unknown message digest %s\n", argv[1]); | ||
165 | exit(1); | ||
166 | } | ||
167 | |||
168 | EVP_DigestInit(&mdctx, md); | ||
169 | EVP_DigestUpdate(&mdctx, mess1, strlen(mess1)); | ||
170 | EVP_DigestUpdate(&mdctx, mess2, strlen(mess2)); | ||
171 | EVP_DigestFinal(&mdctx, md_value, &md_len); | ||
172 | |||
173 | printf("Digest is: "); | ||
174 | for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); | ||
175 | printf("\n"); | ||
176 | } | ||
177 | |||
178 | =head1 BUGS | ||
179 | |||
180 | Several of the functions do not return values: maybe they should. Although the | ||
181 | internal digest operations will never fail some future hardware based operations | ||
182 | might. | ||
183 | |||
184 | The link between digests and signing algorithms results in a situation where | ||
185 | EVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS | ||
186 | even though they are identical digests. | ||
187 | |||
188 | The size of an B<EVP_MD_CTX> structure is determined at compile time: this results | ||
189 | in code that must be recompiled if the size of B<EVP_MD_CTX> increases. | ||
190 | |||
191 | =head1 SEE ALSO | ||
192 | |||
193 | L<evp(3)|evp(3)>, L<HMAC(3)|HMAC(3)>, L<MD2(3)|MD2(3)>, | ||
194 | L<MD5(3)|MD5(3)>, L<MDC2(3)|MDC2(3)>, L<RIPEMD160(3)|RIPEMD160(3)>, | ||
195 | L<SHA1(3)|SHA1(3)> | ||
196 | |||
197 | =head1 HISTORY | ||
198 | |||
199 | EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are | ||
200 | available in all versions of SSLeay and OpenSSL. | ||
201 | |||
202 | =cut | ||