diff options
Diffstat (limited to 'src/lib/libcrypto/doc')
135 files changed, 0 insertions, 12469 deletions
diff --git a/src/lib/libcrypto/doc/DES_set_key.pod b/src/lib/libcrypto/doc/DES_set_key.pod deleted file mode 100644 index d1bd43c592..0000000000 --- a/src/lib/libcrypto/doc/DES_set_key.pod +++ /dev/null | |||
@@ -1,339 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, | ||
6 | DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key, | ||
7 | DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt, | ||
8 | DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt, | ||
9 | DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, | ||
10 | DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, | ||
11 | DES_ede3_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, | ||
12 | DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, | ||
13 | DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption | ||
14 | |||
15 | =head1 SYNOPSIS | ||
16 | |||
17 | #include <openssl/des.h> | ||
18 | |||
19 | void DES_random_key(DES_cblock *ret); | ||
20 | |||
21 | int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule); | ||
22 | int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule); | ||
23 | int DES_set_key_checked(const_DES_cblock *key, | ||
24 | DES_key_schedule *schedule); | ||
25 | void DES_set_key_unchecked(const_DES_cblock *key, | ||
26 | DES_key_schedule *schedule); | ||
27 | |||
28 | void DES_set_odd_parity(DES_cblock *key); | ||
29 | int DES_is_weak_key(const_DES_cblock *key); | ||
30 | |||
31 | void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output, | ||
32 | DES_key_schedule *ks, int enc); | ||
33 | void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output, | ||
34 | DES_key_schedule *ks1, DES_key_schedule *ks2, int enc); | ||
35 | void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output, | ||
36 | DES_key_schedule *ks1, DES_key_schedule *ks2, | ||
37 | DES_key_schedule *ks3, int enc); | ||
38 | |||
39 | void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output, | ||
40 | long length, DES_key_schedule *schedule, DES_cblock *ivec, | ||
41 | int enc); | ||
42 | void DES_cfb_encrypt(const unsigned char *in, unsigned char *out, | ||
43 | int numbits, long length, DES_key_schedule *schedule, | ||
44 | DES_cblock *ivec, int enc); | ||
45 | void DES_ofb_encrypt(const unsigned char *in, unsigned char *out, | ||
46 | int numbits, long length, DES_key_schedule *schedule, | ||
47 | DES_cblock *ivec); | ||
48 | void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output, | ||
49 | long length, DES_key_schedule *schedule, DES_cblock *ivec, | ||
50 | int enc); | ||
51 | void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out, | ||
52 | long length, DES_key_schedule *schedule, DES_cblock *ivec, | ||
53 | int *num, int enc); | ||
54 | void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out, | ||
55 | long length, DES_key_schedule *schedule, DES_cblock *ivec, | ||
56 | int *num); | ||
57 | |||
58 | void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output, | ||
59 | long length, DES_key_schedule *schedule, DES_cblock *ivec, | ||
60 | const_DES_cblock *inw, const_DES_cblock *outw, int enc); | ||
61 | |||
62 | void DES_ede2_cbc_encrypt(const unsigned char *input, | ||
63 | unsigned char *output, long length, DES_key_schedule *ks1, | ||
64 | DES_key_schedule *ks2, DES_cblock *ivec, int enc); | ||
65 | void DES_ede2_cfb64_encrypt(const unsigned char *in, | ||
66 | unsigned char *out, long length, DES_key_schedule *ks1, | ||
67 | DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc); | ||
68 | void DES_ede2_ofb64_encrypt(const unsigned char *in, | ||
69 | unsigned char *out, long length, DES_key_schedule *ks1, | ||
70 | DES_key_schedule *ks2, DES_cblock *ivec, int *num); | ||
71 | |||
72 | void DES_ede3_cbc_encrypt(const unsigned char *input, | ||
73 | unsigned char *output, long length, DES_key_schedule *ks1, | ||
74 | DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec, | ||
75 | int enc); | ||
76 | void DES_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out, | ||
77 | long length, DES_key_schedule *ks1, DES_key_schedule *ks2, | ||
78 | DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2, | ||
79 | int enc); | ||
80 | void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, | ||
81 | long length, DES_key_schedule *ks1, DES_key_schedule *ks2, | ||
82 | DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc); | ||
83 | void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, | ||
84 | long length, DES_key_schedule *ks1, | ||
85 | DES_key_schedule *ks2, DES_key_schedule *ks3, | ||
86 | DES_cblock *ivec, int *num); | ||
87 | |||
88 | DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output, | ||
89 | long length, DES_key_schedule *schedule, | ||
90 | const_DES_cblock *ivec); | ||
91 | DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[], | ||
92 | long length, int out_count, DES_cblock *seed); | ||
93 | void DES_string_to_key(const char *str, DES_cblock *key); | ||
94 | void DES_string_to_2keys(const char *str, DES_cblock *key1, | ||
95 | DES_cblock *key2); | ||
96 | |||
97 | char *DES_fcrypt(const char *buf, const char *salt, char *ret); | ||
98 | char *DES_crypt(const char *buf, const char *salt); | ||
99 | |||
100 | int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched, | ||
101 | DES_cblock *iv); | ||
102 | int DES_enc_write(int fd, const void *buf, int len, | ||
103 | DES_key_schedule *sched, DES_cblock *iv); | ||
104 | |||
105 | =head1 DESCRIPTION | ||
106 | |||
107 | This library contains a fast implementation of the DES encryption | ||
108 | algorithm. | ||
109 | |||
110 | There are two phases to the use of DES encryption. The first is the | ||
111 | generation of a I<DES_key_schedule> from a key, the second is the | ||
112 | actual encryption. A DES key is of type I<DES_cblock>. This type is | ||
113 | consists of 8 bytes with odd parity. The least significant bit in | ||
114 | each byte is the parity bit. The key schedule is an expanded form of | ||
115 | the key; it is used to speed the encryption process. | ||
116 | |||
117 | DES_random_key() generates a random key in odd parity. | ||
118 | |||
119 | Before a DES key can be used, it must be converted into the | ||
120 | architecture dependent I<DES_key_schedule> via the | ||
121 | DES_set_key_checked() or DES_set_key_unchecked() function. | ||
122 | |||
123 | DES_set_key_checked() will check that the key passed is of odd parity | ||
124 | and is not a week or semi-weak key. If the parity is wrong, then -1 | ||
125 | is returned. If the key is a weak key, then -2 is returned. If an | ||
126 | error is returned, the key schedule is not generated. | ||
127 | |||
128 | DES_set_key() works like | ||
129 | DES_set_key_checked() if the I<DES_check_key> flag is non-zero, | ||
130 | otherwise like DES_set_key_unchecked(). These functions are available | ||
131 | for compatibility; it is recommended to use a function that does not | ||
132 | depend on a global variable. | ||
133 | |||
134 | DES_set_odd_parity() sets the parity of the passed I<key> to odd. | ||
135 | |||
136 | DES_is_weak_key() returns 1 is the passed key is a weak key, 0 if it | ||
137 | is ok. | ||
138 | |||
139 | The following routines mostly operate on an input and output stream of | ||
140 | I<DES_cblock>s. | ||
141 | |||
142 | DES_ecb_encrypt() is the basic DES encryption routine that encrypts or | ||
143 | decrypts a single 8-byte I<DES_cblock> in I<electronic code book> | ||
144 | (ECB) mode. It always transforms the input data, pointed to by | ||
145 | I<input>, into the output data, pointed to by the I<output> argument. | ||
146 | If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input> | ||
147 | (cleartext) is encrypted in to the I<output> (ciphertext) using the | ||
148 | key_schedule specified by the I<schedule> argument, previously set via | ||
149 | I<DES_set_key>. If I<encrypt> is zero (DES_DECRYPT), the I<input> (now | ||
150 | ciphertext) is decrypted into the I<output> (now cleartext). Input | ||
151 | and output may overlap. DES_ecb_encrypt() does not return a value. | ||
152 | |||
153 | DES_ecb3_encrypt() encrypts/decrypts the I<input> block by using | ||
154 | three-key Triple-DES encryption in ECB mode. This involves encrypting | ||
155 | the input with I<ks1>, decrypting with the key schedule I<ks2>, and | ||
156 | then encrypting with I<ks3>. This routine greatly reduces the chances | ||
157 | of brute force breaking of DES and has the advantage of if I<ks1>, | ||
158 | I<ks2> and I<ks3> are the same, it is equivalent to just encryption | ||
159 | using ECB mode and I<ks1> as the key. | ||
160 | |||
161 | The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES | ||
162 | encryption by using I<ks1> for the final encryption. | ||
163 | |||
164 | DES_ncbc_encrypt() encrypts/decrypts using the I<cipher-block-chaining> | ||
165 | (CBC) mode of DES. If the I<encrypt> argument is non-zero, the | ||
166 | routine cipher-block-chain encrypts the cleartext data pointed to by | ||
167 | the I<input> argument into the ciphertext pointed to by the I<output> | ||
168 | argument, using the key schedule provided by the I<schedule> argument, | ||
169 | and initialization vector provided by the I<ivec> argument. If the | ||
170 | I<length> argument is not an integral multiple of eight bytes, the | ||
171 | last block is copied to a temporary area and zero filled. The output | ||
172 | is always an integral multiple of eight bytes. | ||
173 | |||
174 | DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses I<inw> and | ||
175 | I<outw> to 'whiten' the encryption. I<inw> and I<outw> are secret | ||
176 | (unlike the iv) and are as such, part of the key. So the key is sort | ||
177 | of 24 bytes. This is much better than CBC DES. | ||
178 | |||
179 | DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with | ||
180 | three keys. This means that each DES operation inside the CBC mode is | ||
181 | really an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL. | ||
182 | |||
183 | The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by | ||
184 | reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>. | ||
185 | This form of Triple-DES is used by the RSAREF library. | ||
186 | |||
187 | DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block | ||
188 | chaining mode used by Kerberos v4. Its parameters are the same as | ||
189 | DES_ncbc_encrypt(). | ||
190 | |||
191 | DES_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This | ||
192 | method takes an array of characters as input and outputs and array of | ||
193 | characters. It does not require any padding to 8 character groups. | ||
194 | Note: the I<ivec> variable is changed and the new changed value needs to | ||
195 | be passed to the next call to this function. Since this function runs | ||
196 | a complete DES ECB encryption per I<numbits>, this function is only | ||
197 | suggested for use when sending small numbers of characters. | ||
198 | |||
199 | DES_cfb64_encrypt() | ||
200 | implements CFB mode of DES with 64bit feedback. Why is this | ||
201 | useful you ask? Because this routine will allow you to encrypt an | ||
202 | arbitrary number of bytes, no 8 byte padding. Each call to this | ||
203 | routine will encrypt the input bytes to output and then update ivec | ||
204 | and num. num contains 'how far' we are though ivec. If this does | ||
205 | not make much sense, read more about cfb mode of DES :-). | ||
206 | |||
207 | DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as | ||
208 | DES_cfb64_encrypt() except that Triple-DES is used. | ||
209 | |||
210 | DES_ofb_encrypt() encrypts using output feedback mode. This method | ||
211 | takes an array of characters as input and outputs and array of | ||
212 | characters. It does not require any padding to 8 character groups. | ||
213 | Note: the I<ivec> variable is changed and the new changed value needs to | ||
214 | be passed to the next call to this function. Since this function runs | ||
215 | a complete DES ECB encryption per numbits, this function is only | ||
216 | suggested for use when sending small numbers of characters. | ||
217 | |||
218 | DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output | ||
219 | Feed Back mode. | ||
220 | |||
221 | DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as | ||
222 | DES_ofb64_encrypt(), using Triple-DES. | ||
223 | |||
224 | The following functions are included in the DES library for | ||
225 | compatibility with the MIT Kerberos library. | ||
226 | |||
227 | DES_cbc_cksum() produces an 8 byte checksum based on the input stream | ||
228 | (via CBC encryption). The last 4 bytes of the checksum are returned | ||
229 | and the complete 8 bytes are placed in I<output>. This function is | ||
230 | used by Kerberos v4. Other applications should use | ||
231 | L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead. | ||
232 | |||
233 | DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte | ||
234 | checksum from the input bytes. The algorithm can be iterated over the | ||
235 | input, depending on I<out_count>, 1, 2, 3 or 4 times. If I<output> is | ||
236 | non-NULL, the 8 bytes generated by each pass are written into | ||
237 | I<output>. | ||
238 | |||
239 | The following are DES-based transformations: | ||
240 | |||
241 | DES_fcrypt() is a fast version of the Unix crypt(3) function. This | ||
242 | version takes only a small amount of space relative to other fast | ||
243 | crypt() implementations. This is different to the normal crypt in | ||
244 | that the third parameter is the buffer that the return value is | ||
245 | written into. It needs to be at least 14 bytes long. This function | ||
246 | is thread safe, unlike the normal crypt. | ||
247 | |||
248 | DES_crypt() is a faster replacement for the normal system crypt(). | ||
249 | This function calls DES_fcrypt() with a static array passed as the | ||
250 | third parameter. This emulates the normal non-thread safe semantics | ||
251 | of crypt(3). | ||
252 | |||
253 | DES_enc_write() writes I<len> bytes to file descriptor I<fd> from | ||
254 | buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default) | ||
255 | using I<sched> for the key and I<iv> as a starting vector. The actual | ||
256 | data send down I<fd> consists of 4 bytes (in network byte order) | ||
257 | containing the length of the following encrypted data. The encrypted | ||
258 | data then follows, padded with random data out to a multiple of 8 | ||
259 | bytes. | ||
260 | |||
261 | DES_enc_read() is used to read I<len> bytes from file descriptor | ||
262 | I<fd> into buffer I<buf>. The data being read from I<fd> is assumed to | ||
263 | have come from DES_enc_write() and is decrypted using I<sched> for | ||
264 | the key schedule and I<iv> for the initial vector. | ||
265 | |||
266 | B<Warning:> The data format used by DES_enc_write() and DES_enc_read() | ||
267 | has a cryptographic weakness: When asked to write more than MAXWRITE | ||
268 | bytes, DES_enc_write() will split the data into several chunks that | ||
269 | are all encrypted using the same IV. So don't use these functions | ||
270 | unless you are sure you know what you do (in which case you might not | ||
271 | want to use them anyway). They cannot handle non-blocking sockets. | ||
272 | DES_enc_read() uses an internal state and thus cannot be used on | ||
273 | multiple files. | ||
274 | |||
275 | I<DES_rw_mode> is used to specify the encryption mode to use with | ||
276 | DES_enc_read() and DES_end_write(). If set to I<DES_PCBC_MODE> (the | ||
277 | default), DES_pcbc_encrypt is used. If set to I<DES_CBC_MODE> | ||
278 | DES_cbc_encrypt is used. | ||
279 | |||
280 | =head1 NOTES | ||
281 | |||
282 | Single-key DES is insecure due to its short key size. ECB mode is | ||
283 | not suitable for most applications. | ||
284 | |||
285 | The L<evp(3)|evp(3)> library provides higher-level encryption functions. | ||
286 | |||
287 | =head1 BUGS | ||
288 | |||
289 | DES_cbc_encrypt() does not modify B<ivec>; use DES_ncbc_encrypt() | ||
290 | instead. | ||
291 | |||
292 | DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits. | ||
293 | What this means is that if you set numbits to 12, and length to 2, the | ||
294 | first 12 bits will come from the 1st input byte and the low half of | ||
295 | the second input byte. The second 12 bits will have the low 8 bits | ||
296 | taken from the 3rd input byte and the top 4 bits taken from the 4th | ||
297 | input byte. The same holds for output. This function has been | ||
298 | implemented this way because most people will be using a multiple of 8 | ||
299 | and because once you get into pulling bytes input bytes apart things | ||
300 | get ugly! | ||
301 | |||
302 | DES_string_to_key() is available for backward compatibility with the | ||
303 | MIT library. New applications should use a cryptographic hash function. | ||
304 | The same applies for DES_string_to_2key(). | ||
305 | |||
306 | =head1 CONFORMING TO | ||
307 | |||
308 | ANSI X3.106 | ||
309 | |||
310 | The B<des> library was initially written to be source code compatible with | ||
311 | the MIT Kerberos library. | ||
312 | |||
313 | =head1 SEE ALSO | ||
314 | |||
315 | crypt(3), L<evp(3)|evp(3)>, L<rand(3)|rand(3)> | ||
316 | |||
317 | =head1 HISTORY | ||
318 | |||
319 | In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid | ||
320 | clashes with older versions of libdes. | ||
321 | |||
322 | DES_set_key_checked() and DES_set_key_unchecked() were added in | ||
323 | OpenSSL 0.9.5. | ||
324 | |||
325 | des_generate_random_block(), des_init_random_number_generator(), | ||
326 | des_new_random_key(), des_set_random_generator_seed() and | ||
327 | des_set_sequence_number() and des_rand_data() are used in newer | ||
328 | versions of Kerberos but are not implemented here. | ||
329 | |||
330 | DES_random_key() generated cryptographically weak random data in | ||
331 | SSLeay and in OpenSSL prior version 0.9.5, as well as in the original | ||
332 | MIT library. | ||
333 | |||
334 | =head1 AUTHOR | ||
335 | |||
336 | Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project | ||
337 | (http://www.openssl.org). | ||
338 | |||
339 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_generate_key.pod b/src/lib/libcrypto/doc/DH_generate_key.pod deleted file mode 100644 index 148e13762b..0000000000 --- a/src/lib/libcrypto/doc/DH_generate_key.pod +++ /dev/null | |||
@@ -1,51 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | int DH_generate_key(DH *dh); | ||
12 | |||
13 | int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | DH_generate_key() performs the first step of a Diffie-Hellman key | ||
18 | exchange by generating private and public DH values. By calling | ||
19 | DH_compute_key(), these are combined with the other party's public | ||
20 | value to compute the shared key. | ||
21 | |||
22 | DH_generate_key() expects B<dh> to contain the shared parameters | ||
23 | B<dh-E<gt>p> and B<dh-E<gt>g>. It generates a random private DH value | ||
24 | unless B<dh-E<gt>priv_key> is already set, and computes the | ||
25 | corresponding public value B<dh-E<gt>pub_key>, which can then be | ||
26 | published. | ||
27 | |||
28 | DH_compute_key() computes the shared secret from the private DH value | ||
29 | in B<dh> and the other party's public value in B<pub_key> and stores | ||
30 | it in B<key>. B<key> must point to B<DH_size(dh)> bytes of memory. | ||
31 | |||
32 | =head1 RETURN VALUES | ||
33 | |||
34 | DH_generate_key() returns 1 on success, 0 otherwise. | ||
35 | |||
36 | DH_compute_key() returns the size of the shared secret on success, -1 | ||
37 | on error. | ||
38 | |||
39 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
40 | |||
41 | =head1 SEE ALSO | ||
42 | |||
43 | L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, | ||
44 | L<DH_size(3)|DH_size(3)> | ||
45 | |||
46 | =head1 HISTORY | ||
47 | |||
48 | DH_generate_key() and DH_compute_key() are available in all versions | ||
49 | of SSLeay and OpenSSL. | ||
50 | |||
51 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_generate_parameters.pod b/src/lib/libcrypto/doc/DH_generate_parameters.pod deleted file mode 100644 index bd0782cb0c..0000000000 --- a/src/lib/libcrypto/doc/DH_generate_parameters.pod +++ /dev/null | |||
@@ -1,80 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_generate_parameters_ex, DH_generate_parameters, | ||
6 | DH_check - generate and check Diffie-Hellman parameters | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/dh.h> | ||
11 | |||
12 | int DH_generate_parameters_ex(DH *dh, int prime_len,int generator, BN_GENCB *cb); | ||
13 | |||
14 | int DH_check(DH *dh, int *codes); | ||
15 | |||
16 | Deprecated: | ||
17 | |||
18 | DH *DH_generate_parameters(int prime_len, int generator, | ||
19 | void (*callback)(int, int, void *), void *cb_arg); | ||
20 | |||
21 | =head1 DESCRIPTION | ||
22 | |||
23 | DH_generate_parameters_ex() generates Diffie-Hellman parameters that can | ||
24 | be shared among a group of users, and stores them in the provided B<DH> | ||
25 | structure. | ||
26 | |||
27 | B<prime_len> is the length in bits of the safe prime to be generated. | ||
28 | B<generator> is a small number E<gt> 1, typically 2 or 5. | ||
29 | |||
30 | A callback function may be used to provide feedback about the progress | ||
31 | of the key generation. If B<cb> is not B<NULL>, it will be | ||
32 | called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime number is | ||
33 | generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)> is | ||
34 | called. See L<BN_generate_prime(3)|BN_generate_prime(3)> for information on | ||
35 | the BN_GENCB_call() function. | ||
36 | |||
37 | DH_check() validates Diffie-Hellman parameters. It checks that B<p> is | ||
38 | a safe prime, and that B<g> is a suitable generator. In the case of an | ||
39 | error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or | ||
40 | DH_NOT_SUITABLE_GENERATOR are set in B<*codes>. | ||
41 | DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be | ||
42 | checked, i.e. it does not equal 2 or 5. | ||
43 | |||
44 | =head1 RETURN VALUES | ||
45 | |||
46 | DH_generate_parameters_ex() and DH_check() return 1 if the check could be | ||
47 | performed, 0 otherwise. | ||
48 | |||
49 | DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or | ||
50 | NULL if the parameter generation fails. | ||
51 | |||
52 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
53 | |||
54 | =head1 NOTES | ||
55 | |||
56 | DH_generate_parameters_ex() and DH_generate_parameters() may run for several | ||
57 | hours before finding a suitable prime. | ||
58 | |||
59 | The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters() | ||
60 | are not to be used in signature schemes. | ||
61 | |||
62 | =head1 BUGS | ||
63 | |||
64 | If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not | ||
65 | a usable generator. | ||
66 | |||
67 | =head1 SEE ALSO | ||
68 | |||
69 | L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, | ||
70 | L<DH_free(3)|DH_free(3)> | ||
71 | |||
72 | =head1 HISTORY | ||
73 | |||
74 | DH_check() is available in all versions of SSLeay and OpenSSL. | ||
75 | The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0. | ||
76 | |||
77 | In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used | ||
78 | instead of DH_CHECK_P_NOT_SAFE_PRIME. | ||
79 | |||
80 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_get_ex_new_index.pod b/src/lib/libcrypto/doc/DH_get_ex_new_index.pod deleted file mode 100644 index 934ec094bb..0000000000 --- a/src/lib/libcrypto/doc/DH_get_ex_new_index.pod +++ /dev/null | |||
@@ -1,37 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific | ||
6 | data to DH structures | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/dh.h> | ||
11 | |||
12 | int DH_get_ex_new_index(long argl, void *argp, | ||
13 | CRYPTO_EX_new *new_func, | ||
14 | CRYPTO_EX_dup *dup_func, | ||
15 | CRYPTO_EX_free *free_func); | ||
16 | |||
17 | int DH_set_ex_data(DH *d, int idx, void *arg); | ||
18 | |||
19 | char *DH_get_ex_data(DH *d, int idx); | ||
20 | |||
21 | =head1 DESCRIPTION | ||
22 | |||
23 | These functions handle application specific data in DH | ||
24 | structures. Their usage is identical to that of | ||
25 | RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() | ||
26 | as described in L<RSA_get_ex_new_index(3)>. | ||
27 | |||
28 | =head1 SEE ALSO | ||
29 | |||
30 | L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dh(3)|dh(3)> | ||
31 | |||
32 | =head1 HISTORY | ||
33 | |||
34 | DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are | ||
35 | available since OpenSSL 0.9.5. | ||
36 | |||
37 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_new.pod b/src/lib/libcrypto/doc/DH_new.pod deleted file mode 100644 index 0fdb7b9680..0000000000 --- a/src/lib/libcrypto/doc/DH_new.pod +++ /dev/null | |||
@@ -1,38 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_new, DH_free - allocate and free DH objects | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | DH* DH_new(void); | ||
12 | |||
13 | void DH_free(DH *dh); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | DH_new() allocates and initializes a B<DH> structure. | ||
18 | |||
19 | DH_free() frees the B<DH> structure and its components. The values are | ||
20 | erased before the memory is returned to the system. | ||
21 | |||
22 | =head1 RETURN VALUES | ||
23 | |||
24 | If the allocation fails, DH_new() returns B<NULL> and sets an error code that | ||
25 | can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a | ||
26 | pointer to the newly allocated structure. | ||
27 | |||
28 | =head1 SEE ALSO | ||
29 | |||
30 | L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, | ||
31 | L<DH_generate_parameters(3)|DH_generate_parameters(3)>, | ||
32 | L<DH_generate_key(3)|DH_generate_key(3)> | ||
33 | |||
34 | =head1 HISTORY | ||
35 | |||
36 | DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL. | ||
37 | |||
38 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_set_method.pod b/src/lib/libcrypto/doc/DH_set_method.pod deleted file mode 100644 index d82fe7377a..0000000000 --- a/src/lib/libcrypto/doc/DH_set_method.pod +++ /dev/null | |||
@@ -1,129 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_set_default_method, DH_get_default_method, | ||
6 | DH_set_method, DH_new_method, DH_OpenSSL, | ||
7 | DH_set_default_openssl_method, DH_get_default_openssl_method | ||
8 | - select DH method | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/dh.h> | ||
13 | #include <openssl/engine.h> | ||
14 | |||
15 | void DH_set_default_method(const DH_METHOD *meth); | ||
16 | |||
17 | const DH_METHOD *DH_get_default_method(void); | ||
18 | |||
19 | int DH_set_method(DH *dh, const DH_METHOD *meth); | ||
20 | |||
21 | DH *DH_new_method(ENGINE *engine); | ||
22 | |||
23 | const DH_METHOD *DH_OpenSSL(void); | ||
24 | |||
25 | =head1 DESCRIPTION | ||
26 | |||
27 | A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman | ||
28 | operations. By modifying the method, alternative implementations | ||
29 | such as hardware accelerators may be used. IMPORTANT: See the NOTES section for | ||
30 | important information about how these DH API functions are affected by the use | ||
31 | of B<ENGINE> API calls. | ||
32 | |||
33 | Initially, the default DH_METHOD is the OpenSSL internal implementation, as | ||
34 | returned by DH_OpenSSL(). | ||
35 | |||
36 | DH_set_default_method() makes B<meth> the default method for all DH | ||
37 | structures created later. B<NB>: This is true only whilst no ENGINE has been set | ||
38 | as a default for DH, so this function is no longer recommended. | ||
39 | |||
40 | DH_get_default_method() returns a pointer to the current default DH_METHOD. | ||
41 | However, the meaningfulness of this result is dependent on whether the ENGINE | ||
42 | API is being used, so this function is no longer recommended. | ||
43 | |||
44 | DH_set_method() selects B<meth> to perform all operations using the key B<dh>. | ||
45 | This will replace the DH_METHOD used by the DH key and if the previous method | ||
46 | was supplied by an ENGINE, the handle to that ENGINE will be released during the | ||
47 | change. It is possible to have DH keys that only work with certain DH_METHOD | ||
48 | implementations (eg. from an ENGINE module that supports embedded | ||
49 | hardware-protected keys), and in such cases attempting to change the DH_METHOD | ||
50 | for the key can have unexpected results. | ||
51 | |||
52 | DH_new_method() allocates and initializes a DH structure so that B<engine> will | ||
53 | be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH | ||
54 | operations is used, and if no default ENGINE is set, the DH_METHOD controlled by | ||
55 | DH_set_default_method() is used. | ||
56 | |||
57 | =head1 THE DH_METHOD STRUCTURE | ||
58 | |||
59 | typedef struct dh_meth_st | ||
60 | { | ||
61 | /* name of the implementation */ | ||
62 | const char *name; | ||
63 | |||
64 | /* generate private and public DH values for key agreement */ | ||
65 | int (*generate_key)(DH *dh); | ||
66 | |||
67 | /* compute shared secret */ | ||
68 | int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); | ||
69 | |||
70 | /* compute r = a ^ p mod m (May be NULL for some implementations) */ | ||
71 | int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, | ||
72 | const BIGNUM *m, BN_CTX *ctx, | ||
73 | BN_MONT_CTX *m_ctx); | ||
74 | |||
75 | /* called at DH_new */ | ||
76 | int (*init)(DH *dh); | ||
77 | |||
78 | /* called at DH_free */ | ||
79 | int (*finish)(DH *dh); | ||
80 | |||
81 | int flags; | ||
82 | |||
83 | char *app_data; /* ?? */ | ||
84 | |||
85 | } DH_METHOD; | ||
86 | |||
87 | =head1 RETURN VALUES | ||
88 | |||
89 | DH_OpenSSL() and DH_get_default_method() return pointers to the respective | ||
90 | B<DH_METHOD>s. | ||
91 | |||
92 | DH_set_method() returns non-zero if the provided B<meth> was successfully set as | ||
93 | the method for B<dh> (including unloading the ENGINE handle if the previous | ||
94 | method was supplied by an ENGINE). | ||
95 | |||
96 | DH_new_method() returns NULL and sets an error code that can be obtained by | ||
97 | L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it | ||
98 | returns a pointer to the newly allocated structure. | ||
99 | |||
100 | =head1 NOTES | ||
101 | |||
102 | As of version 0.9.7, DH_METHOD implementations are grouped together with other | ||
103 | algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a | ||
104 | default ENGINE is specified for DH functionality using an ENGINE API function, | ||
105 | that will override any DH defaults set using the DH API (ie. | ||
106 | DH_set_default_method()). For this reason, the ENGINE API is the recommended way | ||
107 | to control default implementations for use in DH and other cryptographic | ||
108 | algorithms. | ||
109 | |||
110 | =head1 SEE ALSO | ||
111 | |||
112 | L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)> | ||
113 | |||
114 | =head1 HISTORY | ||
115 | |||
116 | DH_set_default_method(), DH_get_default_method(), DH_set_method(), | ||
117 | DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4. | ||
118 | |||
119 | DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced | ||
120 | DH_set_default_method() and DH_get_default_method() respectively, and | ||
121 | DH_set_method() and DH_new_method() were altered to use B<ENGINE>s rather than | ||
122 | B<DH_METHOD>s during development of the engine version of OpenSSL 0.9.6. For | ||
123 | 0.9.7, the handling of defaults in the ENGINE API was restructured so that this | ||
124 | change was reversed, and behaviour of the other functions resembled more closely | ||
125 | the previous behaviour. The behaviour of defaults in the ENGINE API now | ||
126 | transparently overrides the behaviour of defaults in the DH API without | ||
127 | requiring changing these function prototypes. | ||
128 | |||
129 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DH_size.pod b/src/lib/libcrypto/doc/DH_size.pod deleted file mode 100644 index 97f26fda78..0000000000 --- a/src/lib/libcrypto/doc/DH_size.pod +++ /dev/null | |||
@@ -1,33 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DH_size - get Diffie-Hellman prime size | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | int DH_size(DH *dh); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | This function returns the Diffie-Hellman size in bytes. It can be used | ||
16 | to determine how much memory must be allocated for the shared secret | ||
17 | computed by DH_compute_key(). | ||
18 | |||
19 | B<dh-E<gt>p> must not be B<NULL>. | ||
20 | |||
21 | =head1 RETURN VALUE | ||
22 | |||
23 | The size in bytes. | ||
24 | |||
25 | =head1 SEE ALSO | ||
26 | |||
27 | L<dh(3)|dh(3)>, L<DH_generate_key(3)|DH_generate_key(3)> | ||
28 | |||
29 | =head1 HISTORY | ||
30 | |||
31 | DH_size() is available in all versions of SSLeay and OpenSSL. | ||
32 | |||
33 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_SIG_new.pod b/src/lib/libcrypto/doc/DSA_SIG_new.pod deleted file mode 100644 index 77aa649db0..0000000000 --- a/src/lib/libcrypto/doc/DSA_SIG_new.pod +++ /dev/null | |||
@@ -1,38 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DSA_SIG *DSA_SIG_new(void); | ||
12 | |||
13 | void DSA_SIG_free(DSA_SIG *a); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | DSA_SIG_new() allocates and initializes a B<DSA_SIG> structure. | ||
18 | |||
19 | DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The | ||
20 | values are erased before the memory is returned to the system. | ||
21 | |||
22 | =head1 RETURN VALUES | ||
23 | |||
24 | If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an | ||
25 | error code that can be obtained by | ||
26 | L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer | ||
27 | to the newly allocated structure. | ||
28 | |||
29 | =head1 SEE ALSO | ||
30 | |||
31 | L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, | ||
32 | L<DSA_do_sign(3)|DSA_do_sign(3)> | ||
33 | |||
34 | =head1 HISTORY | ||
35 | |||
36 | DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3. | ||
37 | |||
38 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_do_sign.pod b/src/lib/libcrypto/doc/DSA_do_sign.pod deleted file mode 100644 index 5dfc733b20..0000000000 --- a/src/lib/libcrypto/doc/DSA_do_sign.pod +++ /dev/null | |||
@@ -1,47 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_do_sign, DSA_do_verify - raw DSA signature operations | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); | ||
12 | |||
13 | int DSA_do_verify(const unsigned char *dgst, int dgst_len, | ||
14 | DSA_SIG *sig, DSA *dsa); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | DSA_do_sign() computes a digital signature on the B<len> byte message | ||
19 | digest B<dgst> using the private key B<dsa> and returns it in a | ||
20 | newly allocated B<DSA_SIG> structure. | ||
21 | |||
22 | L<DSA_sign_setup(3)|DSA_sign_setup(3)> may be used to precompute part | ||
23 | of the signing operation in case signature generation is | ||
24 | time-critical. | ||
25 | |||
26 | DSA_do_verify() verifies that the signature B<sig> matches a given | ||
27 | message digest B<dgst> of size B<len>. B<dsa> is the signer's public | ||
28 | key. | ||
29 | |||
30 | =head1 RETURN VALUES | ||
31 | |||
32 | DSA_do_sign() returns the signature, NULL on error. DSA_do_verify() | ||
33 | returns 1 for a valid signature, 0 for an incorrect signature and -1 | ||
34 | on error. The error codes can be obtained by | ||
35 | L<ERR_get_error(3)|ERR_get_error(3)>. | ||
36 | |||
37 | =head1 SEE ALSO | ||
38 | |||
39 | L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, | ||
40 | L<DSA_SIG_new(3)|DSA_SIG_new(3)>, | ||
41 | L<DSA_sign(3)|DSA_sign(3)> | ||
42 | |||
43 | =head1 HISTORY | ||
44 | |||
45 | DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3. | ||
46 | |||
47 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_dup_DH.pod b/src/lib/libcrypto/doc/DSA_dup_DH.pod deleted file mode 100644 index 7f6f0d1115..0000000000 --- a/src/lib/libcrypto/doc/DSA_dup_DH.pod +++ /dev/null | |||
@@ -1,36 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_dup_DH - create a DH structure out of DSA structure | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DH * DSA_dup_DH(const DSA *r); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q | ||
16 | is lost during that conversion, but the resulting DH parameters | ||
17 | contain its length. | ||
18 | |||
19 | =head1 RETURN VALUE | ||
20 | |||
21 | DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The | ||
22 | error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
23 | |||
24 | =head1 NOTE | ||
25 | |||
26 | Be careful to avoid small subgroup attacks when using this. | ||
27 | |||
28 | =head1 SEE ALSO | ||
29 | |||
30 | L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> | ||
31 | |||
32 | =head1 HISTORY | ||
33 | |||
34 | DSA_dup_DH() was added in OpenSSL 0.9.4. | ||
35 | |||
36 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_generate_key.pod b/src/lib/libcrypto/doc/DSA_generate_key.pod deleted file mode 100644 index 069a05767c..0000000000 --- a/src/lib/libcrypto/doc/DSA_generate_key.pod +++ /dev/null | |||
@@ -1,32 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_generate_key - generate DSA key pair | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | int DSA_generate_key(DSA *a); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | DSA_generate_key() expects B<a> to contain DSA parameters. It generates | ||
16 | a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>. | ||
17 | |||
18 | =head1 RETURN VALUE | ||
19 | |||
20 | DSA_generate_key() returns 1 on success, 0 otherwise. | ||
21 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
22 | |||
23 | =head1 SEE ALSO | ||
24 | |||
25 | L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, | ||
26 | L<DSA_generate_parameters(3)|DSA_generate_parameters(3)> | ||
27 | |||
28 | =head1 HISTORY | ||
29 | |||
30 | DSA_generate_key() is available since SSLeay 0.8. | ||
31 | |||
32 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_generate_parameters.pod b/src/lib/libcrypto/doc/DSA_generate_parameters.pod deleted file mode 100644 index 698b555a0e..0000000000 --- a/src/lib/libcrypto/doc/DSA_generate_parameters.pod +++ /dev/null | |||
@@ -1,122 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | int DSA_generate_parameters_ex(DSA *dsa, int bits, | ||
12 | const unsigned char *seed,int seed_len, | ||
13 | int *counter_ret, unsigned long *h_ret, BN_GENCB *cb); | ||
14 | |||
15 | Deprecated: | ||
16 | |||
17 | DSA *DSA_generate_parameters(int bits, unsigned char *seed, | ||
18 | int seed_len, int *counter_ret, unsigned long *h_ret, | ||
19 | void (*callback)(int, int, void *), void *cb_arg); | ||
20 | |||
21 | =head1 DESCRIPTION | ||
22 | |||
23 | DSA_generate_parameters_ex() generates primes p and q and a generator g | ||
24 | for use in the DSA and stores the result in B<dsa>. | ||
25 | |||
26 | B<bits> is the length of the prime to be generated; the DSS allows a | ||
27 | maximum of 1024 bits. | ||
28 | |||
29 | If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be | ||
30 | generated at random. Otherwise, the seed is used to generate | ||
31 | them. If the given seed does not yield a prime q, a new random | ||
32 | seed is chosen and placed at B<seed>. | ||
33 | |||
34 | DSA_generate_parameters_ex() places the iteration count in | ||
35 | *B<counter_ret> and a counter used for finding a generator in | ||
36 | *B<h_ret>, unless these are B<NULL>. | ||
37 | |||
38 | A callback function may be used to provide feedback about the progress | ||
39 | of the key generation. If B<cb> is not B<NULL>, it will be | ||
40 | called as shown below. For information on the BN_GENCB structure and the | ||
41 | BN_GENCB_call function discussed below, refer to | ||
42 | L<BN_generate_prime(3)|BN_generate_prime(3)>. | ||
43 | |||
44 | =over 4 | ||
45 | |||
46 | =item * | ||
47 | |||
48 | When a candidate for q is generated, B<BN_GENCB_call(cb, 0, m++)> is called | ||
49 | (m is 0 for the first candidate). | ||
50 | |||
51 | =item * | ||
52 | |||
53 | When a candidate for q has passed a test by trial division, | ||
54 | B<BN_GENCB_call(cb, 1, -1)> is called. | ||
55 | While a candidate for q is tested by Miller-Rabin primality tests, | ||
56 | B<BN_GENCB_call(cb, 1, i)> is called in the outer loop | ||
57 | (once for each witness that confirms that the candidate may be prime); | ||
58 | i is the loop counter (starting at 0). | ||
59 | |||
60 | =item * | ||
61 | |||
62 | When a prime q has been found, B<BN_GENCB_call(cb, 2, 0)> and | ||
63 | B<BN_GENCB_call(cb, 3, 0)> are called. | ||
64 | |||
65 | =item * | ||
66 | |||
67 | Before a candidate for p (other than the first) is generated and tested, | ||
68 | B<BN_GENCB_call(cb, 0, counter)> is called. | ||
69 | |||
70 | =item * | ||
71 | |||
72 | When a candidate for p has passed the test by trial division, | ||
73 | B<BN_GENCB_call(cb, 1, -1)> is called. | ||
74 | While it is tested by the Miller-Rabin primality test, | ||
75 | B<BN_GENCB_call(cb, 1, i)> is called in the outer loop | ||
76 | (once for each witness that confirms that the candidate may be prime). | ||
77 | i is the loop counter (starting at 0). | ||
78 | |||
79 | =item * | ||
80 | |||
81 | When p has been found, B<BN_GENCB_call(cb, 2, 1)> is called. | ||
82 | |||
83 | =item * | ||
84 | |||
85 | When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called. | ||
86 | |||
87 | =back | ||
88 | |||
89 | DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B<dsa> parameter is passed and | ||
90 | instead a newly allocated B<DSA> structure is returned. Additionally "old | ||
91 | style" callbacks are used instead of the newer BN_GENCB based approach. | ||
92 | Refer to L<BN_generate_prime(3)|BN_generate_prime(3)> for further information. | ||
93 | |||
94 | =head1 RETURN VALUE | ||
95 | |||
96 | DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise. | ||
97 | |||
98 | DSA_generate_parameters() returns a pointer to the DSA structure, or | ||
99 | B<NULL> if the parameter generation fails. | ||
100 | |||
101 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
102 | |||
103 | =head1 BUGS | ||
104 | |||
105 | Seed lengths E<gt> 20 are not supported. | ||
106 | |||
107 | =head1 SEE ALSO | ||
108 | |||
109 | L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, | ||
110 | L<DSA_free(3)|DSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)> | ||
111 | |||
112 | =head1 HISTORY | ||
113 | |||
114 | DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg> | ||
115 | argument was added in SSLeay 0.9.0. | ||
116 | In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called | ||
117 | in the inner loop of the Miller-Rabin test whenever it reached the | ||
118 | squaring step (the parameters to B<callback> did not reveal how many | ||
119 | witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)> | ||
120 | is called as in BN_is_prime(3), i.e. once for each witness. | ||
121 | |||
122 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod b/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod deleted file mode 100644 index e2fcabf370..0000000000 --- a/src/lib/libcrypto/doc/DSA_get_ex_new_index.pod +++ /dev/null | |||
@@ -1,37 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application | ||
6 | specific data to DSA structures | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/dsa.h> | ||
11 | |||
12 | int DSA_get_ex_new_index(long argl, void *argp, | ||
13 | CRYPTO_EX_new *new_func, | ||
14 | CRYPTO_EX_dup *dup_func, | ||
15 | CRYPTO_EX_free *free_func); | ||
16 | |||
17 | int DSA_set_ex_data(DSA *d, int idx, void *arg); | ||
18 | |||
19 | char *DSA_get_ex_data(DSA *d, int idx); | ||
20 | |||
21 | =head1 DESCRIPTION | ||
22 | |||
23 | These functions handle application specific data in DSA | ||
24 | structures. Their usage is identical to that of | ||
25 | RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() | ||
26 | as described in L<RSA_get_ex_new_index(3)>. | ||
27 | |||
28 | =head1 SEE ALSO | ||
29 | |||
30 | L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dsa(3)|dsa(3)> | ||
31 | |||
32 | =head1 HISTORY | ||
33 | |||
34 | DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are | ||
35 | available since OpenSSL 0.9.5. | ||
36 | |||
37 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_new.pod b/src/lib/libcrypto/doc/DSA_new.pod deleted file mode 100644 index e1e30b9a07..0000000000 --- a/src/lib/libcrypto/doc/DSA_new.pod +++ /dev/null | |||
@@ -1,40 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_new, DSA_free - allocate and free DSA objects | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | DSA* DSA_new(void); | ||
12 | |||
13 | void DSA_free(DSA *dsa); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to | ||
18 | calling DSA_new_method(NULL). | ||
19 | |||
20 | DSA_free() frees the B<DSA> structure and its components. The values are | ||
21 | erased before the memory is returned to the system. | ||
22 | |||
23 | =head1 RETURN VALUES | ||
24 | |||
25 | If the allocation fails, DSA_new() returns B<NULL> and sets an error | ||
26 | code that can be obtained by | ||
27 | L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer | ||
28 | to the newly allocated structure. | ||
29 | |||
30 | =head1 SEE ALSO | ||
31 | |||
32 | L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, | ||
33 | L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, | ||
34 | L<DSA_generate_key(3)|DSA_generate_key(3)> | ||
35 | |||
36 | =head1 HISTORY | ||
37 | |||
38 | DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL. | ||
39 | |||
40 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_set_method.pod b/src/lib/libcrypto/doc/DSA_set_method.pod deleted file mode 100644 index bc57a3e8e2..0000000000 --- a/src/lib/libcrypto/doc/DSA_set_method.pod +++ /dev/null | |||
@@ -1,143 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_set_default_method, DSA_get_default_method, | ||
6 | DSA_set_method, DSA_new_method, DSA_OpenSSL, | ||
7 | DSA_set_default_openssl_method, DSA_get_default_openssl_method | ||
8 | - select DSA method | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/dsa.h> | ||
13 | #include <openssl/engine.h> | ||
14 | |||
15 | void DSA_set_default_method(const DSA_METHOD *meth); | ||
16 | |||
17 | const DSA_METHOD *DSA_get_default_method(void); | ||
18 | |||
19 | int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); | ||
20 | |||
21 | DSA *DSA_new_method(ENGINE *engine); | ||
22 | |||
23 | DSA_METHOD *DSA_OpenSSL(void); | ||
24 | |||
25 | =head1 DESCRIPTION | ||
26 | |||
27 | A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA | ||
28 | operations. By modifying the method, alternative implementations | ||
29 | such as hardware accelerators may be used. IMPORTANT: See the NOTES section for | ||
30 | important information about how these DSA API functions are affected by the use | ||
31 | of B<ENGINE> API calls. | ||
32 | |||
33 | Initially, the default DSA_METHOD is the OpenSSL internal implementation, | ||
34 | as returned by DSA_OpenSSL(). | ||
35 | |||
36 | DSA_set_default_method() makes B<meth> the default method for all DSA | ||
37 | structures created later. B<NB>: This is true only whilst no ENGINE has | ||
38 | been set as a default for DSA, so this function is no longer recommended. | ||
39 | |||
40 | DSA_get_default_method() returns a pointer to the current default | ||
41 | DSA_METHOD. However, the meaningfulness of this result is dependent on | ||
42 | whether the ENGINE API is being used, so this function is no longer | ||
43 | recommended. | ||
44 | |||
45 | DSA_set_method() selects B<meth> to perform all operations using the key | ||
46 | B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the | ||
47 | previous method was supplied by an ENGINE, the handle to that ENGINE will | ||
48 | be released during the change. It is possible to have DSA keys that only | ||
49 | work with certain DSA_METHOD implementations (eg. from an ENGINE module | ||
50 | that supports embedded hardware-protected keys), and in such cases | ||
51 | attempting to change the DSA_METHOD for the key can have unexpected | ||
52 | results. | ||
53 | |||
54 | DSA_new_method() allocates and initializes a DSA structure so that B<engine> | ||
55 | will be used for the DSA operations. If B<engine> is NULL, the default engine | ||
56 | for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD | ||
57 | controlled by DSA_set_default_method() is used. | ||
58 | |||
59 | =head1 THE DSA_METHOD STRUCTURE | ||
60 | |||
61 | struct | ||
62 | { | ||
63 | /* name of the implementation */ | ||
64 | const char *name; | ||
65 | |||
66 | /* sign */ | ||
67 | DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, | ||
68 | DSA *dsa); | ||
69 | |||
70 | /* pre-compute k^-1 and r */ | ||
71 | int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, | ||
72 | BIGNUM **rp); | ||
73 | |||
74 | /* verify */ | ||
75 | int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, | ||
76 | DSA_SIG *sig, DSA *dsa); | ||
77 | |||
78 | /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some | ||
79 | implementations) */ | ||
80 | int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, | ||
81 | BIGNUM *a2, BIGNUM *p2, BIGNUM *m, | ||
82 | BN_CTX *ctx, BN_MONT_CTX *in_mont); | ||
83 | |||
84 | /* compute r = a ^ p mod m (May be NULL for some implementations) */ | ||
85 | int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, | ||
86 | const BIGNUM *p, const BIGNUM *m, | ||
87 | BN_CTX *ctx, BN_MONT_CTX *m_ctx); | ||
88 | |||
89 | /* called at DSA_new */ | ||
90 | int (*init)(DSA *DSA); | ||
91 | |||
92 | /* called at DSA_free */ | ||
93 | int (*finish)(DSA *DSA); | ||
94 | |||
95 | int flags; | ||
96 | |||
97 | char *app_data; /* ?? */ | ||
98 | |||
99 | } DSA_METHOD; | ||
100 | |||
101 | =head1 RETURN VALUES | ||
102 | |||
103 | DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective | ||
104 | B<DSA_METHOD>s. | ||
105 | |||
106 | DSA_set_method() returns non-zero if the provided B<meth> was successfully set | ||
107 | as the method for B<dsa> (including unloading the ENGINE handle if the previous | ||
108 | method was supplied by an ENGINE). | ||
109 | |||
110 | DSA_new_method() returns NULL and sets an error code that can be | ||
111 | obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation | ||
112 | fails. Otherwise it returns a pointer to the newly allocated structure. | ||
113 | |||
114 | =head1 NOTES | ||
115 | |||
116 | As of version 0.9.7, DSA_METHOD implementations are grouped together with other | ||
117 | algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a | ||
118 | default ENGINE is specified for DSA functionality using an ENGINE API function, | ||
119 | that will override any DSA defaults set using the DSA API (ie. | ||
120 | DSA_set_default_method()). For this reason, the ENGINE API is the recommended | ||
121 | way to control default implementations for use in DSA and other cryptographic | ||
122 | algorithms. | ||
123 | |||
124 | =head1 SEE ALSO | ||
125 | |||
126 | L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)> | ||
127 | |||
128 | =head1 HISTORY | ||
129 | |||
130 | DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), | ||
131 | DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4. | ||
132 | |||
133 | DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced | ||
134 | DSA_set_default_method() and DSA_get_default_method() respectively, and | ||
135 | DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s rather than | ||
136 | B<DSA_METHOD>s during development of the engine version of OpenSSL 0.9.6. For | ||
137 | 0.9.7, the handling of defaults in the ENGINE API was restructured so that this | ||
138 | change was reversed, and behaviour of the other functions resembled more closely | ||
139 | the previous behaviour. The behaviour of defaults in the ENGINE API now | ||
140 | transparently overrides the behaviour of defaults in the DSA API without | ||
141 | requiring changing these function prototypes. | ||
142 | |||
143 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_sign.pod b/src/lib/libcrypto/doc/DSA_sign.pod deleted file mode 100644 index 4e78a71390..0000000000 --- a/src/lib/libcrypto/doc/DSA_sign.pod +++ /dev/null | |||
@@ -1,63 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | int DSA_sign(int type, const unsigned char *dgst, int len, | ||
12 | unsigned char *sigret, unsigned int *siglen, DSA *dsa); | ||
13 | |||
14 | int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, | ||
15 | BIGNUM **rp); | ||
16 | |||
17 | int DSA_verify(int type, const unsigned char *dgst, int len, | ||
18 | unsigned char *sigbuf, int siglen, DSA *dsa); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | DSA_sign() computes a digital signature on the B<len> byte message | ||
23 | digest B<dgst> using the private key B<dsa> and places its ASN.1 DER | ||
24 | encoding at B<sigret>. The length of the signature is places in | ||
25 | *B<siglen>. B<sigret> must point to DSA_size(B<dsa>) bytes of memory. | ||
26 | |||
27 | DSA_sign_setup() may be used to precompute part of the signing | ||
28 | operation in case signature generation is time-critical. It expects | ||
29 | B<dsa> to contain DSA parameters. It places the precomputed values | ||
30 | in newly allocated B<BIGNUM>s at *B<kinvp> and *B<rp>, after freeing | ||
31 | the old ones unless *B<kinvp> and *B<rp> are NULL. These values may | ||
32 | be passed to DSA_sign() in B<dsa-E<gt>kinv> and B<dsa-E<gt>r>. | ||
33 | B<ctx> is a pre-allocated B<BN_CTX> or NULL. | ||
34 | |||
35 | DSA_verify() verifies that the signature B<sigbuf> of size B<siglen> | ||
36 | matches a given message digest B<dgst> of size B<len>. | ||
37 | B<dsa> is the signer's public key. | ||
38 | |||
39 | The B<type> parameter is ignored. | ||
40 | |||
41 | =head1 RETURN VALUES | ||
42 | |||
43 | DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. | ||
44 | DSA_verify() returns 1 for a valid signature, 0 for an incorrect | ||
45 | signature and -1 on error. The error codes can be obtained by | ||
46 | L<ERR_get_error(3)|ERR_get_error(3)>. | ||
47 | |||
48 | =head1 CONFORMING TO | ||
49 | |||
50 | US Federal Information Processing Standard FIPS 186 (Digital Signature | ||
51 | Standard, DSS), ANSI X9.30 | ||
52 | |||
53 | =head1 SEE ALSO | ||
54 | |||
55 | L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, | ||
56 | L<DSA_do_sign(3)|DSA_do_sign(3)> | ||
57 | |||
58 | =head1 HISTORY | ||
59 | |||
60 | DSA_sign() and DSA_verify() are available in all versions of SSLeay. | ||
61 | DSA_sign_setup() was added in SSLeay 0.8. | ||
62 | |||
63 | =cut | ||
diff --git a/src/lib/libcrypto/doc/DSA_size.pod b/src/lib/libcrypto/doc/DSA_size.pod deleted file mode 100644 index ba4f650361..0000000000 --- a/src/lib/libcrypto/doc/DSA_size.pod +++ /dev/null | |||
@@ -1,33 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | DSA_size - get DSA signature size | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | |||
11 | int DSA_size(const DSA *dsa); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | This function returns the size of an ASN.1 encoded DSA signature in | ||
16 | bytes. It can be used to determine how much memory must be allocated | ||
17 | for a DSA signature. | ||
18 | |||
19 | B<dsa-E<gt>q> must not be B<NULL>. | ||
20 | |||
21 | =head1 RETURN VALUE | ||
22 | |||
23 | The size in bytes. | ||
24 | |||
25 | =head1 SEE ALSO | ||
26 | |||
27 | L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)> | ||
28 | |||
29 | =head1 HISTORY | ||
30 | |||
31 | DSA_size() is available in all versions of SSLeay and OpenSSL. | ||
32 | |||
33 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EC_GFp_simple_method.pod b/src/lib/libcrypto/doc/EC_GFp_simple_method.pod deleted file mode 100644 index aff20ac175..0000000000 --- a/src/lib/libcrypto/doc/EC_GFp_simple_method.pod +++ /dev/null | |||
@@ -1,60 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining B<EC_METHOD> objects. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | |||
11 | const EC_METHOD *EC_GFp_simple_method(void); | ||
12 | const EC_METHOD *EC_GFp_mont_method(void); | ||
13 | const EC_METHOD *EC_GFp_nist_method(void); | ||
14 | const EC_METHOD *EC_GFp_nistp224_method(void); | ||
15 | const EC_METHOD *EC_GFp_nistp256_method(void); | ||
16 | const EC_METHOD *EC_GFp_nistp521_method(void); | ||
17 | |||
18 | const EC_METHOD *EC_GF2m_simple_method(void); | ||
19 | |||
20 | int EC_METHOD_get_field_type(const EC_METHOD *meth); | ||
21 | |||
22 | =head1 DESCRIPTION | ||
23 | |||
24 | The Elliptic Curve library provides a number of different implementations through a single common interface. | ||
25 | When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)|EC_GROUP_new(3)>) an | ||
26 | implementation method must be provided. The functions described here all return a const pointer to an | ||
27 | B<EC_METHOD> structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation | ||
28 | type for the form of curve selected is used. | ||
29 | |||
30 | For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method. | ||
31 | |||
32 | For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All | ||
33 | other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the | ||
34 | use of montgomery multiplication (see L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>). EC_GFp_nist_method | ||
35 | offers an implementation optimised for use with NIST recommended curves (NIST curves are available through | ||
36 | EC_GROUP_new_by_curve_name as described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>). | ||
37 | |||
38 | The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit | ||
39 | optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these | ||
40 | implementations are not available on all platforms. | ||
41 | |||
42 | EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either | ||
43 | F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is | ||
44 | F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the | ||
45 | obj_mac.h header file. | ||
46 | |||
47 | =head1 RETURN VALUES | ||
48 | |||
49 | All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure. | ||
50 | |||
51 | EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports. | ||
52 | |||
53 | =head1 SEE ALSO | ||
54 | |||
55 | L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, | ||
56 | L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, | ||
57 | L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>, | ||
58 | L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> | ||
59 | |||
60 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EC_GROUP_copy.pod b/src/lib/libcrypto/doc/EC_GROUP_copy.pod deleted file mode 100644 index d4896af1d5..0000000000 --- a/src/lib/libcrypto/doc/EC_GROUP_copy.pod +++ /dev/null | |||
@@ -1,174 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis - Functions for manipulating B<EC_GROUP> objects. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | #include <openssl/bn.h> | ||
11 | |||
12 | int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); | ||
13 | EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); | ||
14 | |||
15 | const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); | ||
16 | |||
17 | int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); | ||
18 | const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); | ||
19 | |||
20 | int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); | ||
21 | int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); | ||
22 | |||
23 | void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); | ||
24 | int EC_GROUP_get_curve_name(const EC_GROUP *group); | ||
25 | |||
26 | void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); | ||
27 | int EC_GROUP_get_asn1_flag(const EC_GROUP *group); | ||
28 | |||
29 | void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); | ||
30 | point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); | ||
31 | |||
32 | unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); | ||
33 | size_t EC_GROUP_get_seed_len(const EC_GROUP *); | ||
34 | size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); | ||
35 | |||
36 | int EC_GROUP_get_degree(const EC_GROUP *group); | ||
37 | |||
38 | int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); | ||
39 | |||
40 | int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); | ||
41 | |||
42 | int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); | ||
43 | |||
44 | int EC_GROUP_get_basis_type(const EC_GROUP *); | ||
45 | int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); | ||
46 | int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, | ||
47 | unsigned int *k2, unsigned int *k3); | ||
48 | |||
49 | =head1 DESCRIPTION | ||
50 | |||
51 | EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD. | ||
52 | |||
53 | EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created | ||
54 | EC_GROUP object. | ||
55 | |||
56 | EC_GROUP_method_of obtains the EC_METHOD of B<group>. | ||
57 | |||
58 | EC_GROUP_set_generator sets curve paramaters that must be agreed by all participants using the curve. These | ||
59 | paramaters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the | ||
60 | curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and | ||
61 | n-1 where n is the B<order>. The B<order> multipied by the B<cofactor> gives the number of points on the curve. | ||
62 | |||
63 | EC_GROUP_get0_generator returns the generator for the identified B<group>. | ||
64 | |||
65 | The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters | ||
66 | with the respective order and cofactors for the B<group>. | ||
67 | |||
68 | The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively | ||
69 | (see L<EC_GROUP_new(3)|EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name | ||
70 | will return 0. | ||
71 | |||
72 | The asn1_flag value on a curve is used to determine whether there is a specific ASN1 OID to describe the curve or not. | ||
73 | If the asn1_flag is 1 then this is a named curve with an associated ASN1 OID. If not then asn1_flag is 0. The functions | ||
74 | EC_GROUP_get_asn1_flag and EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. If set then | ||
75 | the curve_name must also be set. | ||
76 | |||
77 | The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). | ||
78 | point_conversion_form_t is an enum defined as follows: | ||
79 | |||
80 | typedef enum { | ||
81 | /** the point is encoded as z||x, where the octet z specifies | ||
82 | * which solution of the quadratic equation y is */ | ||
83 | POINT_CONVERSION_COMPRESSED = 2, | ||
84 | /** the point is encoded as z||x||y, where z is the octet 0x02 */ | ||
85 | POINT_CONVERSION_UNCOMPRESSED = 4, | ||
86 | /** the point is encoded as z||x||y, where the octet z specifies | ||
87 | * which solution of the quadratic equation y is */ | ||
88 | POINT_CONVERSION_HYBRID = 6 | ||
89 | } point_conversion_form_t; | ||
90 | |||
91 | |||
92 | For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by | ||
93 | the octets for x, followed by the octets for y. | ||
94 | |||
95 | For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For | ||
96 | POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of | ||
97 | the two possible solutions for y has been used, followed by the octets for x. | ||
98 | |||
99 | For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two | ||
100 | possible solutions for y has been used, followed by the octets for x, followed by the octets for y. | ||
101 | |||
102 | The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form | ||
103 | for the curve respectively. | ||
104 | |||
105 | ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages | ||
106 | in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it. | ||
107 | If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library | ||
108 | does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block | ||
109 | containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the | ||
110 | builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using | ||
111 | EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use | ||
112 | this seed value, although it will be preserved in any ASN1 based communications. | ||
113 | |||
114 | EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be | ||
115 | the value m. | ||
116 | |||
117 | The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid. | ||
118 | For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is | ||
119 | simply b. In either case for the curve to be valid the discriminant must be non zero. | ||
120 | |||
121 | The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include | ||
122 | verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has | ||
123 | the correct order. | ||
124 | |||
125 | EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not. | ||
126 | |||
127 | The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves | ||
128 | defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial | ||
129 | function f(x). This function is either a trinomial of the form: | ||
130 | |||
131 | f(x) = x^m + x^k + 1 with m > k >= 1 | ||
132 | |||
133 | or a pentanomial of the form: | ||
134 | |||
135 | f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1 | ||
136 | |||
137 | The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The | ||
138 | function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly | ||
139 | the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>, | ||
140 | B<k2> and B<k3> respectively. | ||
141 | |||
142 | =head1 RETURN VALUES | ||
143 | |||
144 | The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check, | ||
145 | EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis. | ||
146 | |||
147 | EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error. | ||
148 | |||
149 | EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error. | ||
150 | |||
151 | EC_GROUP_get0_generator returns the generator for the given curve or NULL on error. | ||
152 | |||
153 | EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form | ||
154 | and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the | ||
155 | specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0. | ||
156 | |||
157 | EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not | ||
158 | specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified. | ||
159 | |||
160 | EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is | ||
161 | 0, the return value will be 1. On error 0 is returned. | ||
162 | |||
163 | EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error. | ||
164 | |||
165 | EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a | ||
166 | trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned. | ||
167 | |||
168 | =head1 SEE ALSO | ||
169 | |||
170 | L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, | ||
171 | L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, | ||
172 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> | ||
173 | |||
174 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EC_GROUP_new.pod b/src/lib/libcrypto/doc/EC_GROUP_new.pod deleted file mode 100644 index 9ab3566e65..0000000000 --- a/src/lib/libcrypto/doc/EC_GROUP_new.pod +++ /dev/null | |||
@@ -1,95 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves - Functions for creating and destroying B<EC_GROUP> objects. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | #include <openssl/bn.h> | ||
11 | |||
12 | EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); | ||
13 | void EC_GROUP_free(EC_GROUP *group); | ||
14 | void EC_GROUP_clear_free(EC_GROUP *group); | ||
15 | |||
16 | EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
17 | EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
18 | EC_GROUP *EC_GROUP_new_by_curve_name(int nid); | ||
19 | |||
20 | int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
21 | int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
22 | int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
23 | int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
24 | |||
25 | size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); | ||
26 | |||
27 | =head1 DESCRIPTION | ||
28 | |||
29 | Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the | ||
30 | prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised | ||
31 | elliptic curve equation as follows: | ||
32 | |||
33 | y^2 mod p = x^3 +ax + b mod p | ||
34 | |||
35 | The second form is those defined over a binary field F2^m where the elements of the field are integers of length at | ||
36 | most m bits. For this form the elliptic curve equation is modified to: | ||
37 | |||
38 | y^2 + xy = x^3 + ax^2 + b (where b != 0) | ||
39 | |||
40 | Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL | ||
41 | use a trinomial or a pentanomial for this parameter. | ||
42 | |||
43 | A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see | ||
44 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or | ||
45 | EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively. | ||
46 | |||
47 | EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>. | ||
48 | EC_group_get_curve_GFp obtains the previously set curve parameters. | ||
49 | |||
50 | EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<p> represents | ||
51 | the irreducible polynomial - each bit represents a term in the polynomial. Therefore there will either be three | ||
52 | or five bits set dependent on whether the polynomial is a trinomial or a pentanomial. | ||
53 | EC_group_get_curve_GF2m obtains the previously set curve parameters. | ||
54 | |||
55 | The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the | ||
56 | appropriate EC_group_set_curve function. An appropriate default implementation method will be used. | ||
57 | |||
58 | Whilst the library can be used to create any curve using the functions described above, there are also a number of | ||
59 | predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function | ||
60 | EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function | ||
61 | will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of | ||
62 | curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be | ||
63 | provided. The return value is the total number of curves available (whether that number has been populated in B<r> or | ||
64 | not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available. | ||
65 | The EC_builtin_curve structure is defined as follows: | ||
66 | |||
67 | typedef struct { | ||
68 | int nid; | ||
69 | const char *comment; | ||
70 | } EC_builtin_curve; | ||
71 | |||
72 | Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve. | ||
73 | |||
74 | In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to | ||
75 | be constructed. | ||
76 | |||
77 | EC_GROUP_free frees the memory associated with the EC_GROUP. | ||
78 | |||
79 | EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. | ||
80 | |||
81 | =head1 RETURN VALUES | ||
82 | |||
83 | All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error. | ||
84 | |||
85 | EC_get_builtin_curves returns the number of builtin curves that are available. | ||
86 | |||
87 | EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error. | ||
88 | |||
89 | =head1 SEE ALSO | ||
90 | |||
91 | L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, | ||
92 | L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, | ||
93 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> | ||
94 | |||
95 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EC_KEY_new.pod b/src/lib/libcrypto/doc/EC_KEY_new.pod deleted file mode 100644 index 02d7bac82c..0000000000 --- a/src/lib/libcrypto/doc/EC_KEY_new.pod +++ /dev/null | |||
@@ -1,115 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_get_key_method_data, EC_KEY_insert_key_method_data, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates - Functions for creating, destroying and manipulating B<EC_KEY> objects. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | #include <openssl/bn.h> | ||
11 | |||
12 | EC_KEY *EC_KEY_new(void); | ||
13 | int EC_KEY_get_flags(const EC_KEY *key); | ||
14 | void EC_KEY_set_flags(EC_KEY *key, int flags); | ||
15 | void EC_KEY_clear_flags(EC_KEY *key, int flags); | ||
16 | EC_KEY *EC_KEY_new_by_curve_name(int nid); | ||
17 | void EC_KEY_free(EC_KEY *key); | ||
18 | EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); | ||
19 | EC_KEY *EC_KEY_dup(const EC_KEY *src); | ||
20 | int EC_KEY_up_ref(EC_KEY *key); | ||
21 | const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); | ||
22 | int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); | ||
23 | const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); | ||
24 | int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); | ||
25 | const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); | ||
26 | int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); | ||
27 | unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); | ||
28 | void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); | ||
29 | point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); | ||
30 | void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); | ||
31 | void *EC_KEY_get_key_method_data(EC_KEY *key, | ||
32 | void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); | ||
33 | void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, | ||
34 | void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); | ||
35 | void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); | ||
36 | int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); | ||
37 | int EC_KEY_generate_key(EC_KEY *key); | ||
38 | int EC_KEY_check_key(const EC_KEY *key); | ||
39 | int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); | ||
40 | |||
41 | =head1 DESCRIPTION | ||
42 | |||
43 | An EC_KEY represents a public key and (optionally) an associated private key. A new EC_KEY (with no associated curve) can be constructed by calling EC_KEY_new. | ||
44 | The reference count for the newly created EC_KEY is initially set to 1. A curve can be associated with the EC_KEY by calling | ||
45 | EC_KEY_set_group. | ||
46 | |||
47 | Alternatively a new EC_KEY can be constructed by calling EC_KEY_new_by_curve_name and supplying the nid of the associated curve. Refer to L<EC_GROUP_new(3)|EC_GROUP_new(3)> for a description of curve names. This function simply wraps calls to EC_KEY_new and | ||
48 | EC_GROUP_new_by_curve_name. | ||
49 | |||
50 | Calling EC_KEY_free decrements the reference count for the EC_KEY object, and if it has dropped to zero then frees the memory associated | ||
51 | with it. | ||
52 | |||
53 | EC_KEY_copy copies the contents of the EC_KEY in B<src> into B<dest>. | ||
54 | |||
55 | EC_KEY_dup creates a new EC_KEY object and copies B<ec_key> into it. | ||
56 | |||
57 | EC_KEY_up_ref increments the reference count associated with the EC_KEY object. | ||
58 | |||
59 | EC_KEY_generate_key generates a new public and private key for the supplied B<eckey> object. B<eckey> must have an EC_GROUP object | ||
60 | associated with it before calling this function. The private key is a random integer (0 < priv_key < order, where order is the order | ||
61 | of the EC_GROUP object). The public key is an EC_POINT on the curve calculated by multiplying the generator for the curve by the | ||
62 | private key. | ||
63 | |||
64 | EC_KEY_check_key performs various sanity checks on the EC_KEY object to confirm that it is valid. | ||
65 | |||
66 | EC_KEY_set_public_key_affine_coordinates sets the public key for B<key> based on its affine co-ordinates, i.e. it constructs an EC_POINT | ||
67 | object based on the supplied B<x> and B<y> values and sets the public key to be this EC_POINT. It will also performs certain sanity checks | ||
68 | on the key to confirm that it is valid. | ||
69 | |||
70 | The functions EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, and EC_KEY_set_public_key get and set the EC_GROUP object, the private key and the EC_POINT public key for the B<key> respectively. | ||
71 | |||
72 | The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the value of the encoding flags for the B<key>. There are two encoding | ||
73 | flags currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags define the behaviour of how the B<key> is | ||
74 | converted into ASN1 in a call to i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for the curve are not encoded | ||
75 | along with the private key. If EC_PKEY_NO_PUBKEY is set then the public key is not encoded along with the private key. | ||
76 | |||
77 | The functions EC_KEY_get_conv_form and EC_KEY_set_conv_form get and set the point_conversion_form for the B<key>. For a description | ||
78 | of point_conversion_forms please refer to L<EC_POINT_new(3)|EC_POINT_new(3)>. | ||
79 | |||
80 | EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitrary additional data specific to the | ||
81 | elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B<data> parameter, which must have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted. | ||
82 | |||
83 | EC_KEY_set_flags sets the flags in the B<flags> parameter on the EC_KEY object. Any flags that are already set are left set. The currently defined standard flags are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH and is defined in ecdh.h. EC_KEY_get_flags returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags clears the flags indicated by the B<flags> parameter. All other flags are left in their existing state. | ||
84 | |||
85 | EC_KEY_set_asn1_flag sets the asn1_flag on the underlying EC_GROUP object (if set). Refer to L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for further information on the asn1_flag. | ||
86 | |||
87 | EC_KEY_precompute_mult stores multiples of the underlying EC_GROUP generator for faster point multiplication. See also L<EC_POINT_add(3)|EC_POINT_add(3)>. | ||
88 | |||
89 | |||
90 | =head1 RETURN VALUES | ||
91 | |||
92 | EC_KEY_new, EC_KEY_new_by_curve_name and EC_KEY_dup return a pointer to the newly created EC_KEY object, or NULL on error. | ||
93 | |||
94 | EC_KEY_get_flags returns the flags associated with the EC_KEY object as an integer. | ||
95 | |||
96 | EC_KEY_copy returns a pointer to the destination key, or NULL on error. | ||
97 | |||
98 | EC_KEY_up_ref, EC_KEY_set_group, EC_KEY_set_private_key, EC_KEY_set_public_key, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key and EC_KEY_set_public_key_affine_coordinates return 1 on success or 0 on error. | ||
99 | |||
100 | EC_KEY_get0_group returns the EC_GROUP associated with the EC_KEY. | ||
101 | |||
102 | EC_KEY_get0_private_key returns the private key associated with the EC_KEY. | ||
103 | |||
104 | EC_KEY_get_enc_flags returns the value of the current encoding flags for the EC_KEY. | ||
105 | |||
106 | EC_KEY_get_conv_form return the point_conversion_form for the EC_KEY. | ||
107 | |||
108 | |||
109 | =head1 SEE ALSO | ||
110 | |||
111 | L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, | ||
112 | L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, | ||
113 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> | ||
114 | |||
115 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EC_POINT_add.pod b/src/lib/libcrypto/doc/EC_POINT_add.pod deleted file mode 100644 index ae92640843..0000000000 --- a/src/lib/libcrypto/doc/EC_POINT_add.pod +++ /dev/null | |||
@@ -1,72 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on B<EC_POINT> objects. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | #include <openssl/bn.h> | ||
11 | |||
12 | int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); | ||
13 | int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); | ||
14 | int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); | ||
15 | int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); | ||
16 | int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); | ||
17 | int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); | ||
18 | int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); | ||
19 | int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); | ||
20 | int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); | ||
21 | int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); | ||
22 | int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); | ||
23 | int EC_GROUP_have_precompute_mult(const EC_GROUP *group); | ||
24 | |||
25 | |||
26 | =head1 DESCRIPTION | ||
27 | |||
28 | EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the | ||
29 | result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>. | ||
30 | |||
31 | EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>. | ||
32 | |||
33 | The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not. | ||
34 | |||
35 | EC_POINT_is_on_curve tests whether the supplied point is on the curve or not. | ||
36 | |||
37 | EC_POINT_cmp compares the two supplied points and tests whether or not they are equal. | ||
38 | |||
39 | The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine | ||
40 | co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be | ||
41 | forced. | ||
42 | |||
43 | EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>. The value B<n> may be NULL in which case the result is just B<q> * B<m>. | ||
44 | |||
45 | EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value | ||
46 | B<n> may be NULL. | ||
47 | |||
48 | The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst | ||
49 | EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for information | ||
50 | about the generator. | ||
51 | |||
52 | |||
53 | =head1 RETURN VALUES | ||
54 | |||
55 | The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine, | ||
56 | EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult. | ||
57 | |||
58 | EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise. | ||
59 | |||
60 | EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error. | ||
61 | |||
62 | EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error. | ||
63 | |||
64 | EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not. | ||
65 | |||
66 | =head1 SEE ALSO | ||
67 | |||
68 | L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, | ||
69 | L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, | ||
70 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> | ||
71 | |||
72 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EC_POINT_new.pod b/src/lib/libcrypto/doc/EC_POINT_new.pod deleted file mode 100644 index b41ca0ed0c..0000000000 --- a/src/lib/libcrypto/doc/EC_POINT_new.pod +++ /dev/null | |||
@@ -1,123 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating B<EC_POINT> objects. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | #include <openssl/bn.h> | ||
11 | |||
12 | EC_POINT *EC_POINT_new(const EC_GROUP *group); | ||
13 | void EC_POINT_free(EC_POINT *point); | ||
14 | void EC_POINT_clear_free(EC_POINT *point); | ||
15 | int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); | ||
16 | EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); | ||
17 | const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); | ||
18 | int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); | ||
19 | int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, | ||
20 | const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); | ||
21 | int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, | ||
22 | const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); | ||
23 | int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, | ||
24 | const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); | ||
25 | int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, | ||
26 | const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | ||
27 | int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, | ||
28 | const BIGNUM *x, int y_bit, BN_CTX *ctx); | ||
29 | int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, | ||
30 | const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); | ||
31 | int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, | ||
32 | const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | ||
33 | int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, | ||
34 | const BIGNUM *x, int y_bit, BN_CTX *ctx); | ||
35 | size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, | ||
36 | point_conversion_form_t form, | ||
37 | unsigned char *buf, size_t len, BN_CTX *ctx); | ||
38 | int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, | ||
39 | const unsigned char *buf, size_t len, BN_CTX *ctx); | ||
40 | BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, | ||
41 | point_conversion_form_t form, BIGNUM *, BN_CTX *); | ||
42 | EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, | ||
43 | EC_POINT *, BN_CTX *); | ||
44 | char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, | ||
45 | point_conversion_form_t form, BN_CTX *); | ||
46 | EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, | ||
47 | EC_POINT *, BN_CTX *); | ||
48 | |||
49 | |||
50 | =head1 DESCRIPTION | ||
51 | |||
52 | An EC_POINT represents a point on a curve. A new point is constructed by calling the function EC_POINT_new and providing the B<group> | ||
53 | object that the point relates to. | ||
54 | |||
55 | EC_POINT_free frees the memory associated with the EC_POINT. | ||
56 | |||
57 | EC_POINT_clear_free destroys any sensitive data held within the EC_POINT and then frees its memory. | ||
58 | |||
59 | EC_POINT_copy copies the point B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD. | ||
60 | |||
61 | EC_POINT_dup creates a new EC_POINT object and copies the content from B<src> to the newly created | ||
62 | EC_POINT object. | ||
63 | |||
64 | EC_POINT_method_of obtains the EC_METHOD associated with B<point>. | ||
65 | |||
66 | A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity. | ||
67 | |||
68 | The affine co-ordinates for a point describe a point in terms of its x and y position. The functions | ||
69 | EC_POINT_set_affine_coordinates_GFp and EC_POINT_set_affine_coordinates_GF2m set the B<x> and B<y> co-ordinates for the point | ||
70 | B<p> defined over the curve given in B<group>. | ||
71 | |||
72 | As well as the affine co-ordinates, a point can alternatively be described in terms of its Jacobian | ||
73 | projective co-ordinates (for Fp curves only). Jacobian projective co-ordinates are expressed as three values x, y and z. Working in | ||
74 | this co-ordinate system provides more efficient point multiplication operations. | ||
75 | A mapping exists between Jacobian projective co-ordinates and affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian projective to affine co-ordinates is simple. The co-ordinate (x, y) is | ||
76 | mapped to (x, y, 1). To set or get the projective co-ordinates use EC_POINT_set_Jprojective_coordinates_GFp and | ||
77 | EC_POINT_get_Jprojective_coordinates_GFp respectively. | ||
78 | |||
79 | Points can also be described in terms of their compressed co-ordinates. For a point (x, y), for any given value for x such that the point is | ||
80 | on the curve there will only ever be two possible values for y. Therefore a point can be set using the EC_POINT_set_compressed_coordinates_GFp | ||
81 | and EC_POINT_set_compressed_coordinates_GF2m functions where B<x> is the x co-ordinate and B<y_bit> is a value 0 or 1 to identify which of | ||
82 | the two possible values for y should be used. | ||
83 | |||
84 | In addition EC_POINTs can be converted to and from various external representations. Supported representations are octet strings, BIGNUMs and hexadecimal. The format of the external representation is described by the point_conversion_form. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for | ||
85 | a description of point_conversion_form. Octet strings are stored in a buffer along with an associated buffer length. A point held in a BIGNUM is calculated by converting the point to an octet string and then converting that octet string into a BIGNUM integer. Points in hexadecimal format are stored in a NULL terminated character string where each character is one of the printable values 0-9 or A-F (or a-f). | ||
86 | |||
87 | The functions EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex and EC_POINT_hex2point convert | ||
88 | from and to EC_POINTs for the formats: octet string, BIGNUM and hexadecimal respectively. | ||
89 | |||
90 | The function EC_POINT_point2oct must be supplied with a buffer long enough to store the octet string. The return value provides the number of | ||
91 | octets stored. Calling the function with a NULL buffer will not perform the conversion but will still return the required buffer length. | ||
92 | |||
93 | The function EC_POINT_point2hex will allocate sufficient memory to store the hexadecimal string. It is the caller's responsibility to free | ||
94 | this memory with a subsequent call to free(). | ||
95 | |||
96 | =head1 RETURN VALUES | ||
97 | |||
98 | EC_POINT_new and EC_POINT_dup return the newly allocated EC_POINT or NULL on error. | ||
99 | |||
100 | The following functions return 1 on success or 0 on error: EC_POINT_copy, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates_GFp, | ||
101 | EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, | ||
102 | EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, | ||
103 | EC_POINT_set_compressed_coordinates_GF2m and EC_POINT_oct2point. | ||
104 | |||
105 | EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT. | ||
106 | |||
107 | EC_POINT_point2oct returns the length of the required buffer, or 0 on error. | ||
108 | |||
109 | EC_POINT_point2bn returns the pointer to the BIGNUM supplied, or NULL on error. | ||
110 | |||
111 | EC_POINT_bn2point returns the pointer to the EC_POINT supplied, or NULL on error. | ||
112 | |||
113 | EC_POINT_point2hex returns a pointer to the hex string, or NULL on error. | ||
114 | |||
115 | EC_POINT_hex2point returns the pointer to the EC_POINT supplied, or NULL on error. | ||
116 | |||
117 | =head1 SEE ALSO | ||
118 | |||
119 | L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, | ||
120 | L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, | ||
121 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> | ||
122 | |||
123 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR.pod b/src/lib/libcrypto/doc/ERR.pod deleted file mode 100644 index 343a9b84c2..0000000000 --- a/src/lib/libcrypto/doc/ERR.pod +++ /dev/null | |||
@@ -1,185 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR - error codes | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | unsigned long ERR_get_error(void); | ||
12 | unsigned long ERR_peek_error(void); | ||
13 | unsigned long ERR_get_error_line(const char **file, int *line); | ||
14 | unsigned long ERR_peek_error_line(const char **file, int *line); | ||
15 | unsigned long ERR_get_error_line_data(const char **file, int *line, | ||
16 | const char **data, int *flags); | ||
17 | unsigned long ERR_peek_error_line_data(const char **file, int *line, | ||
18 | const char **data, int *flags); | ||
19 | |||
20 | int ERR_GET_LIB(unsigned long e); | ||
21 | int ERR_GET_FUNC(unsigned long e); | ||
22 | int ERR_GET_REASON(unsigned long e); | ||
23 | |||
24 | void ERR_clear_error(void); | ||
25 | |||
26 | char *ERR_error_string(unsigned long e, char *buf); | ||
27 | const char *ERR_lib_error_string(unsigned long e); | ||
28 | const char *ERR_func_error_string(unsigned long e); | ||
29 | const char *ERR_reason_error_string(unsigned long e); | ||
30 | |||
31 | void ERR_print_errors(BIO *bp); | ||
32 | void ERR_print_errors_fp(FILE *fp); | ||
33 | |||
34 | void ERR_load_crypto_strings(void); | ||
35 | void ERR_free_strings(void); | ||
36 | |||
37 | void ERR_remove_state(unsigned long pid); | ||
38 | |||
39 | void ERR_put_error(int lib, int func, int reason, const char *file, | ||
40 | int line); | ||
41 | void ERR_add_error_data(int num, ...); | ||
42 | |||
43 | void ERR_load_strings(int lib,ERR_STRING_DATA str[]); | ||
44 | unsigned long ERR_PACK(int lib, int func, int reason); | ||
45 | int ERR_get_next_error_library(void); | ||
46 | |||
47 | =head1 DESCRIPTION | ||
48 | |||
49 | When a call to the OpenSSL library fails, this is usually signalled | ||
50 | by the return value, and an error code is stored in an error queue | ||
51 | associated with the current thread. The B<err> library provides | ||
52 | functions to obtain these error codes and textual error messages. | ||
53 | |||
54 | The L<ERR_get_error(3)|ERR_get_error(3)> manpage describes how to | ||
55 | access error codes. | ||
56 | |||
57 | Error codes contain information about where the error occurred, and | ||
58 | what went wrong. L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> describes how to | ||
59 | extract this information. A method to obtain human-readable error | ||
60 | messages is described in L<ERR_error_string(3)|ERR_error_string(3)>. | ||
61 | |||
62 | L<ERR_clear_error(3)|ERR_clear_error(3)> can be used to clear the | ||
63 | error queue. | ||
64 | |||
65 | Note that L<ERR_remove_state(3)|ERR_remove_state(3)> should be used to | ||
66 | avoid memory leaks when threads are terminated. | ||
67 | |||
68 | =head1 ADDING NEW ERROR CODES TO OPENSSL | ||
69 | |||
70 | See L<ERR_put_error(3)> if you want to record error codes in the | ||
71 | OpenSSL error system from within your application. | ||
72 | |||
73 | The remainder of this section is of interest only if you want to add | ||
74 | new error codes to OpenSSL or add error codes from external libraries. | ||
75 | |||
76 | =head2 Reporting errors | ||
77 | |||
78 | Each sub-library has a specific macro XXXerr() that is used to report | ||
79 | errors. Its first argument is a function code B<XXX_F_...>, the second | ||
80 | argument is a reason code B<XXX_R_...>. Function codes are derived | ||
81 | from the function names; reason codes consist of textual error | ||
82 | descriptions. For example, the function ssl23_read() reports a | ||
83 | "handshake failure" as follows: | ||
84 | |||
85 | SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); | ||
86 | |||
87 | Function and reason codes should consist of upper case characters, | ||
88 | numbers and underscores only. The error file generation script translates | ||
89 | function codes into function names by looking in the header files | ||
90 | for an appropriate function name, if none is found it just uses | ||
91 | the capitalized form such as "SSL23_READ" in the above example. | ||
92 | |||
93 | The trailing section of a reason code (after the "_R_") is translated | ||
94 | into lower case and underscores changed to spaces. | ||
95 | |||
96 | When you are using new function or reason codes, run B<make errors>. | ||
97 | The necessary B<#define>s will then automatically be added to the | ||
98 | sub-library's header file. | ||
99 | |||
100 | Although a library will normally report errors using its own specific | ||
101 | XXXerr macro, another library's macro can be used. This is normally | ||
102 | only done when a library wants to include ASN1 code which must use | ||
103 | the ASN1err() macro. | ||
104 | |||
105 | =head2 Adding new libraries | ||
106 | |||
107 | When adding a new sub-library to OpenSSL, assign it a library number | ||
108 | B<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its | ||
109 | name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add | ||
110 | C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function | ||
111 | (in B<crypto/err/err_all.c>). Finally, add an entry | ||
112 | |||
113 | L XXX xxx.h xxx_err.c | ||
114 | |||
115 | to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile. | ||
116 | Running B<make errors> will then generate a file B<xxx_err.c>, and | ||
117 | add all error codes used in the library to B<xxx.h>. | ||
118 | |||
119 | Additionally the library include file must have a certain form. | ||
120 | Typically it will initially look like this: | ||
121 | |||
122 | #ifndef HEADER_XXX_H | ||
123 | #define HEADER_XXX_H | ||
124 | |||
125 | #ifdef __cplusplus | ||
126 | extern "C" { | ||
127 | #endif | ||
128 | |||
129 | /* Include files */ | ||
130 | |||
131 | #include <openssl/bio.h> | ||
132 | #include <openssl/x509.h> | ||
133 | |||
134 | /* Macros, structures and function prototypes */ | ||
135 | |||
136 | |||
137 | /* BEGIN ERROR CODES */ | ||
138 | |||
139 | The B<BEGIN ERROR CODES> sequence is used by the error code | ||
140 | generation script as the point to place new error codes, any text | ||
141 | after this point will be overwritten when B<make errors> is run. | ||
142 | The closing #endif etc will be automatically added by the script. | ||
143 | |||
144 | The generated C error code file B<xxx_err.c> will load the header | ||
145 | files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the | ||
146 | header file must load any additional header files containing any | ||
147 | definitions it uses. | ||
148 | |||
149 | =head1 USING ERROR CODES IN EXTERNAL LIBRARIES | ||
150 | |||
151 | It is also possible to use OpenSSL's error code scheme in external | ||
152 | libraries. The library needs to load its own codes and call the OpenSSL | ||
153 | error code insertion script B<mkerr.pl> explicitly to add codes to | ||
154 | the header file and generate the C error code file. This will normally | ||
155 | be done if the external library needs to generate new ASN1 structures | ||
156 | but it can also be used to add more general purpose error code handling. | ||
157 | |||
158 | =head1 INTERNALS | ||
159 | |||
160 | The error queues are stored in a hash table with one B<ERR_STATE> | ||
161 | entry for each pid. ERR_get_state() returns the current thread's | ||
162 | B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> error | ||
163 | codes. When more error codes are added, the old ones are overwritten, | ||
164 | on the assumption that the most recent errors are most important. | ||
165 | |||
166 | Error strings are also stored in hash table. The hash tables can | ||
167 | be obtained by calling ERR_get_err_state_table(void) and | ||
168 | ERR_get_string_table(void) respectively. | ||
169 | |||
170 | =head1 SEE ALSO | ||
171 | |||
172 | L<CRYPTO_set_id_callback(3)|CRYPTO_set_id_callback(3)>, | ||
173 | L<CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3)>, | ||
174 | L<ERR_get_error(3)|ERR_get_error(3)>, | ||
175 | L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>, | ||
176 | L<ERR_clear_error(3)|ERR_clear_error(3)>, | ||
177 | L<ERR_error_string(3)|ERR_error_string(3)>, | ||
178 | L<ERR_print_errors(3)|ERR_print_errors(3)>, | ||
179 | L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, | ||
180 | L<ERR_remove_state(3)|ERR_remove_state(3)>, | ||
181 | L<ERR_put_error(3)|ERR_put_error(3)>, | ||
182 | L<ERR_load_strings(3)|ERR_load_strings(3)>, | ||
183 | L<SSL_get_error(3)|SSL_get_error(3)> | ||
184 | |||
185 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_GET_LIB.pod b/src/lib/libcrypto/doc/ERR_GET_LIB.pod deleted file mode 100644 index 2a129da036..0000000000 --- a/src/lib/libcrypto/doc/ERR_GET_LIB.pod +++ /dev/null | |||
@@ -1,51 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and | ||
6 | reason code | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/err.h> | ||
11 | |||
12 | int ERR_GET_LIB(unsigned long e); | ||
13 | |||
14 | int ERR_GET_FUNC(unsigned long e); | ||
15 | |||
16 | int ERR_GET_REASON(unsigned long e); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | The error code returned by ERR_get_error() consists of a library | ||
21 | number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC() | ||
22 | and ERR_GET_REASON() can be used to extract these. | ||
23 | |||
24 | The library number and function code describe where the error | ||
25 | occurred, the reason code is the information about what went wrong. | ||
26 | |||
27 | Each sub-library of OpenSSL has a unique library number; function and | ||
28 | reason codes are unique within each sub-library. Note that different | ||
29 | libraries may use the same value to signal different functions and | ||
30 | reasons. | ||
31 | |||
32 | B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally | ||
33 | unique. However, when checking for sub-library specific reason codes, | ||
34 | be sure to also compare the library number. | ||
35 | |||
36 | ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros. | ||
37 | |||
38 | =head1 RETURN VALUES | ||
39 | |||
40 | The library number, function code and reason code respectively. | ||
41 | |||
42 | =head1 SEE ALSO | ||
43 | |||
44 | L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> | ||
45 | |||
46 | =head1 HISTORY | ||
47 | |||
48 | ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in | ||
49 | all versions of SSLeay and OpenSSL. | ||
50 | |||
51 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_clear_error.pod b/src/lib/libcrypto/doc/ERR_clear_error.pod deleted file mode 100644 index 566e1f4e31..0000000000 --- a/src/lib/libcrypto/doc/ERR_clear_error.pod +++ /dev/null | |||
@@ -1,29 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_clear_error - clear the error queue | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | void ERR_clear_error(void); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | ERR_clear_error() empties the current thread's error queue. | ||
16 | |||
17 | =head1 RETURN VALUES | ||
18 | |||
19 | ERR_clear_error() has no return value. | ||
20 | |||
21 | =head1 SEE ALSO | ||
22 | |||
23 | L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> | ||
24 | |||
25 | =head1 HISTORY | ||
26 | |||
27 | ERR_clear_error() is available in all versions of SSLeay and OpenSSL. | ||
28 | |||
29 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_error_string.pod b/src/lib/libcrypto/doc/ERR_error_string.pod deleted file mode 100644 index cdfa7fe1fe..0000000000 --- a/src/lib/libcrypto/doc/ERR_error_string.pod +++ /dev/null | |||
@@ -1,73 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_error_string, ERR_error_string_n, ERR_lib_error_string, | ||
6 | ERR_func_error_string, ERR_reason_error_string - obtain human-readable | ||
7 | error message | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/err.h> | ||
12 | |||
13 | char *ERR_error_string(unsigned long e, char *buf); | ||
14 | void ERR_error_string_n(unsigned long e, char *buf, size_t len); | ||
15 | |||
16 | const char *ERR_lib_error_string(unsigned long e); | ||
17 | const char *ERR_func_error_string(unsigned long e); | ||
18 | const char *ERR_reason_error_string(unsigned long e); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | ERR_error_string() generates a human-readable string representing the | ||
23 | error code I<e>, and places it at I<buf>. I<buf> must be at least 120 | ||
24 | bytes long. If I<buf> is B<NULL>, the error string is placed in a | ||
25 | static buffer. | ||
26 | ERR_error_string_n() is a variant of ERR_error_string() that writes | ||
27 | at most I<len> characters (including the terminating 0) | ||
28 | and truncates the string if necessary. | ||
29 | For ERR_error_string_n(), I<buf> may not be B<NULL>. | ||
30 | |||
31 | The string will have the following format: | ||
32 | |||
33 | error:[error code]:[library name]:[function name]:[reason string] | ||
34 | |||
35 | I<error code> is an 8 digit hexadecimal number, I<library name>, | ||
36 | I<function name> and I<reason string> are ASCII text. | ||
37 | |||
38 | ERR_lib_error_string(), ERR_func_error_string() and | ||
39 | ERR_reason_error_string() return the library name, function | ||
40 | name and reason string respectively. | ||
41 | |||
42 | The OpenSSL error strings should be loaded by calling | ||
43 | L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL | ||
44 | applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> | ||
45 | first. | ||
46 | If there is no text string registered for the given error code, | ||
47 | the error string will contain the numeric code. | ||
48 | |||
49 | L<ERR_print_errors(3)|ERR_print_errors(3)> can be used to print | ||
50 | all error codes currently in the queue. | ||
51 | |||
52 | =head1 RETURN VALUES | ||
53 | |||
54 | ERR_error_string() returns a pointer to a static buffer containing the | ||
55 | string if I<buf> B<== NULL>, I<buf> otherwise. | ||
56 | |||
57 | ERR_lib_error_string(), ERR_func_error_string() and | ||
58 | ERR_reason_error_string() return the strings, and B<NULL> if | ||
59 | none is registered for the error code. | ||
60 | |||
61 | =head1 SEE ALSO | ||
62 | |||
63 | L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, | ||
64 | L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, | ||
65 | L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> | ||
66 | L<ERR_print_errors(3)|ERR_print_errors(3)> | ||
67 | |||
68 | =head1 HISTORY | ||
69 | |||
70 | ERR_error_string() is available in all versions of SSLeay and OpenSSL. | ||
71 | ERR_error_string_n() was added in OpenSSL 0.9.6. | ||
72 | |||
73 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_get_error.pod b/src/lib/libcrypto/doc/ERR_get_error.pod deleted file mode 100644 index 460a79f3f6..0000000000 --- a/src/lib/libcrypto/doc/ERR_get_error.pod +++ /dev/null | |||
@@ -1,79 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_get_error, ERR_peek_error, ERR_peek_last_error, | ||
6 | ERR_get_error_line, ERR_peek_error_line, ERR_peek_last_error_line, | ||
7 | ERR_get_error_line_data, ERR_peek_error_line_data, | ||
8 | ERR_peek_last_error_line_data - obtain error code and data | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/err.h> | ||
13 | |||
14 | unsigned long ERR_get_error(void); | ||
15 | unsigned long ERR_peek_error(void); | ||
16 | unsigned long ERR_peek_last_error(void); | ||
17 | |||
18 | unsigned long ERR_get_error_line(const char **file, int *line); | ||
19 | unsigned long ERR_peek_error_line(const char **file, int *line); | ||
20 | unsigned long ERR_peek_last_error_line(const char **file, int *line); | ||
21 | |||
22 | unsigned long ERR_get_error_line_data(const char **file, int *line, | ||
23 | const char **data, int *flags); | ||
24 | unsigned long ERR_peek_error_line_data(const char **file, int *line, | ||
25 | const char **data, int *flags); | ||
26 | unsigned long ERR_peek_last_error_line_data(const char **file, int *line, | ||
27 | const char **data, int *flags); | ||
28 | |||
29 | =head1 DESCRIPTION | ||
30 | |||
31 | ERR_get_error() returns the earliest error code from the thread's error | ||
32 | queue and removes the entry. This function can be called repeatedly | ||
33 | until there are no more error codes to return. | ||
34 | |||
35 | ERR_peek_error() returns the earliest error code from the thread's | ||
36 | error queue without modifying it. | ||
37 | |||
38 | ERR_peek_last_error() returns the latest error code from the thread's | ||
39 | error queue without modifying it. | ||
40 | |||
41 | See L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> for obtaining information about | ||
42 | location and reason of the error, and | ||
43 | L<ERR_error_string(3)|ERR_error_string(3)> for human-readable error | ||
44 | messages. | ||
45 | |||
46 | ERR_get_error_line(), ERR_peek_error_line() and | ||
47 | ERR_peek_last_error_line() are the same as the above, but they | ||
48 | additionally store the file name and line number where | ||
49 | the error occurred in *B<file> and *B<line>, unless these are B<NULL>. | ||
50 | |||
51 | ERR_get_error_line_data(), ERR_peek_error_line_data() and | ||
52 | ERR_peek_last_error_line_data() store additional data and flags | ||
53 | associated with the error code in *B<data> | ||
54 | and *B<flags>, unless these are B<NULL>. *B<data> contains a string | ||
55 | if *B<flags>&B<ERR_TXT_STRING> is true. | ||
56 | |||
57 | An application B<MUST NOT> free the *B<data> pointer (or any other pointers | ||
58 | returned by these functions) with free() as freeing is handled | ||
59 | automatically by the error library. | ||
60 | |||
61 | =head1 RETURN VALUES | ||
62 | |||
63 | The error code, or 0 if there is no error in the queue. | ||
64 | |||
65 | =head1 SEE ALSO | ||
66 | |||
67 | L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, | ||
68 | L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> | ||
69 | |||
70 | =head1 HISTORY | ||
71 | |||
72 | ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and | ||
73 | ERR_peek_error_line() are available in all versions of SSLeay and | ||
74 | OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data() | ||
75 | were added in SSLeay 0.9.0. | ||
76 | ERR_peek_last_error(), ERR_peek_last_error_line() and | ||
77 | ERR_peek_last_error_line_data() were added in OpenSSL 0.9.7. | ||
78 | |||
79 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_load_crypto_strings.pod b/src/lib/libcrypto/doc/ERR_load_crypto_strings.pod deleted file mode 100644 index 9bdec75a46..0000000000 --- a/src/lib/libcrypto/doc/ERR_load_crypto_strings.pod +++ /dev/null | |||
@@ -1,46 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_load_crypto_strings, SSL_load_error_strings, ERR_free_strings - | ||
6 | load and free error strings | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/err.h> | ||
11 | |||
12 | void ERR_load_crypto_strings(void); | ||
13 | void ERR_free_strings(void); | ||
14 | |||
15 | #include <openssl/ssl.h> | ||
16 | |||
17 | void SSL_load_error_strings(void); | ||
18 | |||
19 | =head1 DESCRIPTION | ||
20 | |||
21 | ERR_load_crypto_strings() registers the error strings for all | ||
22 | B<libcrypto> functions. SSL_load_error_strings() does the same, | ||
23 | but also registers the B<libssl> error strings. | ||
24 | |||
25 | One of these functions should be called before generating | ||
26 | textual error messages. However, this is not required when memory | ||
27 | usage is an issue. | ||
28 | |||
29 | ERR_free_strings() frees all previously loaded error strings. | ||
30 | |||
31 | =head1 RETURN VALUES | ||
32 | |||
33 | ERR_load_crypto_strings(), SSL_load_error_strings() and | ||
34 | ERR_free_strings() return no values. | ||
35 | |||
36 | =head1 SEE ALSO | ||
37 | |||
38 | L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)> | ||
39 | |||
40 | =head1 HISTORY | ||
41 | |||
42 | ERR_load_error_strings(), SSL_load_error_strings() and | ||
43 | ERR_free_strings() are available in all versions of SSLeay and | ||
44 | OpenSSL. | ||
45 | |||
46 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_load_strings.pod b/src/lib/libcrypto/doc/ERR_load_strings.pod deleted file mode 100644 index e9c5cf0fc5..0000000000 --- a/src/lib/libcrypto/doc/ERR_load_strings.pod +++ /dev/null | |||
@@ -1,54 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_load_strings, ERR_PACK, ERR_get_next_error_library - load | ||
6 | arbitrary error strings | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/err.h> | ||
11 | |||
12 | void ERR_load_strings(int lib, ERR_STRING_DATA str[]); | ||
13 | |||
14 | int ERR_get_next_error_library(void); | ||
15 | |||
16 | unsigned long ERR_PACK(int lib, int func, int reason); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | ERR_load_strings() registers error strings for library number B<lib>. | ||
21 | |||
22 | B<str> is an array of error string data: | ||
23 | |||
24 | typedef struct ERR_string_data_st | ||
25 | { | ||
26 | unsigned long error; | ||
27 | char *string; | ||
28 | } ERR_STRING_DATA; | ||
29 | |||
30 | The error code is generated from the library number and a function and | ||
31 | reason code: B<error> = ERR_PACK(B<lib>, B<func>, B<reason>). | ||
32 | ERR_PACK() is a macro. | ||
33 | |||
34 | The last entry in the array is {0,0}. | ||
35 | |||
36 | ERR_get_next_error_library() can be used to assign library numbers | ||
37 | to user libraries at runtime. | ||
38 | |||
39 | =head1 RETURN VALUE | ||
40 | |||
41 | ERR_PACK() return the error code. | ||
42 | ERR_get_next_error_library() returns a new library number. | ||
43 | |||
44 | =head1 SEE ALSO | ||
45 | |||
46 | L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> | ||
47 | |||
48 | =head1 HISTORY | ||
49 | |||
50 | ERR_load_error_strings() and ERR_PACK() are available in all versions | ||
51 | of SSLeay and OpenSSL. ERR_get_next_error_library() was added in | ||
52 | SSLeay 0.9.0. | ||
53 | |||
54 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_print_errors.pod b/src/lib/libcrypto/doc/ERR_print_errors.pod deleted file mode 100644 index b100a5fa2b..0000000000 --- a/src/lib/libcrypto/doc/ERR_print_errors.pod +++ /dev/null | |||
@@ -1,51 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_print_errors, ERR_print_errors_fp - print error messages | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | void ERR_print_errors(BIO *bp); | ||
12 | void ERR_print_errors_fp(FILE *fp); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | ERR_print_errors() is a convenience function that prints the error | ||
17 | strings for all errors that OpenSSL has recorded to B<bp>, thus | ||
18 | emptying the error queue. | ||
19 | |||
20 | ERR_print_errors_fp() is the same, except that the output goes to a | ||
21 | B<FILE>. | ||
22 | |||
23 | |||
24 | The error strings will have the following format: | ||
25 | |||
26 | [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message] | ||
27 | |||
28 | I<error code> is an 8 digit hexadecimal number. I<library name>, | ||
29 | I<function name> and I<reason string> are ASCII text, as is I<optional | ||
30 | text message> if one was set for the respective error code. | ||
31 | |||
32 | If there is no text string registered for the given error code, | ||
33 | the error string will contain the numeric code. | ||
34 | |||
35 | =head1 RETURN VALUES | ||
36 | |||
37 | ERR_print_errors() and ERR_print_errors_fp() return no values. | ||
38 | |||
39 | =head1 SEE ALSO | ||
40 | |||
41 | L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, | ||
42 | L<ERR_get_error(3)|ERR_get_error(3)>, | ||
43 | L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, | ||
44 | L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> | ||
45 | |||
46 | =head1 HISTORY | ||
47 | |||
48 | ERR_print_errors() and ERR_print_errors_fp() | ||
49 | are available in all versions of SSLeay and OpenSSL. | ||
50 | |||
51 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_put_error.pod b/src/lib/libcrypto/doc/ERR_put_error.pod deleted file mode 100644 index acd241fbe4..0000000000 --- a/src/lib/libcrypto/doc/ERR_put_error.pod +++ /dev/null | |||
@@ -1,44 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_put_error, ERR_add_error_data - record an error | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | void ERR_put_error(int lib, int func, int reason, const char *file, | ||
12 | int line); | ||
13 | |||
14 | void ERR_add_error_data(int num, ...); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | ERR_put_error() adds an error code to the thread's error queue. It | ||
19 | signals that the error of reason code B<reason> occurred in function | ||
20 | B<func> of library B<lib>, in line number B<line> of B<file>. | ||
21 | This function is usually called by a macro. | ||
22 | |||
23 | ERR_add_error_data() associates the concatenation of its B<num> string | ||
24 | arguments with the error code added last. | ||
25 | |||
26 | L<ERR_load_strings(3)|ERR_load_strings(3)> can be used to register | ||
27 | error strings so that the application can a generate human-readable | ||
28 | error messages for the error code. | ||
29 | |||
30 | =head1 RETURN VALUES | ||
31 | |||
32 | ERR_put_error() and ERR_add_error_data() return | ||
33 | no values. | ||
34 | |||
35 | =head1 SEE ALSO | ||
36 | |||
37 | L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> | ||
38 | |||
39 | =head1 HISTORY | ||
40 | |||
41 | ERR_put_error() is available in all versions of SSLeay and OpenSSL. | ||
42 | ERR_add_error_data() was added in SSLeay 0.9.0. | ||
43 | |||
44 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_remove_state.pod b/src/lib/libcrypto/doc/ERR_remove_state.pod deleted file mode 100644 index a4d38c17fd..0000000000 --- a/src/lib/libcrypto/doc/ERR_remove_state.pod +++ /dev/null | |||
@@ -1,45 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_remove_thread_state, ERR_remove_state - free a thread's error queue | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | void ERR_remove_thread_state(const CRYPTO_THREADID *tid); | ||
12 | |||
13 | Deprecated: | ||
14 | |||
15 | void ERR_remove_state(unsigned long pid); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | ERR_remove_thread_state() frees the error queue associated with thread B<tid>. | ||
20 | If B<tid> == B<NULL>, the current thread will have its error queue removed. | ||
21 | |||
22 | Since error queue data structures are allocated automatically for new | ||
23 | threads, they must be freed when threads are terminated in order to | ||
24 | avoid memory leaks. | ||
25 | |||
26 | ERR_remove_state is deprecated and has been replaced by | ||
27 | ERR_remove_thread_state. Since threads in OpenSSL are no longer identified | ||
28 | by unsigned long values any argument to this function is ignored. Calling | ||
29 | ERR_remove_state is equivalent to B<ERR_remove_thread_state(NULL)>. | ||
30 | |||
31 | =head1 RETURN VALUE | ||
32 | |||
33 | ERR_remove_thread_state and ERR_remove_state() return no value. | ||
34 | |||
35 | =head1 SEE ALSO | ||
36 | |||
37 | L<err(3)|err(3)> | ||
38 | |||
39 | =head1 HISTORY | ||
40 | |||
41 | ERR_remove_state() is available in all versions of SSLeay and OpenSSL. It | ||
42 | was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state was introduced | ||
43 | and thread IDs were introduced to identify threads instead of 'unsigned long'. | ||
44 | |||
45 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ERR_set_mark.pod b/src/lib/libcrypto/doc/ERR_set_mark.pod deleted file mode 100644 index d3ca4f2e77..0000000000 --- a/src/lib/libcrypto/doc/ERR_set_mark.pod +++ /dev/null | |||
@@ -1,38 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ERR_set_mark, ERR_pop_to_mark - set marks and pop errors until mark | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/err.h> | ||
10 | |||
11 | int ERR_set_mark(void); | ||
12 | |||
13 | int ERR_pop_to_mark(void); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | ERR_set_mark() sets a mark on the current topmost error record if there | ||
18 | is one. | ||
19 | |||
20 | ERR_pop_to_mark() will pop the top of the error stack until a mark is found. | ||
21 | The mark is then removed. If there is no mark, the whole stack is removed. | ||
22 | |||
23 | =head1 RETURN VALUES | ||
24 | |||
25 | ERR_set_mark() returns 0 if the error stack is empty, otherwise 1. | ||
26 | |||
27 | ERR_pop_to_mark() returns 0 if there was no mark in the error stack, which | ||
28 | implies that the stack became empty, otherwise 1. | ||
29 | |||
30 | =head1 SEE ALSO | ||
31 | |||
32 | L<err(3)|err(3)> | ||
33 | |||
34 | =head1 HISTORY | ||
35 | |||
36 | ERR_set_mark() and ERR_pop_to_mark() were added in OpenSSL 0.9.8. | ||
37 | |||
38 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_BytesToKey.pod b/src/lib/libcrypto/doc/EVP_BytesToKey.pod deleted file mode 100644 index 2dffaa1efa..0000000000 --- a/src/lib/libcrypto/doc/EVP_BytesToKey.pod +++ /dev/null | |||
@@ -1,68 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_BytesToKey - password based encryption routine | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md, | ||
12 | const unsigned char *salt, | ||
13 | const unsigned char *data, int datal, int count, | ||
14 | unsigned char *key,unsigned char *iv); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | EVP_BytesToKey() derives a key and IV from various parameters. B<type> is | ||
19 | the cipher to derive the key and IV for. B<md> is the message digest to use. | ||
20 | The B<salt> parameter is used as a salt in the derivation: it should point to | ||
21 | an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing | ||
22 | B<datal> bytes which is used to derive the keying data. B<count> is the | ||
23 | iteration count to use. The derived key and IV will be written to B<key> | ||
24 | and B<iv> respectively. | ||
25 | |||
26 | =head1 NOTES | ||
27 | |||
28 | A typical application of this function is to derive keying material for an | ||
29 | encryption algorithm from a password in the B<data> parameter. | ||
30 | |||
31 | Increasing the B<count> parameter slows down the algorithm which makes it | ||
32 | harder for an attacker to perform a brute force attack using a large number | ||
33 | of candidate passwords. | ||
34 | |||
35 | If the total key and IV length is less than the digest length and | ||
36 | B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5 | ||
37 | otherwise a non standard extension is used to derive the extra data. | ||
38 | |||
39 | Newer applications should use more standard algorithms such as PBKDF2 as | ||
40 | defined in PKCS#5v2.1 for key derivation. | ||
41 | |||
42 | =head1 KEY DERIVATION ALGORITHM | ||
43 | |||
44 | The key and IV is derived by concatenating D_1, D_2, etc until | ||
45 | enough data is available for the key and IV. D_i is defined as: | ||
46 | |||
47 | D_i = HASH^count(D_(i-1) || data || salt) | ||
48 | |||
49 | where || denotes concatenation, D_0 is empty, HASH is the digest | ||
50 | algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) | ||
51 | is HASH(HASH(data)) and so on. | ||
52 | |||
53 | The initial bytes are used for the key and the subsequent bytes for | ||
54 | the IV. | ||
55 | |||
56 | =head1 RETURN VALUES | ||
57 | |||
58 | EVP_BytesToKey() returns the size of the derived key in bytes. | ||
59 | |||
60 | =head1 SEE ALSO | ||
61 | |||
62 | L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, | ||
63 | L<PKCS5_PBKDF2_HMAC(3)|PKCS5_PBKDF2_HMAC(3)>, | ||
64 | L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> | ||
65 | |||
66 | =head1 HISTORY | ||
67 | |||
68 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_DigestInit.pod b/src/lib/libcrypto/doc/EVP_DigestInit.pod deleted file mode 100644 index c83dcc736f..0000000000 --- a/src/lib/libcrypto/doc/EVP_DigestInit.pod +++ /dev/null | |||
@@ -1,277 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate, | ||
6 | EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE, | ||
7 | EVP_MD_CTX_copy_ex, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, | ||
8 | EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, | ||
9 | EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, | ||
10 | EVP_sha1, EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_dss, EVP_dss1, | ||
11 | EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, | ||
12 | EVP_get_digestbyobj, EVP_DigestInit, EVP_DigestFinal - EVP digest routines | ||
13 | |||
14 | =head1 SYNOPSIS | ||
15 | |||
16 | #include <openssl/evp.h> | ||
17 | |||
18 | void EVP_MD_CTX_init(EVP_MD_CTX *ctx); | ||
19 | EVP_MD_CTX *EVP_MD_CTX_create(void); | ||
20 | |||
21 | int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); | ||
22 | int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); | ||
23 | int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, | ||
24 | unsigned int *s); | ||
25 | |||
26 | int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx); | ||
27 | void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); | ||
28 | |||
29 | int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); | ||
30 | |||
31 | int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); | ||
32 | int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, | ||
33 | unsigned int *s); | ||
34 | |||
35 | int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); | ||
36 | |||
37 | #define EVP_MAX_MD_SIZE 64 /* SHA512 */ | ||
38 | |||
39 | int EVP_MD_type(const EVP_MD *md); | ||
40 | int EVP_MD_pkey_type(const EVP_MD *md); | ||
41 | int EVP_MD_size(const EVP_MD *md); | ||
42 | int EVP_MD_block_size(const EVP_MD *md); | ||
43 | |||
44 | const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); | ||
45 | #define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e)) | ||
46 | #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) | ||
47 | #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) | ||
48 | |||
49 | const EVP_MD *EVP_md_null(void); | ||
50 | const EVP_MD *EVP_md2(void); | ||
51 | const EVP_MD *EVP_md5(void); | ||
52 | const EVP_MD *EVP_sha1(void); | ||
53 | const EVP_MD *EVP_dss(void); | ||
54 | const EVP_MD *EVP_dss1(void); | ||
55 | const EVP_MD *EVP_ripemd160(void); | ||
56 | |||
57 | const EVP_MD *EVP_sha224(void); | ||
58 | const EVP_MD *EVP_sha256(void); | ||
59 | const EVP_MD *EVP_sha384(void); | ||
60 | const EVP_MD *EVP_sha512(void); | ||
61 | |||
62 | const EVP_MD *EVP_get_digestbyname(const char *name); | ||
63 | #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) | ||
64 | #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) | ||
65 | |||
66 | =head1 DESCRIPTION | ||
67 | |||
68 | The EVP digest routines are a high level interface to message digests. | ||
69 | |||
70 | EVP_MD_CTX_init() initializes digest context B<ctx>. | ||
71 | |||
72 | EVP_MD_CTX_create() allocates, initializes and returns a digest context. | ||
73 | |||
74 | EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest | ||
75 | B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this | ||
76 | function. B<type> will typically be supplied by a function such as EVP_sha1(). | ||
77 | If B<impl> is NULL then the default implementation of digest B<type> is used. | ||
78 | |||
79 | EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the | ||
80 | digest context B<ctx>. This function can be called several times on the | ||
81 | same B<ctx> to hash additional data. | ||
82 | |||
83 | EVP_DigestFinal_ex() retrieves the digest value from B<ctx> and places | ||
84 | it in B<md>. If the B<s> parameter is not NULL then the number of | ||
85 | bytes of data written (i.e. the length of the digest) will be written | ||
86 | to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written. | ||
87 | After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() | ||
88 | can be made, but EVP_DigestInit_ex() can be called to initialize a new | ||
89 | digest operation. | ||
90 | |||
91 | EVP_MD_CTX_cleanup() cleans up digest context B<ctx>, it should be called | ||
92 | after a digest context is no longer needed. | ||
93 | |||
94 | EVP_MD_CTX_destroy() cleans up digest context B<ctx> and frees up the | ||
95 | space allocated to it, it should be called only on a context created | ||
96 | using EVP_MD_CTX_create(). | ||
97 | |||
98 | EVP_MD_CTX_copy_ex() can be used to copy the message digest state from | ||
99 | B<in> to B<out>. This is useful if large amounts of data are to be | ||
100 | hashed which only differ in the last few bytes. B<out> must be initialized | ||
101 | before calling this function. | ||
102 | |||
103 | EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except | ||
104 | the passed context B<ctx> does not have to be initialized, and it always | ||
105 | uses the default digest implementation. | ||
106 | |||
107 | EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest | ||
108 | context B<ctx> is automatically cleaned up. | ||
109 | |||
110 | EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination | ||
111 | B<out> does not have to be initialized. | ||
112 | |||
113 | EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest | ||
114 | when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure, i.e. the size of the | ||
115 | hash. | ||
116 | |||
117 | EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the | ||
118 | message digest when passed an B<EVP_MD> or an B<EVP_MD_CTX> structure. | ||
119 | |||
120 | EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER | ||
121 | representing the given message digest when passed an B<EVP_MD> structure. | ||
122 | For example EVP_MD_type(EVP_sha1()) returns B<NID_sha1>. This function is | ||
123 | normally used when setting ASN1 OIDs. | ||
124 | |||
125 | EVP_MD_CTX_md() returns the B<EVP_MD> structure corresponding to the passed | ||
126 | B<EVP_MD_CTX>. | ||
127 | |||
128 | EVP_MD_pkey_type() returns the NID of the public key signing algorithm | ||
129 | associated with this digest. For example EVP_sha1() is associated with RSA so | ||
130 | this will return B<NID_sha1WithRSAEncryption>. Since digests and signature | ||
131 | algorithms are no longer linked this function is only retained for | ||
132 | compatibility reasons. | ||
133 | |||
134 | EVP_md2(), EVP_md5(), EVP_sha1(), EVP_sha224(), EVP_sha256(), EVP_sha384(), | ||
135 | EVP_sha512() and EVP_ripemd160() return B<EVP_MD> structures for the MD2, MD5, | ||
136 | SHA1, SHA224, SHA256, SHA384, SHA512 and RIPEMD160 digest algorithms | ||
137 | respectively. | ||
138 | |||
139 | EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA1 digest | ||
140 | algorithms but using DSS (DSA) for the signature algorithm. Note: there is | ||
141 | no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are | ||
142 | however retained for compatibility. | ||
143 | |||
144 | EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it | ||
145 | returns is of zero length. | ||
146 | |||
147 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() | ||
148 | return an B<EVP_MD> structure when passed a digest name, a digest NID or | ||
149 | an ASN1_OBJECT structure respectively. The digest table must be initialized | ||
150 | using, for example, OpenSSL_add_all_digests() for these functions to work. | ||
151 | |||
152 | =head1 RETURN VALUES | ||
153 | |||
154 | EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for | ||
155 | success and 0 for failure. | ||
156 | |||
157 | EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure. | ||
158 | |||
159 | EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the | ||
160 | corresponding OBJECT IDENTIFIER or NID_undef if none exists. | ||
161 | |||
162 | EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and | ||
163 | EVP_MD_CTX_block_size() return the digest or block size in bytes. | ||
164 | |||
165 | EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(), EVP_dss(), | ||
166 | EVP_dss1() and EVP_ripemd160() return pointers to the | ||
167 | corresponding EVP_MD structures. | ||
168 | |||
169 | EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() | ||
170 | return either an B<EVP_MD> structure or NULL if an error occurs. | ||
171 | |||
172 | =head1 NOTES | ||
173 | |||
174 | The B<EVP> interface to message digests should almost always be used in | ||
175 | preference to the low level interfaces. This is because the code then becomes | ||
176 | transparent to the digest used and much more flexible. | ||
177 | |||
178 | New applications should use the SHA2 digest algorithms such as SHA256. | ||
179 | The other digest algorithms are still in common use. | ||
180 | |||
181 | For most applications the B<impl> parameter to EVP_DigestInit_ex() will be | ||
182 | set to NULL to use the default digest implementation. | ||
183 | |||
184 | The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are | ||
185 | obsolete but are retained to maintain compatibility with existing code. New | ||
186 | applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and | ||
187 | EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context | ||
188 | instead of initializing and cleaning it up on each call and allow non default | ||
189 | implementations of digests to be specified. | ||
190 | |||
191 | In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use | ||
192 | memory leaks will occur. | ||
193 | |||
194 | Stack allocation of EVP_MD_CTX structures is common, for example: | ||
195 | |||
196 | EVP_MD_CTX mctx; | ||
197 | EVP_MD_CTX_init(&mctx); | ||
198 | |||
199 | This will cause binary compatibility issues if the size of EVP_MD_CTX | ||
200 | structure changes (this will only happen with a major release of OpenSSL). | ||
201 | Applications wishing to avoid this should use EVP_MD_CTX_create() instead: | ||
202 | |||
203 | EVP_MD_CTX *mctx; | ||
204 | mctx = EVP_MD_CTX_create(); | ||
205 | |||
206 | |||
207 | =head1 EXAMPLE | ||
208 | |||
209 | This example digests the data "Test Message\n" and "Hello World\n", using the | ||
210 | digest name passed on the command line. | ||
211 | |||
212 | #include <stdio.h> | ||
213 | #include <openssl/evp.h> | ||
214 | |||
215 | int | ||
216 | main(int argc, char *argv[]) | ||
217 | { | ||
218 | EVP_MD_CTX *mdctx; | ||
219 | const EVP_MD *md; | ||
220 | const char mess1[] = "Test Message\n"; | ||
221 | const char mess2[] = "Hello World\n"; | ||
222 | unsigned char md_value[EVP_MAX_MD_SIZE]; | ||
223 | int md_len, i; | ||
224 | |||
225 | OpenSSL_add_all_digests(); | ||
226 | |||
227 | if (argc <= 1) { | ||
228 | printf("Usage: mdtest digestname\n"); | ||
229 | exit(1); | ||
230 | } | ||
231 | |||
232 | md = EVP_get_digestbyname(argv[1]); | ||
233 | if (md == NULL) { | ||
234 | printf("Unknown message digest %s\n", argv[1]); | ||
235 | exit(1); | ||
236 | } | ||
237 | |||
238 | mdctx = EVP_MD_CTX_create(); | ||
239 | EVP_DigestInit_ex(mdctx, md, NULL); | ||
240 | EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); | ||
241 | EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); | ||
242 | EVP_DigestFinal_ex(mdctx, md_value, &md_len); | ||
243 | EVP_MD_CTX_destroy(mdctx); | ||
244 | |||
245 | printf("Digest is: "); | ||
246 | for(i = 0; i < md_len; i++) | ||
247 | printf("%02x", md_value[i]); | ||
248 | printf("\n"); | ||
249 | } | ||
250 | |||
251 | =head1 SEE ALSO | ||
252 | |||
253 | L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, | ||
254 | L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>, | ||
255 | L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> | ||
256 | |||
257 | =head1 HISTORY | ||
258 | |||
259 | EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are | ||
260 | available in all versions of SSLeay and OpenSSL. | ||
261 | |||
262 | EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(), | ||
263 | EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex() | ||
264 | and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7. | ||
265 | |||
266 | EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(), | ||
267 | EVP_dss(), EVP_dss1() and EVP_ripemd160() were | ||
268 | changed to return truely const EVP_MD * in OpenSSL 0.9.7. | ||
269 | |||
270 | The link between digests and signing algorithms was fixed in OpenSSL 1.0 and | ||
271 | later, so now EVP_sha1() can be used with RSA and DSA, there is no need to | ||
272 | use EVP_dss1() any more. | ||
273 | |||
274 | OpenSSL 1.0 and later does not include the MD2 digest algorithm in the | ||
275 | default configuration due to its security weaknesses. | ||
276 | |||
277 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_DigestSignInit.pod b/src/lib/libcrypto/doc/EVP_DigestSignInit.pod deleted file mode 100644 index 00205d2ae9..0000000000 --- a/src/lib/libcrypto/doc/EVP_DigestSignInit.pod +++ /dev/null | |||
@@ -1,85 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing | ||
6 | functions | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, | ||
13 | const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); | ||
14 | int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); | ||
15 | int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | The EVP signature routines are a high level interface to digital signatures. | ||
20 | |||
21 | EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from | ||
22 | ENGINE B<impl> and private key B<pkey>. B<ctx> must be initialized with | ||
23 | EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the | ||
24 | EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can | ||
25 | be used to set alternative signing options. | ||
26 | |||
27 | EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the | ||
28 | signature context B<ctx>. This function can be called several times on the | ||
29 | same B<ctx> to include additional data. This function is currently implemented | ||
30 | using a macro. | ||
31 | |||
32 | EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>. | ||
33 | If B<sig> is B<NULL> then the maximum size of the output buffer is written to | ||
34 | the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the | ||
35 | B<siglen> parameter should contain the length of the B<sig> buffer, if the | ||
36 | call is successful the signature is written to B<sig> and the amount of data | ||
37 | written to B<siglen>. | ||
38 | |||
39 | =head1 RETURN VALUES | ||
40 | |||
41 | EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return | ||
42 | 1 for success and 0 or a negative value for failure. In particular a return | ||
43 | value of -2 indicates the operation is not supported by the public key | ||
44 | algorithm. | ||
45 | |||
46 | The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. | ||
47 | |||
48 | =head1 NOTES | ||
49 | |||
50 | The B<EVP> interface to digital signatures should almost always be used in | ||
51 | preference to the low level interfaces. This is because the code then becomes | ||
52 | transparent to the algorithm used and much more flexible. | ||
53 | |||
54 | In previous versions of OpenSSL there was a link between message digest types | ||
55 | and public key algorithms. This meant that "clone" digests such as EVP_dss1() | ||
56 | needed to be used to sign using SHA1 and DSA. This is no longer necessary and | ||
57 | the use of clone digest is now discouraged. | ||
58 | |||
59 | The call to EVP_DigestSignFinal() internally finalizes a copy of the digest | ||
60 | context. This means that calls to EVP_DigestSignUpdate() and | ||
61 | EVP_DigestSignFinal() can be called later to digest and sign additional data. | ||
62 | |||
63 | Since only a copy of the digest context is ever finalized the context must | ||
64 | be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak | ||
65 | will occur. | ||
66 | |||
67 | The use of EVP_PKEY_size() with these functions is discouraged because some | ||
68 | signature operations may have a signature length which depends on the | ||
69 | parameters set. As a result EVP_PKEY_size() would have to return a value | ||
70 | which indicates the maximum possible signature for any set of parameters. | ||
71 | |||
72 | =head1 SEE ALSO | ||
73 | |||
74 | L<EVP_DigestVerifyInit(3)|EVP_DigestVerifyInit(3)>, | ||
75 | L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, | ||
76 | L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, | ||
77 | L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>, | ||
78 | L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> | ||
79 | |||
80 | =head1 HISTORY | ||
81 | |||
82 | EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() | ||
83 | were first added to OpenSSL 1.0.0. | ||
84 | |||
85 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod b/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod deleted file mode 100644 index 5dcfec1837..0000000000 --- a/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod +++ /dev/null | |||
@@ -1,80 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP | ||
6 | signature verification functions | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, | ||
13 | const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); | ||
14 | int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); | ||
15 | int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t siglen); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | The EVP signature routines are a high level interface to digital signatures. | ||
20 | |||
21 | EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest | ||
22 | B<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be initialized | ||
23 | with EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the | ||
24 | EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this | ||
25 | can be used to set alternative verification options. | ||
26 | |||
27 | EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the | ||
28 | verification context B<ctx>. This function can be called several times on the | ||
29 | same B<ctx> to include additional data. This function is currently implemented | ||
30 | using a macro. | ||
31 | |||
32 | EVP_DigestVerifyFinal() verifies the data in B<ctx> against the signature in | ||
33 | B<sig> of length B<siglen>. | ||
34 | |||
35 | =head1 RETURN VALUES | ||
36 | |||
37 | EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 | ||
38 | or a negative value for failure. In particular a return value of -2 indicates | ||
39 | the operation is not supported by the public key algorithm. | ||
40 | |||
41 | Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only | ||
42 | indicates that the signature did not verify successfully (that is tbs did | ||
43 | not match the original data or the signature was of invalid form) it is not an | ||
44 | indication of a more serious error. | ||
45 | |||
46 | The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. | ||
47 | |||
48 | =head1 NOTES | ||
49 | |||
50 | The B<EVP> interface to digital signatures should almost always be used in | ||
51 | preference to the low level interfaces. This is because the code then becomes | ||
52 | transparent to the algorithm used and much more flexible. | ||
53 | |||
54 | In previous versions of OpenSSL there was a link between message digest types | ||
55 | and public key algorithms. This meant that "clone" digests such as EVP_dss1() | ||
56 | needed to be used to sign using SHA1 and DSA. This is no longer necessary and | ||
57 | the use of clone digest is now discouraged. | ||
58 | |||
59 | The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest | ||
60 | context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can | ||
61 | be called later to digest and verify additional data. | ||
62 | |||
63 | Since only a copy of the digest context is ever finalized the context must | ||
64 | be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak | ||
65 | will occur. | ||
66 | |||
67 | =head1 SEE ALSO | ||
68 | |||
69 | L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>, | ||
70 | L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, | ||
71 | L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, | ||
72 | L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>, | ||
73 | L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> | ||
74 | |||
75 | =head1 HISTORY | ||
76 | |||
77 | EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() | ||
78 | were first added to OpenSSL 1.0.0. | ||
79 | |||
80 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_EncryptInit.pod b/src/lib/libcrypto/doc/EVP_EncryptInit.pod deleted file mode 100644 index 02d02ba5f5..0000000000 --- a/src/lib/libcrypto/doc/EVP_EncryptInit.pod +++ /dev/null | |||
@@ -1,548 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate, | ||
6 | EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate, | ||
7 | EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate, | ||
8 | EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, | ||
9 | EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit, | ||
10 | EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, | ||
11 | EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname, | ||
12 | EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid, | ||
13 | EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, | ||
14 | EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, | ||
15 | EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, | ||
16 | EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data, | ||
17 | EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags, | ||
18 | EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, | ||
19 | EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb, | ||
20 | EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb, | ||
21 | EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb, | ||
22 | EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc, | ||
23 | EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, EVP_rc2_cbc, | ||
24 | EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc, | ||
25 | EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc, | ||
26 | EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, | ||
27 | EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm, | ||
28 | EVP_aes_192_ccm, EVP_aes_256_ccm, EVP_rc5_32_12_16_cbc, | ||
29 | EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_ofb | ||
30 | - EVP cipher routines | ||
31 | |||
32 | =head1 SYNOPSIS | ||
33 | |||
34 | #include <openssl/evp.h> | ||
35 | |||
36 | void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a); | ||
37 | |||
38 | int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
39 | ENGINE *impl, unsigned char *key, unsigned char *iv); | ||
40 | int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
41 | int *outl, unsigned char *in, int inl); | ||
42 | int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
43 | int *outl); | ||
44 | |||
45 | int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
46 | ENGINE *impl, unsigned char *key, unsigned char *iv); | ||
47 | int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
48 | int *outl, unsigned char *in, int inl); | ||
49 | int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, | ||
50 | int *outl); | ||
51 | |||
52 | int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
53 | ENGINE *impl, unsigned char *key, unsigned char *iv, int enc); | ||
54 | int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
55 | int *outl, unsigned char *in, int inl); | ||
56 | int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, | ||
57 | int *outl); | ||
58 | |||
59 | int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
60 | unsigned char *key, unsigned char *iv); | ||
61 | int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
62 | int *outl); | ||
63 | |||
64 | int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
65 | unsigned char *key, unsigned char *iv); | ||
66 | int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, | ||
67 | int *outl); | ||
68 | |||
69 | int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
70 | unsigned char *key, unsigned char *iv, int enc); | ||
71 | int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, | ||
72 | int *outl); | ||
73 | |||
74 | int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); | ||
75 | int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); | ||
76 | int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr); | ||
77 | int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); | ||
78 | |||
79 | const EVP_CIPHER *EVP_get_cipherbyname(const char *name); | ||
80 | #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) | ||
81 | #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) | ||
82 | |||
83 | #define EVP_CIPHER_nid(e) ((e)->nid) | ||
84 | #define EVP_CIPHER_block_size(e) ((e)->block_size) | ||
85 | #define EVP_CIPHER_key_length(e) ((e)->key_len) | ||
86 | #define EVP_CIPHER_iv_length(e) ((e)->iv_len) | ||
87 | #define EVP_CIPHER_flags(e) ((e)->flags) | ||
88 | #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE) | ||
89 | int EVP_CIPHER_type(const EVP_CIPHER *ctx); | ||
90 | |||
91 | #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) | ||
92 | #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid) | ||
93 | #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size) | ||
94 | #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len) | ||
95 | #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) | ||
96 | #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data) | ||
97 | #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d)) | ||
98 | #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) | ||
99 | #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags) | ||
100 | #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE) | ||
101 | |||
102 | int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); | ||
103 | int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); | ||
104 | |||
105 | =head1 DESCRIPTION | ||
106 | |||
107 | The EVP cipher routines are a high level interface to certain | ||
108 | symmetric ciphers. | ||
109 | |||
110 | EVP_CIPHER_CTX_init() initializes cipher context B<ctx>. | ||
111 | |||
112 | EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption | ||
113 | with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized | ||
114 | before calling this function. B<type> is normally supplied | ||
115 | by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the | ||
116 | default implementation is used. B<key> is the symmetric key to use | ||
117 | and B<iv> is the IV to use (if necessary), the actual number of bytes | ||
118 | used for the key and IV depends on the cipher. It is possible to set | ||
119 | all parameters to NULL except B<type> in an initial call and supply | ||
120 | the remaining parameters in subsequent calls, all of which have B<type> | ||
121 | set to NULL. This is done when the default cipher parameters are not | ||
122 | appropriate. | ||
123 | |||
124 | EVP_EncryptUpdate() encrypts B<inl> bytes from the buffer B<in> and | ||
125 | writes the encrypted version to B<out>. This function can be called | ||
126 | multiple times to encrypt successive blocks of data. The amount | ||
127 | of data written depends on the block alignment of the encrypted data: | ||
128 | as a result the amount of data written may be anything from zero bytes | ||
129 | to (inl + cipher_block_size - 1) so B<outl> should contain sufficient | ||
130 | room. The actual number of bytes written is placed in B<outl>. | ||
131 | |||
132 | If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts | ||
133 | the "final" data, that is any data that remains in a partial block. | ||
134 | It uses L<standard block padding|/NOTES> (aka PKCS padding). The encrypted | ||
135 | final data is written to B<out> which should have sufficient space for | ||
136 | one cipher block. The number of bytes written is placed in B<outl>. After | ||
137 | this function is called the encryption operation is finished and no further | ||
138 | calls to EVP_EncryptUpdate() should be made. | ||
139 | |||
140 | If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more | ||
141 | data and it will return an error if any data remains in a partial block: | ||
142 | that is if the total data length is not a multiple of the block size. | ||
143 | |||
144 | EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the | ||
145 | corresponding decryption operations. EVP_DecryptFinal() will return an | ||
146 | error code if padding is enabled and the final block is not correctly | ||
147 | formatted. The parameters and restrictions are identical to the encryption | ||
148 | operations except that if padding is enabled the decrypted data buffer B<out> | ||
149 | passed to EVP_DecryptUpdate() should have sufficient room for | ||
150 | (B<inl> + cipher_block_size) bytes unless the cipher block size is 1 in | ||
151 | which case B<inl> bytes is sufficient. | ||
152 | |||
153 | EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are | ||
154 | functions that can be used for decryption or encryption. The operation | ||
155 | performed depends on the value of the B<enc> parameter. It should be set | ||
156 | to 1 for encryption, 0 for decryption and -1 to leave the value unchanged | ||
157 | (the actual value of 'enc' being supplied in a previous call). | ||
158 | |||
159 | EVP_CIPHER_CTX_cleanup() clears all information from a cipher context | ||
160 | and free up any allocated memory associate with it. It should be called | ||
161 | after all operations using a cipher are complete so sensitive information | ||
162 | does not remain in memory. | ||
163 | |||
164 | EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a | ||
165 | similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and | ||
166 | EVP_CipherInit_ex() except the B<ctx> parameter does not need to be | ||
167 | initialized and they always use the default cipher implementation. | ||
168 | |||
169 | EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are | ||
170 | identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and | ||
171 | EVP_CipherFinal_ex(). In previous releases they also used to clean up | ||
172 | the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean() | ||
173 | must be called to free any context resources. | ||
174 | |||
175 | EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() | ||
176 | return an EVP_CIPHER structure when passed a cipher name, a NID or an | ||
177 | ASN1_OBJECT structure. | ||
178 | |||
179 | EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when | ||
180 | passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID | ||
181 | value is an internal value which may not have a corresponding OBJECT | ||
182 | IDENTIFIER. | ||
183 | |||
184 | EVP_CIPHER_CTX_set_padding() enables or disables padding. By default | ||
185 | encryption operations are padded using standard block padding and the | ||
186 | padding is checked and removed when decrypting. If the B<pad> parameter | ||
187 | is zero then no padding is performed, the total amount of data encrypted | ||
188 | or decrypted must then be a multiple of the block size or an error will | ||
189 | occur. | ||
190 | |||
191 | EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key | ||
192 | length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> | ||
193 | structure. The constant B<EVP_MAX_KEY_LENGTH> is the maximum key length | ||
194 | for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a | ||
195 | given cipher, the value of EVP_CIPHER_CTX_key_length() may be different | ||
196 | for variable key length ciphers. | ||
197 | |||
198 | EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx. | ||
199 | If the cipher is a fixed length cipher then attempting to set the key | ||
200 | length to any value other than the fixed value is an error. | ||
201 | |||
202 | EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV | ||
203 | length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX>. | ||
204 | It will return zero if the cipher does not use an IV. The constant | ||
205 | B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers. | ||
206 | |||
207 | EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block | ||
208 | size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> | ||
209 | structure. The constant B<EVP_MAX_IV_LENGTH> is also the maximum block | ||
210 | length for all ciphers. | ||
211 | |||
212 | EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed | ||
213 | cipher or context. This "type" is the actual NID of the cipher OBJECT | ||
214 | IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and | ||
215 | 128 bit RC2 have the same NID. If the cipher does not have an object | ||
216 | identifier or does not have ASN1 support this function will return | ||
217 | B<NID_undef>. | ||
218 | |||
219 | EVP_CIPHER_CTX_cipher() returns the B<EVP_CIPHER> structure when passed | ||
220 | an B<EVP_CIPHER_CTX> structure. | ||
221 | |||
222 | EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode: | ||
223 | EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or | ||
224 | EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then | ||
225 | EVP_CIPH_STREAM_CIPHER is returned. | ||
226 | |||
227 | EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based | ||
228 | on the passed cipher. This will typically include any parameters and an | ||
229 | IV. The cipher IV (if any) must be set when this call is made. This call | ||
230 | should be made before the cipher is actually "used" (before any | ||
231 | EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function | ||
232 | may fail if the cipher does not have any ASN1 support. | ||
233 | |||
234 | EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 | ||
235 | AlgorithmIdentifier "parameter". The precise effect depends on the cipher | ||
236 | In the case of RC2, for example, it will set the IV and effective key length. | ||
237 | This function should be called after the base cipher type is set but before | ||
238 | the key is set. For example EVP_CipherInit() will be called with the IV and | ||
239 | key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally | ||
240 | EVP_CipherInit() again with all parameters except the key set to NULL. It is | ||
241 | possible for this function to fail if the cipher does not have any ASN1 support | ||
242 | or the parameters cannot be set (for example the RC2 effective key length | ||
243 | is not supported. | ||
244 | |||
245 | EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined | ||
246 | and set. Currently only the RC2 effective key length and the number of rounds of | ||
247 | RC5 can be set. | ||
248 | |||
249 | =head1 RETURN VALUES | ||
250 | |||
251 | EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex() | ||
252 | return 1 for success and 0 for failure. | ||
253 | |||
254 | EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for | ||
255 | failure. EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for | ||
256 | success. | ||
257 | |||
258 | EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for | ||
259 | failure. EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for | ||
260 | success. | ||
261 | |||
262 | EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure. | ||
263 | |||
264 | EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() | ||
265 | return an B<EVP_CIPHER> structure or NULL on error. | ||
266 | |||
267 | EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID. | ||
268 | |||
269 | EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block | ||
270 | size. | ||
271 | |||
272 | EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key | ||
273 | length. | ||
274 | |||
275 | EVP_CIPHER_CTX_set_padding() always returns 1. | ||
276 | |||
277 | EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV | ||
278 | length or zero if the cipher does not use an IV. | ||
279 | |||
280 | EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's | ||
281 | OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. | ||
282 | |||
283 | EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure. | ||
284 | |||
285 | EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for | ||
286 | success or zero for failure. | ||
287 | |||
288 | =head1 CIPHER LISTING | ||
289 | |||
290 | All algorithms have a fixed key length unless otherwise stated. | ||
291 | |||
292 | =over 4 | ||
293 | |||
294 | =item EVP_enc_null(void) | ||
295 | |||
296 | Null cipher: does nothing. | ||
297 | |||
298 | =item EVP_aes_128_cbc(void), EVP_aes_128_ecb(void), EVP_aes_128_cfb(void), EVP_aes_128_ofb(void) | ||
299 | |||
300 | 128-bit AES in CBC, ECB, CFB and OFB modes respectively. | ||
301 | |||
302 | =item EVP_aes_192_cbc(void), EVP_aes_192_ecb(void), EVP_aes_192_cfb(void), EVP_aes_192_ofb(void) | ||
303 | |||
304 | 192-bit AES in CBC, ECB, CFB and OFB modes respectively. | ||
305 | |||
306 | =item EVP_aes_256_cbc(void), EVP_aes_256_ecb(void), EVP_aes_256_cfb(void), EVP_aes_256_ofb(void) | ||
307 | |||
308 | 256-bit AES in CBC, ECB, CFB and OFB modes respectively. | ||
309 | |||
310 | =item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void) | ||
311 | |||
312 | DES in CBC, ECB, CFB and OFB modes respectively. | ||
313 | |||
314 | =item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), | ||
315 | EVP_des_ede_cfb(void) | ||
316 | |||
317 | Two key triple DES in CBC, ECB, CFB and OFB modes respectively. | ||
318 | |||
319 | =item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), | ||
320 | EVP_des_ede3_cfb(void) | ||
321 | |||
322 | Three key triple DES in CBC, ECB, CFB and OFB modes respectively. | ||
323 | |||
324 | =item EVP_desx_cbc(void) | ||
325 | |||
326 | DESX algorithm in CBC mode. | ||
327 | |||
328 | =item EVP_rc4(void) | ||
329 | |||
330 | RC4 stream cipher. This is a variable key length cipher with default key length | ||
331 | 128 bits. | ||
332 | |||
333 | =item EVP_rc4_40(void) | ||
334 | |||
335 | RC4 stream cipher with 40 bit key length. This is obsolete and new code should | ||
336 | use EVP_rc4() and the EVP_CIPHER_CTX_set_key_length() function. | ||
337 | |||
338 | =item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), | ||
339 | EVP_idea_ofb(void), EVP_idea_cbc(void) | ||
340 | |||
341 | IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. | ||
342 | |||
343 | =item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void) | ||
344 | |||
345 | RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a | ||
346 | variable key length cipher with an additional parameter called "effective key | ||
347 | bits" or "effective key length". By default both are set to 128 bits. | ||
348 | |||
349 | =item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void) | ||
350 | |||
351 | RC2 algorithm in CBC mode with a default key length and effective key length of | ||
352 | 40 and 64 bits. These are obsolete and new code should use EVP_rc2_cbc(), | ||
353 | EVP_CIPHER_CTX_set_key_length() and EVP_CIPHER_CTX_ctrl() to set the key length | ||
354 | and effective key length. | ||
355 | |||
356 | =item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void); | ||
357 | |||
358 | Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This | ||
359 | is a variable key length cipher. | ||
360 | |||
361 | =item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), | ||
362 | EVP_cast5_ofb(void) | ||
363 | |||
364 | CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is | ||
365 | a variable key length cipher. | ||
366 | |||
367 | =item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), | ||
368 | EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void) | ||
369 | |||
370 | RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a | ||
371 | variable key length cipher with an additional "number of rounds" parameter. By | ||
372 | default the key length is set to 128 bits and 12 rounds. | ||
373 | |||
374 | =back | ||
375 | |||
376 | =head1 NOTES | ||
377 | |||
378 | Where possible the B<EVP> interface to symmetric ciphers should be used in | ||
379 | preference to the low level interfaces. This is because the code then becomes | ||
380 | transparent to the cipher used and much more flexible. | ||
381 | |||
382 | PKCS padding works by adding B<n> padding bytes of value B<n> to make the total | ||
383 | length of the encrypted data a multiple of the block size. Padding is always | ||
384 | added so if the data is already a multiple of the block size B<n> will equal | ||
385 | the block size. For example if the block size is 8 and 11 bytes are to be | ||
386 | encrypted then 5 padding bytes of value 5 will be added. | ||
387 | |||
388 | When decrypting the final block is checked to see if it has the correct form. | ||
389 | |||
390 | Although the decryption operation can produce an error if padding is enabled, | ||
391 | it is not a strong test that the input data or key is correct. A random block | ||
392 | has better than 1 in 256 chance of being of the correct format and problems with | ||
393 | the input data earlier on will not produce a final decrypt error. | ||
394 | |||
395 | If padding is disabled then the decryption operation will always succeed if | ||
396 | the total amount of data decrypted is a multiple of the block size. | ||
397 | |||
398 | The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(), | ||
399 | EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for | ||
400 | compatibility with existing code. New code should use EVP_EncryptInit_ex(), | ||
401 | EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), | ||
402 | EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an | ||
403 | existing context without allocating and freeing it up on each call. | ||
404 | |||
405 | =head1 BUGS | ||
406 | |||
407 | For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is | ||
408 | a limitation of the current RC5 code rather than the EVP interface. | ||
409 | |||
410 | EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with | ||
411 | default key lengths. If custom ciphers exceed these values the results are | ||
412 | unpredictable. This is because it has become standard practice to define a | ||
413 | generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes. | ||
414 | |||
415 | The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested | ||
416 | for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. | ||
417 | |||
418 | =head1 EXAMPLES | ||
419 | |||
420 | Get the number of rounds used in RC5: | ||
421 | |||
422 | int nrounds; | ||
423 | EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds); | ||
424 | |||
425 | Get the RC2 effective key length: | ||
426 | |||
427 | int key_bits; | ||
428 | EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits); | ||
429 | |||
430 | Set the number of rounds used in RC5: | ||
431 | |||
432 | int nrounds; | ||
433 | EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL); | ||
434 | |||
435 | Set the effective key length used in RC2: | ||
436 | |||
437 | int key_bits; | ||
438 | EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL); | ||
439 | |||
440 | Encrypt a string using blowfish: | ||
441 | |||
442 | int | ||
443 | do_crypt(char *outfile) | ||
444 | { | ||
445 | unsigned char outbuf[1024]; | ||
446 | int outlen, tmplen; | ||
447 | /* | ||
448 | * Bogus key and IV: we'd normally set these from | ||
449 | * another source. | ||
450 | */ | ||
451 | unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; | ||
452 | unsigned char iv[] = {1,2,3,4,5,6,7,8}; | ||
453 | const char intext[] = "Some Crypto Text"; | ||
454 | EVP_CIPHER_CTX ctx; | ||
455 | FILE *out; | ||
456 | EVP_CIPHER_CTX_init(&ctx); | ||
457 | EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv); | ||
458 | |||
459 | if (!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, | ||
460 | strlen(intext))) { | ||
461 | /* Error */ | ||
462 | return 0; | ||
463 | } | ||
464 | /* | ||
465 | * Buffer passed to EVP_EncryptFinal() must be after data just | ||
466 | * encrypted to avoid overwriting it. | ||
467 | */ | ||
468 | if (!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen)) { | ||
469 | /* Error */ | ||
470 | return 0; | ||
471 | } | ||
472 | outlen += tmplen; | ||
473 | EVP_CIPHER_CTX_cleanup(&ctx); | ||
474 | /* | ||
475 | * Need binary mode for fopen because encrypted data is | ||
476 | * binary data. Also cannot use strlen() on it because | ||
477 | * it won't be NUL terminated and may contain embedded | ||
478 | * NULs. | ||
479 | */ | ||
480 | out = fopen(outfile, "wb"); | ||
481 | fwrite(outbuf, 1, outlen, out); | ||
482 | fclose(out); | ||
483 | return 1; | ||
484 | } | ||
485 | |||
486 | The ciphertext from the above example can be decrypted using the B<openssl> | ||
487 | utility with the command line: | ||
488 | |||
489 | S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d> | ||
490 | |||
491 | General encryption, decryption function example using FILE I/O and RC2 with an | ||
492 | 80 bit key: | ||
493 | |||
494 | int | ||
495 | do_crypt(FILE *in, FILE *out, int do_encrypt) | ||
496 | { | ||
497 | /* Allow enough space in output buffer for additional block */ | ||
498 | inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; | ||
499 | int inlen, outlen; | ||
500 | /* | ||
501 | * Bogus key and IV: we'd normally set these from | ||
502 | * another source. | ||
503 | */ | ||
504 | unsigned char key[] = "0123456789"; | ||
505 | unsigned char iv[] = "12345678"; | ||
506 | |||
507 | /* Don't set key or IV because we will modify the parameters */ | ||
508 | EVP_CIPHER_CTX_init(&ctx); | ||
509 | EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt); | ||
510 | EVP_CIPHER_CTX_set_key_length(&ctx, 10); | ||
511 | /* We finished modifying parameters so now we can set key and IV */ | ||
512 | EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt); | ||
513 | |||
514 | for(;;) { | ||
515 | inlen = fread(inbuf, 1, 1024, in); | ||
516 | if (inlen <= 0) | ||
517 | break; | ||
518 | if (!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, | ||
519 | inlen)) { | ||
520 | /* Error */ | ||
521 | EVP_CIPHER_CTX_cleanup(&ctx); | ||
522 | return 0; | ||
523 | } | ||
524 | fwrite(outbuf, 1, outlen, out); | ||
525 | } | ||
526 | if (!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) { | ||
527 | /* Error */ | ||
528 | EVP_CIPHER_CTX_cleanup(&ctx); | ||
529 | return 0; | ||
530 | } | ||
531 | fwrite(outbuf, 1, outlen, out); | ||
532 | |||
533 | EVP_CIPHER_CTX_cleanup(&ctx); | ||
534 | return 1; | ||
535 | } | ||
536 | |||
537 | =head1 SEE ALSO | ||
538 | |||
539 | L<evp(3)|evp(3)> | ||
540 | |||
541 | =head1 HISTORY | ||
542 | |||
543 | EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), | ||
544 | EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(), | ||
545 | EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in | ||
546 | OpenSSL 0.9.7. | ||
547 | |||
548 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_OpenInit.pod b/src/lib/libcrypto/doc/EVP_OpenInit.pod deleted file mode 100644 index 0242f66715..0000000000 --- a/src/lib/libcrypto/doc/EVP_OpenInit.pod +++ /dev/null | |||
@@ -1,61 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek, | ||
12 | int ekl,unsigned char *iv,EVP_PKEY *priv); | ||
13 | int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
14 | int *outl, unsigned char *in, int inl); | ||
15 | int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
16 | int *outl); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | The EVP envelope routines are a high level interface to envelope | ||
21 | decryption. They decrypt a public key encrypted symmetric key and | ||
22 | then decrypt data using it. | ||
23 | |||
24 | EVP_OpenInit() initializes a cipher context B<ctx> for decryption | ||
25 | with cipher B<type>. It decrypts the encrypted symmetric key of length | ||
26 | B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>. | ||
27 | The IV is supplied in the B<iv> parameter. | ||
28 | |||
29 | EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties | ||
30 | as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as | ||
31 | documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual | ||
32 | page. | ||
33 | |||
34 | =head1 NOTES | ||
35 | |||
36 | It is possible to call EVP_OpenInit() twice in the same way as | ||
37 | EVP_DecryptInit(). The first call should have B<priv> set to NULL | ||
38 | and (after setting any cipher parameters) it should be called again | ||
39 | with B<type> set to NULL. | ||
40 | |||
41 | If the cipher passed in the B<type> parameter is a variable length | ||
42 | cipher then the key length will be set to the value of the recovered | ||
43 | key length. If the cipher is a fixed length cipher then the recovered | ||
44 | key length must match the fixed cipher length. | ||
45 | |||
46 | =head1 RETURN VALUES | ||
47 | |||
48 | EVP_OpenInit() returns 0 on error or a non zero integer (actually the | ||
49 | recovered secret key size) if successful. | ||
50 | |||
51 | EVP_OpenUpdate() returns 1 for success or 0 for failure. | ||
52 | |||
53 | EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success. | ||
54 | |||
55 | =head1 SEE ALSO | ||
56 | |||
57 | L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, | ||
58 | L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, | ||
59 | L<EVP_SealInit(3)|EVP_SealInit(3)> | ||
60 | |||
61 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod b/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod deleted file mode 100644 index e8776e1e67..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod +++ /dev/null | |||
@@ -1,135 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_get_default_digest_nid, | ||
6 | EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_set_rsa_padding, | ||
7 | EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits, | ||
8 | EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits, | ||
9 | EVP_PKEY_CTX_set_dh_paramgen_prime_len, | ||
10 | EVP_PKEY_CTX_set_dh_paramgen_generator, | ||
11 | EVP_PKEY_CTX_set_ec_paramgen_curve_nid - algorithm specific control operations | ||
12 | |||
13 | =head1 SYNOPSIS | ||
14 | |||
15 | #include <openssl/evp.h> | ||
16 | |||
17 | int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, | ||
18 | int cmd, int p1, void *p2); | ||
19 | int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, | ||
20 | const char *value); | ||
21 | |||
22 | int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); | ||
23 | |||
24 | #include <openssl/rsa.h> | ||
25 | |||
26 | int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); | ||
27 | |||
28 | int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); | ||
29 | int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); | ||
30 | int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); | ||
31 | int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); | ||
32 | |||
33 | #include <openssl/dsa.h> | ||
34 | int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); | ||
35 | |||
36 | #include <openssl/dh.h> | ||
37 | int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); | ||
38 | int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); | ||
39 | |||
40 | #include <openssl/ec.h> | ||
41 | int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); | ||
42 | |||
43 | =head1 DESCRIPTION | ||
44 | |||
45 | The function EVP_PKEY_CTX_ctrl() sends a control operation to the context | ||
46 | B<ctx>. The key type used must match B<keytype> if it is not -1. The parameter | ||
47 | B<optype> is a mask indicating which operations the control can be applied to. | ||
48 | The control command is indicated in B<cmd> and any additional arguments in | ||
49 | B<p1> and B<p2>. | ||
50 | |||
51 | Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will | ||
52 | instead call one of the algorithm specific macros below. | ||
53 | |||
54 | The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm | ||
55 | specific control operation to a context B<ctx> in string form. This is | ||
56 | intended to be used for options specified on the command line or in text | ||
57 | files. The commands supported are documented in the openssl utility | ||
58 | command line pages for the option B<-pkeyopt> which is supported by the | ||
59 | B<pkeyutl>, B<genpkey> and B<req> commands. | ||
60 | |||
61 | All the remaining "functions" are implemented as macros. | ||
62 | |||
63 | The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used | ||
64 | in a signature. It can be used with any public key algorithm supporting | ||
65 | signature operations. | ||
66 | |||
67 | The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>. | ||
68 | The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, | ||
69 | RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding, | ||
70 | RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), | ||
71 | RSA_X931_PADDING for X9.31 padding (signature operations only) and | ||
72 | RSA_PKCS1_PSS_PADDING (sign and verify only). | ||
73 | |||
74 | Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() is | ||
75 | used. If this macro is called for PKCS#1 padding the plaintext buffer is an | ||
76 | actual digest value and is encapsulated in a DigestInfo structure according to | ||
77 | PKCS#1 when signing and this structure is expected (and stripped off) when | ||
78 | verifying. If this control is not used with RSA and PKCS#1 padding then the | ||
79 | supplied data is used directly and not encapsulated. In the case of X9.31 | ||
80 | padding for RSA the algorithm identifier byte is added or checked and removed | ||
81 | if this control is called. If it is not called then the first byte of the | ||
82 | plaintext buffer is expected to be the algorithm identifier byte. | ||
83 | |||
84 | The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to | ||
85 | B<len> as its name implies it is only supported for PSS padding. Two special | ||
86 | values are supported: -1 sets the salt length to the digest length. When | ||
87 | signing -2 sets the salt length to the maximum permissible value. When | ||
88 | verifying -2 causes the salt length to be automatically determined based on the | ||
89 | B<PSS> block structure. If this macro is not called a salt length value of -2 | ||
90 | is used by default. | ||
91 | |||
92 | The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for | ||
93 | RSA key generation to B<bits>. If not specified 1024 bits is used. | ||
94 | |||
95 | The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value | ||
96 | for RSA key generation to B<pubexp> currently it should be an odd integer. The | ||
97 | B<pubexp> pointer is used internally by this function so it should not be | ||
98 | modified or free after the call. If this macro is not called then 65537 is used. | ||
99 | |||
100 | The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used | ||
101 | for DSA parameter generation to B<bits>. If not specified 1024 is used. | ||
102 | |||
103 | The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH | ||
104 | prime parameter B<p> for DH parameter generation. If this macro is not called | ||
105 | then 1024 is used. | ||
106 | |||
107 | The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen> | ||
108 | for DH parameter generation. If not specified 2 is used. | ||
109 | |||
110 | The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter | ||
111 | generation to B<nid>. For EC parameter generation this macro must be called | ||
112 | or an error occurs because there is no default curve. | ||
113 | |||
114 | =head1 RETURN VALUES | ||
115 | |||
116 | EVP_PKEY_CTX_ctrl() and its macros return a positive value for success and 0 | ||
117 | or a negative value for failure. In particular a return value of -2 | ||
118 | indicates the operation is not supported by the public key algorithm. | ||
119 | |||
120 | =head1 SEE ALSO | ||
121 | |||
122 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
123 | L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, | ||
124 | L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, | ||
125 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
126 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | ||
127 | L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, | ||
128 | L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> | ||
129 | L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> | ||
130 | |||
131 | =head1 HISTORY | ||
132 | |||
133 | These functions were first added to OpenSSL 1.0.0. | ||
134 | |||
135 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod b/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod deleted file mode 100644 index 60ad61e853..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod +++ /dev/null | |||
@@ -1,53 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - | ||
6 | public key algorithm context functions. | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e); | ||
13 | EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e); | ||
14 | EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx); | ||
15 | void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | The EVP_PKEY_CTX_new() function allocates public key algorithm context using | ||
20 | the algorithm specified in B<pkey> and ENGINE B<e>. | ||
21 | |||
22 | The EVP_PKEY_CTX_new_id() function allocates public key algorithm context | ||
23 | using the algorithm specified by B<id> and ENGINE B<e>. It is normally used | ||
24 | when no B<EVP_PKEY> structure is associated with the operations, for example | ||
25 | during parameter generation of key generation for some algorithms. | ||
26 | |||
27 | EVP_PKEY_CTX_dup() duplicates the context B<ctx>. | ||
28 | |||
29 | EVP_PKEY_CTX_free() frees up the context B<ctx>. | ||
30 | |||
31 | =head1 NOTES | ||
32 | |||
33 | The B<EVP_PKEY_CTX> structure is an opaque public key algorithm context used | ||
34 | by the OpenSSL high level public key API. Contexts B<MUST NOT> be shared between | ||
35 | threads: that is it is not permissible to use the same context simultaneously | ||
36 | in two threads. | ||
37 | |||
38 | =head1 RETURN VALUES | ||
39 | |||
40 | EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() returns either | ||
41 | the newly allocated B<EVP_PKEY_CTX> structure of B<NULL> if an error occurred. | ||
42 | |||
43 | EVP_PKEY_CTX_free() does not return a value. | ||
44 | |||
45 | =head1 SEE ALSO | ||
46 | |||
47 | L<EVP_PKEY_new(3)|EVP_PKEY_new(3)> | ||
48 | |||
49 | =head1 HISTORY | ||
50 | |||
51 | These functions were first added to OpenSSL 1.0.0. | ||
52 | |||
53 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod b/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod deleted file mode 100644 index 7a690247bf..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod +++ /dev/null | |||
@@ -1,62 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters, | ||
6 | EVP_PKEY_cmp - public key parameter and comparison functions | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); | ||
13 | int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); | ||
14 | |||
15 | int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); | ||
16 | int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | The function EVP_PKEY_missing_parameters() returns 1 if the public key | ||
21 | parameters of B<pkey> are missing and 0 if they are present or the algorithm | ||
22 | doesn't use parameters. | ||
23 | |||
24 | The function EVP_PKEY_copy_parameters() copies the parameters from key | ||
25 | B<from> to key B<to>. | ||
26 | |||
27 | The function EVP_PKEY_cmp_parameters() compares the parameters of keys | ||
28 | B<a> and B<b>. | ||
29 | |||
30 | The function EVP_PKEY_cmp() compares the public key components and parameters | ||
31 | (if present) of keys B<a> and B<b>. | ||
32 | |||
33 | =head1 NOTES | ||
34 | |||
35 | The main purpose of the functions EVP_PKEY_missing_parameters() and | ||
36 | EVP_PKEY_copy_parameters() is to handle public keys in certificates where the | ||
37 | parameters are sometimes omitted from a public key if they are inherited from | ||
38 | the CA that signed it. | ||
39 | |||
40 | Since OpenSSL private keys contain public key components too the function | ||
41 | EVP_PKEY_cmp() can also be used to determine if a private key matches | ||
42 | a public key. | ||
43 | |||
44 | =head1 RETURN VALUES | ||
45 | |||
46 | The function EVP_PKEY_missing_parameters() returns 1 if the public key | ||
47 | parameters of B<pkey> are missing and 0 if they are present or the algorithm | ||
48 | doesn't use parameters. | ||
49 | |||
50 | These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for | ||
51 | failure. | ||
52 | |||
53 | The function EVP_PKEY_cmp_parameters() and EVP_PKEY_cmp() return 1 if the | ||
54 | keys match, 0 if they don't match, -1 if the key types are different and | ||
55 | -2 if the operation is not supported. | ||
56 | |||
57 | =head1 SEE ALSO | ||
58 | |||
59 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
60 | L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> | ||
61 | |||
62 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod b/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod deleted file mode 100644 index a64ef12866..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod +++ /dev/null | |||
@@ -1,93 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx); | ||
12 | int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx, | ||
13 | unsigned char *out, size_t *outlen, | ||
14 | const unsigned char *in, size_t inlen); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | The EVP_PKEY_decrypt_init() function initializes a public key algorithm | ||
19 | context using key B<pkey> for a decryption operation. | ||
20 | |||
21 | The EVP_PKEY_decrypt() function performs a public key decryption operation | ||
22 | using B<ctx>. The data to be decrypted is specified using the B<in> and | ||
23 | B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output | ||
24 | buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then | ||
25 | before the call the B<outlen> parameter should contain the length of the | ||
26 | B<out> buffer, if the call is successful the decrypted data is written to | ||
27 | B<out> and the amount of data written to B<outlen>. | ||
28 | |||
29 | =head1 NOTES | ||
30 | |||
31 | After the call to EVP_PKEY_decrypt_init() algorithm specific control | ||
32 | operations can be performed to set any appropriate parameters for the | ||
33 | operation. | ||
34 | |||
35 | The function EVP_PKEY_decrypt() can be called more than once on the same | ||
36 | context if several operations are performed using the same parameters. | ||
37 | |||
38 | =head1 RETURN VALUES | ||
39 | |||
40 | EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() return 1 for success and 0 | ||
41 | or a negative value for failure. In particular a return value of -2 | ||
42 | indicates the operation is not supported by the public key algorithm. | ||
43 | |||
44 | =head1 EXAMPLE | ||
45 | |||
46 | Decrypt data using OAEP (for RSA keys): | ||
47 | |||
48 | #include <openssl/evp.h> | ||
49 | #include <openssl/rsa.h> | ||
50 | |||
51 | EVP_PKEY_CTX *ctx; | ||
52 | unsigned char *out, *in; | ||
53 | size_t outlen, inlen; | ||
54 | EVP_PKEY *key; | ||
55 | /* NB: assumes key in, inlen are already set up | ||
56 | * and that key is an RSA private key | ||
57 | */ | ||
58 | ctx = EVP_PKEY_CTX_new(key); | ||
59 | if (!ctx) | ||
60 | /* Error occurred */ | ||
61 | if (EVP_PKEY_decrypt_init(ctx) <= 0) | ||
62 | /* Error */ | ||
63 | if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0) | ||
64 | /* Error */ | ||
65 | |||
66 | /* Determine buffer length */ | ||
67 | if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0) | ||
68 | /* Error */ | ||
69 | |||
70 | out = malloc(outlen); | ||
71 | |||
72 | if (!out) | ||
73 | /* malloc failure */ | ||
74 | |||
75 | if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0) | ||
76 | /* Error */ | ||
77 | |||
78 | /* Decrypted data is outlen bytes written to buffer out */ | ||
79 | |||
80 | =head1 SEE ALSO | ||
81 | |||
82 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
83 | L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, | ||
84 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
85 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | ||
86 | L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, | ||
87 | L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> | ||
88 | |||
89 | =head1 HISTORY | ||
90 | |||
91 | These functions were first added to OpenSSL 1.0.0. | ||
92 | |||
93 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_derive.pod b/src/lib/libcrypto/doc/EVP_PKEY_derive.pod deleted file mode 100644 index 09654e1b81..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_derive.pod +++ /dev/null | |||
@@ -1,94 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public | ||
6 | key algorithm shared secret. | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); | ||
13 | int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); | ||
14 | int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | The EVP_PKEY_derive_init() function initializes a public key algorithm | ||
19 | context using key B<pkey> for shared secret derivation. | ||
20 | |||
21 | The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally | ||
22 | be a public key. | ||
23 | |||
24 | The EVP_PKEY_derive() derives a shared secret using B<ctx>. | ||
25 | If B<key> is B<NULL> then the maximum size of the output buffer is written to | ||
26 | the B<keylen> parameter. If B<key> is not B<NULL> then before the call the | ||
27 | B<keylen> parameter should contain the length of the B<key> buffer, if the call | ||
28 | is successful the shared secret is written to B<key> and the amount of data | ||
29 | written to B<keylen>. | ||
30 | |||
31 | =head1 NOTES | ||
32 | |||
33 | After the call to EVP_PKEY_derive_init() algorithm specific control | ||
34 | operations can be performed to set any appropriate parameters for the | ||
35 | operation. | ||
36 | |||
37 | The function EVP_PKEY_derive() can be called more than once on the same | ||
38 | context if several operations are performed using the same parameters. | ||
39 | |||
40 | =head1 RETURN VALUES | ||
41 | |||
42 | EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0 | ||
43 | or a negative value for failure. In particular a return value of -2 | ||
44 | indicates the operation is not supported by the public key algorithm. | ||
45 | |||
46 | =head1 EXAMPLE | ||
47 | |||
48 | Derive shared secret (for example DH or EC keys): | ||
49 | |||
50 | #include <openssl/evp.h> | ||
51 | #include <openssl/rsa.h> | ||
52 | |||
53 | EVP_PKEY_CTX *ctx; | ||
54 | unsigned char *skey; | ||
55 | size_t skeylen; | ||
56 | EVP_PKEY *pkey, *peerkey; | ||
57 | /* NB: assumes pkey, peerkey have been already set up */ | ||
58 | |||
59 | ctx = EVP_PKEY_CTX_new(pkey); | ||
60 | if (!ctx) | ||
61 | /* Error occurred */ | ||
62 | if (EVP_PKEY_derive_init(ctx) <= 0) | ||
63 | /* Error */ | ||
64 | if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) | ||
65 | /* Error */ | ||
66 | |||
67 | /* Determine buffer length */ | ||
68 | if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) | ||
69 | /* Error */ | ||
70 | |||
71 | skey = malloc(skeylen); | ||
72 | |||
73 | if (!skey) | ||
74 | /* malloc failure */ | ||
75 | |||
76 | if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) | ||
77 | /* Error */ | ||
78 | |||
79 | /* Shared secret is skey bytes written to buffer skey */ | ||
80 | |||
81 | =head1 SEE ALSO | ||
82 | |||
83 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
84 | L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, | ||
85 | L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, | ||
86 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
87 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | ||
88 | L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, | ||
89 | |||
90 | =head1 HISTORY | ||
91 | |||
92 | These functions were first added to OpenSSL 1.0.0. | ||
93 | |||
94 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod b/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod deleted file mode 100644 index b3ca123df0..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod +++ /dev/null | |||
@@ -1,93 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx); | ||
12 | int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx, | ||
13 | unsigned char *out, size_t *outlen, | ||
14 | const unsigned char *in, size_t inlen); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | The EVP_PKEY_encrypt_init() function initializes a public key algorithm | ||
19 | context using key B<pkey> for an encryption operation. | ||
20 | |||
21 | The EVP_PKEY_encrypt() function performs a public key encryption operation | ||
22 | using B<ctx>. The data to be encrypted is specified using the B<in> and | ||
23 | B<inlen> parameters. If B<out> is B<NULL> then the maximum size of the output | ||
24 | buffer is written to the B<outlen> parameter. If B<out> is not B<NULL> then | ||
25 | before the call the B<outlen> parameter should contain the length of the | ||
26 | B<out> buffer, if the call is successful the encrypted data is written to | ||
27 | B<out> and the amount of data written to B<outlen>. | ||
28 | |||
29 | =head1 NOTES | ||
30 | |||
31 | After the call to EVP_PKEY_encrypt_init() algorithm specific control | ||
32 | operations can be performed to set any appropriate parameters for the | ||
33 | operation. | ||
34 | |||
35 | The function EVP_PKEY_encrypt() can be called more than once on the same | ||
36 | context if several operations are performed using the same parameters. | ||
37 | |||
38 | =head1 RETURN VALUES | ||
39 | |||
40 | EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() return 1 for success and 0 | ||
41 | or a negative value for failure. In particular a return value of -2 | ||
42 | indicates the operation is not supported by the public key algorithm. | ||
43 | |||
44 | =head1 EXAMPLE | ||
45 | |||
46 | Encrypt data using OAEP (for RSA keys): | ||
47 | |||
48 | #include <openssl/evp.h> | ||
49 | #include <openssl/rsa.h> | ||
50 | |||
51 | EVP_PKEY_CTX *ctx; | ||
52 | unsigned char *out, *in; | ||
53 | size_t outlen, inlen; | ||
54 | EVP_PKEY *key; | ||
55 | /* NB: assumes key in, inlen are already set up | ||
56 | * and that key is an RSA public key | ||
57 | */ | ||
58 | ctx = EVP_PKEY_CTX_new(key); | ||
59 | if (!ctx) | ||
60 | /* Error occurred */ | ||
61 | if (EVP_PKEY_encrypt_init(ctx) <= 0) | ||
62 | /* Error */ | ||
63 | if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0) | ||
64 | /* Error */ | ||
65 | |||
66 | /* Determine buffer length */ | ||
67 | if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0) | ||
68 | /* Error */ | ||
69 | |||
70 | out = malloc(outlen); | ||
71 | |||
72 | if (!out) | ||
73 | /* malloc failure */ | ||
74 | |||
75 | if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0) | ||
76 | /* Error */ | ||
77 | |||
78 | /* Encrypted data is outlen bytes written to buffer out */ | ||
79 | |||
80 | =head1 SEE ALSO | ||
81 | |||
82 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
83 | L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, | ||
84 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
85 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | ||
86 | L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, | ||
87 | L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> | ||
88 | |||
89 | =head1 HISTORY | ||
90 | |||
91 | These functions were first added to OpenSSL 1.0.0. | ||
92 | |||
93 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod b/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod deleted file mode 100644 index 8ff597d44a..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod +++ /dev/null | |||
@@ -1,41 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_get_default_digest_nid - get default signature digest | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); | ||
11 | |||
12 | =head1 DESCRIPTION | ||
13 | |||
14 | The EVP_PKEY_get_default_digest_nid() function sets B<pnid> to the default | ||
15 | message digest NID for the public key signature operations associated with key | ||
16 | B<pkey>. | ||
17 | |||
18 | =head1 NOTES | ||
19 | |||
20 | For all current standard OpenSSL public key algorithms SHA1 is returned. | ||
21 | |||
22 | =head1 RETURN VALUES | ||
23 | |||
24 | The EVP_PKEY_get_default_digest_nid() function returns 1 if the message digest | ||
25 | is advisory (that is other digests can be used) and 2 if it is mandatory (other | ||
26 | digests can not be used). It returns 0 or a negative value for failure. In | ||
27 | particular a return value of -2 indicates the operation is not supported by the | ||
28 | public key algorithm. | ||
29 | |||
30 | =head1 SEE ALSO | ||
31 | |||
32 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
33 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
34 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | ||
35 | L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, | ||
36 | |||
37 | =head1 HISTORY | ||
38 | |||
39 | This function was first added to OpenSSL 1.0.0. | ||
40 | |||
41 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod b/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod deleted file mode 100644 index adcf3560e0..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod +++ /dev/null | |||
@@ -1,170 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, | ||
6 | EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, | ||
7 | EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data, | ||
8 | EVP_PKEY_CTX_get_app_data - key and parameter generation functions | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/evp.h> | ||
13 | |||
14 | int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); | ||
15 | int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); | ||
16 | int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); | ||
17 | int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); | ||
18 | |||
19 | typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); | ||
20 | |||
21 | void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); | ||
22 | EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); | ||
23 | |||
24 | int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); | ||
25 | |||
26 | void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); | ||
27 | void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); | ||
28 | |||
29 | =head1 DESCRIPTION | ||
30 | |||
31 | The EVP_PKEY_keygen_init() function initializes a public key algorithm | ||
32 | context using key B<pkey> for a key generation operation. | ||
33 | |||
34 | The EVP_PKEY_keygen() function performs a key generation operation, the | ||
35 | generated key is written to B<ppkey>. | ||
36 | |||
37 | The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar | ||
38 | except parameters are generated. | ||
39 | |||
40 | The function EVP_PKEY_set_cb() sets the key or parameter generation callback | ||
41 | to B<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter | ||
42 | generation callback. | ||
43 | |||
44 | The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated | ||
45 | with the generation operation. If B<idx> is -1 the total number of | ||
46 | parameters available is returned. Any non negative value returns the value of | ||
47 | that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for | ||
48 | B<idx> should only be called within the generation callback. | ||
49 | |||
50 | If the callback returns 0 then the key generation operation is aborted and an | ||
51 | error occurs. This might occur during a time consuming operation where | ||
52 | a user clicks on a "cancel" button. | ||
53 | |||
54 | The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set | ||
55 | and retrieve an opaque pointer. This can be used to set some application | ||
56 | defined value which can be retrieved in the callback: for example a handle | ||
57 | which is used to update a "progress dialog". | ||
58 | |||
59 | =head1 NOTES | ||
60 | |||
61 | After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm | ||
62 | specific control operations can be performed to set any appropriate parameters | ||
63 | for the operation. | ||
64 | |||
65 | The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than | ||
66 | once on the same context if several operations are performed using the same | ||
67 | parameters. | ||
68 | |||
69 | The meaning of the parameters passed to the callback will depend on the | ||
70 | algorithm and the specific implementation of the algorithm. Some might not | ||
71 | give any useful information at all during key or parameter generation. Others | ||
72 | might not even call the callback. | ||
73 | |||
74 | The operation performed by key or parameter generation depends on the algorithm | ||
75 | used. In some cases (e.g. EC with a supplied named curve) the "generation" | ||
76 | option merely sets the appropriate fields in an EVP_PKEY structure. | ||
77 | |||
78 | In OpenSSL an EVP_PKEY structure containing a private key also contains the | ||
79 | public key components and parameters (if any). An OpenSSL private key is | ||
80 | equivalent to what some libraries call a "key pair". A private key can be used | ||
81 | in functions which require the use of a public key or parameters. | ||
82 | |||
83 | =head1 RETURN VALUES | ||
84 | |||
85 | EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and | ||
86 | EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure. | ||
87 | In particular a return value of -2 indicates the operation is not supported by | ||
88 | the public key algorithm. | ||
89 | |||
90 | =head1 EXAMPLES | ||
91 | |||
92 | Generate a 2048 bit RSA key: | ||
93 | |||
94 | #include <openssl/evp.h> | ||
95 | #include <openssl/rsa.h> | ||
96 | |||
97 | EVP_PKEY_CTX *ctx; | ||
98 | EVP_PKEY *pkey = NULL; | ||
99 | ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); | ||
100 | if (!ctx) | ||
101 | /* Error occurred */ | ||
102 | if (EVP_PKEY_keygen_init(ctx) <= 0) | ||
103 | /* Error */ | ||
104 | if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) | ||
105 | /* Error */ | ||
106 | |||
107 | /* Generate key */ | ||
108 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | ||
109 | /* Error */ | ||
110 | |||
111 | Generate a key from a set of parameters: | ||
112 | |||
113 | #include <openssl/evp.h> | ||
114 | #include <openssl/rsa.h> | ||
115 | |||
116 | EVP_PKEY_CTX *ctx; | ||
117 | EVP_PKEY *pkey = NULL, *param; | ||
118 | /* Assumed param is set up already */ | ||
119 | ctx = EVP_PKEY_CTX_new(param); | ||
120 | if (!ctx) | ||
121 | /* Error occurred */ | ||
122 | if (EVP_PKEY_keygen_init(ctx) <= 0) | ||
123 | /* Error */ | ||
124 | |||
125 | /* Generate key */ | ||
126 | if (EVP_PKEY_keygen(ctx, &pkey) <= 0) | ||
127 | /* Error */ | ||
128 | |||
129 | Example of generation callback for OpenSSL public key implementations: | ||
130 | |||
131 | /* Application data is a BIO to output status to */ | ||
132 | |||
133 | EVP_PKEY_CTX_set_app_data(ctx, status_bio); | ||
134 | |||
135 | static int | ||
136 | genpkey_cb(EVP_PKEY_CTX *ctx) | ||
137 | { | ||
138 | char c = '*'; | ||
139 | BIO *b = EVP_PKEY_CTX_get_app_data(ctx); | ||
140 | int p; | ||
141 | |||
142 | p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); | ||
143 | if (p == 0) | ||
144 | c='.'; | ||
145 | if (p == 1) | ||
146 | c='+'; | ||
147 | if (p == 2) | ||
148 | c='*'; | ||
149 | if (p == 3) | ||
150 | c='\n'; | ||
151 | BIO_write(b,&c,1); | ||
152 | (void)BIO_flush(b); | ||
153 | return 1; | ||
154 | } | ||
155 | |||
156 | =head1 SEE ALSO | ||
157 | |||
158 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
159 | L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, | ||
160 | L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, | ||
161 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
162 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | ||
163 | L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, | ||
164 | L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> | ||
165 | |||
166 | =head1 HISTORY | ||
167 | |||
168 | These functions were first added to OpenSSL 1.0.0. | ||
169 | |||
170 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_new.pod b/src/lib/libcrypto/doc/EVP_PKEY_new.pod deleted file mode 100644 index 7792714659..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_new.pod +++ /dev/null | |||
@@ -1,43 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_new, EVP_PKEY_free - private key allocation functions. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | EVP_PKEY *EVP_PKEY_new(void); | ||
12 | void EVP_PKEY_free(EVP_PKEY *key); | ||
13 | |||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> | ||
18 | structure which is used by OpenSSL to store private keys. | ||
19 | |||
20 | EVP_PKEY_free() frees up the private key B<key>. | ||
21 | |||
22 | =head1 NOTES | ||
23 | |||
24 | The B<EVP_PKEY> structure is used by various OpenSSL functions | ||
25 | which require a general private key without reference to any | ||
26 | particular algorithm. | ||
27 | |||
28 | The structure returned by EVP_PKEY_new() is empty. To add a | ||
29 | private key to this empty structure the functions described in | ||
30 | L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> should be used. | ||
31 | |||
32 | =head1 RETURN VALUES | ||
33 | |||
34 | EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> | ||
35 | structure of B<NULL> if an error occurred. | ||
36 | |||
37 | EVP_PKEY_free() does not return a value. | ||
38 | |||
39 | =head1 SEE ALSO | ||
40 | |||
41 | L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> | ||
42 | |||
43 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod b/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod deleted file mode 100644 index eabbaed264..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod +++ /dev/null | |||
@@ -1,54 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params - public | ||
6 | key algorithm printing routines. | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, | ||
13 | int indent, ASN1_PCTX *pctx); | ||
14 | int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, | ||
15 | int indent, ASN1_PCTX *pctx); | ||
16 | int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, | ||
17 | int indent, ASN1_PCTX *pctx); | ||
18 | |||
19 | =head1 DESCRIPTION | ||
20 | |||
21 | The functions EVP_PKEY_print_public(), EVP_PKEY_print_private() and | ||
22 | EVP_PKEY_print_params() print out the public, private or parameter components | ||
23 | of key B<pkey> respectively. The key is sent to BIO B<out> in human readable | ||
24 | form. The parameter B<indent> indicated how far the printout should be indented. | ||
25 | |||
26 | The B<pctx> parameter allows the print output to be finely tuned by using | ||
27 | ASN1 printing options. If B<pctx> is set to NULL then default values will | ||
28 | be used. | ||
29 | |||
30 | =head1 NOTES | ||
31 | |||
32 | Currently no public key algorithms include any options in the B<pctx> parameter | ||
33 | parameter. | ||
34 | |||
35 | If the key does not include all the components indicated by the function then | ||
36 | only those contained in the key will be printed. For example passing a public | ||
37 | key to EVP_PKEY_print_private() will only print the public components. | ||
38 | |||
39 | =head1 RETURN VALUES | ||
40 | |||
41 | These functions all return 1 for success and 0 or a negative value for failure. | ||
42 | In particular a return value of -2 indicates the operation is not supported by | ||
43 | the public key algorithm. | ||
44 | |||
45 | =head1 SEE ALSO | ||
46 | |||
47 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
48 | L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> | ||
49 | |||
50 | =head1 HISTORY | ||
51 | |||
52 | These functions were first added to OpenSSL 1.0.0. | ||
53 | |||
54 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod b/src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod deleted file mode 100644 index 096e969fa3..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod +++ /dev/null | |||
@@ -1,76 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, | ||
6 | EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, | ||
7 | EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, | ||
8 | EVP_PKEY_assign_EC_KEY, EVP_PKEY_type - EVP_PKEY assignment functions. | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/evp.h> | ||
13 | |||
14 | int EVP_PKEY_set1_RSA(EVP_PKEY *pkey,RSA *key); | ||
15 | int EVP_PKEY_set1_DSA(EVP_PKEY *pkey,DSA *key); | ||
16 | int EVP_PKEY_set1_DH(EVP_PKEY *pkey,DH *key); | ||
17 | int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey,EC_KEY *key); | ||
18 | |||
19 | RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey); | ||
20 | DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey); | ||
21 | DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey); | ||
22 | EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); | ||
23 | |||
24 | int EVP_PKEY_assign_RSA(EVP_PKEY *pkey,RSA *key); | ||
25 | int EVP_PKEY_assign_DSA(EVP_PKEY *pkey,DSA *key); | ||
26 | int EVP_PKEY_assign_DH(EVP_PKEY *pkey,DH *key); | ||
27 | int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey,EC_KEY *key); | ||
28 | |||
29 | int EVP_PKEY_type(int type); | ||
30 | |||
31 | =head1 DESCRIPTION | ||
32 | |||
33 | EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and | ||
34 | EVP_PKEY_set1_EC_KEY() set the key referenced by B<pkey> to B<key>. | ||
35 | |||
36 | EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and | ||
37 | EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or | ||
38 | B<NULL> if the key is not of the correct type. | ||
39 | |||
40 | EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() | ||
41 | and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key> | ||
42 | however these use the supplied B<key> internally and so B<key> | ||
43 | will be freed when the parent B<pkey> is freed. | ||
44 | |||
45 | EVP_PKEY_type() returns the type of key corresponding to the value | ||
46 | B<type>. The type of a key can be obtained with | ||
47 | EVP_PKEY_type(pkey->type). The return value will be EVP_PKEY_RSA, | ||
48 | EVP_PKEY_DSA, EVP_PKEY_DH or EVP_PKEY_EC for the corresponding | ||
49 | key types or NID_undef if the key type is unassigned. | ||
50 | |||
51 | =head1 NOTES | ||
52 | |||
53 | In accordance with the OpenSSL naming convention the key obtained | ||
54 | from or assigned to the B<pkey> using the B<1> functions must be | ||
55 | freed as well as B<pkey>. | ||
56 | |||
57 | EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() | ||
58 | EVP_PKEY_assign_EC_KEY() are implemented as macros. | ||
59 | |||
60 | =head1 RETURN VALUES | ||
61 | |||
62 | EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and | ||
63 | EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure. | ||
64 | |||
65 | EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and | ||
66 | EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if | ||
67 | an error occurred. | ||
68 | |||
69 | EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() | ||
70 | and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure. | ||
71 | |||
72 | =head1 SEE ALSO | ||
73 | |||
74 | L<EVP_PKEY_new(3)|EVP_PKEY_new(3)> | ||
75 | |||
76 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_sign.pod b/src/lib/libcrypto/doc/EVP_PKEY_sign.pod deleted file mode 100644 index 1925706d96..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_sign.pod +++ /dev/null | |||
@@ -1,96 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); | ||
12 | int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, | ||
13 | unsigned char *sig, size_t *siglen, | ||
14 | const unsigned char *tbs, size_t tbslen); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | The EVP_PKEY_sign_init() function initializes a public key algorithm | ||
19 | context using key B<pkey> for a signing operation. | ||
20 | |||
21 | The EVP_PKEY_sign() function performs a public key signing operation | ||
22 | using B<ctx>. The data to be signed is specified using the B<tbs> and | ||
23 | B<tbslen> parameters. If B<sig> is B<NULL> then the maximum size of the output | ||
24 | buffer is written to the B<siglen> parameter. If B<sig> is not B<NULL> then | ||
25 | before the call the B<siglen> parameter should contain the length of the | ||
26 | B<sig> buffer, if the call is successful the signature is written to | ||
27 | B<sig> and the amount of data written to B<siglen>. | ||
28 | |||
29 | =head1 NOTES | ||
30 | |||
31 | After the call to EVP_PKEY_sign_init() algorithm specific control | ||
32 | operations can be performed to set any appropriate parameters for the | ||
33 | operation. | ||
34 | |||
35 | The function EVP_PKEY_sign() can be called more than once on the same | ||
36 | context if several operations are performed using the same parameters. | ||
37 | |||
38 | =head1 RETURN VALUES | ||
39 | |||
40 | EVP_PKEY_sign_init() and EVP_PKEY_sign() return 1 for success and 0 | ||
41 | or a negative value for failure. In particular a return value of -2 | ||
42 | indicates the operation is not supported by the public key algorithm. | ||
43 | |||
44 | =head1 EXAMPLE | ||
45 | |||
46 | Sign data using RSA with PKCS#1 padding and SHA256 digest: | ||
47 | |||
48 | #include <openssl/evp.h> | ||
49 | #include <openssl/rsa.h> | ||
50 | |||
51 | EVP_PKEY_CTX *ctx; | ||
52 | unsigned char *md, *sig; | ||
53 | size_t mdlen, siglen; | ||
54 | EVP_PKEY *signing_key; | ||
55 | /* NB: assumes signing_key, md and mdlen are already set up | ||
56 | * and that signing_key is an RSA private key | ||
57 | */ | ||
58 | ctx = EVP_PKEY_CTX_new(signing_key); | ||
59 | if (!ctx) | ||
60 | /* Error occurred */ | ||
61 | if (EVP_PKEY_sign_init(ctx) <= 0) | ||
62 | /* Error */ | ||
63 | if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) | ||
64 | /* Error */ | ||
65 | if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) | ||
66 | /* Error */ | ||
67 | |||
68 | /* Determine buffer length */ | ||
69 | if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0) | ||
70 | /* Error */ | ||
71 | |||
72 | sig = malloc(siglen); | ||
73 | |||
74 | if (!sig) | ||
75 | /* malloc failure */ | ||
76 | |||
77 | if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0) | ||
78 | /* Error */ | ||
79 | |||
80 | /* Signature is siglen bytes written to buffer sig */ | ||
81 | |||
82 | |||
83 | =head1 SEE ALSO | ||
84 | |||
85 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
86 | L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, | ||
87 | L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, | ||
88 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | ||
89 | L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, | ||
90 | L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> | ||
91 | |||
92 | =head1 HISTORY | ||
93 | |||
94 | These functions were first added to OpenSSL 1.0.0. | ||
95 | |||
96 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_verify.pod b/src/lib/libcrypto/doc/EVP_PKEY_verify.pod deleted file mode 100644 index 0f092ca8e1..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_verify.pod +++ /dev/null | |||
@@ -1,92 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public | ||
6 | key algorithm | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); | ||
13 | int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, | ||
14 | const unsigned char *sig, size_t siglen, | ||
15 | const unsigned char *tbs, size_t tbslen); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | The EVP_PKEY_verify_init() function initializes a public key algorithm | ||
20 | context using key B<pkey> for a signature verification operation. | ||
21 | |||
22 | The EVP_PKEY_verify() function performs a public key verification operation | ||
23 | using B<ctx>. The signature is specified using the B<sig> and | ||
24 | B<siglen> parameters. The verified data (i.e. the data believed originally | ||
25 | signed) is specified using the B<tbs> and B<tbslen> parameters. | ||
26 | |||
27 | =head1 NOTES | ||
28 | |||
29 | After the call to EVP_PKEY_verify_init() algorithm specific control | ||
30 | operations can be performed to set any appropriate parameters for the | ||
31 | operation. | ||
32 | |||
33 | The function EVP_PKEY_verify() can be called more than once on the same | ||
34 | context if several operations are performed using the same parameters. | ||
35 | |||
36 | =head1 RETURN VALUES | ||
37 | |||
38 | EVP_PKEY_verify_init() and EVP_PKEY_verify() return 1 if the verification was | ||
39 | successful and 0 if it failed. Unlike other functions the return value 0 from | ||
40 | EVP_PKEY_verify() only indicates that the signature did not verify | ||
41 | successfully (that is tbs did not match the original data or the signature was | ||
42 | of invalid form) it is not an indication of a more serious error. | ||
43 | |||
44 | A negative value indicates an error other that signature verification failure. | ||
45 | In particular a return value of -2 indicates the operation is not supported by | ||
46 | the public key algorithm. | ||
47 | |||
48 | =head1 EXAMPLE | ||
49 | |||
50 | Verify signature using PKCS#1 and SHA256 digest: | ||
51 | |||
52 | #include <openssl/evp.h> | ||
53 | #include <openssl/rsa.h> | ||
54 | |||
55 | EVP_PKEY_CTX *ctx; | ||
56 | unsigned char *md, *sig; | ||
57 | size_t mdlen, siglen; | ||
58 | EVP_PKEY *verify_key; | ||
59 | /* NB: assumes verify_key, sig, siglen md and mdlen are already set up | ||
60 | * and that verify_key is an RSA public key | ||
61 | */ | ||
62 | ctx = EVP_PKEY_CTX_new(verify_key); | ||
63 | if (!ctx) | ||
64 | /* Error occurred */ | ||
65 | if (EVP_PKEY_verify_init(ctx) <= 0) | ||
66 | /* Error */ | ||
67 | if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) | ||
68 | /* Error */ | ||
69 | if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) | ||
70 | /* Error */ | ||
71 | |||
72 | /* Perform operation */ | ||
73 | ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen); | ||
74 | |||
75 | /* ret == 1 indicates success, 0 verify failure and < 0 for some | ||
76 | * other error. | ||
77 | */ | ||
78 | |||
79 | =head1 SEE ALSO | ||
80 | |||
81 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
82 | L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, | ||
83 | L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, | ||
84 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
85 | L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, | ||
86 | L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> | ||
87 | |||
88 | =head1 HISTORY | ||
89 | |||
90 | These functions were first added to OpenSSL 1.0.0. | ||
91 | |||
92 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod b/src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod deleted file mode 100644 index 095e53ea2f..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod +++ /dev/null | |||
@@ -1,105 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using | ||
6 | a public key algorithm | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx); | ||
13 | int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx, | ||
14 | unsigned char *rout, size_t *routlen, | ||
15 | const unsigned char *sig, size_t siglen); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | The EVP_PKEY_verify_recover_init() function initializes a public key algorithm | ||
20 | context using key B<pkey> for a verify recover operation. | ||
21 | |||
22 | The EVP_PKEY_verify_recover() function recovers signed data | ||
23 | using B<ctx>. The signature is specified using the B<sig> and | ||
24 | B<siglen> parameters. If B<rout> is B<NULL> then the maximum size of the output | ||
25 | buffer is written to the B<routlen> parameter. If B<rout> is not B<NULL> then | ||
26 | before the call the B<routlen> parameter should contain the length of the | ||
27 | B<rout> buffer, if the call is successful recovered data is written to | ||
28 | B<rout> and the amount of data written to B<routlen>. | ||
29 | |||
30 | =head1 NOTES | ||
31 | |||
32 | Normally an application is only interested in whether a signature verification | ||
33 | operation is successful in those cases the EVP_verify() function should be | ||
34 | used. | ||
35 | |||
36 | Sometimes however it is useful to obtain the data originally signed using a | ||
37 | signing operation. Only certain public key algorithms can recover a signature | ||
38 | in this way (for example RSA in PKCS padding mode). | ||
39 | |||
40 | After the call to EVP_PKEY_verify_recover_init() algorithm specific control | ||
41 | operations can be performed to set any appropriate parameters for the | ||
42 | operation. | ||
43 | |||
44 | The function EVP_PKEY_verify_recover() can be called more than once on the same | ||
45 | context if several operations are performed using the same parameters. | ||
46 | |||
47 | =head1 RETURN VALUES | ||
48 | |||
49 | EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for | ||
50 | success | ||
51 | and 0 or a negative value for failure. In particular a return value of -2 | ||
52 | indicates the operation is not supported by the public key algorithm. | ||
53 | |||
54 | =head1 EXAMPLE | ||
55 | |||
56 | Recover digest originally signed using PKCS#1 and SHA256 digest: | ||
57 | |||
58 | #include <openssl/evp.h> | ||
59 | #include <openssl/rsa.h> | ||
60 | |||
61 | EVP_PKEY_CTX *ctx; | ||
62 | unsigned char *rout, *sig; | ||
63 | size_t routlen, siglen; | ||
64 | EVP_PKEY *verify_key; | ||
65 | /* NB: assumes verify_key, sig and siglen are already set up | ||
66 | * and that verify_key is an RSA public key | ||
67 | */ | ||
68 | ctx = EVP_PKEY_CTX_new(verify_key); | ||
69 | if (!ctx) | ||
70 | /* Error occurred */ | ||
71 | if (EVP_PKEY_verify_recover_init(ctx) <= 0) | ||
72 | /* Error */ | ||
73 | if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) | ||
74 | /* Error */ | ||
75 | if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) | ||
76 | /* Error */ | ||
77 | |||
78 | /* Determine buffer length */ | ||
79 | if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0) | ||
80 | /* Error */ | ||
81 | |||
82 | rout = malloc(routlen); | ||
83 | |||
84 | if (!rout) | ||
85 | /* malloc failure */ | ||
86 | |||
87 | if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0) | ||
88 | /* Error */ | ||
89 | |||
90 | /* Recovered data is routlen bytes written to buffer rout */ | ||
91 | |||
92 | =head1 SEE ALSO | ||
93 | |||
94 | L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, | ||
95 | L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, | ||
96 | L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, | ||
97 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
98 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | ||
99 | L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> | ||
100 | |||
101 | =head1 HISTORY | ||
102 | |||
103 | These functions were first added to OpenSSL 1.0.0. | ||
104 | |||
105 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_SealInit.pod b/src/lib/libcrypto/doc/EVP_SealInit.pod deleted file mode 100644 index 76eebb72a9..0000000000 --- a/src/lib/libcrypto/doc/EVP_SealInit.pod +++ /dev/null | |||
@@ -1,82 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, | ||
12 | unsigned char **ek, int *ekl, unsigned char *iv, | ||
13 | EVP_PKEY **pubk, int npubk); | ||
14 | int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
15 | int *outl, unsigned char *in, int inl); | ||
16 | int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, | ||
17 | int *outl); | ||
18 | |||
19 | =head1 DESCRIPTION | ||
20 | |||
21 | The EVP envelope routines are a high level interface to envelope | ||
22 | encryption. They generate a random key and IV (if required) then | ||
23 | "envelope" it by using public key encryption. Data can then be | ||
24 | encrypted using this key. | ||
25 | |||
26 | EVP_SealInit() initializes a cipher context B<ctx> for encryption | ||
27 | with cipher B<type> using a random secret key and IV. B<type> is normally | ||
28 | supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted | ||
29 | using one or more public keys, this allows the same encrypted data to be | ||
30 | decrypted using any of the corresponding private keys. B<ek> is an array of | ||
31 | buffers where the public key encrypted secret key will be written, each buffer | ||
32 | must contain enough room for the corresponding encrypted key: that is | ||
33 | B<ek[i]> must have room for B<EVP_PKEY_size(pubk[i])> bytes. The actual | ||
34 | size of each encrypted secret key is written to the array B<ekl>. B<pubk> is | ||
35 | an array of B<npubk> public keys. | ||
36 | |||
37 | The B<iv> parameter is a buffer where the generated IV is written to. It must | ||
38 | contain enough room for the corresponding cipher's IV, as determined by (for | ||
39 | example) EVP_CIPHER_iv_length(type). | ||
40 | |||
41 | If the cipher does not require an IV then the B<iv> parameter is ignored | ||
42 | and can be B<NULL>. | ||
43 | |||
44 | EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties | ||
45 | as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as | ||
46 | documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual | ||
47 | page. | ||
48 | |||
49 | =head1 RETURN VALUES | ||
50 | |||
51 | EVP_SealInit() returns 0 on error or B<npubk> if successful. | ||
52 | |||
53 | EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for | ||
54 | failure. | ||
55 | |||
56 | =head1 NOTES | ||
57 | |||
58 | The public key must be RSA because it is the only OpenSSL public key | ||
59 | algorithm that supports key transport. | ||
60 | |||
61 | Envelope encryption is the usual method of using public key encryption | ||
62 | on large amounts of data, this is because public key encryption is slow | ||
63 | but symmetric encryption is fast. So symmetric encryption is used for | ||
64 | bulk encryption and the small random symmetric key used is transferred | ||
65 | using public key encryption. | ||
66 | |||
67 | It is possible to call EVP_SealInit() twice in the same way as | ||
68 | EVP_EncryptInit(). The first call should have B<npubk> set to 0 | ||
69 | and (after setting any cipher parameters) it should be called again | ||
70 | with B<type> set to NULL. | ||
71 | |||
72 | =head1 SEE ALSO | ||
73 | |||
74 | L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, | ||
75 | L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, | ||
76 | L<EVP_OpenInit(3)|EVP_OpenInit(3)> | ||
77 | |||
78 | =head1 HISTORY | ||
79 | |||
80 | EVP_SealFinal() did not return a value before OpenSSL 0.9.7. | ||
81 | |||
82 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_SignInit.pod b/src/lib/libcrypto/doc/EVP_SignInit.pod deleted file mode 100644 index 6882211e02..0000000000 --- a/src/lib/libcrypto/doc/EVP_SignInit.pod +++ /dev/null | |||
@@ -1,103 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_SignInit, EVP_SignUpdate, EVP_SignFinal, EVP_PKEY_size | ||
6 | - EVP signing functions | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); | ||
13 | int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); | ||
14 | int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey); | ||
15 | |||
16 | void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); | ||
17 | |||
18 | int EVP_PKEY_size(EVP_PKEY *pkey); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | The EVP signature routines are a high level interface to digital | ||
23 | signatures. | ||
24 | |||
25 | EVP_SignInit_ex() sets up signing context B<ctx> to use digest | ||
26 | B<type> from ENGINE B<impl>. B<ctx> must be initialized with | ||
27 | EVP_MD_CTX_init() before calling this function. | ||
28 | |||
29 | EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the | ||
30 | signature context B<ctx>. This function can be called several times on the | ||
31 | same B<ctx> to include additional data. | ||
32 | |||
33 | EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and | ||
34 | places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey) | ||
35 | bytes in size. B<s> is an OUT parameter, and not used as an IN parameter. | ||
36 | The number of bytes of data written (i.e. the length of the signature) | ||
37 | will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes | ||
38 | will be written. | ||
39 | |||
40 | EVP_SignInit() initializes a signing context B<ctx> to use the default | ||
41 | implementation of digest B<type>. | ||
42 | |||
43 | EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual | ||
44 | signature returned by EVP_SignFinal() may be smaller. | ||
45 | |||
46 | =head1 RETURN VALUES | ||
47 | |||
48 | EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1 | ||
49 | for success and 0 for failure. | ||
50 | |||
51 | EVP_PKEY_size() returns the maximum size of a signature in bytes. | ||
52 | |||
53 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
54 | |||
55 | =head1 NOTES | ||
56 | |||
57 | The B<EVP> interface to digital signatures should almost always be used in | ||
58 | preference to the low level interfaces. This is because the code then becomes | ||
59 | transparent to the algorithm used and much more flexible. | ||
60 | |||
61 | Due to the link between message digests and public key algorithms the correct | ||
62 | digest algorithm must be used with the correct public key type. A list of | ||
63 | algorithms and associated public key algorithms appears in | ||
64 | L<EVP_DigestInit(3)|EVP_DigestInit(3)>. | ||
65 | |||
66 | The call to EVP_SignFinal() internally finalizes a copy of the digest context. | ||
67 | This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called | ||
68 | later to digest and sign additional data. | ||
69 | |||
70 | Since only a copy of the digest context is ever finalized the context must | ||
71 | be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak | ||
72 | will occur. | ||
73 | |||
74 | =head1 BUGS | ||
75 | |||
76 | Older versions of this documentation wrongly stated that calls to | ||
77 | EVP_SignUpdate() could not be made after calling EVP_SignFinal(). | ||
78 | |||
79 | Since the private key is passed in the call to EVP_SignFinal() any error | ||
80 | relating to the private key (for example an unsuitable key and digest | ||
81 | combination) will not be indicated until after potentially large amounts of | ||
82 | data have been passed through EVP_SignUpdate(). | ||
83 | |||
84 | It is not possible to change the signing parameters using these function. | ||
85 | |||
86 | The previous two bugs are fixed in the newer EVP_SignDigest*() function. | ||
87 | |||
88 | =head1 SEE ALSO | ||
89 | |||
90 | L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, | ||
91 | L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, | ||
92 | L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, | ||
93 | L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>, | ||
94 | L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> | ||
95 | |||
96 | =head1 HISTORY | ||
97 | |||
98 | EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are | ||
99 | available in all versions of SSLeay and OpenSSL. | ||
100 | |||
101 | EVP_SignInit_ex() was added in OpenSSL 0.9.7. | ||
102 | |||
103 | =cut | ||
diff --git a/src/lib/libcrypto/doc/EVP_VerifyInit.pod b/src/lib/libcrypto/doc/EVP_VerifyInit.pod deleted file mode 100644 index b0d3f8e4c9..0000000000 --- a/src/lib/libcrypto/doc/EVP_VerifyInit.pod +++ /dev/null | |||
@@ -1,96 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification | ||
6 | functions | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); | ||
13 | int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); | ||
14 | int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey); | ||
15 | |||
16 | int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | The EVP signature verification routines are a high level interface to digital | ||
21 | signatures. | ||
22 | |||
23 | EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest | ||
24 | B<type> from ENGINE B<impl>. B<ctx> must be initialized by calling | ||
25 | EVP_MD_CTX_init() before calling this function. | ||
26 | |||
27 | EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the | ||
28 | verification context B<ctx>. This function can be called several times on the | ||
29 | same B<ctx> to include additional data. | ||
30 | |||
31 | EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey> | ||
32 | and against the B<siglen> bytes at B<sigbuf>. | ||
33 | |||
34 | EVP_VerifyInit() initializes verification context B<ctx> to use the default | ||
35 | implementation of digest B<type>. | ||
36 | |||
37 | =head1 RETURN VALUES | ||
38 | |||
39 | EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for | ||
40 | failure. | ||
41 | |||
42 | EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if | ||
43 | some other error occurred. | ||
44 | |||
45 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
46 | |||
47 | =head1 NOTES | ||
48 | |||
49 | The B<EVP> interface to digital signatures should almost always be used in | ||
50 | preference to the low level interfaces. This is because the code then becomes | ||
51 | transparent to the algorithm used and much more flexible. | ||
52 | |||
53 | Due to the link between message digests and public key algorithms the correct | ||
54 | digest algorithm must be used with the correct public key type. A list of | ||
55 | algorithms and associated public key algorithms appears in | ||
56 | L<EVP_DigestInit(3)|EVP_DigestInit(3)>. | ||
57 | |||
58 | The call to EVP_VerifyFinal() internally finalizes a copy of the digest context. | ||
59 | This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called | ||
60 | later to digest and verify additional data. | ||
61 | |||
62 | Since only a copy of the digest context is ever finalized the context must | ||
63 | be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak | ||
64 | will occur. | ||
65 | |||
66 | =head1 BUGS | ||
67 | |||
68 | Older versions of this documentation wrongly stated that calls to | ||
69 | EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal(). | ||
70 | |||
71 | Since the public key is passed in the call to EVP_SignFinal() any error | ||
72 | relating to the private key (for example an unsuitable key and digest | ||
73 | combination) will not be indicated until after potentially large amounts of | ||
74 | data have been passed through EVP_SignUpdate(). | ||
75 | |||
76 | It is not possible to change the signing parameters using these function. | ||
77 | |||
78 | The previous two bugs are fixed in the newer EVP_VerifyDigest*() function. | ||
79 | |||
80 | =head1 SEE ALSO | ||
81 | |||
82 | L<evp(3)|evp(3)>, | ||
83 | L<EVP_SignInit(3)|EVP_SignInit(3)>, | ||
84 | L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, | ||
85 | L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, | ||
86 | L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>, | ||
87 | L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> | ||
88 | |||
89 | =head1 HISTORY | ||
90 | |||
91 | EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are | ||
92 | available in all versions of SSLeay and OpenSSL. | ||
93 | |||
94 | EVP_VerifyInit_ex() was added in OpenSSL 0.9.7 | ||
95 | |||
96 | =cut | ||
diff --git a/src/lib/libcrypto/doc/HMAC.pod b/src/lib/libcrypto/doc/HMAC.pod deleted file mode 100644 index d92138d273..0000000000 --- a/src/lib/libcrypto/doc/HMAC.pod +++ /dev/null | |||
@@ -1,106 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message | ||
6 | authentication code | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/hmac.h> | ||
11 | |||
12 | unsigned char *HMAC(const EVP_MD *evp_md, const void *key, | ||
13 | int key_len, const unsigned char *d, int n, | ||
14 | unsigned char *md, unsigned int *md_len); | ||
15 | |||
16 | void HMAC_CTX_init(HMAC_CTX *ctx); | ||
17 | |||
18 | int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, | ||
19 | const EVP_MD *md); | ||
20 | int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, | ||
21 | const EVP_MD *md, ENGINE *impl); | ||
22 | int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); | ||
23 | int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); | ||
24 | |||
25 | void HMAC_CTX_cleanup(HMAC_CTX *ctx); | ||
26 | void HMAC_cleanup(HMAC_CTX *ctx); | ||
27 | |||
28 | =head1 DESCRIPTION | ||
29 | |||
30 | HMAC is a MAC (message authentication code), i.e. a keyed hash | ||
31 | function used for message authentication, which is based on a hash | ||
32 | function. | ||
33 | |||
34 | HMAC() computes the message authentication code of the B<n> bytes at | ||
35 | B<d> using the hash function B<evp_md> and the key B<key> which is | ||
36 | B<key_len> bytes long. | ||
37 | |||
38 | It places the result in B<md> (which must have space for the output of | ||
39 | the hash function, which is no more than B<EVP_MAX_MD_SIZE> bytes). | ||
40 | If B<md> is NULL, the digest is placed in a static array. The size of | ||
41 | the output is placed in B<md_len>, unless it is B<NULL>. | ||
42 | |||
43 | B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc. | ||
44 | |||
45 | HMAC_CTX_init() initialises a B<HMAC_CTX> before first use. It must be | ||
46 | called. | ||
47 | |||
48 | HMAC_CTX_cleanup() erases the key and other data from the B<HMAC_CTX> | ||
49 | and releases any associated resources. It must be called when an | ||
50 | B<HMAC_CTX> is no longer required. | ||
51 | |||
52 | HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back | ||
53 | compatibility with 0.9.6b, it is deprecated. | ||
54 | |||
55 | The following functions may be used if the message is not completely | ||
56 | stored in memory: | ||
57 | |||
58 | HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash | ||
59 | function B<evp_md> and the key B<key> which is B<key_len> bytes | ||
60 | long. It is deprecated and only included for backward compatibility | ||
61 | with OpenSSL 0.9.6b. | ||
62 | |||
63 | HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use | ||
64 | the function B<evp_md> and key B<key>. Either can be NULL, in which | ||
65 | case the existing one will be reused. HMAC_CTX_init() must have been | ||
66 | called before the first use of an B<HMAC_CTX> in this | ||
67 | function. B<N.B. HMAC_Init() had this undocumented behaviour in | ||
68 | previous versions of OpenSSL - failure to switch to HMAC_Init_ex() in | ||
69 | programs that expect it will cause them to stop working>. | ||
70 | |||
71 | HMAC_Update() can be called repeatedly with chunks of the message to | ||
72 | be authenticated (B<len> bytes at B<data>). | ||
73 | |||
74 | HMAC_Final() places the message authentication code in B<md>, which | ||
75 | must have space for the hash function output. | ||
76 | |||
77 | =head1 RETURN VALUES | ||
78 | |||
79 | HMAC() returns a pointer to the message authentication code or NULL if | ||
80 | an error occurred. | ||
81 | |||
82 | HMAC_Init_ex(), HMAC_Update() and HMAC_Final() return 1 for success or 0 if | ||
83 | an error occurred. | ||
84 | |||
85 | HMAC_CTX_init() and HMAC_CTX_cleanup() do not return values. | ||
86 | |||
87 | =head1 CONFORMING TO | ||
88 | |||
89 | RFC 2104 | ||
90 | |||
91 | =head1 SEE ALSO | ||
92 | |||
93 | L<sha(3)|sha(3)>, L<evp(3)|evp(3)> | ||
94 | |||
95 | =head1 HISTORY | ||
96 | |||
97 | HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() | ||
98 | are available since SSLeay 0.9.0. | ||
99 | |||
100 | HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available | ||
101 | since OpenSSL 0.9.7. | ||
102 | |||
103 | HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in | ||
104 | versions of OpenSSL before 1.0.0. | ||
105 | |||
106 | =cut | ||
diff --git a/src/lib/libcrypto/doc/MD5.pod b/src/lib/libcrypto/doc/MD5.pod deleted file mode 100644 index b0edd5416f..0000000000 --- a/src/lib/libcrypto/doc/MD5.pod +++ /dev/null | |||
@@ -1,101 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, | ||
6 | MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/md2.h> | ||
11 | |||
12 | unsigned char *MD2(const unsigned char *d, unsigned long n, | ||
13 | unsigned char *md); | ||
14 | |||
15 | int MD2_Init(MD2_CTX *c); | ||
16 | int MD2_Update(MD2_CTX *c, const unsigned char *data, | ||
17 | unsigned long len); | ||
18 | int MD2_Final(unsigned char *md, MD2_CTX *c); | ||
19 | |||
20 | |||
21 | #include <openssl/md4.h> | ||
22 | |||
23 | unsigned char *MD4(const unsigned char *d, unsigned long n, | ||
24 | unsigned char *md); | ||
25 | |||
26 | int MD4_Init(MD4_CTX *c); | ||
27 | int MD4_Update(MD4_CTX *c, const void *data, | ||
28 | unsigned long len); | ||
29 | int MD4_Final(unsigned char *md, MD4_CTX *c); | ||
30 | |||
31 | |||
32 | #include <openssl/md5.h> | ||
33 | |||
34 | unsigned char *MD5(const unsigned char *d, unsigned long n, | ||
35 | unsigned char *md); | ||
36 | |||
37 | int MD5_Init(MD5_CTX *c); | ||
38 | int MD5_Update(MD5_CTX *c, const void *data, | ||
39 | unsigned long len); | ||
40 | int MD5_Final(unsigned char *md, MD5_CTX *c); | ||
41 | |||
42 | =head1 DESCRIPTION | ||
43 | |||
44 | MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. | ||
45 | |||
46 | MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest | ||
47 | of the B<n> bytes at B<d> and place it in B<md> (which must have space | ||
48 | for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 | ||
49 | bytes of output). If B<md> is NULL, the digest is placed in a static | ||
50 | array. | ||
51 | |||
52 | The following functions may be used if the message is not completely | ||
53 | stored in memory: | ||
54 | |||
55 | MD2_Init() initializes a B<MD2_CTX> structure. | ||
56 | |||
57 | MD2_Update() can be called repeatedly with chunks of the message to | ||
58 | be hashed (B<len> bytes at B<data>). | ||
59 | |||
60 | MD2_Final() places the message digest in B<md>, which must have space | ||
61 | for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MD2_CTX>. | ||
62 | |||
63 | MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and | ||
64 | MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure. | ||
65 | |||
66 | Applications should use the higher level functions | ||
67 | L<EVP_DigestInit(3)|EVP_DigestInit(3)> | ||
68 | etc. instead of calling the hash functions directly. | ||
69 | |||
70 | =head1 NOTE | ||
71 | |||
72 | MD2, MD4, and MD5 are recommended only for compatibility with existing | ||
73 | applications. In new applications, SHA-1 or RIPEMD-160 should be | ||
74 | preferred. | ||
75 | |||
76 | =head1 RETURN VALUES | ||
77 | |||
78 | MD2(), MD4(), and MD5() return pointers to the hash value. | ||
79 | |||
80 | MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), | ||
81 | MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for | ||
82 | success, 0 otherwise. | ||
83 | |||
84 | =head1 CONFORMING TO | ||
85 | |||
86 | RFC 1319, RFC 1320, RFC 1321 | ||
87 | |||
88 | =head1 SEE ALSO | ||
89 | |||
90 | L<sha(3)|sha(3)>, L<ripemd(3)|ripemd(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> | ||
91 | |||
92 | =head1 HISTORY | ||
93 | |||
94 | MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), | ||
95 | MD5_Update() and MD5_Final() are available in all versions of SSLeay | ||
96 | and OpenSSL. | ||
97 | |||
98 | MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and | ||
99 | above. | ||
100 | |||
101 | =cut | ||
diff --git a/src/lib/libcrypto/doc/OBJ_nid2obj.pod b/src/lib/libcrypto/doc/OBJ_nid2obj.pod deleted file mode 100644 index 95949ac091..0000000000 --- a/src/lib/libcrypto/doc/OBJ_nid2obj.pod +++ /dev/null | |||
@@ -1,147 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, | ||
6 | OBJ_sn2nid, OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup | ||
7 | - ASN1 object utility functions | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/objects.h> | ||
12 | |||
13 | ASN1_OBJECT * OBJ_nid2obj(int n); | ||
14 | const char * OBJ_nid2ln(int n); | ||
15 | const char * OBJ_nid2sn(int n); | ||
16 | |||
17 | int OBJ_obj2nid(const ASN1_OBJECT *o); | ||
18 | int OBJ_ln2nid(const char *ln); | ||
19 | int OBJ_sn2nid(const char *sn); | ||
20 | |||
21 | int OBJ_txt2nid(const char *s); | ||
22 | |||
23 | ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name); | ||
24 | int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name); | ||
25 | |||
26 | int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b); | ||
27 | ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o); | ||
28 | |||
29 | int OBJ_create(const char *oid,const char *sn,const char *ln); | ||
30 | void OBJ_cleanup(void); | ||
31 | |||
32 | =head1 DESCRIPTION | ||
33 | |||
34 | The ASN1 object utility functions process ASN1_OBJECT structures which are | ||
35 | a representation of the ASN1 OBJECT IDENTIFIER (OID) type. | ||
36 | |||
37 | OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to | ||
38 | an ASN1_OBJECT structure, its long name and its short name respectively, | ||
39 | or B<NULL> is an error occurred. | ||
40 | |||
41 | OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID | ||
42 | for the object B<o>, the long name <ln> or the short name <sn> respectively | ||
43 | or NID_undef if an error occurred. | ||
44 | |||
45 | OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be | ||
46 | a long name, a short name or the numerical representation of an object. | ||
47 | |||
48 | OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure. | ||
49 | If B<no_name> is 0 then long names and short names will be interpreted | ||
50 | as well as numerical forms. If B<no_name> is 1 only the numerical form | ||
51 | is acceptable. | ||
52 | |||
53 | OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation. | ||
54 | The representation is written as a null terminated string to B<buf> | ||
55 | at most B<buf_len> bytes are written, truncating the result if necessary. | ||
56 | The total amount of space required is returned. If B<no_name> is 0 then | ||
57 | if the object has a long or short name then that will be used, otherwise | ||
58 | the numerical form will be used. If B<no_name> is 1 then the numerical | ||
59 | form will always be used. | ||
60 | |||
61 | OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned. | ||
62 | |||
63 | OBJ_dup() returns a copy of B<o>. | ||
64 | |||
65 | OBJ_create() adds a new object to the internal table. B<oid> is the | ||
66 | numerical form of the object, B<sn> the short name and B<ln> the | ||
67 | long name. A new NID is returned for the created object. | ||
68 | |||
69 | OBJ_cleanup() cleans up OpenSSLs internal object table: this should | ||
70 | be called before an application exits if any new objects were added | ||
71 | using OBJ_create(). | ||
72 | |||
73 | =head1 NOTES | ||
74 | |||
75 | Objects in OpenSSL can have a short name, a long name and a numerical | ||
76 | identifier (NID) associated with them. A standard set of objects is | ||
77 | represented in an internal table. The appropriate values are defined | ||
78 | in the header file B<objects.h>. | ||
79 | |||
80 | For example the OID for commonName has the following definitions: | ||
81 | |||
82 | #define SN_commonName "CN" | ||
83 | #define LN_commonName "commonName" | ||
84 | #define NID_commonName 13 | ||
85 | |||
86 | New objects can be added by calling OBJ_create(). | ||
87 | |||
88 | Table objects have certain advantages over other objects: for example | ||
89 | their NIDs can be used in a C language switch statement. They are | ||
90 | also static constant structures which are shared: that is there | ||
91 | is only a single constant structure for each table object. | ||
92 | |||
93 | Objects which are not in the table have the NID value NID_undef. | ||
94 | |||
95 | Objects do not need to be in the internal tables to be processed, | ||
96 | the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical | ||
97 | form of an OID. | ||
98 | |||
99 | =head1 EXAMPLES | ||
100 | |||
101 | Create an object for B<commonName>: | ||
102 | |||
103 | ASN1_OBJECT *o; | ||
104 | o = OBJ_nid2obj(NID_commonName); | ||
105 | |||
106 | Check if an object is B<commonName> | ||
107 | |||
108 | if (OBJ_obj2nid(obj) == NID_commonName) | ||
109 | /* Do something */ | ||
110 | |||
111 | Create a new NID and initialize an object from it: | ||
112 | |||
113 | int new_nid; | ||
114 | ASN1_OBJECT *obj; | ||
115 | new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); | ||
116 | |||
117 | obj = OBJ_nid2obj(new_nid); | ||
118 | |||
119 | Create a new object directly: | ||
120 | |||
121 | obj = OBJ_txt2obj("1.2.3.4", 1); | ||
122 | |||
123 | =head1 BUGS | ||
124 | |||
125 | OBJ_obj2txt() is awkward and messy to use: it doesn't follow the | ||
126 | convention of other OpenSSL functions where the buffer can be set | ||
127 | to B<NULL> to determine the amount of data that should be written. | ||
128 | Instead B<buf> must point to a valid buffer and B<buf_len> should | ||
129 | be set to a positive value. A buffer length of 80 should be more | ||
130 | than enough to handle any OID encountered in practice. | ||
131 | |||
132 | =head1 RETURN VALUES | ||
133 | |||
134 | OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an | ||
135 | error occurred. | ||
136 | |||
137 | OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> | ||
138 | on error. | ||
139 | |||
140 | OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return | ||
141 | a NID or B<NID_undef> on error. | ||
142 | |||
143 | =head1 SEE ALSO | ||
144 | |||
145 | L<ERR_get_error(3)|ERR_get_error(3)> | ||
146 | |||
147 | =cut | ||
diff --git a/src/lib/libcrypto/doc/OPENSSL_VERSION_NUMBER.pod b/src/lib/libcrypto/doc/OPENSSL_VERSION_NUMBER.pod deleted file mode 100644 index 2f63a18a71..0000000000 --- a/src/lib/libcrypto/doc/OPENSSL_VERSION_NUMBER.pod +++ /dev/null | |||
@@ -1,101 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/opensslv.h> | ||
10 | #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL | ||
11 | |||
12 | #include <openssl/crypto.h> | ||
13 | long SSLeay(void); | ||
14 | const char *SSLeay_version(int t); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | OPENSSL_VERSION_NUMBER is a numeric release version identifier: | ||
19 | |||
20 | MMNNFFPPS: major minor fix patch status | ||
21 | |||
22 | The status nibble has one of the values 0 for development, 1 to e for betas | ||
23 | 1 to 14, and f for release. | ||
24 | |||
25 | for example | ||
26 | |||
27 | 0x000906000 == 0.9.6 dev | ||
28 | 0x000906023 == 0.9.6b beta 3 | ||
29 | 0x00090605f == 0.9.6e release | ||
30 | |||
31 | Versions prior to 0.9.3 have identifiers E<lt> 0x0930. | ||
32 | Versions between 0.9.3 and 0.9.5 had a version identifier with this | ||
33 | interpretation: | ||
34 | |||
35 | MMNNFFRBB major minor fix final beta/patch | ||
36 | |||
37 | for example | ||
38 | |||
39 | 0x000904100 == 0.9.4 release | ||
40 | 0x000905000 == 0.9.5 dev | ||
41 | |||
42 | Version 0.9.5a had an interim interpretation that is like the current one, | ||
43 | except the patch level got the highest bit set, to keep continuity. The | ||
44 | number was therefore 0x0090581f. | ||
45 | |||
46 | |||
47 | For backward compatibility, SSLEAY_VERSION_NUMBER is also defined. | ||
48 | |||
49 | SSLeay() returns this number. The return value can be compared to the | ||
50 | macro to make sure that the correct version of the library has been | ||
51 | loaded, especially when using DLLs on Windows systems. | ||
52 | |||
53 | SSLeay_version() returns different strings depending on B<t>: | ||
54 | |||
55 | =over 4 | ||
56 | |||
57 | =item SSLEAY_VERSION | ||
58 | |||
59 | The text variant of the version number and the release date. For example, | ||
60 | "OpenSSL 0.9.5a 1 Apr 2000". | ||
61 | |||
62 | =item SSLEAY_CFLAGS | ||
63 | |||
64 | The compiler flags set for the compilation process in the form | ||
65 | "compiler: ..." if available or "compiler: information not available" | ||
66 | otherwise. | ||
67 | |||
68 | =item SSLEAY_BUILT_ON | ||
69 | |||
70 | The date of the build process in the form "built on: ..." if available | ||
71 | or "built on: date not available" otherwise. | ||
72 | |||
73 | =item SSLEAY_PLATFORM | ||
74 | |||
75 | The "Configure" target of the library build in the form "platform: ..." | ||
76 | if available or "platform: information not available" otherwise. | ||
77 | |||
78 | =item SSLEAY_DIR | ||
79 | |||
80 | The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "..."" | ||
81 | if available or "OPENSSLDIR: N/A" otherwise. | ||
82 | |||
83 | =back | ||
84 | |||
85 | For an unknown B<t>, the text "not available" is returned. | ||
86 | |||
87 | =head1 RETURN VALUE | ||
88 | |||
89 | The version number. | ||
90 | |||
91 | =head1 SEE ALSO | ||
92 | |||
93 | L<crypto(3)|crypto(3)> | ||
94 | |||
95 | =head1 HISTORY | ||
96 | |||
97 | SSLeay() and SSLEAY_VERSION_NUMBER are available in all versions of SSLeay and | ||
98 | OpenSSL. OPENSSL_VERSION_NUMBER is available in all versions of OpenSSL. | ||
99 | B<SSLEAY_DIR> was added in OpenSSL 0.9.7. | ||
100 | |||
101 | =cut | ||
diff --git a/src/lib/libcrypto/doc/OPENSSL_config.pod b/src/lib/libcrypto/doc/OPENSSL_config.pod deleted file mode 100644 index 897d2cce59..0000000000 --- a/src/lib/libcrypto/doc/OPENSSL_config.pod +++ /dev/null | |||
@@ -1,82 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/conf.h> | ||
10 | |||
11 | void OPENSSL_config(const char *config_name); | ||
12 | void OPENSSL_no_config(void); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf> | ||
17 | configuration file name using B<config_name>. If B<config_name> is NULL then | ||
18 | the default name B<openssl_conf> will be used. Any errors are ignored. Further | ||
19 | calls to OPENSSL_config() will have no effect. The configuration file format | ||
20 | is documented in the L<conf(5)|conf(5)> manual page. | ||
21 | |||
22 | OPENSSL_no_config() disables configuration. If called before OPENSSL_config() | ||
23 | no configuration takes place. | ||
24 | |||
25 | =head1 NOTES | ||
26 | |||
27 | It is B<strongly> recommended that B<all> new applications call OPENSSL_config() | ||
28 | or the more sophisticated functions such as CONF_modules_load() during | ||
29 | initialization (that is before starting any threads). By doing this | ||
30 | an application does not need to keep track of all configuration options | ||
31 | and some new functionality can be supported automatically. | ||
32 | |||
33 | It is also possible to automatically call OPENSSL_config() when an application | ||
34 | calls OPENSSL_add_all_algorithms() by compiling an application with the | ||
35 | preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd. In this way configuration | ||
36 | can be added without source changes. | ||
37 | |||
38 | The environment variable B<OPENSSL_CONF> can be set to specify the location | ||
39 | of the configuration file. | ||
40 | |||
41 | Currently ASN1 OBJECTs and ENGINE configuration can be performed future | ||
42 | versions of OpenSSL will add new configuration options. | ||
43 | |||
44 | There are several reasons why calling the OpenSSL configuration routines is | ||
45 | advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7. | ||
46 | In OpenSSL 0.9.7 control functions can be supported by ENGINEs, this can be | ||
47 | used (among other things) to load dynamic ENGINEs from shared libraries (DSOs). | ||
48 | However very few applications currently support the control interface and so | ||
49 | very few can load and use dynamic ENGINEs. Equally in future more sophisticated | ||
50 | ENGINEs will require certain control operations to customize them. If an | ||
51 | application calls OPENSSL_config() it doesn't need to know or care about | ||
52 | ENGINE control operations because they can be performed by editing a | ||
53 | configuration file. | ||
54 | |||
55 | Applications should free up configuration at application closedown by calling | ||
56 | CONF_modules_free(). | ||
57 | |||
58 | =head1 RESTRICTIONS | ||
59 | |||
60 | The OPENSSL_config() function is designed to be a very simple "call it and | ||
61 | forget it" function. As a result its behaviour is somewhat limited. It ignores | ||
62 | all errors silently and it can only load from the standard configuration file | ||
63 | location for example. | ||
64 | |||
65 | It is however B<much> better than nothing. Applications which need finer | ||
66 | control over their configuration functionality should use the configuration | ||
67 | functions such as CONF_load_modules() directly. | ||
68 | |||
69 | =head1 RETURN VALUES | ||
70 | |||
71 | Neither OPENSSL_config() nor OPENSSL_no_config() return a value. | ||
72 | |||
73 | =head1 SEE ALSO | ||
74 | |||
75 | L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>, | ||
76 | L<CONF_modules_free(3)|CONF_modules_free(3)> | ||
77 | |||
78 | =head1 HISTORY | ||
79 | |||
80 | OPENSSL_config() and OPENSSL_no_config() first appeared in OpenSSL 0.9.7 | ||
81 | |||
82 | =cut | ||
diff --git a/src/lib/libcrypto/doc/OPENSSL_load_builtin_modules.pod b/src/lib/libcrypto/doc/OPENSSL_load_builtin_modules.pod deleted file mode 100644 index 828fec651d..0000000000 --- a/src/lib/libcrypto/doc/OPENSSL_load_builtin_modules.pod +++ /dev/null | |||
@@ -1,51 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add standard configuration modules | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/conf.h> | ||
10 | |||
11 | void OPENSSL_load_builtin_modules(void); | ||
12 | void ASN1_add_oid_module(void); | ||
13 | ENGINE_add_conf_module(); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | The function OPENSSL_load_builtin_modules() adds all the standard OpenSSL | ||
18 | configuration modules to the internal list. They can then be used by the | ||
19 | OpenSSL configuration code. | ||
20 | |||
21 | ASN1_add_oid_module() adds just the ASN1 OBJECT module. | ||
22 | |||
23 | ENGINE_add_conf_module() adds just the ENGINE configuration module. | ||
24 | |||
25 | =head1 NOTES | ||
26 | |||
27 | If the simple configuration function OPENSSL_config() is called then | ||
28 | OPENSSL_load_builtin_modules() is called automatically. | ||
29 | |||
30 | Applications which use the configuration functions directly will need to | ||
31 | call OPENSSL_load_builtin_modules() themselves I<before> any other | ||
32 | configuration code. | ||
33 | |||
34 | Applications should call OPENSSL_load_builtin_modules() to load all | ||
35 | configuration modules instead of adding modules selectively: otherwise | ||
36 | functionality may be missing from the application if an when new | ||
37 | modules are added. | ||
38 | |||
39 | =head1 RETURN VALUE | ||
40 | |||
41 | None of the functions return a value. | ||
42 | |||
43 | =head1 SEE ALSO | ||
44 | |||
45 | L<conf(3)|conf(3)>, L<OPENSSL_config(3)|OPENSSL_config(3)> | ||
46 | |||
47 | =head1 HISTORY | ||
48 | |||
49 | These functions first appeared in OpenSSL 0.9.7. | ||
50 | |||
51 | =cut | ||
diff --git a/src/lib/libcrypto/doc/OpenSSL_add_all_algorithms.pod b/src/lib/libcrypto/doc/OpenSSL_add_all_algorithms.pod deleted file mode 100644 index 1bba4d0212..0000000000 --- a/src/lib/libcrypto/doc/OpenSSL_add_all_algorithms.pod +++ /dev/null | |||
@@ -1,66 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests, EVP_cleanup - | ||
6 | add algorithms to internal table | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/evp.h> | ||
11 | |||
12 | void OpenSSL_add_all_algorithms(void); | ||
13 | void OpenSSL_add_all_ciphers(void); | ||
14 | void OpenSSL_add_all_digests(void); | ||
15 | |||
16 | void EVP_cleanup(void); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | OpenSSL keeps an internal table of digest algorithms and ciphers. It uses | ||
21 | this table to lookup ciphers via functions such as EVP_get_cipher_byname(). | ||
22 | |||
23 | OpenSSL_add_all_digests() adds all digest algorithms to the table. | ||
24 | |||
25 | OpenSSL_add_all_algorithms() adds all algorithms to the table (digests and | ||
26 | ciphers). | ||
27 | |||
28 | OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including | ||
29 | password based encryption algorithms. | ||
30 | |||
31 | EVP_cleanup() removes all ciphers and digests from the table. | ||
32 | |||
33 | =head1 RETURN VALUES | ||
34 | |||
35 | None of the functions return a value. | ||
36 | |||
37 | =head1 NOTES | ||
38 | |||
39 | A typical application will call OpenSSL_add_all_algorithms() initially and | ||
40 | EVP_cleanup() before exiting. | ||
41 | |||
42 | An application does not need to add algorithms to use them explicitly, for | ||
43 | example by EVP_sha1(). It just needs to add them if it (or any of the functions | ||
44 | it calls) needs to lookup algorithms. | ||
45 | |||
46 | The cipher and digest lookup functions are used in many parts of the library. | ||
47 | If the table is not initialized several functions will misbehave and complain | ||
48 | they cannot find algorithms. This includes the PEM, PKCS#12, SSL and S/MIME | ||
49 | libraries. This is a common query in the OpenSSL mailing lists. | ||
50 | |||
51 | Calling OpenSSL_add_all_algorithms() links in all algorithms: as a result a | ||
52 | statically linked executable can be quite large. If this is important it is | ||
53 | possible to just add the required ciphers and digests. | ||
54 | |||
55 | =head1 BUGS | ||
56 | |||
57 | Although the functions do not return error codes it is possible for them to | ||
58 | fail. This will only happen as a result of a memory allocation failure so this | ||
59 | is not too much of a problem in practice. | ||
60 | |||
61 | =head1 SEE ALSO | ||
62 | |||
63 | L<evp(3)|evp(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>, | ||
64 | L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> | ||
65 | |||
66 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod b/src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod deleted file mode 100644 index 6d87079a84..0000000000 --- a/src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod +++ /dev/null | |||
@@ -1,498 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, | ||
6 | PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, | ||
7 | PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, | ||
8 | PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, | ||
9 | PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, | ||
10 | PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, | ||
11 | PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, | ||
12 | PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, | ||
13 | PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, | ||
14 | PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, | ||
15 | PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, | ||
16 | PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, | ||
17 | PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, | ||
18 | PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, | ||
19 | PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, | ||
20 | PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, | ||
21 | PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, | ||
22 | PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, | ||
23 | PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, | ||
24 | PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, | ||
25 | PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, | ||
26 | PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, | ||
27 | PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines | ||
28 | |||
29 | =head1 SYNOPSIS | ||
30 | |||
31 | #include <openssl/pem.h> | ||
32 | |||
33 | EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, | ||
34 | pem_password_cb *cb, void *u); | ||
35 | |||
36 | EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, | ||
37 | pem_password_cb *cb, void *u); | ||
38 | |||
39 | int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, | ||
40 | unsigned char *kstr, int klen, | ||
41 | pem_password_cb *cb, void *u); | ||
42 | |||
43 | int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, | ||
44 | unsigned char *kstr, int klen, | ||
45 | pem_password_cb *cb, void *u); | ||
46 | |||
47 | int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, | ||
48 | char *kstr, int klen, | ||
49 | pem_password_cb *cb, void *u); | ||
50 | |||
51 | int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, | ||
52 | char *kstr, int klen, | ||
53 | pem_password_cb *cb, void *u); | ||
54 | |||
55 | int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, | ||
56 | char *kstr, int klen, | ||
57 | pem_password_cb *cb, void *u); | ||
58 | |||
59 | int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, | ||
60 | char *kstr, int klen, | ||
61 | pem_password_cb *cb, void *u); | ||
62 | |||
63 | EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, | ||
64 | pem_password_cb *cb, void *u); | ||
65 | |||
66 | EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, | ||
67 | pem_password_cb *cb, void *u); | ||
68 | |||
69 | int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); | ||
70 | int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); | ||
71 | |||
72 | RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, | ||
73 | pem_password_cb *cb, void *u); | ||
74 | |||
75 | RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, | ||
76 | pem_password_cb *cb, void *u); | ||
77 | |||
78 | int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, | ||
79 | unsigned char *kstr, int klen, | ||
80 | pem_password_cb *cb, void *u); | ||
81 | |||
82 | int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, | ||
83 | unsigned char *kstr, int klen, | ||
84 | pem_password_cb *cb, void *u); | ||
85 | |||
86 | RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, | ||
87 | pem_password_cb *cb, void *u); | ||
88 | |||
89 | RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, | ||
90 | pem_password_cb *cb, void *u); | ||
91 | |||
92 | int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); | ||
93 | |||
94 | int PEM_write_RSAPublicKey(FILE *fp, RSA *x); | ||
95 | |||
96 | RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, | ||
97 | pem_password_cb *cb, void *u); | ||
98 | |||
99 | RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, | ||
100 | pem_password_cb *cb, void *u); | ||
101 | |||
102 | int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); | ||
103 | |||
104 | int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); | ||
105 | |||
106 | DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, | ||
107 | pem_password_cb *cb, void *u); | ||
108 | |||
109 | DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, | ||
110 | pem_password_cb *cb, void *u); | ||
111 | |||
112 | int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, | ||
113 | unsigned char *kstr, int klen, | ||
114 | pem_password_cb *cb, void *u); | ||
115 | |||
116 | int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, | ||
117 | unsigned char *kstr, int klen, | ||
118 | pem_password_cb *cb, void *u); | ||
119 | |||
120 | DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, | ||
121 | pem_password_cb *cb, void *u); | ||
122 | |||
123 | DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, | ||
124 | pem_password_cb *cb, void *u); | ||
125 | |||
126 | int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); | ||
127 | |||
128 | int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); | ||
129 | |||
130 | DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); | ||
131 | |||
132 | DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); | ||
133 | |||
134 | int PEM_write_bio_DSAparams(BIO *bp, DSA *x); | ||
135 | |||
136 | int PEM_write_DSAparams(FILE *fp, DSA *x); | ||
137 | |||
138 | DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); | ||
139 | |||
140 | DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); | ||
141 | |||
142 | int PEM_write_bio_DHparams(BIO *bp, DH *x); | ||
143 | |||
144 | int PEM_write_DHparams(FILE *fp, DH *x); | ||
145 | |||
146 | X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); | ||
147 | |||
148 | X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); | ||
149 | |||
150 | int PEM_write_bio_X509(BIO *bp, X509 *x); | ||
151 | |||
152 | int PEM_write_X509(FILE *fp, X509 *x); | ||
153 | |||
154 | X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); | ||
155 | |||
156 | X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); | ||
157 | |||
158 | int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); | ||
159 | |||
160 | int PEM_write_X509_AUX(FILE *fp, X509 *x); | ||
161 | |||
162 | X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, | ||
163 | pem_password_cb *cb, void *u); | ||
164 | |||
165 | X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, | ||
166 | pem_password_cb *cb, void *u); | ||
167 | |||
168 | int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); | ||
169 | |||
170 | int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); | ||
171 | |||
172 | int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); | ||
173 | |||
174 | int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); | ||
175 | |||
176 | X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, | ||
177 | pem_password_cb *cb, void *u); | ||
178 | X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, | ||
179 | pem_password_cb *cb, void *u); | ||
180 | int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); | ||
181 | int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); | ||
182 | |||
183 | PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); | ||
184 | |||
185 | PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); | ||
186 | |||
187 | int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); | ||
188 | |||
189 | int PEM_write_PKCS7(FILE *fp, PKCS7 *x); | ||
190 | |||
191 | NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, | ||
192 | NETSCAPE_CERT_SEQUENCE **x, | ||
193 | pem_password_cb *cb, void *u); | ||
194 | |||
195 | NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp, | ||
196 | NETSCAPE_CERT_SEQUENCE **x, | ||
197 | pem_password_cb *cb, void *u); | ||
198 | |||
199 | int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x); | ||
200 | |||
201 | int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x); | ||
202 | |||
203 | =head1 DESCRIPTION | ||
204 | |||
205 | The PEM functions read or write structures in PEM format. In | ||
206 | this sense PEM format is simply base64 encoded data surrounded | ||
207 | by header lines. | ||
208 | |||
209 | For more details about the meaning of arguments see the | ||
210 | B<PEM FUNCTION ARGUMENTS> section. | ||
211 | |||
212 | Each operation has four functions associated with it. For | ||
213 | clarity the term "B<foobar> functions" will be used to collectively | ||
214 | refer to the PEM_read_bio_foobar(), PEM_read_foobar(), | ||
215 | PEM_write_bio_foobar() and PEM_write_foobar() functions. | ||
216 | |||
217 | The B<PrivateKey> functions read or write a private key in | ||
218 | PEM format using an EVP_PKEY structure. The write routines use | ||
219 | "traditional" private key format and can handle both RSA and DSA | ||
220 | private keys. The read functions can additionally transparently | ||
221 | handle PKCS#8 format encrypted and unencrypted keys too. | ||
222 | |||
223 | PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() | ||
224 | write a private key in an EVP_PKEY structure in PKCS#8 | ||
225 | EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption | ||
226 | algorithms. The B<cipher> argument specifies the encryption algorithm to | ||
227 | use: unlike all other PEM routines the encryption is applied at the | ||
228 | PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no | ||
229 | encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. | ||
230 | |||
231 | PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() | ||
232 | also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however | ||
233 | it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm | ||
234 | to use is specified in the B<nid> parameter and should be the NID of the | ||
235 | corresponding OBJECT IDENTIFIER (see NOTES section). | ||
236 | |||
237 | The B<PUBKEY> functions process a public key using an EVP_PKEY | ||
238 | structure. The public key is encoded as a SubjectPublicKeyInfo | ||
239 | structure. | ||
240 | |||
241 | The B<RSAPrivateKey> functions process an RSA private key using an | ||
242 | RSA structure. It handles the same formats as the B<PrivateKey> | ||
243 | functions but an error occurs if the private key is not RSA. | ||
244 | |||
245 | The B<RSAPublicKey> functions process an RSA public key using an | ||
246 | RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey | ||
247 | structure. | ||
248 | |||
249 | The B<RSA_PUBKEY> functions also process an RSA public key using | ||
250 | an RSA structure. However the public key is encoded using a | ||
251 | SubjectPublicKeyInfo structure and an error occurs if the public | ||
252 | key is not RSA. | ||
253 | |||
254 | The B<DSAPrivateKey> functions process a DSA private key using a | ||
255 | DSA structure. It handles the same formats as the B<PrivateKey> | ||
256 | functions but an error occurs if the private key is not DSA. | ||
257 | |||
258 | The B<DSA_PUBKEY> functions process a DSA public key using | ||
259 | a DSA structure. The public key is encoded using a | ||
260 | SubjectPublicKeyInfo structure and an error occurs if the public | ||
261 | key is not DSA. | ||
262 | |||
263 | The B<DSAparams> functions process DSA parameters using a DSA | ||
264 | structure. The parameters are encoded using a foobar structure. | ||
265 | |||
266 | The B<DHparams> functions process DH parameters using a DH | ||
267 | structure. The parameters are encoded using a PKCS#3 DHparameter | ||
268 | structure. | ||
269 | |||
270 | The B<X509> functions process an X509 certificate using an X509 | ||
271 | structure. They will also process a trusted X509 certificate but | ||
272 | any trust settings are discarded. | ||
273 | |||
274 | The B<X509_AUX> functions process a trusted X509 certificate using | ||
275 | an X509 structure. | ||
276 | |||
277 | The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10 | ||
278 | certificate request using an X509_REQ structure. The B<X509_REQ> | ||
279 | write functions use B<CERTIFICATE REQUEST> in the header whereas | ||
280 | the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST> | ||
281 | (as required by some CAs). The B<X509_REQ> read functions will | ||
282 | handle either form so there are no B<X509_REQ_NEW> read functions. | ||
283 | |||
284 | The B<X509_CRL> functions process an X509 CRL using an X509_CRL | ||
285 | structure. | ||
286 | |||
287 | The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7 | ||
288 | structure. | ||
289 | |||
290 | The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate | ||
291 | Sequence using a NETSCAPE_CERT_SEQUENCE structure. | ||
292 | |||
293 | =head1 PEM FUNCTION ARGUMENTS | ||
294 | |||
295 | The PEM functions have many common arguments. | ||
296 | |||
297 | The B<bp> BIO parameter (if present) specifies the BIO to read from | ||
298 | or write to. | ||
299 | |||
300 | The B<fp> FILE parameter (if present) specifies the FILE pointer to | ||
301 | read from or write to. | ||
302 | |||
303 | The PEM read functions all take an argument B<TYPE **x> and return | ||
304 | a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function | ||
305 | uses. If B<x> is NULL then the parameter is ignored. If B<x> is not | ||
306 | NULL but B<*x> is NULL then the structure returned will be written | ||
307 | to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made | ||
308 | to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections). | ||
309 | Irrespective of the value of B<x> a pointer to the structure is always | ||
310 | returned (or NULL if an error occurred). | ||
311 | |||
312 | The PEM functions which write private keys take an B<enc> parameter | ||
313 | which specifies the encryption algorithm to use, encryption is done | ||
314 | at the PEM level. If this parameter is set to NULL then the private | ||
315 | key is written in unencrypted form. | ||
316 | |||
317 | The B<cb> argument is the callback to use when querying for the pass | ||
318 | phrase used for encrypted PEM structures (normally only private keys). | ||
319 | |||
320 | For the PEM write routines if the B<kstr> parameter is not NULL then | ||
321 | B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is | ||
322 | ignored. | ||
323 | |||
324 | If the B<cb> parameters is set to NULL and the B<u> parameter is not | ||
325 | NULL then the B<u> parameter is interpreted as a null terminated string | ||
326 | to use as the passphrase. If both B<cb> and B<u> are NULL then the | ||
327 | default callback routine is used which will typically prompt for the | ||
328 | passphrase on the current terminal with echoing turned off. | ||
329 | |||
330 | The default passphrase callback is sometimes inappropriate (for example | ||
331 | in a GUI application) so an alternative can be supplied. The callback | ||
332 | routine has the following form: | ||
333 | |||
334 | int cb(char *buf, int size, int rwflag, void *u); | ||
335 | |||
336 | B<buf> is the buffer to write the passphrase to. B<size> is the maximum | ||
337 | length of the passphrase (i.e. the size of buf). B<rwflag> is a flag | ||
338 | which is set to 0 when reading and 1 when writing. A typical routine | ||
339 | will ask the user to verify the passphrase (for example by prompting | ||
340 | for it twice) if B<rwflag> is 1. The B<u> parameter has the same | ||
341 | value as the B<u> parameter passed to the PEM routine. It allows | ||
342 | arbitrary data to be passed to the callback by the application | ||
343 | (for example a window handle in a GUI application). The callback | ||
344 | B<must> return the number of characters in the passphrase or 0 if | ||
345 | an error occurred. | ||
346 | |||
347 | =head1 EXAMPLES | ||
348 | |||
349 | Although the PEM routines take several arguments in almost all applications | ||
350 | most of them are set to 0 or NULL. | ||
351 | |||
352 | Read a certificate in PEM format from a BIO: | ||
353 | |||
354 | X509 *x; | ||
355 | x = PEM_read_bio_X509(bp, NULL, 0, NULL); | ||
356 | if (x == NULL) { | ||
357 | /* Error */ | ||
358 | } | ||
359 | |||
360 | Alternative method: | ||
361 | |||
362 | X509 *x = NULL; | ||
363 | if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { | ||
364 | /* Error */ | ||
365 | } | ||
366 | |||
367 | Write a certificate to a BIO: | ||
368 | |||
369 | if (!PEM_write_bio_X509(bp, x)) { | ||
370 | /* Error */ | ||
371 | } | ||
372 | |||
373 | Write an unencrypted private key to a FILE pointer: | ||
374 | |||
375 | if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) { | ||
376 | /* Error */ | ||
377 | } | ||
378 | |||
379 | Write a private key (using traditional format) to a BIO using | ||
380 | triple DES encryption, the pass phrase is prompted for: | ||
381 | |||
382 | if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), | ||
383 | NULL, 0, 0, NULL)) { | ||
384 | /* Error */ | ||
385 | } | ||
386 | |||
387 | Write a private key (using PKCS#8 format) to a BIO using triple | ||
388 | DES encryption, using the pass phrase "hello": | ||
389 | |||
390 | if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), | ||
391 | NULL, 0, 0, "hello")) { | ||
392 | /* Error */ | ||
393 | } | ||
394 | |||
395 | Read a private key from a BIO using the pass phrase "hello": | ||
396 | |||
397 | key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); | ||
398 | if (key == NULL) { | ||
399 | /* Error */ | ||
400 | } | ||
401 | |||
402 | Read a private key from a BIO using a pass phrase callback: | ||
403 | |||
404 | key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); | ||
405 | if (key == NULL) { | ||
406 | /* Error */ | ||
407 | } | ||
408 | |||
409 | Skeleton pass phrase callback: | ||
410 | |||
411 | int | ||
412 | pass_cb(char *buf, int size, int rwflag, void *u) | ||
413 | { | ||
414 | int len; | ||
415 | char *tmp; | ||
416 | |||
417 | /* We'd probably do something else if 'rwflag' is 1 */ | ||
418 | printf("Enter pass phrase for \"%s\"\n", u); | ||
419 | |||
420 | /* get pass phrase, length 'len' into 'tmp' */ | ||
421 | tmp = "hello"; | ||
422 | len = strlen(tmp); | ||
423 | |||
424 | if (len == 0) | ||
425 | return 0; | ||
426 | /* if too long, truncate */ | ||
427 | if (len > size) | ||
428 | len = size; | ||
429 | memcpy(buf, tmp, len); | ||
430 | return len; | ||
431 | } | ||
432 | |||
433 | =head1 NOTES | ||
434 | |||
435 | The old B<PrivateKey> write routines are retained for compatibility. | ||
436 | New applications should write private keys using the | ||
437 | PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines | ||
438 | because they are more secure (they use an iteration count of 2048 whereas | ||
439 | the traditional routines use a count of 1) unless compatibility with older | ||
440 | versions of OpenSSL is important. | ||
441 | |||
442 | The B<PrivateKey> read routines can be used in all applications because | ||
443 | they handle all formats transparently. | ||
444 | |||
445 | A frequent cause of problems is attempting to use the PEM routines like | ||
446 | this: | ||
447 | |||
448 | X509 *x; | ||
449 | PEM_read_bio_X509(bp, &x, 0, NULL); | ||
450 | |||
451 | this is a bug because an attempt will be made to reuse the data at B<x> | ||
452 | which is an uninitialised pointer. | ||
453 | |||
454 | =head1 PEM ENCRYPTION FORMAT | ||
455 | |||
456 | This old B<PrivateKey> routines use a non standard technique for encryption. | ||
457 | |||
458 | The private key (or other data) takes the following form: | ||
459 | |||
460 | -----BEGIN RSA PRIVATE KEY----- | ||
461 | Proc-Type: 4,ENCRYPTED | ||
462 | DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 | ||
463 | |||
464 | ...base64 encoded data... | ||
465 | -----END RSA PRIVATE KEY----- | ||
466 | |||
467 | The line beginning DEK-Info contains two comma separated pieces of information: | ||
468 | the encryption algorithm name as used by EVP_get_cipherbyname() and an 8 | ||
469 | byte B<salt> encoded as a set of hexadecimal digits. | ||
470 | |||
471 | After this is the base64 encoded encrypted data. | ||
472 | |||
473 | The encryption key is determined using EVP_bytestokey(), using B<salt> and an | ||
474 | iteration count of 1. The IV used is the value of B<salt> and *not* the IV | ||
475 | returned by EVP_bytestokey(). | ||
476 | |||
477 | =head1 BUGS | ||
478 | |||
479 | The PEM read routines in some versions of OpenSSL will not correctly reuse | ||
480 | an existing structure. Therefore the following: | ||
481 | |||
482 | PEM_read_bio_X509(bp, &x, 0, NULL); | ||
483 | |||
484 | where B<x> already contains a valid certificate, may not work, whereas: | ||
485 | |||
486 | X509_free(x); | ||
487 | x = PEM_read_bio_X509(bp, NULL, 0, NULL); | ||
488 | |||
489 | is guaranteed to work. | ||
490 | |||
491 | =head1 RETURN CODES | ||
492 | |||
493 | The read routines return either a pointer to the structure read or NULL | ||
494 | if an error occurred. | ||
495 | |||
496 | The write routines return 1 for success or 0 for failure. | ||
497 | |||
498 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PEM_write_bio_CMS_stream.pod b/src/lib/libcrypto/doc/PEM_write_bio_CMS_stream.pod deleted file mode 100644 index f9946adebf..0000000000 --- a/src/lib/libcrypto/doc/PEM_write_bio_CMS_stream.pod +++ /dev/null | |||
@@ -1,41 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/cms.h> | ||
10 | #include <openssl/pem.h> | ||
11 | |||
12 | int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | PEM_write_bio_CMS_stream() outputs a CMS_ContentInfo structure in PEM format. | ||
17 | |||
18 | It is otherwise identical to the function SMIME_write_CMS(). | ||
19 | |||
20 | =head1 NOTES | ||
21 | |||
22 | This function is effectively a version of the PEM_write_bio_CMS() supporting | ||
23 | streaming. | ||
24 | |||
25 | =head1 RETURN VALUES | ||
26 | |||
27 | PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure. | ||
28 | |||
29 | =head1 SEE ALSO | ||
30 | |||
31 | L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, | ||
32 | L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> | ||
33 | L<CMS_decrypt(3)|CMS_decrypt(3)>, | ||
34 | L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>, | ||
35 | L<i2d_CMS_bio_stream(3)|i2d_CMS_bio_stream(3)> | ||
36 | |||
37 | =head1 HISTORY | ||
38 | |||
39 | PEM_write_bio_CMS_stream() was added to OpenSSL 1.0.0 | ||
40 | |||
41 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod b/src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod deleted file mode 100644 index 16fc9b6845..0000000000 --- a/src/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod +++ /dev/null | |||
@@ -1,41 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs7.h> | ||
10 | #include <openssl/pem.h> | ||
11 | |||
12 | int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | PEM_write_bio_PKCS7_stream() outputs a PKCS7 structure in PEM format. | ||
17 | |||
18 | It is otherwise identical to the function SMIME_write_PKCS7(). | ||
19 | |||
20 | =head1 NOTES | ||
21 | |||
22 | This function is effectively a version of the PEM_write_bio_PKCS7() supporting | ||
23 | streaming. | ||
24 | |||
25 | =head1 RETURN VALUES | ||
26 | |||
27 | PEM_write_bio_PKCS7_stream() returns 1 for success or 0 for failure. | ||
28 | |||
29 | =head1 SEE ALSO | ||
30 | |||
31 | L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, | ||
32 | L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> | ||
33 | L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, | ||
34 | L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, | ||
35 | L<i2d_PKCS7_bio_stream(3)|i2d_PKCS7_bio_stream(3)> | ||
36 | |||
37 | =head1 HISTORY | ||
38 | |||
39 | PEM_write_bio_PKCS7_stream() was added to OpenSSL 1.0.0 | ||
40 | |||
41 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PKCS12_create.pod b/src/lib/libcrypto/doc/PKCS12_create.pod deleted file mode 100644 index 3b27c11a10..0000000000 --- a/src/lib/libcrypto/doc/PKCS12_create.pod +++ /dev/null | |||
@@ -1,73 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PKCS12_create - create a PKCS#12 structure | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs12.h> | ||
10 | |||
11 | PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, | ||
12 | X509 *cert, STACK_OF(X509) *ca, int nid_key, int nid_cert, | ||
13 | int iter, int mac_iter, int keytype); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | PKCS12_create() creates a PKCS#12 structure. | ||
18 | |||
19 | B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for | ||
20 | the supplied certificate and key. B<pkey> is the private key to include in | ||
21 | the structure and B<cert> its corresponding certificates. B<ca> is an optional | ||
22 | set of certificates to also include in the structure. | ||
23 | Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or | ||
24 | certificate is required. | ||
25 | |||
26 | B<nid_key> and B<nid_cert> are the encryption algorithms that should be used | ||
27 | for the key and certificate respectively. If either B<nid_key> or B<nid_cert> | ||
28 | is set to -1, no encryption will be used. | ||
29 | |||
30 | B<iter> is the encryption algorithm iteration count to use and B<mac_iter> is | ||
31 | the MAC iteration count to use. If B<mac_iter> is set to -1, the MAC will be | ||
32 | omitted entirely. | ||
33 | |||
34 | B<keytype> is the type of key. | ||
35 | |||
36 | =head1 NOTES | ||
37 | |||
38 | The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype> | ||
39 | can all be set to zero and sensible defaults will be used. | ||
40 | |||
41 | These defaults are: 40 bit RC2 encryption for certificates, triple DES | ||
42 | encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER | ||
43 | (currently 2048) and a MAC iteration count of 1. | ||
44 | |||
45 | The default MAC iteration count is 1 in order to retain compatibility with | ||
46 | old software which did not interpret MAC iteration counts. If such compatibility | ||
47 | is not required then B<mac_iter> should be set to PKCS12_DEFAULT_ITER. | ||
48 | |||
49 | B<keytype> adds a flag to the store private key. This is a non standard | ||
50 | extension that is only currently interpreted by MSIE. If set to zero the flag | ||
51 | is omitted, if set to B<KEY_SIG> the key can be used for signing only, if set | ||
52 | to B<KEY_EX> it can be used for signing and encryption. This option was useful | ||
53 | for old export grade software which could use signing only keys of arbitrary | ||
54 | size but had restrictions on the permissible sizes of keys which could be used | ||
55 | for encryption. | ||
56 | |||
57 | If a certificate contains an B<alias> or B<keyid> then this will be | ||
58 | used for the corresponding B<friendlyName> or B<localKeyID> in the | ||
59 | PKCS12 structure. | ||
60 | |||
61 | =head1 SEE ALSO | ||
62 | |||
63 | L<d2i_PKCS12(3)|d2i_PKCS12(3)> | ||
64 | |||
65 | =head1 HISTORY | ||
66 | |||
67 | PKCS12_create was added in OpenSSL 0.9.3. | ||
68 | |||
69 | Before OpenSSL 0.9.8, neither B<pkey> nor B<cert> were allowed to be B<NULL>, | ||
70 | and a value of B<-1> was not allowed for B<nid_key>, B<nid_cert> and | ||
71 | B<mac_iter>. | ||
72 | |||
73 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PKCS12_parse.pod b/src/lib/libcrypto/doc/PKCS12_parse.pod deleted file mode 100644 index c54cf2ad61..0000000000 --- a/src/lib/libcrypto/doc/PKCS12_parse.pod +++ /dev/null | |||
@@ -1,57 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PKCS12_parse - parse a PKCS#12 structure | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs12.h> | ||
10 | |||
11 | int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, STACK_OF(X509) **ca); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | PKCS12_parse() parses a PKCS12 structure. | ||
16 | |||
17 | B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use. | ||
18 | If successful the private key will be written to B<*pkey>, the corresponding | ||
19 | certificate to B<*cert> and any additional certificates to B<*ca>. | ||
20 | |||
21 | =head1 NOTES | ||
22 | |||
23 | The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> in | ||
24 | which case additional certificates will be discarded. B<*ca> can also be a | ||
25 | valid STACK in which case additional certificates are appended to B<*ca>. If | ||
26 | B<*ca> is B<NULL> a new STACK will be allocated. | ||
27 | |||
28 | The B<friendlyName> and B<localKeyID> attributes (if present) on each | ||
29 | certificate will be stored in the B<alias> and B<keyid> attributes of the | ||
30 | B<X509> structure. | ||
31 | |||
32 | =head1 RETURN VALUES | ||
33 | |||
34 | PKCS12_parse() returns 1 for success and zero if an error occurred. | ||
35 | |||
36 | The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> | ||
37 | |||
38 | =head1 BUGS | ||
39 | |||
40 | Only a single private key and corresponding certificate is returned by this | ||
41 | function. More complex PKCS#12 files with multiple private keys will only | ||
42 | return the first match. | ||
43 | |||
44 | Only B<friendlyName> and B<localKeyID> attributes are currently stored in | ||
45 | certificates. Other attributes are discarded. | ||
46 | |||
47 | Attributes currently cannot be stored in the private key B<EVP_PKEY> structure. | ||
48 | |||
49 | =head1 SEE ALSO | ||
50 | |||
51 | L<d2i_PKCS12(3)|d2i_PKCS12(3)> | ||
52 | |||
53 | =head1 HISTORY | ||
54 | |||
55 | PKCS12_parse was added in OpenSSL 0.9.3 | ||
56 | |||
57 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod b/src/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod deleted file mode 100644 index 0c164a0ed6..0000000000 --- a/src/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod +++ /dev/null | |||
@@ -1,64 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PKCS5_PBKDF2_HMAC, PKCS5_PBKDF2_HMAC_SHA1 - password based derivation routines with salt and iteration count | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | int PKCS5_PBKDF2_HMAC(const char *pass, int passlen, | ||
12 | const unsigned char *salt, int saltlen, int iter, | ||
13 | const EVP_MD *digest, | ||
14 | int keylen, unsigned char *out); | ||
15 | |||
16 | int PKCS5_PBKDF2_HMAC_SHA1(const char *pass, int passlen, | ||
17 | const unsigned char *salt, int saltlen, int iter, | ||
18 | int keylen, unsigned char *out); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | PKCS5_PBKDF2_HMAC() derives a key from a password using a salt and iteration count | ||
23 | as specified in RFC 2898. | ||
24 | |||
25 | B<pass> is the password used in the derivation of length B<passlen>. B<pass> | ||
26 | is an optional parameter and can be NULL. If B<passlen> is -1, then the | ||
27 | function will calculate the length of B<pass> using strlen(). | ||
28 | |||
29 | B<salt> is the salt used in the derivation of length B<saltlen>. If the | ||
30 | B<salt> is NULL, then B<saltlen> must be 0. The function will not | ||
31 | attempt to calculate the length of the B<salt> because it is not assumed to | ||
32 | be NULL terminated. | ||
33 | |||
34 | B<iter> is the iteration count and its value should be greater than or | ||
35 | equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any | ||
36 | B<iter> less than 1 is treated as a single iteration. | ||
37 | |||
38 | B<digest> is the message digest function used in the derivation. Values include | ||
39 | any of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls | ||
40 | PKCS5_PBKDF2_HMAC() with EVP_sha1(). | ||
41 | |||
42 | The derived key will be written to B<out>. The size of the B<out> buffer | ||
43 | is specified via B<keylen>. | ||
44 | |||
45 | =head1 NOTES | ||
46 | |||
47 | A typical application of this function is to derive keying material for an | ||
48 | encryption algorithm from a password in the B<pass>, a salt in B<salt>, | ||
49 | and an iteration count. | ||
50 | |||
51 | Increasing the B<iter> parameter slows down the algorithm which makes it | ||
52 | harder for an attacker to perform a brute force attack using a large number | ||
53 | of candidate passwords. | ||
54 | |||
55 | =head1 RETURN VALUES | ||
56 | |||
57 | PKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on error. | ||
58 | |||
59 | =head1 SEE ALSO | ||
60 | |||
61 | L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, | ||
62 | L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> | ||
63 | |||
64 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PKCS7_decrypt.pod b/src/lib/libcrypto/doc/PKCS7_decrypt.pod deleted file mode 100644 index 78919998ce..0000000000 --- a/src/lib/libcrypto/doc/PKCS7_decrypt.pod +++ /dev/null | |||
@@ -1,57 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs7.h> | ||
10 | |||
11 | int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData | ||
16 | structure. B<pkey> is the private key of the recipient, B<cert> is the | ||
17 | recipients certificate, B<data> is a BIO to write the content to and | ||
18 | B<flags> is an optional set of flags. | ||
19 | |||
20 | =head1 NOTES | ||
21 | |||
22 | OpenSSL_add_all_algorithms() (or equivalent) should be called before using this | ||
23 | function or errors about unknown algorithms will occur. | ||
24 | |||
25 | Although the recipients certificate is not needed to decrypt the data it is | ||
26 | needed to locate the appropriate (of possible several) recipients in the PKCS#7 | ||
27 | structure. | ||
28 | |||
29 | The following flags can be passed in the B<flags> parameter. | ||
30 | |||
31 | If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted | ||
32 | from the content. If the content is not of type B<text/plain> then an error is | ||
33 | returned. | ||
34 | |||
35 | =head1 RETURN VALUES | ||
36 | |||
37 | PKCS7_decrypt() returns either 1 for success or 0 for failure. | ||
38 | The error can be obtained from ERR_get_error(3) | ||
39 | |||
40 | =head1 BUGS | ||
41 | |||
42 | PKCS7_decrypt() must be passed the correct recipient key and certificate. It | ||
43 | would be better if it could look up the correct key and certificate from a | ||
44 | database. | ||
45 | |||
46 | The lack of single pass processing and need to hold all data in memory as | ||
47 | mentioned in PKCS7_sign() also applies to PKCS7_verify(). | ||
48 | |||
49 | =head1 SEE ALSO | ||
50 | |||
51 | L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> | ||
52 | |||
53 | =head1 HISTORY | ||
54 | |||
55 | PKCS7_decrypt() was added to OpenSSL 0.9.5 | ||
56 | |||
57 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PKCS7_encrypt.pod b/src/lib/libcrypto/doc/PKCS7_encrypt.pod deleted file mode 100644 index 8bc77407b9..0000000000 --- a/src/lib/libcrypto/doc/PKCS7_encrypt.pod +++ /dev/null | |||
@@ -1,73 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PKCS7_encrypt - create a PKCS#7 envelopedData structure | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs7.h> | ||
10 | |||
11 | PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs> | ||
16 | is a list of recipient certificates. B<in> is the content to be encrypted. | ||
17 | B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. | ||
18 | |||
19 | =head1 NOTES | ||
20 | |||
21 | Only RSA keys are supported in PKCS#7 and envelopedData so the recipient | ||
22 | certificates supplied to this function must all contain RSA public keys, though | ||
23 | they do not have to be signed using the RSA algorithm. | ||
24 | |||
25 | The algorithm passed in the B<cipher> parameter must support ASN1 encoding of | ||
26 | its parameters. | ||
27 | |||
28 | Many browsers implement a "sign and encrypt" option which is simply an S/MIME | ||
29 | envelopedData containing an S/MIME signed message. This can be readily produced | ||
30 | by storing the S/MIME signed message in a memory BIO and passing it to | ||
31 | PKCS7_encrypt(). | ||
32 | |||
33 | The following flags can be passed in the B<flags> parameter. | ||
34 | |||
35 | If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are | ||
36 | prepended to the data. | ||
37 | |||
38 | Normally the supplied content is translated into MIME canonical format (as | ||
39 | required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation | ||
40 | occurs. This option should be used if the supplied data is in binary format | ||
41 | otherwise the translation will corrupt it. If B<PKCS7_BINARY> is set then | ||
42 | B<PKCS7_TEXT> is ignored. | ||
43 | |||
44 | If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output | ||
45 | suitable for streaming I/O: no data is read from the BIO B<in>. | ||
46 | |||
47 | =head1 NOTES | ||
48 | |||
49 | If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> | ||
50 | complete and outputting its contents via a function that does not | ||
51 | properly finalize the B<PKCS7> structure will give unpredictable | ||
52 | results. | ||
53 | |||
54 | Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), | ||
55 | PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization | ||
56 | can be performed by obtaining the streaming ASN1 B<BIO> directly using | ||
57 | BIO_new_PKCS7(). | ||
58 | |||
59 | =head1 RETURN VALUES | ||
60 | |||
61 | PKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred. | ||
62 | The error can be obtained from ERR_get_error(3). | ||
63 | |||
64 | =head1 SEE ALSO | ||
65 | |||
66 | L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> | ||
67 | |||
68 | =head1 HISTORY | ||
69 | |||
70 | PKCS7_decrypt() was added to OpenSSL 0.9.5 | ||
71 | The B<PKCS7_STREAM> flag was first supported in OpenSSL 1.0.0. | ||
72 | |||
73 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PKCS7_sign.pod b/src/lib/libcrypto/doc/PKCS7_sign.pod deleted file mode 100644 index 64a3036c0a..0000000000 --- a/src/lib/libcrypto/doc/PKCS7_sign.pod +++ /dev/null | |||
@@ -1,116 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PKCS7_sign - create a PKCS#7 signedData structure | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs7.h> | ||
10 | |||
11 | PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is | ||
16 | the certificate to sign with, B<pkey> is the corresponding private key. | ||
17 | B<certs> is an optional additional set of certificates to include in the PKCS#7 | ||
18 | structure (for example any intermediate CAs in the chain). | ||
19 | |||
20 | The data to be signed is read from BIO B<data>. | ||
21 | |||
22 | B<flags> is an optional set of flags. | ||
23 | |||
24 | =head1 NOTES | ||
25 | |||
26 | Any of the following flags (ored together) can be passed in the B<flags> | ||
27 | parameter. | ||
28 | |||
29 | Many S/MIME clients expect the signed content to include valid MIME headers. If | ||
30 | the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended | ||
31 | to the data. | ||
32 | |||
33 | If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the | ||
34 | PKCS7 structure, the signer's certificate must still be supplied in the | ||
35 | B<signcert> parameter though. This can reduce the size of the signature if the | ||
36 | signers certificate can be obtained by other means: for example a previously | ||
37 | signed message. | ||
38 | |||
39 | The data being signed is included in the PKCS7 structure, unless | ||
40 | B<PKCS7_DETACHED> is set in which case it is omitted. This is used for PKCS7 | ||
41 | detached signatures which are used in S/MIME plaintext signed messages for | ||
42 | example. | ||
43 | |||
44 | Normally the supplied content is translated into MIME canonical format (as | ||
45 | required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation | ||
46 | occurs. This option should be used if the supplied data is in binary format | ||
47 | otherwise the translation will corrupt it. | ||
48 | |||
49 | The signedData structure includes several PKCS#7 authenticatedAttributes | ||
50 | including the signing time, the PKCS#7 content type and the supported list of | ||
51 | ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no | ||
52 | authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just | ||
53 | the SMIMECapabilities are omitted. | ||
54 | |||
55 | If present the SMIMECapabilities attribute indicates support for the following | ||
56 | algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of | ||
57 | these algorithms is disabled then it will not be included. | ||
58 | |||
59 | If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is | ||
60 | just initialized ready to perform the signing operation. The signing is however | ||
61 | B<not> performed and the data to be signed is not read from the B<data> | ||
62 | parameter. Signing is deferred until after the data has been written. In this | ||
63 | way data can be signed in a single pass. | ||
64 | |||
65 | If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to | ||
66 | which additional signers and capabilities can be added before finalization. | ||
67 | |||
68 | |||
69 | =head1 NOTES | ||
70 | |||
71 | If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> | ||
72 | complete and outputting its contents via a function that does not properly | ||
73 | finalize the B<PKCS7> structure will give unpredictable results. | ||
74 | |||
75 | Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), | ||
76 | PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization | ||
77 | can be performed by obtaining the streaming ASN1 B<BIO> directly using | ||
78 | BIO_new_PKCS7(). | ||
79 | |||
80 | If a signer is specified it will use the default digest for the signing | ||
81 | algorithm. This is B<SHA1> for both RSA and DSA keys. | ||
82 | |||
83 | In OpenSSL 1.0.0 the B<certs>, B<signcert> and B<pkey> parameters can all be | ||
84 | B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added | ||
85 | using the function B<PKCS7_sign_add_signer()>. B<PKCS7_final()> must also be | ||
86 | called to finalize the structure if streaming is not enabled. Alternative | ||
87 | signing digests can also be specified using this method. | ||
88 | |||
89 | In OpenSSL 1.0.0 if B<signcert> and B<pkey> are NULL then a certificates only | ||
90 | PKCS#7 structure is output. | ||
91 | |||
92 | In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must | ||
93 | B<NOT> be NULL. | ||
94 | |||
95 | =head1 BUGS | ||
96 | |||
97 | Some advanced attributes such as counter signatures are not supported. | ||
98 | |||
99 | =head1 RETURN VALUES | ||
100 | |||
101 | PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error | ||
102 | occurred. The error can be obtained from ERR_get_error(3). | ||
103 | |||
104 | =head1 SEE ALSO | ||
105 | |||
106 | L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)> | ||
107 | |||
108 | =head1 HISTORY | ||
109 | |||
110 | PKCS7_sign() was added to OpenSSL 0.9.5 | ||
111 | |||
112 | The B<PKCS7_PARTIAL> flag was added in OpenSSL 1.0.0 | ||
113 | |||
114 | The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0 | ||
115 | |||
116 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod b/src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod deleted file mode 100644 index 280455d476..0000000000 --- a/src/lib/libcrypto/doc/PKCS7_sign_add_signer.pod +++ /dev/null | |||
@@ -1,87 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PKCS7_sign_add_signer - add a signer PKCS7 signed data structure. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs7.h> | ||
10 | |||
11 | PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags); | ||
12 | |||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | PKCS7_sign_add_signer() adds a signer with certificate B<signcert> and private | ||
17 | key B<pkey> using message digest B<md> to a PKCS7 signed data structure | ||
18 | B<p7>. | ||
19 | |||
20 | The PKCS7 structure should be obtained from an initial call to PKCS7_sign() | ||
21 | with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7 | ||
22 | signed data structure. | ||
23 | |||
24 | If the B<md> parameter is B<NULL> then the default digest for the public | ||
25 | key algorithm will be used. | ||
26 | |||
27 | Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned PKCS7 structure | ||
28 | is not complete and must be finalized either by streaming (if applicable) or | ||
29 | a call to PKCS7_final(). | ||
30 | |||
31 | |||
32 | =head1 NOTES | ||
33 | |||
34 | The main purpose of this function is to provide finer control over a PKCS#7 | ||
35 | signed data structure where the simpler PKCS7_sign() function defaults are | ||
36 | not appropriate. For example if multiple signers or non default digest | ||
37 | algorithms are needed. | ||
38 | |||
39 | Any of the following flags (ored together) can be passed in the B<flags> | ||
40 | parameter. | ||
41 | |||
42 | If B<PKCS7_REUSE_DIGEST> is set then an attempt is made to copy the content | ||
43 | digest value from the PKCS7 structure: to add a signer to an existing structure. | ||
44 | An error occurs if a matching digest value cannot be found to copy. The | ||
45 | returned PKCS7 structure will be valid and finalized when this flag is set. | ||
46 | |||
47 | If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the | ||
48 | B<PKCS7_SIGNER_INO> structure will not be finalized so additional attributes | ||
49 | can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is | ||
50 | needed to finalize it. | ||
51 | |||
52 | If B<PKCS7_NOCERTS> is set the signer's certificate will not be included in the | ||
53 | PKCS7 structure, the signer's certificate must still be supplied in the | ||
54 | B<signcert> parameter though. This can reduce the size of the signature if the | ||
55 | signers certificate can be obtained by other means: for example a previously | ||
56 | signed message. | ||
57 | |||
58 | The signedData structure includes several PKCS#7 authenticatedAttributes | ||
59 | including the signing time, the PKCS#7 content type and the supported list of | ||
60 | ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no | ||
61 | authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just | ||
62 | the SMIMECapabilities are omitted. | ||
63 | |||
64 | If present the SMIMECapabilities attribute indicates support for the following | ||
65 | algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of | ||
66 | these algorithms is disabled then it will not be included. | ||
67 | |||
68 | |||
69 | PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO | ||
70 | structure just added, this can be used to set additional attributes | ||
71 | before it is finalized. | ||
72 | |||
73 | =head1 RETURN VALUES | ||
74 | |||
75 | PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO | ||
76 | structure just added or NULL if an error occurs. | ||
77 | |||
78 | =head1 SEE ALSO | ||
79 | |||
80 | L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, | ||
81 | L<PKCS7_final(3)|PKCS7_final(3)>, | ||
82 | |||
83 | =head1 HISTORY | ||
84 | |||
85 | PPKCS7_sign_add_signer() was added to OpenSSL 1.0.0 | ||
86 | |||
87 | =cut | ||
diff --git a/src/lib/libcrypto/doc/PKCS7_verify.pod b/src/lib/libcrypto/doc/PKCS7_verify.pod deleted file mode 100644 index 059fbff8e9..0000000000 --- a/src/lib/libcrypto/doc/PKCS7_verify.pod +++ /dev/null | |||
@@ -1,118 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs7.h> | ||
10 | |||
11 | int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags); | ||
12 | |||
13 | STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7 | ||
18 | structure to verify. B<certs> is a set of certificates in which to search for | ||
19 | the signer's certificate. B<store> is a trusted certificate store (used for | ||
20 | chain verification). B<indata> is the signed data if the content is not | ||
21 | present in B<p7> (that is it is detached). The content is written to B<out> | ||
22 | if it is not NULL. | ||
23 | |||
24 | B<flags> is an optional set of flags, which can be used to modify the verify | ||
25 | operation. | ||
26 | |||
27 | PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does | ||
28 | B<not> check their validity or whether any signatures are valid. The B<certs> | ||
29 | and B<flags> parameters have the same meanings as in PKCS7_verify(). | ||
30 | |||
31 | =head1 VERIFY PROCESS | ||
32 | |||
33 | Normally the verify process proceeds as follows. | ||
34 | |||
35 | Initially some sanity checks are performed on B<p7>. The type of B<p7> must | ||
36 | be signedData. There must be at least one signature on the data and if | ||
37 | the content is detached B<indata> cannot be B<NULL>. | ||
38 | |||
39 | An attempt is made to locate all the signer's certificates, first looking in | ||
40 | the B<certs> parameter (if it is not B<NULL>) and then looking in any | ||
41 | certificates contained in the B<p7> structure itself. If any signer's | ||
42 | certificates cannot be located the operation fails. | ||
43 | |||
44 | Each signer's certificate is chain verified using the B<smimesign> purpose and | ||
45 | the supplied trusted certificate store. Any internal certificates in the message | ||
46 | are used as untrusted CAs. If any chain verify fails an error code is returned. | ||
47 | |||
48 | Finally the signed content is read (and written to B<out> is it is not NULL) and | ||
49 | the signature's checked. | ||
50 | |||
51 | If all signature's verify correctly then the function is successful. | ||
52 | |||
53 | Any of the following flags (ored together) can be passed in the B<flags> | ||
54 | parameter to change the default verify behaviour. Only the flag | ||
55 | B<PKCS7_NOINTERN> is meaningful to PKCS7_get0_signers(). | ||
56 | |||
57 | If B<PKCS7_NOINTERN> is set the certificates in the message itself are not | ||
58 | searched when locating the signer's certificate. This means that all the signers | ||
59 | certificates must be in the B<certs> parameter. | ||
60 | |||
61 | If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted | ||
62 | from the content. If the content is not of type B<text/plain> then an error is | ||
63 | returned. | ||
64 | |||
65 | If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified. | ||
66 | |||
67 | If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are | ||
68 | not used as untrusted CAs. This means that the whole verify chain (apart from | ||
69 | the signer's certificate) must be contained in the trusted store. | ||
70 | |||
71 | If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked. | ||
72 | |||
73 | =head1 NOTES | ||
74 | |||
75 | One application of B<PKCS7_NOINTERN> is to only accept messages signed by | ||
76 | a small number of certificates. The acceptable certificates would be passed | ||
77 | in the B<certs> parameter. In this case if the signer is not one of the | ||
78 | certificates supplied in B<certs> then the verify will fail because the | ||
79 | signer cannot be found. | ||
80 | |||
81 | Care should be taken when modifying the default verify behaviour, for example | ||
82 | setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification | ||
83 | and any signed message will be considered valid. This combination is however | ||
84 | useful if one merely wishes to write the content to B<out> and its validity | ||
85 | is not considered important. | ||
86 | |||
87 | Chain verification should arguably be performed using the signing time rather | ||
88 | than the current time. However since the signing time is supplied by the | ||
89 | signer it cannot be trusted without additional evidence (such as a trusted | ||
90 | timestamp). | ||
91 | |||
92 | =head1 RETURN VALUES | ||
93 | |||
94 | PKCS7_verify() returns 1 for a successful verification and zero or a negative | ||
95 | value if an error occurs. | ||
96 | |||
97 | PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred. | ||
98 | |||
99 | The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> | ||
100 | |||
101 | =head1 BUGS | ||
102 | |||
103 | The trusted certificate store is not searched for the signers certificate, | ||
104 | this is primarily due to the inadequacies of the current B<X509_STORE> | ||
105 | functionality. | ||
106 | |||
107 | The lack of single pass processing and need to hold all data in memory as | ||
108 | mentioned in PKCS7_sign() also applies to PKCS7_verify(). | ||
109 | |||
110 | =head1 SEE ALSO | ||
111 | |||
112 | L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)> | ||
113 | |||
114 | =head1 HISTORY | ||
115 | |||
116 | PKCS7_verify() was added to OpenSSL 0.9.5 | ||
117 | |||
118 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND.pod b/src/lib/libcrypto/doc/RAND.pod deleted file mode 100644 index dd6962fa35..0000000000 --- a/src/lib/libcrypto/doc/RAND.pod +++ /dev/null | |||
@@ -1,34 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND - pseudo-random number generator | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | int RAND_bytes(unsigned char *buf, int num); | ||
12 | int RAND_pseudo_bytes(unsigned char *buf, int num); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | These functions give access to the systems cryptographically secure | ||
17 | pseudo-random number generator (PRNG). It is used by other library functions | ||
18 | for example to generate random keys, and applications can use it when they | ||
19 | need randomness. | ||
20 | |||
21 | L<RAND_bytes(3)|RAND_bytes(3)> describes how to obtain random data from the | ||
22 | PRNG. | ||
23 | |||
24 | =head1 INTERNALS | ||
25 | |||
26 | The RAND_SSLeay() method implements a PRNG based on the systems' | ||
27 | L<arc4random_buf(3)> random number generator. | ||
28 | |||
29 | =head1 SEE ALSO | ||
30 | |||
31 | L<BN_rand(3)|BN_rand(3)>, | ||
32 | L<RAND_bytes(3)|RAND_bytes(3)> | ||
33 | |||
34 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_add.pod b/src/lib/libcrypto/doc/RAND_add.pod deleted file mode 100644 index 3ffd4910c4..0000000000 --- a/src/lib/libcrypto/doc/RAND_add.pod +++ /dev/null | |||
@@ -1,30 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_add, RAND_seed, RAND_status - add entropy to the PRNG (DEPRECATED) | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | void RAND_seed(const void *buf, int num); | ||
12 | |||
13 | void RAND_add(const void *buf, int num, double entropy); | ||
14 | |||
15 | int RAND_status(void); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | These functions used to allow for the state of the random number generator | ||
20 | to be controlled by external sources. | ||
21 | |||
22 | They are kept for ABI compatibility but are no longer functional, and | ||
23 | should not be used in new programs. | ||
24 | |||
25 | =head1 SEE ALSO | ||
26 | |||
27 | L<rand(3)|rand(3)>, | ||
28 | L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> | ||
29 | |||
30 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_bytes.pod b/src/lib/libcrypto/doc/RAND_bytes.pod deleted file mode 100644 index c89961ada3..0000000000 --- a/src/lib/libcrypto/doc/RAND_bytes.pod +++ /dev/null | |||
@@ -1,43 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_bytes, RAND_pseudo_bytes - generate random data | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | int RAND_bytes(unsigned char *buf, int num); | ||
12 | |||
13 | int RAND_pseudo_bytes(unsigned char *buf, int num); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes | ||
18 | into B<buf>. | ||
19 | |||
20 | RAND_pseudo_bytes() puts B<num> pseudo-random bytes into B<buf>. | ||
21 | Pseudo-random byte sequences generated by RAND_pseudo_bytes() will be | ||
22 | unique if they are of sufficient length, but are not necessarily | ||
23 | unpredictable. They can be used for non-cryptographic purposes and for | ||
24 | certain purposes in cryptographic protocols, but usually not for key | ||
25 | generation etc. | ||
26 | |||
27 | =head1 RETURN VALUES | ||
28 | |||
29 | RAND_bytes() returns 1. | ||
30 | RAND_pseudo_bytes() returns 1. | ||
31 | |||
32 | =head1 SEE ALSO | ||
33 | |||
34 | L<rand(3)|rand(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, | ||
35 | L<RAND_add(3)|RAND_add(3)> | ||
36 | |||
37 | =head1 HISTORY | ||
38 | |||
39 | RAND_bytes() is available in all versions of SSLeay and OpenSSL. It | ||
40 | has a return value since OpenSSL 0.9.5. RAND_pseudo_bytes() was added | ||
41 | in OpenSSL 0.9.5. | ||
42 | |||
43 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_cleanup.pod b/src/lib/libcrypto/doc/RAND_cleanup.pod deleted file mode 100644 index 10cb39ce7a..0000000000 --- a/src/lib/libcrypto/doc/RAND_cleanup.pod +++ /dev/null | |||
@@ -1,25 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_cleanup - erase the PRNG state | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | void RAND_cleanup(void); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | RAND_cleanup() erases the memory used by the PRNG. | ||
16 | |||
17 | =head1 SEE ALSO | ||
18 | |||
19 | L<rand(3)|rand(3)> | ||
20 | |||
21 | =head1 HISTORY | ||
22 | |||
23 | RAND_cleanup() is available in all versions of SSLeay and OpenSSL. | ||
24 | |||
25 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_load_file.pod b/src/lib/libcrypto/doc/RAND_load_file.pod deleted file mode 100644 index 5e4c2481d8..0000000000 --- a/src/lib/libcrypto/doc/RAND_load_file.pod +++ /dev/null | |||
@@ -1,52 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | const char *RAND_file_name(char *buf, size_t num); | ||
12 | |||
13 | int RAND_load_file(const char *filename, long max_bytes); | ||
14 | |||
15 | int RAND_write_file(const char *filename); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | RAND_file_name() returns a default path for the random seed file. | ||
20 | B<buf> points to a buffer of size B<num> in which to store the | ||
21 | filename. If B<num> is too small for the path name, an error occurs. | ||
22 | |||
23 | RAND_load_file() used to allow for the state of the random number generator | ||
24 | to be controlled by external sources. | ||
25 | |||
26 | It is kept for ABI compatibility but is no longer functional, and | ||
27 | should not used in new programs. | ||
28 | |||
29 | RAND_write_file() writes a number of random bytes (currently 1024) to | ||
30 | file B<filename>. | ||
31 | |||
32 | =head1 RETURN VALUES | ||
33 | |||
34 | RAND_load_file() always returns 0. | ||
35 | |||
36 | RAND_write_file() returns the number of bytes written, and -1 if the | ||
37 | bytes written were generated without appropriate seed. | ||
38 | |||
39 | RAND_file_name() returns a pointer to B<buf> on success, and NULL on | ||
40 | error. | ||
41 | |||
42 | =head1 SEE ALSO | ||
43 | |||
44 | L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, | ||
45 | L<RAND_cleanup(3)|RAND_cleanup(3)> | ||
46 | |||
47 | =head1 HISTORY | ||
48 | |||
49 | RAND_load_file(), RAND_write_file() and RAND_file_name() are available in | ||
50 | all versions of SSLeay and OpenSSL. | ||
51 | |||
52 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RAND_set_rand_method.pod b/src/lib/libcrypto/doc/RAND_set_rand_method.pod deleted file mode 100644 index c02068bf76..0000000000 --- a/src/lib/libcrypto/doc/RAND_set_rand_method.pod +++ /dev/null | |||
@@ -1,40 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - select RAND method | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rand.h> | ||
10 | |||
11 | void RAND_set_rand_method(const RAND_METHOD *meth); | ||
12 | |||
13 | const RAND_METHOD *RAND_get_rand_method(void); | ||
14 | |||
15 | RAND_METHOD *RAND_SSLeay(void); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | These functions used to allow for the random number generator functions | ||
20 | to be replaced by arbitrary code. | ||
21 | |||
22 | They are kept for ABI compatibility but are no longer functional, and | ||
23 | should not be used in new programs. | ||
24 | |||
25 | =head1 SEE ALSO | ||
26 | |||
27 | L<rand(3)|rand(3)> | ||
28 | |||
29 | =head1 HISTORY | ||
30 | |||
31 | RAND_set_rand_method(), RAND_get_rand_method() and RAND_SSLeay() are | ||
32 | available in all versions of OpenSSL. | ||
33 | |||
34 | In the engine version of version 0.9.6, RAND_set_rand_method() was altered to | ||
35 | take an ENGINE pointer as its argument. As of version 0.9.7, that has been | ||
36 | reverted as the ENGINE API transparently overrides RAND defaults if used, | ||
37 | otherwise RAND API functions work as before. RAND_set_rand_engine() was also | ||
38 | introduced in version 0.9.7. | ||
39 | |||
40 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RC4.pod b/src/lib/libcrypto/doc/RC4.pod deleted file mode 100644 index b6d3a4342c..0000000000 --- a/src/lib/libcrypto/doc/RC4.pod +++ /dev/null | |||
@@ -1,62 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RC4_set_key, RC4 - RC4 encryption | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rc4.h> | ||
10 | |||
11 | void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); | ||
12 | |||
13 | void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, | ||
14 | unsigned char *outdata); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | This library implements the Alleged RC4 cipher, which is described for | ||
19 | example in I<Applied Cryptography>. It is believed to be compatible | ||
20 | with RC4[TM], a proprietary cipher of RSA Security Inc. | ||
21 | |||
22 | RC4 is a stream cipher with variable key length. Typically, 128 bit | ||
23 | (16 byte) keys are used for strong encryption, but shorter insecure | ||
24 | key sizes have been widely used due to export restrictions. | ||
25 | |||
26 | RC4 consists of a key setup phase and the actual encryption or | ||
27 | decryption phase. | ||
28 | |||
29 | RC4_set_key() sets up the B<RC4_KEY> B<key> using the B<len> bytes long | ||
30 | key at B<data>. | ||
31 | |||
32 | RC4() encrypts or decrypts the B<len> bytes of data at B<indata> using | ||
33 | B<key> and places the result at B<outdata>. Repeated RC4() calls with | ||
34 | the same B<key> yield a continuous key stream. | ||
35 | |||
36 | Since RC4 is a stream cipher (the input is XORed with a pseudo-random | ||
37 | key stream to produce the output), decryption uses the same function | ||
38 | calls as encryption. | ||
39 | |||
40 | Applications should use the higher level functions | ||
41 | L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> | ||
42 | etc. instead of calling the RC4 functions directly. | ||
43 | |||
44 | =head1 RETURN VALUES | ||
45 | |||
46 | RC4_set_key() and RC4() do not return values. | ||
47 | |||
48 | =head1 NOTE | ||
49 | |||
50 | Certain conditions have to be observed to securely use stream ciphers. | ||
51 | It is not permissible to perform multiple encryptions using the same | ||
52 | key stream. | ||
53 | |||
54 | =head1 SEE ALSO | ||
55 | |||
56 | L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)> | ||
57 | |||
58 | =head1 HISTORY | ||
59 | |||
60 | RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. | ||
61 | |||
62 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RIPEMD160.pod b/src/lib/libcrypto/doc/RIPEMD160.pod deleted file mode 100644 index f66fb02ed2..0000000000 --- a/src/lib/libcrypto/doc/RIPEMD160.pod +++ /dev/null | |||
@@ -1,66 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - | ||
6 | RIPEMD-160 hash function | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/ripemd.h> | ||
11 | |||
12 | unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, | ||
13 | unsigned char *md); | ||
14 | |||
15 | int RIPEMD160_Init(RIPEMD160_CTX *c); | ||
16 | int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, | ||
17 | unsigned long len); | ||
18 | int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | RIPEMD-160 is a cryptographic hash function with a | ||
23 | 160 bit output. | ||
24 | |||
25 | RIPEMD160() computes the RIPEMD-160 message digest of the B<n> | ||
26 | bytes at B<d> and places it in B<md> (which must have space for | ||
27 | RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest | ||
28 | is placed in a static array. | ||
29 | |||
30 | The following functions may be used if the message is not completely | ||
31 | stored in memory: | ||
32 | |||
33 | RIPEMD160_Init() initializes a B<RIPEMD160_CTX> structure. | ||
34 | |||
35 | RIPEMD160_Update() can be called repeatedly with chunks of the message to | ||
36 | be hashed (B<len> bytes at B<data>). | ||
37 | |||
38 | RIPEMD160_Final() places the message digest in B<md>, which must have | ||
39 | space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases | ||
40 | the B<RIPEMD160_CTX>. | ||
41 | |||
42 | Applications should use the higher level functions | ||
43 | L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the | ||
44 | hash functions directly. | ||
45 | |||
46 | =head1 RETURN VALUES | ||
47 | |||
48 | RIPEMD160() returns a pointer to the hash value. | ||
49 | |||
50 | RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for | ||
51 | success, 0 otherwise. | ||
52 | |||
53 | =head1 CONFORMING TO | ||
54 | |||
55 | ISO/IEC 10118-3 (draft) (??) | ||
56 | |||
57 | =head1 SEE ALSO | ||
58 | |||
59 | L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> | ||
60 | |||
61 | =head1 HISTORY | ||
62 | |||
63 | RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and | ||
64 | RIPEMD160_Final() are available since SSLeay 0.9.0. | ||
65 | |||
66 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_blinding_on.pod b/src/lib/libcrypto/doc/RSA_blinding_on.pod deleted file mode 100644 index f96e3cf7c9..0000000000 --- a/src/lib/libcrypto/doc/RSA_blinding_on.pod +++ /dev/null | |||
@@ -1,41 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_blinding_on, RSA_blinding_off - protect the RSA operation from timing | ||
6 | attacks | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/rsa.h> | ||
11 | |||
12 | int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); | ||
13 | |||
14 | void RSA_blinding_off(RSA *rsa); | ||
15 | |||
16 | =head1 DESCRIPTION | ||
17 | |||
18 | RSA is vulnerable to timing attacks. In a setup where attackers can | ||
19 | measure the time of RSA decryption or signature operations, blinding | ||
20 | must be used to protect the RSA operation from that attack. | ||
21 | |||
22 | RSA_blinding_on() turns blinding on for key B<rsa> and generates a | ||
23 | random blinding factor. B<ctx> is B<NULL> or a pre-allocated and | ||
24 | initialized B<BN_CTX>. | ||
25 | |||
26 | RSA_blinding_off() turns blinding off and frees the memory used for | ||
27 | the blinding factor. | ||
28 | |||
29 | =head1 RETURN VALUES | ||
30 | |||
31 | RSA_blinding_on() returns 1 on success, and 0 if an error occurred. | ||
32 | |||
33 | =head1 SEE ALSO | ||
34 | |||
35 | L<rsa(3)|rsa(3)>, L<rand(3)|rand(3)> | ||
36 | |||
37 | =head1 HISTORY | ||
38 | |||
39 | RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0. | ||
40 | |||
41 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_check_key.pod b/src/lib/libcrypto/doc/RSA_check_key.pod deleted file mode 100644 index a5198f3db5..0000000000 --- a/src/lib/libcrypto/doc/RSA_check_key.pod +++ /dev/null | |||
@@ -1,67 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_check_key - validate private RSA keys | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_check_key(RSA *rsa); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | This function validates RSA keys. It checks that B<p> and B<q> are | ||
16 | in fact prime, and that B<n = p*q>. | ||
17 | |||
18 | It also checks that B<d*e = 1 mod (p-1*q-1)>, | ||
19 | and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>. | ||
20 | |||
21 | As such, this function can not be used with any arbitrary RSA key object, | ||
22 | even if it is otherwise fit for regular RSA operation. See B<NOTES> for more | ||
23 | information. | ||
24 | |||
25 | =head1 RETURN VALUE | ||
26 | |||
27 | RSA_check_key() returns 1 if B<rsa> is a valid RSA key, and 0 otherwise. | ||
28 | -1 is returned if an error occurs while checking the key. | ||
29 | |||
30 | If the key is invalid or an error occurred, the reason code can be | ||
31 | obtained using L<ERR_get_error(3)|ERR_get_error(3)>. | ||
32 | |||
33 | =head1 NOTES | ||
34 | |||
35 | This function does not work on RSA public keys that have only the modulus | ||
36 | and public exponent elements populated. It performs integrity checks on all | ||
37 | the RSA key material, so the RSA key structure must contain all the private | ||
38 | key data too. | ||
39 | |||
40 | Unlike most other RSA functions, this function does B<not> work | ||
41 | transparently with any underlying ENGINE implementation because it uses the | ||
42 | key data in the RSA structure directly. An ENGINE implementation can | ||
43 | override the way key data is stored and handled, and can even provide | ||
44 | support for HSM keys - in which case the RSA structure may contain B<no> | ||
45 | key data at all! If the ENGINE in question is only being used for | ||
46 | acceleration or analysis purposes, then in all likelihood the RSA key data | ||
47 | is complete and untouched, but this can't be assumed in the general case. | ||
48 | |||
49 | =head1 BUGS | ||
50 | |||
51 | A method of verifying the RSA key using opaque RSA API functions might need | ||
52 | to be considered. Right now RSA_check_key() simply uses the RSA structure | ||
53 | elements directly, bypassing the RSA_METHOD table altogether (and | ||
54 | completely violating encapsulation and object-orientation in the process). | ||
55 | The best fix will probably be to introduce a "check_key()" handler to the | ||
56 | RSA_METHOD function table so that alternative implementations can also | ||
57 | provide their own verifiers. | ||
58 | |||
59 | =head1 SEE ALSO | ||
60 | |||
61 | L<rsa(3)|rsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> | ||
62 | |||
63 | =head1 HISTORY | ||
64 | |||
65 | RSA_check_key() appeared in OpenSSL 0.9.4. | ||
66 | |||
67 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_generate_key.pod b/src/lib/libcrypto/doc/RSA_generate_key.pod deleted file mode 100644 index 00026f04df..0000000000 --- a/src/lib/libcrypto/doc/RSA_generate_key.pod +++ /dev/null | |||
@@ -1,79 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_generate_key_ex, RSA_generate_key - generate RSA key pair | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); | ||
12 | |||
13 | Deprecated: | ||
14 | |||
15 | RSA *RSA_generate_key(int num, unsigned long e, | ||
16 | void (*callback)(int,int,void *), void *cb_arg); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | RSA_generate_key_ex() generates a key pair and stores it in the B<RSA> | ||
21 | structure provided in B<rsa>. | ||
22 | |||
23 | The modulus size will be of length B<bits>, and the public exponent will be | ||
24 | B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure. | ||
25 | The exponent is an odd number, typically 3, 17 or 65537. | ||
26 | |||
27 | A callback function may be used to provide feedback about the | ||
28 | progress of the key generation. If B<cb> is not B<NULL>, it | ||
29 | will be called as follows using the BN_GENCB_call() function | ||
30 | described on the L<BN_generate_prime(3)|BN_generate_prime(3)> page: | ||
31 | |||
32 | =over 4 | ||
33 | |||
34 | =item * | ||
35 | |||
36 | While a random prime number is generated, it is called as | ||
37 | described in L<BN_generate_prime(3)|BN_generate_prime(3)>. | ||
38 | |||
39 | =item * | ||
40 | |||
41 | When the n-th randomly generated prime is rejected as not | ||
42 | suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called. | ||
43 | |||
44 | =item * | ||
45 | |||
46 | When a random p has been found with p-1 relatively prime to B<e>, | ||
47 | it is called as B<BN_GENCB_call(cb, 3, 0)>. | ||
48 | |||
49 | =back | ||
50 | |||
51 | The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>. | ||
52 | |||
53 | RSA_generate_key is deprecated (new applications should use | ||
54 | RSA_generate_key_ex instead). RSA_generate_key works in the same was as | ||
55 | RSA_generate_key_ex except it uses "old style" call backs. See | ||
56 | L<BN_generate_prime(3)|BN_generate_prime(3)> for further details. | ||
57 | |||
58 | =head1 RETURN VALUE | ||
59 | |||
60 | If key generation fails, RSA_generate_key() returns B<NULL>. | ||
61 | |||
62 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
63 | |||
64 | =head1 BUGS | ||
65 | |||
66 | B<BN_GENCB_call(cb, 2, x)> is used with two different meanings. | ||
67 | |||
68 | RSA_generate_key() goes into an infinite loop for illegal input values. | ||
69 | |||
70 | =head1 SEE ALSO | ||
71 | |||
72 | L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, | ||
73 | L<RSA_free(3)|RSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)> | ||
74 | |||
75 | =head1 HISTORY | ||
76 | |||
77 | The B<cb_arg> argument was added in SSLeay 0.9.0. | ||
78 | |||
79 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod b/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod deleted file mode 100644 index b1ac1167dd..0000000000 --- a/src/lib/libcrypto/doc/RSA_get_ex_new_index.pod +++ /dev/null | |||
@@ -1,122 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application | ||
6 | specific data to RSA structures | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/rsa.h> | ||
11 | |||
12 | int RSA_get_ex_new_index(long argl, void *argp, | ||
13 | CRYPTO_EX_new *new_func, | ||
14 | CRYPTO_EX_dup *dup_func, | ||
15 | CRYPTO_EX_free *free_func); | ||
16 | |||
17 | int RSA_set_ex_data(RSA *r, int idx, void *arg); | ||
18 | |||
19 | void *RSA_get_ex_data(RSA *r, int idx); | ||
20 | |||
21 | typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, | ||
22 | int idx, long argl, void *argp); | ||
23 | typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, | ||
24 | int idx, long argl, void *argp); | ||
25 | typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, | ||
26 | int idx, long argl, void *argp); | ||
27 | |||
28 | =head1 DESCRIPTION | ||
29 | |||
30 | Several OpenSSL structures can have application specific data attached to them. | ||
31 | This has several potential uses, it can be used to cache data associated with | ||
32 | a structure (for example the hash of some part of the structure) or some | ||
33 | additional data (for example a handle to the data in an external library). | ||
34 | |||
35 | Since the application data can be anything at all it is passed and retrieved | ||
36 | as a B<void *> type. | ||
37 | |||
38 | The B<RSA_get_ex_new_index()> function is initially called to "register" some | ||
39 | new application specific data. It takes three optional function pointers which | ||
40 | are called when the parent structure (in this case an RSA structure) is | ||
41 | initially created, when it is copied and when it is freed up. If any or all of | ||
42 | these function pointer arguments are not used they should be set to NULL. The | ||
43 | precise manner in which these function pointers are called is described in more | ||
44 | detail below. B<RSA_get_ex_new_index()> also takes additional long and pointer | ||
45 | parameters which will be passed to the supplied functions but which otherwise | ||
46 | have no special meaning. It returns an B<index> which should be stored | ||
47 | (typically in a static variable) and passed used in the B<idx> parameter in | ||
48 | the remaining functions. Each successful call to B<RSA_get_ex_new_index()> | ||
49 | will return an index greater than any previously returned, this is important | ||
50 | because the optional functions are called in order of increasing index value. | ||
51 | |||
52 | B<RSA_set_ex_data()> is used to set application specific data, the data is | ||
53 | supplied in the B<arg> parameter and its precise meaning is up to the | ||
54 | application. | ||
55 | |||
56 | B<RSA_get_ex_data()> is used to retrieve application specific data. The data | ||
57 | is returned to the application, this will be the same value as supplied to | ||
58 | a previous B<RSA_set_ex_data()> call. | ||
59 | |||
60 | B<new_func()> is called when a structure is initially allocated (for example | ||
61 | with B<RSA_new()>. The parent structure members will not have any meaningful | ||
62 | values at this point. This function will typically be used to allocate any | ||
63 | application specific structure. | ||
64 | |||
65 | B<free_func()> is called when a structure is being freed up. The dynamic parent | ||
66 | structure members should not be accessed because they will be freed up when | ||
67 | this function is called. | ||
68 | |||
69 | B<new_func()> and B<free_func()> take the same parameters. B<parent> is a | ||
70 | pointer to the parent RSA structure. B<ptr> is a the application specific data | ||
71 | (this wont be of much use in B<new_func()>. B<ad> is a pointer to the | ||
72 | B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions | ||
73 | B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate | ||
74 | it. The B<idx> parameter is the index: this will be the same value returned by | ||
75 | B<RSA_get_ex_new_index()> when the functions were initially registered. Finally | ||
76 | the B<argl> and B<argp> parameters are the values originally passed to the same | ||
77 | corresponding parameters when B<RSA_get_ex_new_index()> was called. | ||
78 | |||
79 | B<dup_func()> is called when a structure is being copied. Pointers to the | ||
80 | destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and | ||
81 | B<from> parameters respectively. The B<from_d> parameter is passed a pointer to | ||
82 | the source application data when the function is called, when the function | ||
83 | returns the value is copied to the destination: the application can thus modify | ||
84 | the data pointed to by B<from_d> and have different values in the source and | ||
85 | destination. The B<idx>, B<argl> and B<argp> parameters are the same as those | ||
86 | in B<new_func()> and B<free_func()>. | ||
87 | |||
88 | =head1 RETURN VALUES | ||
89 | |||
90 | B<RSA_get_ex_new_index()> returns a new index or -1 on failure (note 0 is a | ||
91 | valid index value). | ||
92 | |||
93 | B<RSA_set_ex_data()> returns 1 on success or 0 on failure. | ||
94 | |||
95 | B<RSA_get_ex_data()> returns the application data or 0 on failure. 0 may also | ||
96 | be valid application data but currently it can only fail if given an invalid | ||
97 | B<idx> parameter. | ||
98 | |||
99 | B<new_func()> and B<dup_func()> should return 0 for failure and 1 for success. | ||
100 | |||
101 | On failure an error code can be obtained from | ||
102 | L<ERR_get_error(3)|ERR_get_error(3)>. | ||
103 | |||
104 | =head1 BUGS | ||
105 | |||
106 | B<dup_func()> is currently never called. | ||
107 | |||
108 | The return value of B<new_func()> is ignored. | ||
109 | |||
110 | The B<new_func()> function isn't very useful because no meaningful values are | ||
111 | present in the parent RSA structure when it is called. | ||
112 | |||
113 | =head1 SEE ALSO | ||
114 | |||
115 | L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> | ||
116 | |||
117 | =head1 HISTORY | ||
118 | |||
119 | RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are | ||
120 | available since SSLeay 0.9.0. | ||
121 | |||
122 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_new.pod b/src/lib/libcrypto/doc/RSA_new.pod deleted file mode 100644 index 0c85dc1d62..0000000000 --- a/src/lib/libcrypto/doc/RSA_new.pod +++ /dev/null | |||
@@ -1,39 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_new, RSA_free - allocate and free RSA objects | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | RSA * RSA_new(void); | ||
12 | |||
13 | void RSA_free(RSA *rsa); | ||
14 | |||
15 | =head1 DESCRIPTION | ||
16 | |||
17 | RSA_new() allocates and initializes an B<RSA> structure. It is equivalent to | ||
18 | calling RSA_new_method(NULL). | ||
19 | |||
20 | RSA_free() frees the B<RSA> structure and its components. The key is | ||
21 | erased before the memory is returned to the system. | ||
22 | |||
23 | =head1 RETURN VALUES | ||
24 | |||
25 | If the allocation fails, RSA_new() returns B<NULL> and sets an error code that | ||
26 | can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a | ||
27 | pointer to the newly allocated structure. | ||
28 | |||
29 | =head1 SEE ALSO | ||
30 | |||
31 | L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>, | ||
32 | L<RSA_generate_key(3)|RSA_generate_key(3)>, | ||
33 | L<RSA_new_method(3)|RSA_new_method(3)> | ||
34 | |||
35 | =head1 HISTORY | ||
36 | |||
37 | RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL. | ||
38 | |||
39 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod b/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod deleted file mode 100644 index 1c90b2b44d..0000000000 --- a/src/lib/libcrypto/doc/RSA_padding_add_PKCS1_type_1.pod +++ /dev/null | |||
@@ -1,121 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1, | ||
6 | RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2, | ||
7 | RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP, | ||
8 | RSA_padding_add_SSLv23, RSA_padding_check_SSLv23, | ||
9 | RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption | ||
10 | padding | ||
11 | |||
12 | =head1 SYNOPSIS | ||
13 | |||
14 | #include <openssl/rsa.h> | ||
15 | |||
16 | int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, | ||
17 | unsigned char *f, int fl); | ||
18 | |||
19 | int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, | ||
20 | unsigned char *f, int fl, int rsa_len); | ||
21 | |||
22 | int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, | ||
23 | unsigned char *f, int fl); | ||
24 | |||
25 | int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, | ||
26 | unsigned char *f, int fl, int rsa_len); | ||
27 | |||
28 | int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, | ||
29 | unsigned char *f, int fl, unsigned char *p, int pl); | ||
30 | |||
31 | int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, | ||
32 | unsigned char *f, int fl, int rsa_len, unsigned char *p, int pl); | ||
33 | |||
34 | int RSA_padding_add_SSLv23(unsigned char *to, int tlen, | ||
35 | unsigned char *f, int fl); | ||
36 | |||
37 | int RSA_padding_check_SSLv23(unsigned char *to, int tlen, | ||
38 | unsigned char *f, int fl, int rsa_len); | ||
39 | |||
40 | int RSA_padding_add_none(unsigned char *to, int tlen, | ||
41 | unsigned char *f, int fl); | ||
42 | |||
43 | int RSA_padding_check_none(unsigned char *to, int tlen, | ||
44 | unsigned char *f, int fl, int rsa_len); | ||
45 | |||
46 | =head1 DESCRIPTION | ||
47 | |||
48 | The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, | ||
49 | decrypt, sign and verify functions. Normally they should not be called | ||
50 | from application programs. | ||
51 | |||
52 | However, they can also be called directly to implement padding for other | ||
53 | asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and | ||
54 | RSA_padding_check_PKCS1_OAEP() may be used in an application combined | ||
55 | with B<RSA_NO_PADDING> in order to implement OAEP with an encoding | ||
56 | parameter. | ||
57 | |||
58 | RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into | ||
59 | B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl> | ||
60 | does not meet the size requirements of the encoding method. | ||
61 | |||
62 | The following encoding methods are implemented: | ||
63 | |||
64 | =over 4 | ||
65 | |||
66 | =item PKCS1_type_1 | ||
67 | |||
68 | PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures | ||
69 | |||
70 | =item PKCS1_type_2 | ||
71 | |||
72 | PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) | ||
73 | |||
74 | =item PKCS1_OAEP | ||
75 | |||
76 | PKCS #1 v2.0 EME-OAEP | ||
77 | |||
78 | =item SSLv23 | ||
79 | |||
80 | PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification | ||
81 | |||
82 | =item none | ||
83 | |||
84 | simply copy the data | ||
85 | |||
86 | =back | ||
87 | |||
88 | RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain | ||
89 | a valid encoding for a B<rsa_len> byte RSA key in the respective | ||
90 | encoding method and stores the recovered data of at most B<tlen> bytes | ||
91 | (for B<RSA_NO_PADDING>: of size B<tlen>) | ||
92 | at B<to>. | ||
93 | |||
94 | For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter | ||
95 | of length B<pl>. B<p> may be B<NULL> if B<pl> is 0. | ||
96 | |||
97 | =head1 RETURN VALUES | ||
98 | |||
99 | The RSA_padding_add_xxx() functions return 1 on success, 0 on error. | ||
100 | The RSA_padding_check_xxx() functions return the length of the | ||
101 | recovered data, -1 on error. Error codes can be obtained by calling | ||
102 | L<ERR_get_error(3)|ERR_get_error(3)>. | ||
103 | |||
104 | =head1 SEE ALSO | ||
105 | |||
106 | L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, | ||
107 | L<RSA_private_decrypt(3)|RSA_private_decrypt(3)>, | ||
108 | L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> | ||
109 | |||
110 | =head1 HISTORY | ||
111 | |||
112 | RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(), | ||
113 | RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(), | ||
114 | RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(), | ||
115 | RSA_padding_add_none() and RSA_padding_check_none() appeared in | ||
116 | SSLeay 0.9.0. | ||
117 | |||
118 | RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were | ||
119 | added in OpenSSL 0.9.2b. | ||
120 | |||
121 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_print.pod b/src/lib/libcrypto/doc/RSA_print.pod deleted file mode 100644 index c971e91f4d..0000000000 --- a/src/lib/libcrypto/doc/RSA_print.pod +++ /dev/null | |||
@@ -1,49 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_print, RSA_print_fp, | ||
6 | DSAparams_print, DSAparams_print_fp, DSA_print, DSA_print_fp, | ||
7 | DHparams_print, DHparams_print_fp - print cryptographic parameters | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/rsa.h> | ||
12 | |||
13 | int RSA_print(BIO *bp, RSA *x, int offset); | ||
14 | int RSA_print_fp(FILE *fp, RSA *x, int offset); | ||
15 | |||
16 | #include <openssl/dsa.h> | ||
17 | |||
18 | int DSAparams_print(BIO *bp, DSA *x); | ||
19 | int DSAparams_print_fp(FILE *fp, DSA *x); | ||
20 | int DSA_print(BIO *bp, DSA *x, int offset); | ||
21 | int DSA_print_fp(FILE *fp, DSA *x, int offset); | ||
22 | |||
23 | #include <openssl/dh.h> | ||
24 | |||
25 | int DHparams_print(BIO *bp, DH *x); | ||
26 | int DHparams_print_fp(FILE *fp, DH *x); | ||
27 | |||
28 | =head1 DESCRIPTION | ||
29 | |||
30 | A human-readable hexadecimal output of the components of the RSA | ||
31 | key, DSA parameters or key or DH parameters is printed to B<bp> or B<fp>. | ||
32 | |||
33 | The output lines are indented by B<offset> spaces. | ||
34 | |||
35 | =head1 RETURN VALUES | ||
36 | |||
37 | These functions return 1 on success, 0 on error. | ||
38 | |||
39 | =head1 SEE ALSO | ||
40 | |||
41 | L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> | ||
42 | |||
43 | =head1 HISTORY | ||
44 | |||
45 | RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(), | ||
46 | DH_print_fp() are available in all versions of SSLeay and OpenSSL. | ||
47 | DSAparams_print() and DSAparams_print_fp() were added in SSLeay 0.8. | ||
48 | |||
49 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_private_encrypt.pod b/src/lib/libcrypto/doc/RSA_private_encrypt.pod deleted file mode 100644 index aa2bc1bd76..0000000000 --- a/src/lib/libcrypto/doc/RSA_private_encrypt.pod +++ /dev/null | |||
@@ -1,69 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_private_encrypt, RSA_public_decrypt - low level signature operations | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_private_encrypt(int flen, unsigned char *from, | ||
12 | unsigned char *to, RSA *rsa, int padding); | ||
13 | |||
14 | int RSA_public_decrypt(int flen, unsigned char *from, | ||
15 | unsigned char *to, RSA *rsa, int padding); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | These functions handle RSA signatures at a low level. | ||
20 | |||
21 | RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a | ||
22 | message digest with an algorithm identifier) using the private key | ||
23 | B<rsa> and stores the signature in B<to>. B<to> must point to | ||
24 | B<RSA_size(rsa)> bytes of memory. | ||
25 | |||
26 | B<padding> denotes one of the following modes: | ||
27 | |||
28 | =over 4 | ||
29 | |||
30 | =item RSA_PKCS1_PADDING | ||
31 | |||
32 | PKCS #1 v1.5 padding. This function does not handle the B<algorithmIdentifier> | ||
33 | specified in PKCS #1. When generating or verifying PKCS #1 signatures, | ||
34 | L<RSA_sign(3)|RSA_sign(3)> and L<RSA_verify(3)|RSA_verify(3)> should be used. | ||
35 | |||
36 | =item RSA_NO_PADDING | ||
37 | |||
38 | Raw RSA signature. This mode should I<only> be used to implement | ||
39 | cryptographically sound padding modes in the application code. | ||
40 | Signing user data directly with RSA is insecure. | ||
41 | |||
42 | =back | ||
43 | |||
44 | RSA_public_decrypt() recovers the message digest from the B<flen> | ||
45 | bytes long signature at B<from> using the signer's public key | ||
46 | B<rsa>. B<to> must point to a memory section large enough to hold the | ||
47 | message digest (which is smaller than B<RSA_size(rsa) - | ||
48 | 11>). B<padding> is the padding mode that was used to sign the data. | ||
49 | |||
50 | =head1 RETURN VALUES | ||
51 | |||
52 | RSA_private_encrypt() returns the size of the signature (i.e., | ||
53 | RSA_size(rsa)). RSA_public_decrypt() returns the size of the | ||
54 | recovered message digest. | ||
55 | |||
56 | On error, -1 is returned; the error codes can be | ||
57 | obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
58 | |||
59 | =head1 SEE ALSO | ||
60 | |||
61 | L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>, | ||
62 | L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> | ||
63 | |||
64 | =head1 HISTORY | ||
65 | |||
66 | The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is | ||
67 | available since SSLeay 0.9.0. | ||
68 | |||
69 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_public_encrypt.pod b/src/lib/libcrypto/doc/RSA_public_encrypt.pod deleted file mode 100644 index 4bbee53f09..0000000000 --- a/src/lib/libcrypto/doc/RSA_public_encrypt.pod +++ /dev/null | |||
@@ -1,82 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_public_encrypt(int flen, unsigned char *from, | ||
12 | unsigned char *to, RSA *rsa, int padding); | ||
13 | |||
14 | int RSA_private_decrypt(int flen, unsigned char *from, | ||
15 | unsigned char *to, RSA *rsa, int padding); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a | ||
20 | session key) using the public key B<rsa> and stores the ciphertext in | ||
21 | B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory. | ||
22 | |||
23 | B<padding> denotes one of the following modes: | ||
24 | |||
25 | =over 4 | ||
26 | |||
27 | =item RSA_PKCS1_PADDING | ||
28 | |||
29 | PKCS #1 v1.5 padding. This currently is the most widely used mode. | ||
30 | |||
31 | =item RSA_PKCS1_OAEP_PADDING | ||
32 | |||
33 | EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty | ||
34 | encoding parameter. This mode is recommended for all new applications. | ||
35 | |||
36 | =item RSA_SSLV23_PADDING | ||
37 | |||
38 | PKCS #1 v1.5 padding with an SSL-specific modification that denotes | ||
39 | that the server is SSL3 capable. | ||
40 | |||
41 | =item RSA_NO_PADDING | ||
42 | |||
43 | Raw RSA encryption. This mode should I<only> be used to implement | ||
44 | cryptographically sound padding modes in the application code. | ||
45 | Encrypting user data directly with RSA is insecure. | ||
46 | |||
47 | =back | ||
48 | |||
49 | B<flen> must be less than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5 | ||
50 | based padding modes, less than RSA_size(B<rsa>) - 41 for | ||
51 | RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING. | ||
52 | |||
53 | RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the | ||
54 | private key B<rsa> and stores the plaintext in B<to>. B<to> must point | ||
55 | to a memory section large enough to hold the decrypted data (which is | ||
56 | smaller than RSA_size(B<rsa>)). B<padding> is the padding mode that | ||
57 | was used to encrypt the data. | ||
58 | |||
59 | =head1 RETURN VALUES | ||
60 | |||
61 | RSA_public_encrypt() returns the size of the encrypted data (i.e., | ||
62 | RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the | ||
63 | recovered plaintext. | ||
64 | |||
65 | On error, -1 is returned; the error codes can be | ||
66 | obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
67 | |||
68 | =head1 CONFORMING TO | ||
69 | |||
70 | SSL, PKCS #1 v2.0 | ||
71 | |||
72 | =head1 SEE ALSO | ||
73 | |||
74 | L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, | ||
75 | L<RSA_size(3)|RSA_size(3)> | ||
76 | |||
77 | =head1 HISTORY | ||
78 | |||
79 | The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is | ||
80 | available since SSLeay 0.9.0, OAEP was added in OpenSSL 0.9.2b. | ||
81 | |||
82 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_set_method.pod b/src/lib/libcrypto/doc/RSA_set_method.pod deleted file mode 100644 index 3f50a89e5c..0000000000 --- a/src/lib/libcrypto/doc/RSA_set_method.pod +++ /dev/null | |||
@@ -1,201 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_set_default_method, RSA_get_default_method, RSA_set_method, | ||
6 | RSA_get_method, RSA_PKCS1_SSLeay, RSA_null_method, RSA_flags, | ||
7 | RSA_new_method, RSA_get_default_openssl_method, | ||
8 | RSA_set_default_openssl_method - select RSA method | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/rsa.h> | ||
13 | |||
14 | void RSA_set_default_method(const RSA_METHOD *meth); | ||
15 | |||
16 | RSA_METHOD *RSA_get_default_method(void); | ||
17 | |||
18 | int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); | ||
19 | |||
20 | RSA_METHOD *RSA_get_method(const RSA *rsa); | ||
21 | |||
22 | RSA_METHOD *RSA_PKCS1_SSLeay(void); | ||
23 | |||
24 | RSA_METHOD *RSA_null_method(void); | ||
25 | |||
26 | int RSA_flags(const RSA *rsa); | ||
27 | |||
28 | RSA *RSA_new_method(RSA_METHOD *method); | ||
29 | |||
30 | =head1 DESCRIPTION | ||
31 | |||
32 | An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA | ||
33 | operations. By modifying the method, alternative implementations such as | ||
34 | hardware accelerators may be used. IMPORTANT: See the NOTES section for | ||
35 | important information about how these RSA API functions are affected by the | ||
36 | use of B<ENGINE> API calls. | ||
37 | |||
38 | Initially, the default RSA_METHOD is the OpenSSL internal implementation, | ||
39 | as returned by RSA_PKCS1_SSLeay(). | ||
40 | |||
41 | RSA_set_default_method() makes B<meth> the default method for all RSA | ||
42 | structures created later. B<NB>: This is true only whilst no ENGINE has | ||
43 | been set as a default for RSA, so this function is no longer recommended. | ||
44 | |||
45 | RSA_get_default_method() returns a pointer to the current default | ||
46 | RSA_METHOD. However, the meaningfulness of this result is dependent on | ||
47 | whether the ENGINE API is being used, so this function is no longer | ||
48 | recommended. | ||
49 | |||
50 | RSA_set_method() selects B<meth> to perform all operations using the key | ||
51 | B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the | ||
52 | previous method was supplied by an ENGINE, the handle to that ENGINE will | ||
53 | be released during the change. It is possible to have RSA keys that only | ||
54 | work with certain RSA_METHOD implementations (eg. from an ENGINE module | ||
55 | that supports embedded hardware-protected keys), and in such cases | ||
56 | attempting to change the RSA_METHOD for the key can have unexpected | ||
57 | results. | ||
58 | |||
59 | RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>. | ||
60 | This method may or may not be supplied by an ENGINE implementation, but if | ||
61 | it is, the return value can only be guaranteed to be valid as long as the | ||
62 | RSA key itself is valid and does not have its implementation changed by | ||
63 | RSA_set_method(). | ||
64 | |||
65 | RSA_flags() returns the B<flags> that are set for B<rsa>'s current | ||
66 | RSA_METHOD. See the BUGS section. | ||
67 | |||
68 | RSA_new_method() allocates and initializes an RSA structure so that | ||
69 | B<engine> will be used for the RSA operations. If B<engine> is NULL, the | ||
70 | default ENGINE for RSA operations is used, and if no default ENGINE is set, | ||
71 | the RSA_METHOD controlled by RSA_set_default_method() is used. | ||
72 | |||
73 | RSA_flags() returns the B<flags> that are set for B<rsa>'s current method. | ||
74 | |||
75 | RSA_new_method() allocates and initializes an B<RSA> structure so that | ||
76 | B<method> will be used for the RSA operations. If B<method> is B<NULL>, | ||
77 | the default method is used. | ||
78 | |||
79 | =head1 THE RSA_METHOD STRUCTURE | ||
80 | |||
81 | typedef struct rsa_meth_st | ||
82 | { | ||
83 | /* name of the implementation */ | ||
84 | const char *name; | ||
85 | |||
86 | /* encrypt */ | ||
87 | int (*rsa_pub_enc)(int flen, unsigned char *from, | ||
88 | unsigned char *to, RSA *rsa, int padding); | ||
89 | |||
90 | /* verify arbitrary data */ | ||
91 | int (*rsa_pub_dec)(int flen, unsigned char *from, | ||
92 | unsigned char *to, RSA *rsa, int padding); | ||
93 | |||
94 | /* sign arbitrary data */ | ||
95 | int (*rsa_priv_enc)(int flen, unsigned char *from, | ||
96 | unsigned char *to, RSA *rsa, int padding); | ||
97 | |||
98 | /* decrypt */ | ||
99 | int (*rsa_priv_dec)(int flen, unsigned char *from, | ||
100 | unsigned char *to, RSA *rsa, int padding); | ||
101 | |||
102 | /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some | ||
103 | implementations) */ | ||
104 | int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); | ||
105 | |||
106 | /* compute r = a ^ p mod m (May be NULL for some implementations) */ | ||
107 | int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, | ||
108 | const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); | ||
109 | |||
110 | /* called at RSA_new */ | ||
111 | int (*init)(RSA *rsa); | ||
112 | |||
113 | /* called at RSA_free */ | ||
114 | int (*finish)(RSA *rsa); | ||
115 | |||
116 | /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key | ||
117 | * operations, even if p,q,dmp1,dmq1,iqmp | ||
118 | * are NULL | ||
119 | * RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify | ||
120 | * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match | ||
121 | */ | ||
122 | int flags; | ||
123 | |||
124 | char *app_data; /* ?? */ | ||
125 | |||
126 | /* sign. For backward compatibility, this is used only | ||
127 | * if (flags & RSA_FLAG_SIGN_VER) | ||
128 | */ | ||
129 | int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len, | ||
130 | unsigned char *sigret, unsigned int *siglen, RSA *rsa); | ||
131 | |||
132 | /* verify. For backward compatibility, this is used only | ||
133 | * if (flags & RSA_FLAG_SIGN_VER) | ||
134 | */ | ||
135 | int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len, | ||
136 | unsigned char *sigbuf, unsigned int siglen, RSA *rsa); | ||
137 | |||
138 | } RSA_METHOD; | ||
139 | |||
140 | =head1 RETURN VALUES | ||
141 | |||
142 | RSA_PKCS1_SSLeay(), RSA_PKCS1_null_method(), RSA_get_default_method() | ||
143 | and RSA_get_method() return pointers to the respective RSA_METHODs. | ||
144 | |||
145 | RSA_set_method() returns a pointer to the old RSA_METHOD implementation | ||
146 | that was replaced. However, this return value should probably be ignored | ||
147 | because if it was supplied by an ENGINE, the pointer could be invalidated | ||
148 | at any time if the ENGINE is unloaded (in fact it could be unloaded as a | ||
149 | result of the RSA_set_method() function releasing its handle to the | ||
150 | ENGINE). For this reason, the return type may be replaced with a B<void> | ||
151 | declaration in a future release. | ||
152 | |||
153 | RSA_new_method() returns NULL and sets an error code that can be obtained | ||
154 | by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise | ||
155 | it returns a pointer to the newly allocated structure. | ||
156 | |||
157 | =head1 NOTES | ||
158 | |||
159 | As of version 0.9.7, RSA_METHOD implementations are grouped together with | ||
160 | other algorithmic APIs (eg. DSA_METHOD, EVP_CIPHER, etc) into B<ENGINE> | ||
161 | modules. If a default ENGINE is specified for RSA functionality using an | ||
162 | ENGINE API function, that will override any RSA defaults set using the RSA | ||
163 | API (ie. RSA_set_default_method()). For this reason, the ENGINE API is the | ||
164 | recommended way to control default implementations for use in RSA and other | ||
165 | cryptographic algorithms. | ||
166 | |||
167 | =head1 BUGS | ||
168 | |||
169 | The behaviour of RSA_flags() is a mis-feature that is left as-is for now | ||
170 | to avoid creating compatibility problems. RSA functionality, such as the | ||
171 | encryption functions, are controlled by the B<flags> value in the RSA key | ||
172 | itself, not by the B<flags> value in the RSA_METHOD attached to the RSA key | ||
173 | (which is what this function returns). If the flags element of an RSA key | ||
174 | is changed, the changes will be honoured by RSA functionality but will not | ||
175 | be reflected in the return value of the RSA_flags() function - in effect | ||
176 | RSA_flags() behaves more like an RSA_default_flags() function (which does | ||
177 | not currently exist). | ||
178 | |||
179 | =head1 SEE ALSO | ||
180 | |||
181 | L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)> | ||
182 | |||
183 | =head1 HISTORY | ||
184 | |||
185 | RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8. | ||
186 | RSA_get_default_method(), RSA_set_method() and RSA_get_method() as | ||
187 | well as the rsa_sign and rsa_verify components of RSA_METHOD were | ||
188 | added in OpenSSL 0.9.4. | ||
189 | |||
190 | RSA_set_default_openssl_method() and RSA_get_default_openssl_method() | ||
191 | replaced RSA_set_default_method() and RSA_get_default_method() | ||
192 | respectively, and RSA_set_method() and RSA_new_method() were altered to use | ||
193 | B<ENGINE>s rather than B<RSA_METHOD>s during development of the engine | ||
194 | version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the ENGINE | ||
195 | API was restructured so that this change was reversed, and behaviour of the | ||
196 | other functions resembled more closely the previous behaviour. The | ||
197 | behaviour of defaults in the ENGINE API now transparently overrides the | ||
198 | behaviour of defaults in the RSA API without requiring changing these | ||
199 | function prototypes. | ||
200 | |||
201 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_sign.pod b/src/lib/libcrypto/doc/RSA_sign.pod deleted file mode 100644 index 51587bdc41..0000000000 --- a/src/lib/libcrypto/doc/RSA_sign.pod +++ /dev/null | |||
@@ -1,61 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_sign, RSA_verify - RSA signatures | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_sign(int type, const unsigned char *m, unsigned int m_len, | ||
12 | unsigned char *sigret, unsigned int *siglen, RSA *rsa); | ||
13 | |||
14 | int RSA_verify(int type, const unsigned char *m, unsigned int m_len, | ||
15 | unsigned char *sigbuf, unsigned int siglen, RSA *rsa); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | RSA_sign() signs the message digest B<m> of size B<m_len> using the | ||
20 | private key B<rsa> as specified in PKCS #1 v2.0. It stores the | ||
21 | signature in B<sigret> and the signature size in B<siglen>. B<sigret> | ||
22 | must point to RSA_size(B<rsa>) bytes of memory. | ||
23 | Note that PKCS #1 adds meta-data, placing limits on the size of the | ||
24 | key that can be used. | ||
25 | See L<RSA_private_encrypt(3)|RSA_private_encrypt(3)> for lower-level | ||
26 | operations. | ||
27 | |||
28 | B<type> denotes the message digest algorithm that was used to generate | ||
29 | B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>; | ||
30 | see L<objects(3)|objects(3)> for details. If B<type> is B<NID_md5_sha1>, | ||
31 | an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding | ||
32 | and no algorithm identifier) is created. | ||
33 | |||
34 | RSA_verify() verifies that the signature B<sigbuf> of size B<siglen> | ||
35 | matches a given message digest B<m> of size B<m_len>. B<type> denotes | ||
36 | the message digest algorithm that was used to generate the signature. | ||
37 | B<rsa> is the signer's public key. | ||
38 | |||
39 | =head1 RETURN VALUES | ||
40 | |||
41 | RSA_sign() returns 1 on success, 0 otherwise. RSA_verify() returns 1 | ||
42 | on successful verification, 0 otherwise. | ||
43 | |||
44 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
45 | |||
46 | =head1 CONFORMING TO | ||
47 | |||
48 | SSL, PKCS #1 v2.0 | ||
49 | |||
50 | =head1 SEE ALSO | ||
51 | |||
52 | L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>, | ||
53 | L<rsa(3)|rsa(3)>, L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, | ||
54 | L<RSA_public_decrypt(3)|RSA_public_decrypt(3)> | ||
55 | |||
56 | =head1 HISTORY | ||
57 | |||
58 | RSA_sign() and RSA_verify() are available in all versions of SSLeay | ||
59 | and OpenSSL. | ||
60 | |||
61 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod b/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod deleted file mode 100644 index 664b46174b..0000000000 --- a/src/lib/libcrypto/doc/RSA_sign_ASN1_OCTET_STRING.pod +++ /dev/null | |||
@@ -1,57 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, | ||
12 | unsigned int m_len, unsigned char *sigret, unsigned int *siglen, | ||
13 | RSA *rsa); | ||
14 | |||
15 | int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, | ||
16 | unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, | ||
17 | RSA *rsa); | ||
18 | |||
19 | =head1 DESCRIPTION | ||
20 | |||
21 | RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size | ||
22 | B<m_len> using the private key B<rsa> represented in DER using PKCS #1 | ||
23 | padding. It stores the signature in B<sigret> and the signature size | ||
24 | in B<siglen>. B<sigret> must point to B<RSA_size(rsa)> bytes of | ||
25 | memory. | ||
26 | |||
27 | B<dummy> is ignored. | ||
28 | |||
29 | RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf> | ||
30 | of size B<siglen> is the DER representation of a given octet string | ||
31 | B<m> of size B<m_len>. B<dummy> is ignored. B<rsa> is the signer's | ||
32 | public key. | ||
33 | |||
34 | =head1 RETURN VALUES | ||
35 | |||
36 | RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise. | ||
37 | RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0 | ||
38 | otherwise. | ||
39 | |||
40 | The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
41 | |||
42 | =head1 BUGS | ||
43 | |||
44 | These functions serve no recognizable purpose. | ||
45 | |||
46 | =head1 SEE ALSO | ||
47 | |||
48 | L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>, | ||
49 | L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, | ||
50 | L<RSA_verify(3)|RSA_verify(3)> | ||
51 | |||
52 | =head1 HISTORY | ||
53 | |||
54 | RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were | ||
55 | added in SSLeay 0.8. | ||
56 | |||
57 | =cut | ||
diff --git a/src/lib/libcrypto/doc/RSA_size.pod b/src/lib/libcrypto/doc/RSA_size.pod deleted file mode 100644 index 5b7f835f95..0000000000 --- a/src/lib/libcrypto/doc/RSA_size.pod +++ /dev/null | |||
@@ -1,33 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | RSA_size - get RSA modulus size | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | |||
11 | int RSA_size(const RSA *rsa); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | This function returns the RSA modulus size in bytes. It can be used to | ||
16 | determine how much memory must be allocated for an RSA encrypted | ||
17 | value. | ||
18 | |||
19 | B<rsa-E<gt>n> must not be B<NULL>. | ||
20 | |||
21 | =head1 RETURN VALUE | ||
22 | |||
23 | The size in bytes. | ||
24 | |||
25 | =head1 SEE ALSO | ||
26 | |||
27 | L<rsa(3)|rsa(3)> | ||
28 | |||
29 | =head1 HISTORY | ||
30 | |||
31 | RSA_size() is available in all versions of SSLeay and OpenSSL. | ||
32 | |||
33 | =cut | ||
diff --git a/src/lib/libcrypto/doc/SHA1.pod b/src/lib/libcrypto/doc/SHA1.pod deleted file mode 100644 index 9fffdf59e7..0000000000 --- a/src/lib/libcrypto/doc/SHA1.pod +++ /dev/null | |||
@@ -1,71 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/sha.h> | ||
10 | |||
11 | unsigned char *SHA1(const unsigned char *d, unsigned long n, | ||
12 | unsigned char *md); | ||
13 | |||
14 | int SHA1_Init(SHA_CTX *c); | ||
15 | int SHA1_Update(SHA_CTX *c, const void *data, | ||
16 | unsigned long len); | ||
17 | int SHA1_Final(unsigned char *md, SHA_CTX *c); | ||
18 | |||
19 | =head1 DESCRIPTION | ||
20 | |||
21 | SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a | ||
22 | 160 bit output. | ||
23 | |||
24 | SHA1() computes the SHA-1 message digest of the B<n> | ||
25 | bytes at B<d> and places it in B<md> (which must have space for | ||
26 | SHA_DIGEST_LENGTH == 20 bytes of output). If B<md> is NULL, the digest | ||
27 | is placed in a static array. | ||
28 | |||
29 | The following functions may be used if the message is not completely | ||
30 | stored in memory: | ||
31 | |||
32 | SHA1_Init() initializes a B<SHA_CTX> structure. | ||
33 | |||
34 | SHA1_Update() can be called repeatedly with chunks of the message to | ||
35 | be hashed (B<len> bytes at B<data>). | ||
36 | |||
37 | SHA1_Final() places the message digest in B<md>, which must have space | ||
38 | for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B<SHA_CTX>. | ||
39 | |||
40 | Applications should use the higher level functions | ||
41 | L<EVP_DigestInit(3)|EVP_DigestInit(3)> | ||
42 | etc. instead of calling the hash functions directly. | ||
43 | |||
44 | The predecessor of SHA-1, SHA, is also implemented, but it should be | ||
45 | used only when backward compatibility is required. | ||
46 | |||
47 | =head1 RETURN VALUES | ||
48 | |||
49 | SHA1() returns a pointer to the hash value. | ||
50 | |||
51 | SHA1_Init(), SHA1_Update() and SHA1_Final() return 1 for success, 0 otherwise. | ||
52 | |||
53 | =head1 CONFORMING TO | ||
54 | |||
55 | SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash | ||
56 | Standard), | ||
57 | SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash | ||
58 | Standard), | ||
59 | ANSI X9.30 | ||
60 | |||
61 | =head1 SEE ALSO | ||
62 | |||
63 | L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, | ||
64 | L<EVP_DigestInit(3)|EVP_DigestInit(3)> | ||
65 | |||
66 | =head1 HISTORY | ||
67 | |||
68 | SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all | ||
69 | versions of SSLeay and OpenSSL. | ||
70 | |||
71 | =cut | ||
diff --git a/src/lib/libcrypto/doc/SMIME_read_CMS.pod b/src/lib/libcrypto/doc/SMIME_read_CMS.pod deleted file mode 100644 index acc5524c14..0000000000 --- a/src/lib/libcrypto/doc/SMIME_read_CMS.pod +++ /dev/null | |||
@@ -1,70 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | SMIME_read_CMS - parse S/MIME message. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/cms.h> | ||
10 | |||
11 | CMS_ContentInfo *SMIME_read_CMS(BIO *in, BIO **bcont); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | SMIME_read_CMS() parses a message in S/MIME format. | ||
16 | |||
17 | B<in> is a BIO to read the message from. | ||
18 | |||
19 | If cleartext signing is used then the content is saved in a memory bio which is | ||
20 | written to B<*bcont>, otherwise B<*bcont> is set to NULL. | ||
21 | |||
22 | The parsed CMS_ContentInfo structure is returned or NULL if an | ||
23 | error occurred. | ||
24 | |||
25 | =head1 NOTES | ||
26 | |||
27 | If B<*bcont> is not NULL then the message is clear text signed. B<*bcont> can | ||
28 | then be passed to CMS_verify() with the B<CMS_DETACHED> flag set. | ||
29 | |||
30 | Otherwise the type of the returned structure can be determined | ||
31 | using CMS_get0_type(). | ||
32 | |||
33 | To support future functionality if B<bcont> is not NULL B<*bcont> should be | ||
34 | initialized to NULL. For example: | ||
35 | |||
36 | BIO *cont = NULL; | ||
37 | CMS_ContentInfo *cms; | ||
38 | |||
39 | cms = SMIME_read_CMS(in, &cont); | ||
40 | |||
41 | =head1 BUGS | ||
42 | |||
43 | The MIME parser used by SMIME_read_CMS() is somewhat primitive. While it will | ||
44 | handle most S/MIME messages more complex compound formats may not work. | ||
45 | |||
46 | The parser assumes that the CMS_ContentInfo structure is always base64 encoded | ||
47 | and will not handle the case where it is in binary format or uses quoted | ||
48 | printable format. | ||
49 | |||
50 | The use of a memory BIO to hold the signed content limits the size of message | ||
51 | which can be processed due to memory restraints: a streaming single pass option | ||
52 | should be available. | ||
53 | |||
54 | =head1 RETURN VALUES | ||
55 | |||
56 | SMIME_read_CMS() returns a valid B<CMS_ContentInfo> structure or B<NULL> | ||
57 | if an error occurred. The error can be obtained from ERR_get_error(3). | ||
58 | |||
59 | =head1 SEE ALSO | ||
60 | |||
61 | L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_type(3)|CMS_type(3)> | ||
62 | L<SMIME_read_CMS(3)|SMIME_read_CMS(3)>, L<CMS_sign(3)|CMS_sign(3)>, | ||
63 | L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> | ||
64 | L<CMS_decrypt(3)|CMS_decrypt(3)> | ||
65 | |||
66 | =head1 HISTORY | ||
67 | |||
68 | SMIME_read_CMS() was added to OpenSSL 0.9.8 | ||
69 | |||
70 | =cut | ||
diff --git a/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod b/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod deleted file mode 100644 index 9d46715941..0000000000 --- a/src/lib/libcrypto/doc/SMIME_read_PKCS7.pod +++ /dev/null | |||
@@ -1,73 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | SMIME_read_PKCS7 - parse S/MIME message. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs7.h> | ||
10 | |||
11 | PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | SMIME_read_PKCS7() parses a message in S/MIME format. | ||
16 | |||
17 | B<in> is a BIO to read the message from. | ||
18 | |||
19 | If cleartext signing is used then the content is saved in | ||
20 | a memory bio which is written to B<*bcont>, otherwise | ||
21 | B<*bcont> is set to B<NULL>. | ||
22 | |||
23 | The parsed PKCS#7 structure is returned or B<NULL> if an | ||
24 | error occurred. | ||
25 | |||
26 | =head1 NOTES | ||
27 | |||
28 | If B<*bcont> is not B<NULL> then the message is clear text | ||
29 | signed. B<*bcont> can then be passed to PKCS7_verify() with | ||
30 | the B<PKCS7_DETACHED> flag set. | ||
31 | |||
32 | Otherwise the type of the returned structure can be determined | ||
33 | using PKCS7_type(). | ||
34 | |||
35 | To support future functionality if B<bcont> is not B<NULL> | ||
36 | B<*bcont> should be initialized to B<NULL>. For example: | ||
37 | |||
38 | BIO *cont = NULL; | ||
39 | PKCS7 *p7; | ||
40 | |||
41 | p7 = SMIME_read_PKCS7(in, &cont); | ||
42 | |||
43 | =head1 BUGS | ||
44 | |||
45 | The MIME parser used by SMIME_read_PKCS7() is somewhat primitive. | ||
46 | While it will handle most S/MIME messages more complex compound | ||
47 | formats may not work. | ||
48 | |||
49 | The parser assumes that the PKCS7 structure is always base64 | ||
50 | encoded and will not handle the case where it is in binary format | ||
51 | or uses quoted printable format. | ||
52 | |||
53 | The use of a memory BIO to hold the signed content limits the size | ||
54 | of message which can be processed due to memory restraints: a | ||
55 | streaming single pass option should be available. | ||
56 | |||
57 | =head1 RETURN VALUES | ||
58 | |||
59 | SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL> | ||
60 | is an error occurred. The error can be obtained from ERR_get_error(3). | ||
61 | |||
62 | =head1 SEE ALSO | ||
63 | |||
64 | L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_type(3)|PKCS7_type(3)> | ||
65 | L<SMIME_read_PKCS7(3)|SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, | ||
66 | L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> | ||
67 | L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> | ||
68 | |||
69 | =head1 HISTORY | ||
70 | |||
71 | SMIME_read_PKCS7() was added to OpenSSL 0.9.5 | ||
72 | |||
73 | =cut | ||
diff --git a/src/lib/libcrypto/doc/SMIME_write_CMS.pod b/src/lib/libcrypto/doc/SMIME_write_CMS.pod deleted file mode 100644 index 04bedfb429..0000000000 --- a/src/lib/libcrypto/doc/SMIME_write_CMS.pod +++ /dev/null | |||
@@ -1,64 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | SMIME_write_CMS - convert CMS structure to S/MIME format. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/cms.h> | ||
10 | |||
11 | int SMIME_write_CMS(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | SMIME_write_CMS() adds the appropriate MIME headers to a CMS | ||
16 | structure to produce an S/MIME message. | ||
17 | |||
18 | B<out> is the BIO to write the data to. B<cms> is the appropriate | ||
19 | B<CMS_ContentInfo> structure. If streaming is enabled then the content must be | ||
20 | supplied in the B<data> argument. B<flags> is an optional set of flags. | ||
21 | |||
22 | =head1 NOTES | ||
23 | |||
24 | The following flags can be passed in the B<flags> parameter. | ||
25 | |||
26 | If B<CMS_DETACHED> is set then cleartext signing will be used, this option only | ||
27 | makes sense for SignedData where B<CMS_DETACHED> is also set when CMS_sign() is | ||
28 | called. | ||
29 | |||
30 | If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are added to | ||
31 | the content, this only makes sense if B<CMS_DETACHED> is also set. | ||
32 | |||
33 | If the B<CMS_STREAM> flag is set streaming is performed. This flag should only | ||
34 | be set if B<CMS_STREAM> was also set in the previous call to a CMS_ContentInfo | ||
35 | creation function. | ||
36 | |||
37 | If cleartext signing is being used and B<CMS_STREAM> not set then the data must | ||
38 | be read twice: once to compute the signature in CMS_sign() and once to output | ||
39 | the S/MIME message. | ||
40 | |||
41 | If streaming is performed the content is output in BER format using indefinite | ||
42 | length constructed encoding except in the case of signed data with detached | ||
43 | content where the content is absent and DER format is used. | ||
44 | |||
45 | =head1 BUGS | ||
46 | |||
47 | SMIME_write_CMS() always base64 encodes CMS structures, there should be an | ||
48 | option to disable this. | ||
49 | |||
50 | =head1 RETURN VALUES | ||
51 | |||
52 | SMIME_write_CMS() returns 1 for success or 0 for failure. | ||
53 | |||
54 | =head1 SEE ALSO | ||
55 | |||
56 | L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, | ||
57 | L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> | ||
58 | L<CMS_decrypt(3)|CMS_decrypt(3)> | ||
59 | |||
60 | =head1 HISTORY | ||
61 | |||
62 | SMIME_write_CMS() was added to OpenSSL 0.9.8 | ||
63 | |||
64 | =cut | ||
diff --git a/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod b/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod deleted file mode 100644 index 4a7cd08c42..0000000000 --- a/src/lib/libcrypto/doc/SMIME_write_PKCS7.pod +++ /dev/null | |||
@@ -1,65 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs7.h> | ||
10 | |||
11 | int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | SMIME_write_PKCS7() adds the appropriate MIME headers to a PKCS#7 | ||
16 | structure to produce an S/MIME message. | ||
17 | |||
18 | B<out> is the BIO to write the data to. B<p7> is the appropriate B<PKCS7> | ||
19 | structure. If streaming is enabled then the content must be supplied in the | ||
20 | B<data> argument. B<flags> is an optional set of flags. | ||
21 | |||
22 | =head1 NOTES | ||
23 | |||
24 | The following flags can be passed in the B<flags> parameter. | ||
25 | |||
26 | If B<PKCS7_DETACHED> is set then cleartext signing will be used, | ||
27 | this option only makes sense for signedData where B<PKCS7_DETACHED> | ||
28 | is also set when PKCS7_sign() is also called. | ||
29 | |||
30 | If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> | ||
31 | are added to the content, this only makes sense if B<PKCS7_DETACHED> | ||
32 | is also set. | ||
33 | |||
34 | If the B<PKCS7_STREAM> flag is set streaming is performed. This flag should | ||
35 | only be set if B<PKCS7_STREAM> was also set in the previous call to | ||
36 | PKCS7_sign() or B<PKCS7_encrypt()>. | ||
37 | |||
38 | If cleartext signing is being used and B<PKCS7_STREAM> not set then | ||
39 | the data must be read twice: once to compute the signature in PKCS7_sign() | ||
40 | and once to output the S/MIME message. | ||
41 | |||
42 | If streaming is performed the content is output in BER format using indefinite | ||
43 | length constructed encoding except in the case of signed data with detached | ||
44 | content where the content is absent and DER format is used. | ||
45 | |||
46 | =head1 BUGS | ||
47 | |||
48 | SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there | ||
49 | should be an option to disable this. | ||
50 | |||
51 | =head1 RETURN VALUES | ||
52 | |||
53 | SMIME_write_PKCS7() returns 1 for success or 0 for failure. | ||
54 | |||
55 | =head1 SEE ALSO | ||
56 | |||
57 | L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, | ||
58 | L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> | ||
59 | L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> | ||
60 | |||
61 | =head1 HISTORY | ||
62 | |||
63 | SMIME_write_PKCS7() was added to OpenSSL 0.9.5 | ||
64 | |||
65 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod b/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod deleted file mode 100644 index 4603202db8..0000000000 --- a/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod +++ /dev/null | |||
@@ -1,70 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data, | ||
6 | X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data, | ||
7 | X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID, | ||
8 | X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/x509.h> | ||
13 | |||
14 | ASN1_OBJECT * X509_NAME_ENTRY_get_object(X509_NAME_ENTRY *ne); | ||
15 | ASN1_STRING * X509_NAME_ENTRY_get_data(X509_NAME_ENTRY *ne); | ||
16 | |||
17 | int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, ASN1_OBJECT *obj); | ||
18 | int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, const unsigned char *bytes, int len); | ||
19 | |||
20 | X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, const char *field, int type, const unsigned char *bytes, int len); | ||
21 | X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type,unsigned char *bytes, int len); | ||
22 | X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len); | ||
23 | |||
24 | =head1 DESCRIPTION | ||
25 | |||
26 | X509_NAME_ENTRY_get_object() retrieves the field name of B<ne> in | ||
27 | and B<ASN1_OBJECT> structure. | ||
28 | |||
29 | X509_NAME_ENTRY_get_data() retrieves the field value of B<ne> in | ||
30 | and B<ASN1_STRING> structure. | ||
31 | |||
32 | X509_NAME_ENTRY_set_object() sets the field name of B<ne> to B<obj>. | ||
33 | |||
34 | X509_NAME_ENTRY_set_data() sets the field value of B<ne> to string type | ||
35 | B<type> and value determined by B<bytes> and B<len>. | ||
36 | |||
37 | X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID() | ||
38 | and X509_NAME_ENTRY_create_by_OBJ() create and return an | ||
39 | B<X509_NAME_ENTRY> structure. | ||
40 | |||
41 | =head1 NOTES | ||
42 | |||
43 | X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be | ||
44 | used to examine an B<X509_NAME_ENTRY> function as returned by | ||
45 | X509_NAME_get_entry() for example. | ||
46 | |||
47 | X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID(), | ||
48 | and X509_NAME_ENTRY_create_by_OBJ() create and return an | ||
49 | |||
50 | X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(), | ||
51 | X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data() | ||
52 | are seldom used in practice because B<X509_NAME_ENTRY> structures | ||
53 | are almost always part of B<X509_NAME> structures and the | ||
54 | corresponding B<X509_NAME> functions are typically used to | ||
55 | create and add new entries in a single operation. | ||
56 | |||
57 | The arguments of these functions support similar options to the similarly | ||
58 | named ones of the corresponding B<X509_NAME> functions such as | ||
59 | X509_NAME_add_entry_by_txt(). So for example B<type> can be set to | ||
60 | B<MBSTRING_ASC> but in the case of X509_set_data() the field name must be | ||
61 | set first so the relevant field information can be looked up internally. | ||
62 | |||
63 | =head1 RETURN VALUES | ||
64 | |||
65 | =head1 SEE ALSO | ||
66 | |||
67 | L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>, | ||
68 | L<OBJ_nid2obj(3)|OBJ_nid2obj(3)> | ||
69 | |||
70 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod b/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod deleted file mode 100644 index f97e05e683..0000000000 --- a/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod +++ /dev/null | |||
@@ -1,117 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, | ||
6 | X509_NAME_add_entry_by_NID, X509_NAME_add_entry, X509_NAME_delete_entry - | ||
7 | X509_NAME modification functions | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/x509.h> | ||
12 | |||
13 | int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set); | ||
14 | |||
15 | int X509_NAME_add_entry_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set); | ||
16 | |||
17 | int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set); | ||
18 | |||
19 | int X509_NAME_add_entry(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set); | ||
20 | |||
21 | X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc); | ||
22 | |||
23 | =head1 DESCRIPTION | ||
24 | |||
25 | X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and | ||
26 | X509_NAME_add_entry_by_NID() add a field whose name is defined | ||
27 | by a string B<field>, an object B<obj> or a NID B<nid> respectively. | ||
28 | The field value to be added is in B<bytes> of length B<len>. If | ||
29 | B<len> is -1 then the field length is calculated internally using | ||
30 | strlen(bytes). | ||
31 | |||
32 | The type of field is determined by B<type> which can either be a | ||
33 | definition of the type of B<bytes> (such as B<MBSTRING_ASC>) or a | ||
34 | standard ASN1 type (such as B<V_ASN1_IA5STRING>). The new entry is | ||
35 | added to a position determined by B<loc> and B<set>. | ||
36 | |||
37 | X509_NAME_add_entry() adds a copy of B<X509_NAME_ENTRY> structure B<ne> | ||
38 | to B<name>. The new entry is added to a position determined by B<loc> | ||
39 | and B<set>. Since a copy of B<ne> is added B<ne> must be freed up after | ||
40 | the call. | ||
41 | |||
42 | X509_NAME_delete_entry() deletes an entry from B<name> at position | ||
43 | B<loc>. The deleted entry is returned and must be freed up. | ||
44 | |||
45 | =head1 NOTES | ||
46 | |||
47 | The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8> | ||
48 | is strongly recommended for the B<type> parameter. This allows the | ||
49 | internal code to correctly determine the type of the field and to | ||
50 | apply length checks according to the relevant standards. This is | ||
51 | done using ASN1_STRING_set_by_NID(). | ||
52 | |||
53 | If instead an ASN1 type is used no checks are performed and the | ||
54 | supplied data in B<bytes> is used directly. | ||
55 | |||
56 | In X509_NAME_add_entry_by_txt() the B<field> string represents | ||
57 | the field name using OBJ_txt2obj(field, 0). | ||
58 | |||
59 | The B<loc> and B<set> parameters determine where a new entry should | ||
60 | be added. For almost all applications B<loc> can be set to -1 and B<set> | ||
61 | to 0. This adds a new entry to the end of B<name> as a single valued | ||
62 | RelativeDistinguishedName (RDN). | ||
63 | |||
64 | B<loc> actually determines the index where the new entry is inserted: | ||
65 | if it is -1 it is appended. | ||
66 | |||
67 | B<set> determines how the new type is added. If it is zero a | ||
68 | new RDN is created. | ||
69 | |||
70 | If B<set> is -1 or 1 it is added to the previous or next RDN | ||
71 | structure respectively. This will then be a multivalued RDN: | ||
72 | since multivalues RDNs are very seldom used B<set> is almost | ||
73 | always set to zero. | ||
74 | |||
75 | =head1 EXAMPLES | ||
76 | |||
77 | Create an B<X509_NAME> structure: | ||
78 | |||
79 | "C=UK, O=Disorganized Organization, CN=Joe Bloggs" | ||
80 | |||
81 | X509_NAME *nm; | ||
82 | nm = X509_NAME_new(); | ||
83 | if (nm == NULL) | ||
84 | /* Some error */ | ||
85 | if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, | ||
86 | "C", "UK", -1, -1, 0)) | ||
87 | /* Error */ | ||
88 | if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, | ||
89 | "O", "Disorganized Organization", -1, -1, 0)) | ||
90 | /* Error */ | ||
91 | if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, | ||
92 | "CN", "Joe Bloggs", -1, -1, 0)) | ||
93 | /* Error */ | ||
94 | |||
95 | =head1 RETURN VALUES | ||
96 | |||
97 | X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(), | ||
98 | X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for | ||
99 | success of 0 if an error occurred. | ||
100 | |||
101 | X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY> | ||
102 | structure of B<NULL> if an error occurred. | ||
103 | |||
104 | =head1 BUGS | ||
105 | |||
106 | B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a | ||
107 | different algorithm to determine field types. Since this form does | ||
108 | not understand multicharacter types, performs no length checks and | ||
109 | can result in invalid field types its use is strongly discouraged. | ||
110 | |||
111 | =head1 SEE ALSO | ||
112 | |||
113 | L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> | ||
114 | |||
115 | =head1 HISTORY | ||
116 | |||
117 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod b/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod deleted file mode 100644 index 48510890e8..0000000000 --- a/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod +++ /dev/null | |||
@@ -1,102 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry, | ||
6 | X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ - | ||
7 | X509_NAME lookup and enumeration functions | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/x509.h> | ||
12 | |||
13 | int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos); | ||
14 | int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos); | ||
15 | |||
16 | int X509_NAME_entry_count(X509_NAME *name); | ||
17 | X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc); | ||
18 | |||
19 | int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len); | ||
20 | int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len); | ||
21 | |||
22 | =head1 DESCRIPTION | ||
23 | |||
24 | These functions allow an B<X509_NAME> structure to be examined. The | ||
25 | B<X509_NAME> structure is the same as the B<Name> type defined in | ||
26 | RFC2459 (and elsewhere) and used for example in certificate subject | ||
27 | and issuer names. | ||
28 | |||
29 | X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve | ||
30 | the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos> | ||
31 | should initially be set to -1. If there are no more entries -1 is returned. | ||
32 | |||
33 | X509_NAME_entry_count() returns the total number of entries in B<name>. | ||
34 | |||
35 | X509_NAME_get_entry() retrieves the B<X509_NAME_ENTRY> from B<name> | ||
36 | corresponding to index B<loc>. Acceptable values for B<loc> run from | ||
37 | 0 to (X509_NAME_entry_count(name) - 1). The value returned is an | ||
38 | internal pointer which must not be freed. | ||
39 | |||
40 | X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve | ||
41 | the "text" from the first entry in B<name> which matches B<nid> or | ||
42 | B<obj>, if no such entry exists -1 is returned. At most B<len> bytes | ||
43 | will be written and the text written to B<buf> will be null | ||
44 | terminated. The length of the output string written is returned | ||
45 | excluding the terminating null. If B<buf> is <NULL> then the amount | ||
46 | of space needed in B<buf> (excluding the final null) is returned. | ||
47 | |||
48 | =head1 NOTES | ||
49 | |||
50 | X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are | ||
51 | legacy functions which have various limitations which make them | ||
52 | of minimal use in practice. They can only find the first matching | ||
53 | entry and will copy the contents of the field verbatim: this can | ||
54 | be highly confusing if the target is a multicharacter string type | ||
55 | like a BMPString or a UTF8String. | ||
56 | |||
57 | For a more general solution X509_NAME_get_index_by_NID() or | ||
58 | X509_NAME_get_index_by_OBJ() should be used followed by | ||
59 | X509_NAME_get_entry() on any matching indices and then the | ||
60 | various B<X509_NAME_ENTRY> utility functions on the result. | ||
61 | |||
62 | =head1 EXAMPLES | ||
63 | |||
64 | Process all entries: | ||
65 | |||
66 | int i; | ||
67 | X509_NAME_ENTRY *e; | ||
68 | |||
69 | for (i = 0; i < X509_NAME_entry_count(nm); i++) { | ||
70 | e = X509_NAME_get_entry(nm, i); | ||
71 | /* Do something with e */ | ||
72 | } | ||
73 | |||
74 | Process all commonName entries: | ||
75 | |||
76 | int loc; | ||
77 | X509_NAME_ENTRY *e; | ||
78 | |||
79 | loc = -1; | ||
80 | for (;;) { | ||
81 | lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); | ||
82 | if (lastpos == -1) | ||
83 | break; | ||
84 | e = X509_NAME_get_entry(nm, lastpos); | ||
85 | /* Do something with e */ | ||
86 | } | ||
87 | |||
88 | =head1 RETURN VALUES | ||
89 | |||
90 | X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() | ||
91 | return the index of the next matching entry or -1 if not found. | ||
92 | |||
93 | X509_NAME_entry_count() returns the total number of entries. | ||
94 | |||
95 | X509_NAME_get_entry() returns an B<X509_NAME> pointer to the | ||
96 | requested entry or B<NULL> if the index is invalid. | ||
97 | |||
98 | =head1 SEE ALSO | ||
99 | |||
100 | L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> | ||
101 | |||
102 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_NAME_print_ex.pod b/src/lib/libcrypto/doc/X509_NAME_print_ex.pod deleted file mode 100644 index 5cdf636c16..0000000000 --- a/src/lib/libcrypto/doc/X509_NAME_print_ex.pod +++ /dev/null | |||
@@ -1,103 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print, | ||
6 | X509_NAME_oneline - X509_NAME printing routines. | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/x509.h> | ||
11 | |||
12 | int X509_NAME_print_ex(BIO *out, X509_NAME *nm, int indent, unsigned long flags); | ||
13 | int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags); | ||
14 | char * X509_NAME_oneline(X509_NAME *a,char *buf,int size); | ||
15 | int X509_NAME_print(BIO *bp, X509_NAME *name, int obase); | ||
16 | |||
17 | =head1 DESCRIPTION | ||
18 | |||
19 | X509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>. | ||
20 | Each line (for multiline formats) is indented by B<indent> spaces. The output | ||
21 | format can be extensively customised by use of the B<flags> parameter. | ||
22 | |||
23 | X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output | ||
24 | is written to FILE pointer B<fp>. | ||
25 | |||
26 | X509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. At most B<size> | ||
27 | bytes will be written. If B<buf> is B<NULL> then a buffer is dynamically | ||
28 | allocated and returned, otherwise B<buf> is returned. | ||
29 | |||
30 | X509_NAME_print() prints out B<name> to B<bp> indenting each line by B<obase> | ||
31 | characters. Multiple lines are used if the output (including indent) exceeds | ||
32 | 80 characters. | ||
33 | |||
34 | =head1 NOTES | ||
35 | |||
36 | The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions | ||
37 | which produce a non standard output form, they don't handle multi character | ||
38 | fields and have various quirks and inconsistencies. Their use is strongly | ||
39 | discouraged in new applications. | ||
40 | |||
41 | Although there are a large number of possible flags for most purposes | ||
42 | B<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice. | ||
43 | As noted on the L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)> manual page | ||
44 | for UTF8 terminals the B<ASN1_STRFLGS_ESC_MSB> should be unset: so for example | ||
45 | B<XN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB> would be used. | ||
46 | |||
47 | The complete set of the flags supported by X509_NAME_print_ex() is listed below. | ||
48 | |||
49 | Several options can be ored together. | ||
50 | |||
51 | The options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>, | ||
52 | B<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field | ||
53 | separators to use. Two distinct separators are used between distinct | ||
54 | RelativeDistinguishedName components and separate values in the same RDN for a | ||
55 | multi-valued RDN. Multi-valued RDNs are currently very rare so the second | ||
56 | separator will hardly ever be used. | ||
57 | |||
58 | B<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators. | ||
59 | B<XN_FLAG_SEP_CPLUS_SPC> uses comma and plus with spaces: this is more readable | ||
60 | that plain comma and plus. B<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and | ||
61 | plus. B<XN_FLAG_SEP_MULTILINE> uses spaced newline and plus respectively. | ||
62 | |||
63 | If B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order. | ||
64 | |||
65 | The fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>, | ||
66 | B<XN_FLAG_FN_NONE> determine how a field name is displayed. It will | ||
67 | use the short name (e.g. CN) the long name (e.g. commonName) always | ||
68 | use OID numerical form (normally OIDs are only used if the field name is not | ||
69 | recognised) and no field name respectively. | ||
70 | |||
71 | If B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character | ||
72 | separating field names and values. | ||
73 | |||
74 | If B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is | ||
75 | printed instead of the values. | ||
76 | |||
77 | If B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this | ||
78 | is only of use for multiline format. | ||
79 | |||
80 | Additionally all the options supported by ASN1_STRING_print_ex() can be used to | ||
81 | control how each field value is displayed. | ||
82 | |||
83 | In addition a number options can be set for commonly used formats. | ||
84 | |||
85 | B<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it | ||
86 | is equivalent to: | ||
87 | B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS> | ||
88 | |||
89 | |||
90 | B<XN_FLAG_ONELINE> is a more readable one line format which is the same as: | ||
91 | B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN> | ||
92 | |||
93 | B<XN_FLAG_MULTILINE> is a multiline format which is the same as: | ||
94 | B<ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN> | ||
95 | |||
96 | B<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it | ||
97 | calls X509_NAME_print() internally. | ||
98 | |||
99 | =head1 SEE ALSO | ||
100 | |||
101 | L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)> | ||
102 | |||
103 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod deleted file mode 100644 index 270b265ce5..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod +++ /dev/null | |||
@@ -1,323 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, | ||
6 | X509_STORE_CTX_get_error_depth, X509_STORE_CTX_get_current_cert, | ||
7 | X509_STORE_CTX_get1_chain, X509_verify_cert_error_string - get or set | ||
8 | certificate verification status information | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/x509.h> | ||
13 | #include <openssl/x509_vfy.h> | ||
14 | |||
15 | int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); | ||
16 | void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx,int s); | ||
17 | int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx); | ||
18 | X509 * X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx); | ||
19 | |||
20 | STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx); | ||
21 | |||
22 | const char *X509_verify_cert_error_string(long n); | ||
23 | |||
24 | =head1 DESCRIPTION | ||
25 | |||
26 | These functions are typically called after X509_verify_cert() has indicated | ||
27 | an error or in a verification callback to determine the nature of an error. | ||
28 | |||
29 | X509_STORE_CTX_get_error() returns the error code of B<ctx>, see | ||
30 | the B<ERROR CODES> section for a full description of all error codes. | ||
31 | |||
32 | X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example | ||
33 | it might be used in a verification callback to set an error based on additional | ||
34 | checks. | ||
35 | |||
36 | X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a | ||
37 | non-negative integer representing where in the certificate chain the error | ||
38 | occurred. If it is zero it occurred in the end entity certificate, one if | ||
39 | it is the certificate which signed the end entity certificate and so on. | ||
40 | |||
41 | X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which | ||
42 | caused the error or B<NULL> if no certificate is relevant. | ||
43 | |||
44 | X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous | ||
45 | call to X509_verify_cert() is successful. If the call to X509_verify_cert() | ||
46 | is B<not> successful the returned chain may be incomplete or invalid. The | ||
47 | returned chain persists after the B<ctx> structure is freed, when it is | ||
48 | no longer needed it should be free up using: | ||
49 | |||
50 | sk_X509_pop_free(chain, X509_free); | ||
51 | |||
52 | X509_verify_cert_error_string() returns a human readable error string for | ||
53 | verification error B<n>. | ||
54 | |||
55 | =head1 RETURN VALUES | ||
56 | |||
57 | X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code. | ||
58 | |||
59 | X509_STORE_CTX_get_error_depth() returns a non-negative error depth. | ||
60 | |||
61 | X509_STORE_CTX_get_current_cert() returns the certificate which caused the | ||
62 | error or B<NULL> if no certificate is relevant to the error. | ||
63 | |||
64 | X509_verify_cert_error_string() returns a human readable error string for | ||
65 | verification error B<n>. | ||
66 | |||
67 | =head1 ERROR CODES | ||
68 | |||
69 | A list of error codes and messages is shown below. Some of the | ||
70 | error codes are defined but currently never returned: these are described as | ||
71 | "unused". | ||
72 | |||
73 | =over 4 | ||
74 | |||
75 | =item B<X509_V_OK: ok> | ||
76 | |||
77 | the operation was successful. | ||
78 | |||
79 | =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> | ||
80 | |||
81 | the issuer certificate could not be found: this occurs if the issuer certificate | ||
82 | of an untrusted certificate cannot be found. | ||
83 | |||
84 | =item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> | ||
85 | |||
86 | the CRL of a certificate could not be found. | ||
87 | |||
88 | =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt | ||
89 | certificate's signature> | ||
90 | |||
91 | the certificate signature could not be decrypted. This means that the actual | ||
92 | signature value could not be determined rather than it not matching the | ||
93 | expected value, this is only meaningful for RSA keys. | ||
94 | |||
95 | =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's | ||
96 | signature> | ||
97 | |||
98 | the CRL signature could not be decrypted: this means that the actual signature | ||
99 | value could not be determined rather than it not matching the expected value. | ||
100 | Unused. | ||
101 | |||
102 | =item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer | ||
103 | public key> | ||
104 | |||
105 | the public key in the certificate SubjectPublicKeyInfo could not be read. | ||
106 | |||
107 | =item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> | ||
108 | |||
109 | the signature of the certificate is invalid. | ||
110 | |||
111 | =item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> | ||
112 | |||
113 | the signature of the certificate is invalid. | ||
114 | |||
115 | =item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> | ||
116 | |||
117 | the certificate is not yet valid: the notBefore date is after the current time. | ||
118 | |||
119 | =item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> | ||
120 | |||
121 | the certificate has expired: that is the notAfter date is before the current | ||
122 | time. | ||
123 | |||
124 | =item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> | ||
125 | |||
126 | the CRL is not yet valid. | ||
127 | |||
128 | =item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> | ||
129 | |||
130 | the CRL has expired. | ||
131 | |||
132 | =item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in | ||
133 | certificate's notBefore field> | ||
134 | |||
135 | the certificate notBefore field contains an invalid time. | ||
136 | |||
137 | =item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's | ||
138 | notAfter field> | ||
139 | |||
140 | the certificate notAfter field contains an invalid time. | ||
141 | |||
142 | =item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's | ||
143 | lastUpdate field> | ||
144 | |||
145 | the CRL lastUpdate field contains an invalid time. | ||
146 | |||
147 | =item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's | ||
148 | nextUpdate field> | ||
149 | |||
150 | the CRL nextUpdate field contains an invalid time. | ||
151 | |||
152 | =item B<X509_V_ERR_OUT_OF_MEM: out of memory> | ||
153 | |||
154 | an error occurred trying to allocate memory. This should never happen. | ||
155 | |||
156 | =item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> | ||
157 | |||
158 | the passed certificate is self signed and the same certificate cannot be found | ||
159 | in the list of trusted certificates. | ||
160 | |||
161 | =item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in | ||
162 | certificate chain> | ||
163 | |||
164 | the certificate chain could be built up using the untrusted certificates but | ||
165 | the root could not be found locally. | ||
166 | |||
167 | =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local | ||
168 | issuer certificate> | ||
169 | |||
170 | the issuer certificate of a locally looked up certificate could not be found. | ||
171 | This normally means the list of trusted certificates is not complete. | ||
172 | |||
173 | =item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first | ||
174 | certificate> | ||
175 | |||
176 | no signatures could be verified because the chain contains only one certificate | ||
177 | and it is not self signed. | ||
178 | |||
179 | =item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> | ||
180 | |||
181 | the certificate chain length is greater than the supplied maximum depth. Unused. | ||
182 | |||
183 | =item B<X509_V_ERR_CERT_REVOKED: certificate revoked> | ||
184 | |||
185 | the certificate has been revoked. | ||
186 | |||
187 | =item B<X509_V_ERR_INVALID_CA: invalid CA certificate> | ||
188 | |||
189 | a CA certificate is invalid. Either it is not a CA or its extensions are not | ||
190 | consistent with the supplied purpose. | ||
191 | |||
192 | =item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> | ||
193 | |||
194 | the basicConstraints pathlength parameter has been exceeded. | ||
195 | |||
196 | =item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> | ||
197 | |||
198 | the supplied certificate cannot be used for the specified purpose. | ||
199 | |||
200 | =item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> | ||
201 | |||
202 | the root CA is not marked as trusted for the specified purpose. | ||
203 | |||
204 | =item B<X509_V_ERR_CERT_REJECTED: certificate rejected> | ||
205 | |||
206 | the root CA is marked to reject the specified purpose. | ||
207 | |||
208 | =item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> | ||
209 | |||
210 | the current candidate issuer certificate was rejected because its subject name | ||
211 | did not match the issuer name of the current certificate. This is only set | ||
212 | if issuer check debugging is enabled it is used for status notification and | ||
213 | is B<not> in itself an error. | ||
214 | |||
215 | =item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier | ||
216 | mismatch> | ||
217 | |||
218 | the current candidate issuer certificate was rejected because its subject key | ||
219 | identifier was present and did not match the authority key identifier current | ||
220 | certificate. This is only set if issuer check debugging is enabled it is used | ||
221 | for status notification and is B<not> in itself an error. | ||
222 | |||
223 | =item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial | ||
224 | number mismatch> | ||
225 | |||
226 | the current candidate issuer certificate was rejected because its issuer name | ||
227 | and serial number was present and did not match the authority key identifier of | ||
228 | the current certificate. This is only set if issuer check debugging is enabled | ||
229 | it is used for status notification and is B<not> in itself an error. | ||
230 | |||
231 | =item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate | ||
232 | signing> | ||
233 | |||
234 | the current candidate issuer certificate was rejected because its keyUsage | ||
235 | extension does not permit certificate signing. This is only set if issuer check | ||
236 | debugging is enabled it is used for status notification and is B<not> in itself | ||
237 | an error. | ||
238 | |||
239 | =item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate | ||
240 | extension> | ||
241 | |||
242 | A certificate extension had an invalid value (for example an incorrect | ||
243 | encoding) or some value inconsistent with other extensions. | ||
244 | |||
245 | |||
246 | =item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent | ||
247 | certificate policy extension> | ||
248 | |||
249 | A certificate policies extension had an invalid value (for example an incorrect | ||
250 | encoding) or some value inconsistent with other extensions. This error only | ||
251 | occurs if policy processing is enabled. | ||
252 | |||
253 | =item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy> | ||
254 | |||
255 | The verification flags were set to require and explicit policy but none was | ||
256 | present. | ||
257 | |||
258 | =item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope> | ||
259 | |||
260 | The only CRLs that could be found did not match the scope of the certificate. | ||
261 | |||
262 | =item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature> | ||
263 | |||
264 | Some feature of a certificate extension is not supported. Unused. | ||
265 | |||
266 | =item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation> | ||
267 | |||
268 | A name constraint violation occurred in the permitted subtrees. | ||
269 | |||
270 | =item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation> | ||
271 | |||
272 | A name constraint violation occurred in the excluded subtrees. | ||
273 | |||
274 | =item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not | ||
275 | supported> | ||
276 | |||
277 | A certificate name constraints extension included a minimum or maximum field: | ||
278 | this is not supported. | ||
279 | |||
280 | =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint | ||
281 | type> | ||
282 | |||
283 | An unsupported name constraint type was encountered. OpenSSL currently only | ||
284 | supports directory name, DNS name, email and URI types. | ||
285 | |||
286 | =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name | ||
287 | constraint syntax> | ||
288 | |||
289 | The format of the name constraint is not recognised: for example an email | ||
290 | address format of a form not mentioned in RFC3280. This could be caused by | ||
291 | a garbage extension or some new feature not currently supported. | ||
292 | |||
293 | =item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error> | ||
294 | |||
295 | An error occurred when attempting to verify the CRL path. This error can only | ||
296 | happen if extended CRL checking is enabled. | ||
297 | |||
298 | =item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> | ||
299 | |||
300 | an application specific error. This will never be returned unless explicitly | ||
301 | set by an application. | ||
302 | |||
303 | =back | ||
304 | |||
305 | =head1 NOTES | ||
306 | |||
307 | The above functions should be used instead of directly referencing the fields | ||
308 | in the B<X509_VERIFY_CTX> structure. | ||
309 | |||
310 | In versions of OpenSSL before 1.0 the current certificate returned by | ||
311 | X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should | ||
312 | check the return value before printing out any debugging information relating | ||
313 | to the current certificate. | ||
314 | |||
315 | If an unrecognised error code is passed to X509_verify_cert_error_string() the | ||
316 | numerical value of the unknown code is returned in a static buffer. This is not | ||
317 | thread safe but will never happen unless an invalid code is passed. | ||
318 | |||
319 | =head1 SEE ALSO | ||
320 | |||
321 | L<X509_verify_cert(3)|X509_verify_cert(3)> | ||
322 | |||
323 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod deleted file mode 100644 index 25224cef1b..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod +++ /dev/null | |||
@@ -1,43 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, | ||
6 | X509_STORE_CTX_get_ex_data - add application specific data to X509_STORE_CTX | ||
7 | structures | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/x509_vfy.h> | ||
12 | |||
13 | int X509_STORE_CTX_get_ex_new_index(long argl, void *argp, | ||
14 | CRYPTO_EX_new *new_func, | ||
15 | CRYPTO_EX_dup *dup_func, | ||
16 | CRYPTO_EX_free *free_func); | ||
17 | |||
18 | int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg); | ||
19 | |||
20 | void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); | ||
21 | |||
22 | =head1 DESCRIPTION | ||
23 | |||
24 | These functions handle application specific data in X509_STORE_CTX structures. | ||
25 | Their usage is identical to that of RSA_get_ex_new_index(), RSA_set_ex_data() | ||
26 | and RSA_get_ex_data() as described in L<RSA_get_ex_new_index(3)>. | ||
27 | |||
28 | =head1 NOTES | ||
29 | |||
30 | This mechanism is used internally by the B<ssl> library to store the B<SSL> | ||
31 | structure associated with a verification operation in an B<X509_STORE_CTX> | ||
32 | structure. | ||
33 | |||
34 | =head1 SEE ALSO | ||
35 | |||
36 | L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)> | ||
37 | |||
38 | =head1 HISTORY | ||
39 | |||
40 | X509_STORE_CTX_get_ex_new_index(), X509_STORE_CTX_set_ex_data() and | ||
41 | X509_STORE_CTX_get_ex_data() are available since OpenSSL 0.9.5. | ||
42 | |||
43 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_new.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_new.pod deleted file mode 100644 index 66c0da04d2..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_CTX_new.pod +++ /dev/null | |||
@@ -1,126 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, | ||
6 | X509_STORE_CTX_init, X509_STORE_CTX_trusted_stack, X509_STORE_CTX_set_cert, | ||
7 | X509_STORE_CTX_set_chain, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_param, | ||
8 | X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default - X509_STORE_CTX | ||
9 | initialisation | ||
10 | |||
11 | =head1 SYNOPSIS | ||
12 | |||
13 | #include <openssl/x509_vfy.h> | ||
14 | |||
15 | X509_STORE_CTX *X509_STORE_CTX_new(void); | ||
16 | void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); | ||
17 | void X509_STORE_CTX_free(X509_STORE_CTX *ctx); | ||
18 | |||
19 | int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, | ||
20 | X509 *x509, STACK_OF(X509) *chain); | ||
21 | |||
22 | void X509_STORE_CTX_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); | ||
23 | |||
24 | void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx,X509 *x); | ||
25 | void X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx,STACK_OF(X509) *sk); | ||
26 | void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); | ||
27 | |||
28 | X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx); | ||
29 | void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); | ||
30 | int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); | ||
31 | |||
32 | =head1 DESCRIPTION | ||
33 | |||
34 | These functions initialise an B<X509_STORE_CTX> structure for subsequent use | ||
35 | by X509_verify_cert(). | ||
36 | |||
37 | X509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure. | ||
38 | |||
39 | X509_STORE_CTX_cleanup() internally cleans up an B<X509_STORE_CTX> structure. | ||
40 | The context can then be reused with an new call to X509_STORE_CTX_init(). | ||
41 | |||
42 | X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx> | ||
43 | is no longer valid. | ||
44 | |||
45 | X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation. | ||
46 | The trusted certificate store is set to B<store>, the end entity certificate | ||
47 | to be verified is set to B<x509> and a set of additional certificates (which | ||
48 | will be untrusted but may be used to build the chain) in B<chain>. Any or | ||
49 | all of the B<store>, B<x509> and B<chain> parameters can be B<NULL>. | ||
50 | |||
51 | X509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B<ctx> | ||
52 | to B<sk>. This is an alternative way of specifying trusted certificates | ||
53 | instead of using an B<X509_STORE>. | ||
54 | |||
55 | X509_STORE_CTX_set_cert() sets the certificate to be verified in B<ctx> to | ||
56 | B<x>. | ||
57 | |||
58 | X509_STORE_CTX_set_chain() sets the additional certificate chain used by B<ctx> | ||
59 | to B<sk>. | ||
60 | |||
61 | X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate | ||
62 | verification to B<sk>. These CRLs will only be used if CRL verification is | ||
63 | enabled in the associated B<X509_VERIFY_PARAM> structure. This might be | ||
64 | used where additional "useful" CRLs are supplied as part of a protocol, | ||
65 | for example in a PKCS#7 structure. | ||
66 | |||
67 | X509_VERIFY_PARAM *X509_STORE_CTX_get0_param() retrieves an internal pointer | ||
68 | to the verification parameters associated with B<ctx>. | ||
69 | |||
70 | X509_STORE_CTX_set0_param() sets the internal verification parameter pointer | ||
71 | to B<param>. After this call B<param> should not be used. | ||
72 | |||
73 | X509_STORE_CTX_set_default() looks up and sets the default verification | ||
74 | method to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to | ||
75 | find an appropriate set of parameters from B<name>. | ||
76 | |||
77 | =head1 NOTES | ||
78 | |||
79 | The certificates and CRLs in a store are used internally and should B<not> | ||
80 | be freed up until after the associated B<X509_STORE_CTX> is freed. Legacy | ||
81 | applications might implicitly use an B<X509_STORE_CTX> like this: | ||
82 | |||
83 | X509_STORE_CTX ctx; | ||
84 | X509_STORE_CTX_init(&ctx, store, cert, chain); | ||
85 | |||
86 | this is B<not> recommended in new applications they should instead do: | ||
87 | |||
88 | X509_STORE_CTX *ctx; | ||
89 | ctx = X509_STORE_CTX_new(); | ||
90 | if (ctx == NULL) | ||
91 | /* Bad error */ | ||
92 | X509_STORE_CTX_init(ctx, store, cert, chain); | ||
93 | |||
94 | =head1 BUGS | ||
95 | |||
96 | The certificates and CRLs in a context are used internally and should B<not> | ||
97 | be freed up until after the associated B<X509_STORE_CTX> is freed. Copies | ||
98 | should be made or reference counts increased instead. | ||
99 | |||
100 | =head1 RETURN VALUES | ||
101 | |||
102 | X509_STORE_CTX_new() returns an newly allocates context or B<NULL> is an | ||
103 | error occurred. | ||
104 | |||
105 | X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred. | ||
106 | |||
107 | X509_STORE_CTX_get0_param() returns a pointer to an B<X509_VERIFY_PARAM> | ||
108 | structure or B<NULL> if an error occurred. | ||
109 | |||
110 | X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), X509_STORE_CTX_trusted_stack(), | ||
111 | X509_STORE_CTX_set_cert(), X509_STORE_CTX_set_chain(), | ||
112 | X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return | ||
113 | values. | ||
114 | |||
115 | X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred. | ||
116 | |||
117 | =head1 SEE ALSO | ||
118 | |||
119 | L<X509_verify_cert(3)|X509_verify_cert(3)> | ||
120 | L<X509_VERIFY_PARAM_set_flags(3)|X509_VERIFY_PARAM_set_flags(3)> | ||
121 | |||
122 | =head1 HISTORY | ||
123 | |||
124 | X509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0 | ||
125 | |||
126 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod deleted file mode 100644 index 7dfe430c4c..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod +++ /dev/null | |||
@@ -1,165 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_STORE_CTX_set_verify_cb - set verification callback | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/x509_vfy.h> | ||
10 | |||
11 | void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, | ||
12 | int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to | ||
17 | B<verify_cb> overwriting any existing callback. | ||
18 | |||
19 | The verification callback can be used to customise the operation of certificate | ||
20 | verification, either by overriding error conditions or logging errors for | ||
21 | debugging purposes. | ||
22 | |||
23 | However a verification callback is B<not> essential and the default operation | ||
24 | is often sufficient. | ||
25 | |||
26 | The B<ok> parameter to the callback indicates the value the callback should | ||
27 | return to retain the default behaviour. If it is zero then and error condition | ||
28 | is indicated. If it is 1 then no error occurred. If the flag | ||
29 | B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the | ||
30 | policy checking is complete. | ||
31 | |||
32 | The B<ctx> parameter to the callback is the B<X509_STORE_CTX> structure that | ||
33 | is performing the verification operation. A callback can examine this | ||
34 | structure and receive additional information about the error, for example | ||
35 | by calling X509_STORE_CTX_get_current_cert(). Additional application data can | ||
36 | be passed to the callback via the B<ex_data> mechanism. | ||
37 | |||
38 | =head1 WARNING | ||
39 | |||
40 | In general a verification callback should B<NOT> unconditionally return 1 in | ||
41 | all circumstances because this will allow verification to succeed no matter | ||
42 | what the error. This effectively removes all security from the application | ||
43 | because B<any> certificate (including untrusted generated ones) will be | ||
44 | accepted. | ||
45 | |||
46 | =head1 NOTES | ||
47 | |||
48 | The verification callback can be set and inherited from the parent structure | ||
49 | performing the operation. In some cases (such as S/MIME verification) the | ||
50 | B<X509_STORE_CTX> structure is created and destroyed internally and the | ||
51 | only way to set a custom verification callback is by inheriting it from the | ||
52 | associated B<X509_STORE>. | ||
53 | |||
54 | =head1 RETURN VALUES | ||
55 | |||
56 | X509_STORE_CTX_set_verify_cb() does not return a value. | ||
57 | |||
58 | =head1 EXAMPLES | ||
59 | |||
60 | Default callback operation: | ||
61 | |||
62 | int | ||
63 | verify_callback(int ok, X509_STORE_CTX *ctx) | ||
64 | { | ||
65 | return ok; | ||
66 | } | ||
67 | |||
68 | Simple example, suppose a certificate in the chain is expired and we wish | ||
69 | to continue after this error: | ||
70 | |||
71 | int | ||
72 | verify_callback(int ok, X509_STORE_CTX *ctx) | ||
73 | { | ||
74 | /* Tolerate certificate expiration */ | ||
75 | if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) | ||
76 | return 1; | ||
77 | /* Otherwise don't override */ | ||
78 | return ok; | ||
79 | } | ||
80 | |||
81 | More complex example, we don't wish to continue after B<any> certificate has | ||
82 | expired just one specific case: | ||
83 | |||
84 | int | ||
85 | verify_callback(int ok, X509_STORE_CTX *ctx) | ||
86 | { | ||
87 | int err = X509_STORE_CTX_get_error(ctx); | ||
88 | X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); | ||
89 | |||
90 | if (err == X509_V_ERR_CERT_HAS_EXPIRED) { | ||
91 | if (check_is_acceptable_expired_cert(err_cert) | ||
92 | return 1; | ||
93 | } | ||
94 | return ok; | ||
95 | } | ||
96 | |||
97 | Full featured logging callback. In this case the B<bio_err> is assumed to be | ||
98 | a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using | ||
99 | B<ex_data>. | ||
100 | |||
101 | int | ||
102 | verify_callback(int ok, X509_STORE_CTX *ctx) | ||
103 | { | ||
104 | X509 *err_cert; | ||
105 | int err,depth; | ||
106 | |||
107 | err_cert = X509_STORE_CTX_get_current_cert(ctx); | ||
108 | err = X509_STORE_CTX_get_error(ctx); | ||
109 | depth = X509_STORE_CTX_get_error_depth(ctx); | ||
110 | |||
111 | BIO_printf(bio_err,"depth=%d ",depth); | ||
112 | if (err_cert) { | ||
113 | X509_NAME_print_ex(bio_err, | ||
114 | X509_get_subject_name(err_cert), 0, | ||
115 | XN_FLAG_ONELINE); | ||
116 | BIO_puts(bio_err, "\n"); | ||
117 | } else | ||
118 | BIO_puts(bio_err, "<no cert>\n"); | ||
119 | if (!ok) | ||
120 | BIO_printf(bio_err, "verify error:num=%d:%s\n", | ||
121 | err, X509_verify_cert_error_string(err)); | ||
122 | switch (err) { | ||
123 | case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: | ||
124 | BIO_puts(bio_err, "issuer= "); | ||
125 | X509_NAME_print_ex(bio_err, | ||
126 | X509_get_issuer_name(err_cert), 0, | ||
127 | XN_FLAG_ONELINE); | ||
128 | BIO_puts(bio_err, "\n"); | ||
129 | break; | ||
130 | case X509_V_ERR_CERT_NOT_YET_VALID: | ||
131 | case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: | ||
132 | BIO_printf(bio_err, "notBefore="); | ||
133 | ASN1_TIME_print(bio_err, | ||
134 | X509_get_notBefore(err_cert)); | ||
135 | BIO_printf(bio_err, "\n"); | ||
136 | break; | ||
137 | case X509_V_ERR_CERT_HAS_EXPIRED: | ||
138 | case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: | ||
139 | BIO_printf(bio_err, "notAfter="); | ||
140 | ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert)); | ||
141 | BIO_printf(bio_err, "\n"); | ||
142 | break; | ||
143 | case X509_V_ERR_NO_EXPLICIT_POLICY: | ||
144 | policies_print(bio_err, ctx); | ||
145 | break; | ||
146 | } | ||
147 | if (err == X509_V_OK && ok == 2) | ||
148 | /* print out policies */ | ||
149 | |||
150 | BIO_printf(bio_err,"verify return:%d\n",ok); | ||
151 | return(ok); | ||
152 | } | ||
153 | |||
154 | =head1 SEE ALSO | ||
155 | |||
156 | L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)> | ||
157 | L<X509_STORE_set_verify_cb_func(3)|X509_STORE_set_verify_cb_func(3)> | ||
158 | L<X509_STORE_CTX_get_ex_new_index(3)|X509_STORE_CTX_get_ex_new_index(3)> | ||
159 | |||
160 | =head1 HISTORY | ||
161 | |||
162 | X509_STORE_CTX_set_verify_cb() is available in all versions of SSLeay and | ||
163 | OpenSSL. | ||
164 | |||
165 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod b/src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod deleted file mode 100644 index f9602b3e77..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod +++ /dev/null | |||
@@ -1,55 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb - set verification | ||
6 | callback | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/x509_vfy.h> | ||
11 | |||
12 | void X509_STORE_set_verify_cb(X509_STORE *st, | ||
13 | int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); | ||
14 | |||
15 | void X509_STORE_set_verify_cb_func(X509_STORE *st, | ||
16 | int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); | ||
17 | |||
18 | =head1 DESCRIPTION | ||
19 | |||
20 | X509_STORE_set_verify_cb() sets the verification callback of B<ctx> to | ||
21 | B<verify_cb> overwriting any existing callback. | ||
22 | |||
23 | X509_STORE_set_verify_cb_func() also sets the verification callback but it | ||
24 | is implemented as a macro. | ||
25 | |||
26 | =head1 NOTES | ||
27 | |||
28 | The verification callback from an B<X509_STORE> is inherited by | ||
29 | the corresponding B<X509_STORE_CTX> structure when it is initialized. This can | ||
30 | be used to set the verification callback when the B<X509_STORE_CTX> is | ||
31 | otherwise inaccessible (for example during S/MIME verification). | ||
32 | |||
33 | =head1 BUGS | ||
34 | |||
35 | The macro version of this function was the only one available before | ||
36 | OpenSSL 1.0.0. | ||
37 | |||
38 | =head1 RETURN VALUES | ||
39 | |||
40 | X509_STORE_set_verify_cb() and X509_STORE_set_verify_cb_func() do not return | ||
41 | a value. | ||
42 | |||
43 | =head1 SEE ALSO | ||
44 | |||
45 | L<X509_STORE_CTX_set_verify_cb(3)|X509_STORE_CTX_set_verify_cb(3)> | ||
46 | L<CMS_verify(3)|CMS_verify(3)> | ||
47 | |||
48 | =head1 HISTORY | ||
49 | |||
50 | X509_STORE_set_verify_cb_func() is available in all versions of SSLeay and | ||
51 | OpenSSL. | ||
52 | |||
53 | X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0. | ||
54 | |||
55 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod b/src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod deleted file mode 100644 index 6c88aec49e..0000000000 --- a/src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod +++ /dev/null | |||
@@ -1,172 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, | ||
6 | X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, | ||
7 | X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, | ||
8 | X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, | ||
9 | X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies - X509 | ||
10 | verification parameters | ||
11 | |||
12 | =head1 SYNOPSIS | ||
13 | |||
14 | #include <openssl/x509_vfy.h> | ||
15 | |||
16 | int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, unsigned long flags); | ||
17 | int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, | ||
18 | unsigned long flags); | ||
19 | unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); | ||
20 | |||
21 | int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); | ||
22 | int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); | ||
23 | |||
24 | void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); | ||
25 | |||
26 | int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, | ||
27 | ASN1_OBJECT *policy); | ||
28 | int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, | ||
29 | STACK_OF(ASN1_OBJECT) *policies); | ||
30 | |||
31 | void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); | ||
32 | int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); | ||
33 | |||
34 | =head1 DESCRIPTION | ||
35 | |||
36 | These functions manipulate the B<X509_VERIFY_PARAM> structure associated with | ||
37 | a certificate verification operation. | ||
38 | |||
39 | The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring | ||
40 | it with B<flags>. See the B<VERIFICATION FLAGS> section for a complete | ||
41 | description of values the B<flags> parameter can take. | ||
42 | |||
43 | X509_VERIFY_PARAM_get_flags() returns the flags in B<param>. | ||
44 | |||
45 | X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>. | ||
46 | |||
47 | X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param> | ||
48 | to B<purpose>. This determines the acceptable purpose of the certificate | ||
49 | chain, for example SSL client or SSL server. | ||
50 | |||
51 | X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to | ||
52 | B<trust>. | ||
53 | |||
54 | X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to | ||
55 | B<t>. Normally the current time is used. | ||
56 | |||
57 | X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled | ||
58 | by default) and adds B<policy> to the acceptable policy set. | ||
59 | |||
60 | X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled | ||
61 | by default) and sets the acceptable policy set to B<policies>. Any existing | ||
62 | policy set is cleared. The B<policies> parameter can be B<NULL> to clear | ||
63 | an existing policy set. | ||
64 | |||
65 | X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>. | ||
66 | That is the maximum number of untrusted CA certificates that can appear in a | ||
67 | chain. | ||
68 | |||
69 | =head1 RETURN VALUES | ||
70 | |||
71 | X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), | ||
72 | X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), | ||
73 | X509_VERIFY_PARAM_add0_policy() and X509_VERIFY_PARAM_set1_policies() return 1 | ||
74 | for success and 0 for failure. | ||
75 | |||
76 | X509_VERIFY_PARAM_get_flags() returns the current verification flags. | ||
77 | |||
78 | X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return | ||
79 | values. | ||
80 | |||
81 | X509_VERIFY_PARAM_get_depth() returns the current verification depth. | ||
82 | |||
83 | =head1 VERIFICATION FLAGS | ||
84 | |||
85 | The verification flags consists of zero or more of the following flags | ||
86 | ored together. | ||
87 | |||
88 | B<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf | ||
89 | certificate. An error occurs if a suitable CRL cannot be found. | ||
90 | |||
91 | B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate | ||
92 | chain. | ||
93 | |||
94 | B<X509_V_FLAG_IGNORE_CRITICAL> disabled critical extension checking. By default | ||
95 | any unhandled critical extensions in certificates or (if checked) CRLs results | ||
96 | in a fatal error. If this flag is set unhandled critical extensions are | ||
97 | ignored. B<WARNING> setting this option for anything other than debugging | ||
98 | purposes can be a security risk. Finer control over which extensions are | ||
99 | supported can be performed in the verification callback. | ||
100 | |||
101 | THe B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken | ||
102 | certificates and makes the verification strictly apply B<X509> rules. | ||
103 | |||
104 | B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification. | ||
105 | |||
106 | B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default | ||
107 | no policy checking is performed. Additional information is sent to the | ||
108 | verification callback relating to policy checking. | ||
109 | |||
110 | B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and | ||
111 | B<X509_V_FLAG_INHIBIT_MAP> set the B<require explicit policy>, B<inhibit any | ||
112 | policy> and B<inhibit policy mapping> flags respectively as defined in | ||
113 | B<RFC3280>. Policy checking is automatically enabled if any of these flags | ||
114 | are set. | ||
115 | |||
116 | If B<X509_V_FLAG_NOTIFY_POLICY> is set and the policy checking is successful | ||
117 | a special status code is set to the verification callback. This permits it | ||
118 | to examine the valid policy tree and perform additional checks or simply | ||
119 | log it for debugging purposes. | ||
120 | |||
121 | By default some additional features such as indirect CRLs and CRLs signed by | ||
122 | different keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set | ||
123 | they are enabled. | ||
124 | |||
125 | If B<X509_V_FLAG_USE_DELTAS> ise set delta CRLs (if present) are used to | ||
126 | determine certificate status. If not set deltas are ignored. | ||
127 | |||
128 | B<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed | ||
129 | certificate signature. By default this check is disabled because it doesn't | ||
130 | add any additional security but in some cases applications might want to | ||
131 | check the signature anyway. A side effect of not checking the root CA | ||
132 | signature is that disabled or unsupported message digests on the root CA | ||
133 | are not treated as fatal errors. | ||
134 | |||
135 | The B<X509_V_FLAG_CB_ISSUER_CHECK> flag enables debugging of certificate | ||
136 | issuer checks. It is B<not> needed unless you are logging certificate | ||
137 | verification. If this flag is set then additional status codes will be sent | ||
138 | to the verification callback and it B<must> be prepared to handle such cases | ||
139 | without assuming they are hard errors. | ||
140 | |||
141 | =head1 NOTES | ||
142 | |||
143 | The above functions should be used to manipulate verification parameters | ||
144 | instead of legacy functions which work in specific structures such as | ||
145 | X509_STORE_CTX_set_flags(). | ||
146 | |||
147 | =head1 BUGS | ||
148 | |||
149 | Delta CRL checking is currently primitive. Only a single delta can be used and | ||
150 | (partly due to limitations of B<X509_STORE>) constructed CRLs are not | ||
151 | maintained. | ||
152 | |||
153 | If CRLs checking is enable CRLs are expected to be available in the | ||
154 | corresponding B<X509_STORE> structure. No attempt is made to download | ||
155 | CRLs from the CRL distribution points extension. | ||
156 | |||
157 | =head1 EXAMPLE | ||
158 | |||
159 | Enable CRL checking when performing certificate verification during SSL | ||
160 | connections associated with an B<SSL_CTX> structure B<ctx>: | ||
161 | |||
162 | X509_VERIFY_PARAM *param; | ||
163 | param = X509_VERIFY_PARAM_new(); | ||
164 | X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); | ||
165 | SSL_CTX_set1_param(ctx, param); | ||
166 | X509_VERIFY_PARAM_free(param); | ||
167 | |||
168 | =head1 SEE ALSO | ||
169 | |||
170 | L<X509_verify_cert(3)|X509_verify_cert(3)> | ||
171 | |||
172 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_new.pod b/src/lib/libcrypto/doc/X509_new.pod deleted file mode 100644 index a36808b825..0000000000 --- a/src/lib/libcrypto/doc/X509_new.pod +++ /dev/null | |||
@@ -1,38 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_new, X509_free - X509 certificate ASN1 allocation functions | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/x509.h> | ||
10 | |||
11 | X509 *X509_new(void); | ||
12 | void X509_free(X509 *a); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | The X509 ASN1 allocation routines, allocate and free an | ||
17 | X509 structure, which represents an X509 certificate. | ||
18 | |||
19 | X509_new() allocates and initializes a X509 structure. | ||
20 | |||
21 | X509_free() frees up the B<X509> structure B<a>. | ||
22 | If B<a> is a B<NULL> pointer, no action occurs. | ||
23 | |||
24 | =head1 RETURN VALUES | ||
25 | |||
26 | If the allocation fails, X509_new() returns B<NULL> and sets an error | ||
27 | code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
28 | Otherwise it returns a pointer to the newly allocated structure. | ||
29 | |||
30 | =head1 SEE ALSO | ||
31 | |||
32 | L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)> | ||
33 | |||
34 | =head1 HISTORY | ||
35 | |||
36 | X509_new() and X509_free() are available in all versions of SSLeay and OpenSSL. | ||
37 | |||
38 | =cut | ||
diff --git a/src/lib/libcrypto/doc/X509_verify_cert.pod b/src/lib/libcrypto/doc/X509_verify_cert.pod deleted file mode 100644 index f05edd8333..0000000000 --- a/src/lib/libcrypto/doc/X509_verify_cert.pod +++ /dev/null | |||
@@ -1,53 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | X509_verify_cert - discover and verify X509 certificate chain | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/x509.h> | ||
10 | |||
11 | int X509_verify_cert(X509_STORE_CTX *ctx); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | The X509_verify_cert() function attempts to discover and validate a | ||
16 | certificate chain based on parameters in B<ctx>. A complete description of | ||
17 | the process is contained in the L<verify(1)|verify(1)> manual page. | ||
18 | |||
19 | =head1 RETURN VALUES | ||
20 | |||
21 | If a complete chain can be built and validated this function returns 1, | ||
22 | otherwise it return zero, in exceptional circumstances it can also | ||
23 | return a negative code. | ||
24 | |||
25 | If the function fails additional error information can be obtained by | ||
26 | examining B<ctx> using, for example X509_STORE_CTX_get_error(). | ||
27 | |||
28 | =head1 NOTES | ||
29 | |||
30 | Applications rarely call this function directly but it is used by | ||
31 | OpenSSL internally for certificate validation, in both the S/MIME and | ||
32 | SSL/TLS code. | ||
33 | |||
34 | The negative return value from X509_verify_cert() can only occur if no | ||
35 | certificate is set in B<ctx> (due to a programming error) or if a retry | ||
36 | operation is requested during internal lookups (which never happens with | ||
37 | standard lookup methods). It is however recommended that application check | ||
38 | for <= 0 return value on error. | ||
39 | |||
40 | =head1 BUGS | ||
41 | |||
42 | This function uses the header B<x509.h> as opposed to most chain verification | ||
43 | functions which use B<x509_vfy.h>. | ||
44 | |||
45 | =head1 SEE ALSO | ||
46 | |||
47 | L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)> | ||
48 | |||
49 | =head1 HISTORY | ||
50 | |||
51 | X509_verify_cert() is available in all versions of SSLeay and OpenSSL. | ||
52 | |||
53 | =cut | ||
diff --git a/src/lib/libcrypto/doc/bn.pod b/src/lib/libcrypto/doc/bn.pod deleted file mode 100644 index b3ad63320a..0000000000 --- a/src/lib/libcrypto/doc/bn.pod +++ /dev/null | |||
@@ -1,181 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | bn - multiprecision integer arithmetics | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/bn.h> | ||
10 | |||
11 | BIGNUM *BN_new(void); | ||
12 | void BN_free(BIGNUM *a); | ||
13 | void BN_init(BIGNUM *); | ||
14 | void BN_clear(BIGNUM *a); | ||
15 | void BN_clear_free(BIGNUM *a); | ||
16 | |||
17 | BN_CTX *BN_CTX_new(void); | ||
18 | void BN_CTX_init(BN_CTX *c); | ||
19 | void BN_CTX_free(BN_CTX *c); | ||
20 | |||
21 | BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); | ||
22 | BIGNUM *BN_dup(const BIGNUM *a); | ||
23 | |||
24 | BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b); | ||
25 | |||
26 | int BN_num_bytes(const BIGNUM *a); | ||
27 | int BN_num_bits(const BIGNUM *a); | ||
28 | int BN_num_bits_word(BN_ULONG w); | ||
29 | |||
30 | void BN_set_negative(BIGNUM *a, int n); | ||
31 | int BN_is_negative(const BIGNUM *a); | ||
32 | |||
33 | int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); | ||
34 | int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); | ||
35 | int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
36 | int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); | ||
37 | int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, | ||
38 | BN_CTX *ctx); | ||
39 | int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); | ||
40 | int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); | ||
41 | int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, | ||
42 | BN_CTX *ctx); | ||
43 | int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, | ||
44 | BN_CTX *ctx); | ||
45 | int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, | ||
46 | BN_CTX *ctx); | ||
47 | int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); | ||
48 | int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); | ||
49 | int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, | ||
50 | const BIGNUM *m, BN_CTX *ctx); | ||
51 | int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
52 | |||
53 | int BN_add_word(BIGNUM *a, BN_ULONG w); | ||
54 | int BN_sub_word(BIGNUM *a, BN_ULONG w); | ||
55 | int BN_mul_word(BIGNUM *a, BN_ULONG w); | ||
56 | BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); | ||
57 | BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); | ||
58 | |||
59 | int BN_cmp(BIGNUM *a, BIGNUM *b); | ||
60 | int BN_ucmp(BIGNUM *a, BIGNUM *b); | ||
61 | int BN_is_zero(BIGNUM *a); | ||
62 | int BN_is_one(BIGNUM *a); | ||
63 | int BN_is_word(BIGNUM *a, BN_ULONG w); | ||
64 | int BN_is_odd(BIGNUM *a); | ||
65 | |||
66 | int BN_zero(BIGNUM *a); | ||
67 | int BN_one(BIGNUM *a); | ||
68 | const BIGNUM *BN_value_one(void); | ||
69 | int BN_set_word(BIGNUM *a, unsigned long w); | ||
70 | unsigned long BN_get_word(BIGNUM *a); | ||
71 | |||
72 | int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); | ||
73 | int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); | ||
74 | int BN_rand_range(BIGNUM *rnd, BIGNUM *range); | ||
75 | int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); | ||
76 | |||
77 | BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, | ||
78 | BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); | ||
79 | int BN_is_prime(const BIGNUM *p, int nchecks, | ||
80 | void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); | ||
81 | |||
82 | int BN_set_bit(BIGNUM *a, int n); | ||
83 | int BN_clear_bit(BIGNUM *a, int n); | ||
84 | int BN_is_bit_set(const BIGNUM *a, int n); | ||
85 | int BN_mask_bits(BIGNUM *a, int n); | ||
86 | int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); | ||
87 | int BN_lshift1(BIGNUM *r, BIGNUM *a); | ||
88 | int BN_rshift(BIGNUM *r, BIGNUM *a, int n); | ||
89 | int BN_rshift1(BIGNUM *r, BIGNUM *a); | ||
90 | |||
91 | int BN_bn2bin(const BIGNUM *a, unsigned char *to); | ||
92 | BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); | ||
93 | char *BN_bn2hex(const BIGNUM *a); | ||
94 | char *BN_bn2dec(const BIGNUM *a); | ||
95 | int BN_hex2bn(BIGNUM **a, const char *str); | ||
96 | int BN_dec2bn(BIGNUM **a, const char *str); | ||
97 | int BN_print(BIO *fp, const BIGNUM *a); | ||
98 | int BN_print_fp(FILE *fp, const BIGNUM *a); | ||
99 | int BN_bn2mpi(const BIGNUM *a, unsigned char *to); | ||
100 | BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); | ||
101 | |||
102 | BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, | ||
103 | BN_CTX *ctx); | ||
104 | |||
105 | BN_RECP_CTX *BN_RECP_CTX_new(void); | ||
106 | void BN_RECP_CTX_init(BN_RECP_CTX *recp); | ||
107 | void BN_RECP_CTX_free(BN_RECP_CTX *recp); | ||
108 | int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); | ||
109 | int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, | ||
110 | BN_RECP_CTX *recp, BN_CTX *ctx); | ||
111 | |||
112 | BN_MONT_CTX *BN_MONT_CTX_new(void); | ||
113 | void BN_MONT_CTX_init(BN_MONT_CTX *ctx); | ||
114 | void BN_MONT_CTX_free(BN_MONT_CTX *mont); | ||
115 | int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); | ||
116 | BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); | ||
117 | int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, | ||
118 | BN_MONT_CTX *mont, BN_CTX *ctx); | ||
119 | int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, | ||
120 | BN_CTX *ctx); | ||
121 | int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, | ||
122 | BN_CTX *ctx); | ||
123 | |||
124 | BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, | ||
125 | BIGNUM *mod); | ||
126 | void BN_BLINDING_free(BN_BLINDING *b); | ||
127 | int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx); | ||
128 | int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); | ||
129 | int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); | ||
130 | int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, | ||
131 | BN_CTX *ctx); | ||
132 | int BN_BLINDING_invert_ex(BIGNUM *n,const BIGNUM *r,BN_BLINDING *b, | ||
133 | BN_CTX *ctx); | ||
134 | unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); | ||
135 | void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); | ||
136 | unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); | ||
137 | void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); | ||
138 | BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, | ||
139 | const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, | ||
140 | int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, | ||
141 | const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), | ||
142 | BN_MONT_CTX *m_ctx); | ||
143 | |||
144 | =head1 DESCRIPTION | ||
145 | |||
146 | This library performs arithmetic operations on integers of arbitrary | ||
147 | size. It was written for use in public key cryptography, such as RSA | ||
148 | and Diffie-Hellman. | ||
149 | |||
150 | It uses dynamic memory allocation for storing its data structures. | ||
151 | That means that there is no limit on the size of the numbers | ||
152 | manipulated by these functions, but return values must always be | ||
153 | checked in case a memory allocation error has occurred. | ||
154 | |||
155 | The basic object in this library is a B<BIGNUM>. It is used to hold a | ||
156 | single large integer. This type should be considered opaque and fields | ||
157 | should not be modified or accessed directly. | ||
158 | |||
159 | The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>; | ||
160 | L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations. | ||
161 | Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)> | ||
162 | describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of | ||
163 | random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime | ||
164 | numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion | ||
165 | of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>. | ||
166 | |||
167 | =head1 SEE ALSO | ||
168 | |||
169 | L<bn_dump(3)|bn_dump(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, | ||
170 | L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<BN_new(3)|BN_new(3)>, | ||
171 | L<BN_CTX_new(3)|BN_CTX_new(3)>, L<BN_copy(3)|BN_copy(3)>, | ||
172 | L<BN_swap(3)|BN_swap(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, | ||
173 | L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>, | ||
174 | L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>, | ||
175 | L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>, | ||
176 | L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>, | ||
177 | L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>, | ||
178 | L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>, | ||
179 | L<BN_BLINDING_new(3)|BN_BLINDING_new(3)> | ||
180 | |||
181 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_ASN1_OBJECT.pod b/src/lib/libcrypto/doc/d2i_ASN1_OBJECT.pod deleted file mode 100644 index b2712dc55c..0000000000 --- a/src/lib/libcrypto/doc/d2i_ASN1_OBJECT.pod +++ /dev/null | |||
@@ -1,25 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/objects.h> | ||
10 | |||
11 | ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length); | ||
12 | int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | These functions decode and encode an ASN1 OBJECT IDENTIFIER. | ||
17 | |||
18 | Othewise these behave in a similar way to d2i_X509() and i2d_X509() | ||
19 | described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
20 | |||
21 | =head1 SEE ALSO | ||
22 | |||
23 | L<d2i_X509(3)|d2i_X509(3)> | ||
24 | |||
25 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_DHparams.pod b/src/lib/libcrypto/doc/d2i_DHparams.pod deleted file mode 100644 index 9f1aac9137..0000000000 --- a/src/lib/libcrypto/doc/d2i_DHparams.pod +++ /dev/null | |||
@@ -1,26 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | |||
11 | DH *d2i_DHparams(DH **a, unsigned char **pp, long length); | ||
12 | int i2d_DHparams(DH *a, unsigned char **pp); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | These functions decode and encode PKCS#3 DH parameters using the | ||
17 | DHparameter structure described in PKCS#3. | ||
18 | |||
19 | Othewise these behave in a similar way to d2i_X509() and i2d_X509() | ||
20 | described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
21 | |||
22 | =head1 SEE ALSO | ||
23 | |||
24 | L<d2i_X509(3)|d2i_X509(3)> | ||
25 | |||
26 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_DSAPublicKey.pod b/src/lib/libcrypto/doc/d2i_DSAPublicKey.pod deleted file mode 100644 index 10c49e3ad2..0000000000 --- a/src/lib/libcrypto/doc/d2i_DSAPublicKey.pod +++ /dev/null | |||
@@ -1,79 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey, | ||
6 | d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSAparams, i2d_DSAparams, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding | ||
7 | and parsing functions. | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/dsa.h> | ||
12 | #include <openssl/x509.h> | ||
13 | |||
14 | DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length); | ||
15 | |||
16 | int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); | ||
17 | |||
18 | DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length); | ||
19 | |||
20 | int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp); | ||
21 | |||
22 | DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length); | ||
23 | |||
24 | int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); | ||
25 | |||
26 | DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length); | ||
27 | |||
28 | int i2d_DSAparams(const DSA *a, unsigned char **pp); | ||
29 | |||
30 | DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length); | ||
31 | |||
32 | int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); | ||
33 | |||
34 | =head1 DESCRIPTION | ||
35 | |||
36 | d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key | ||
37 | components structure. | ||
38 | |||
39 | d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() decode and encode an DSA public key using | ||
40 | a SubjectPublicKeyInfo (certificate public key) structure. | ||
41 | |||
42 | d2i_DSAPrivateKey(), i2d_DSAPrivateKey() decode and encode the DSA private key | ||
43 | components. | ||
44 | |||
45 | d2i_DSAparams(), i2d_DSAparams() decode and encode the DSA parameters using | ||
46 | a B<Dss-Parms> structure as defined in RFC2459. | ||
47 | |||
48 | d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a | ||
49 | B<Dss-Sig-Value> structure as defined in RFC2459. | ||
50 | |||
51 | The usage of all of these functions is similar to the d2i_X509() and | ||
52 | i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
53 | |||
54 | =head1 NOTES | ||
55 | |||
56 | The B<DSA> structure passed to the private key encoding functions should have | ||
57 | all the private key components present. | ||
58 | |||
59 | The data encoded by the private key functions is unencrypted and therefore | ||
60 | offers no private key security. | ||
61 | |||
62 | The B<DSA_PUBKEY> functions should be used in preference to the B<DSAPublicKey> | ||
63 | functions when encoding public keys because they use a standard format. | ||
64 | |||
65 | The B<DSAPublicKey> functions use an non standard format the actual data encoded | ||
66 | depends on the value of the B<write_params> field of the B<a> key parameter. | ||
67 | If B<write_params> is zero then only the B<pub_key> field is encoded as an | ||
68 | B<INTEGER>. If B<write_params> is 1 then a B<SEQUENCE> consisting of the | ||
69 | B<p>, B<q>, B<g> and B<pub_key> respectively fields are encoded. | ||
70 | |||
71 | The B<DSAPrivateKey> functions also use a non standard structure consisting | ||
72 | consisting of a SEQUENCE containing the B<p>, B<q>, B<g> and B<pub_key> and | ||
73 | B<priv_key> fields respectively. | ||
74 | |||
75 | =head1 SEE ALSO | ||
76 | |||
77 | L<d2i_X509(3)|d2i_X509(3)> | ||
78 | |||
79 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_ECPKParameters.pod b/src/lib/libcrypto/doc/d2i_ECPKParameters.pod deleted file mode 100644 index 704b4ab352..0000000000 --- a/src/lib/libcrypto/doc/d2i_ECPKParameters.pod +++ /dev/null | |||
@@ -1,84 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_ECPKParameters, i2d_ECPKParameters, d2i_ECPKParameters_bio, i2d_ECPKParameters_bio, d2i_ECPKParameters_fp, i2d_ECPKParameters_fp, ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | |||
11 | EC_GROUP *d2i_ECPKParameters(EC_GROUP **px, const unsigned char **in, long len); | ||
12 | int i2d_ECPKParameters(const EC_GROUP *x, unsigned char **out); | ||
13 | #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) | ||
14 | #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) | ||
15 | #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ | ||
16 | (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) | ||
17 | #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ | ||
18 | (unsigned char *)(x)) | ||
19 | int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); | ||
20 | int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); | ||
21 | |||
22 | |||
23 | =head1 DESCRIPTION | ||
24 | |||
25 | The ECPKParameters encode and decode routines encode and parse the public parameters for an | ||
26 | B<EC_GROUP> structure, which represents a curve. | ||
27 | |||
28 | d2i_ECPKParameters() attempts to decode B<len> bytes at B<*in>. If | ||
29 | successful a pointer to the B<EC_GROUP> structure is returned. If an error | ||
30 | occurred then B<NULL> is returned. If B<px> is not B<NULL> then the | ||
31 | returned structure is written to B<*px>. If B<*px> is not B<NULL> | ||
32 | then it is assumed that B<*px> contains a valid B<EC_GROUP> | ||
33 | structure and an attempt is made to reuse it. If the call is | ||
34 | successful B<*in> is incremented to the byte following the | ||
35 | parsed data. | ||
36 | |||
37 | i2d_ECPKParameters() encodes the structure pointed to by B<x> into DER format. | ||
38 | If B<out> is not B<NULL> is writes the DER encoded data to the buffer | ||
39 | at B<*out>, and increments it to point after the data just written. | ||
40 | If the return value is negative an error occurred, otherwise it | ||
41 | returns the length of the encoded data. | ||
42 | |||
43 | If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded | ||
44 | data written to it. In this case B<*out> is not incremented and it points to | ||
45 | the start of the data just written. | ||
46 | |||
47 | d2i_ECPKParameters_bio() is similar to d2i_ECPKParameters() except it attempts | ||
48 | to parse data from BIO B<bp>. | ||
49 | |||
50 | d2i_ECPKParameters_fp() is similar to d2i_ECPKParameters() except it attempts | ||
51 | to parse data from FILE pointer B<fp>. | ||
52 | |||
53 | i2d_ECPKParameters_bio() is similar to i2d_ECPKParameters() except it writes | ||
54 | the encoding of the structure B<x> to BIO B<bp> and it | ||
55 | returns 1 for success and 0 for failure. | ||
56 | |||
57 | i2d_ECPKParameters_fp() is similar to i2d_ECPKParameters() except it writes | ||
58 | the encoding of the structure B<x> to BIO B<bp> and it | ||
59 | returns 1 for success and 0 for failure. | ||
60 | |||
61 | These functions are very similar to the X509 functions described in L<d2i_X509(3)|d2i_X509(3)>, | ||
62 | where further notes and examples are available. | ||
63 | |||
64 | The ECPKParameters_print and ECPKParameters_print_fp functions print a human-readable output | ||
65 | of the public parameters of the EC_GROUP to B<bp> or B<fp>. The output lines are indented by B<off> spaces. | ||
66 | |||
67 | =head1 RETURN VALUES | ||
68 | |||
69 | d2i_ECPKParameters(), d2i_ECPKParameters_bio() and d2i_ECPKParameters_fp() return a valid B<EC_GROUP> structure | ||
70 | or B<NULL> if an error occurs. | ||
71 | |||
72 | i2d_ECPKParameters() returns the number of bytes successfully encoded or a negative | ||
73 | value if an error occurs. | ||
74 | |||
75 | i2d_ECPKParameters_bio(), i2d_ECPKParameters_fp(), ECPKParameters_print and ECPKParameters_print_fp | ||
76 | return 1 for success and 0 if an error occurs. | ||
77 | |||
78 | =head1 SEE ALSO | ||
79 | |||
80 | L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, | ||
81 | L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, | ||
82 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_X509(3)|d2i_X509(3)> | ||
83 | |||
84 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod b/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod deleted file mode 100644 index 11515d0ace..0000000000 --- a/src/lib/libcrypto/doc/d2i_RSAPublicKey.pod +++ /dev/null | |||
@@ -1,63 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, | ||
6 | d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA, | ||
7 | d2i_Netscape_RSA - RSA public and private key encoding functions. | ||
8 | |||
9 | =head1 SYNOPSIS | ||
10 | |||
11 | #include <openssl/rsa.h> | ||
12 | #include <openssl/x509.h> | ||
13 | |||
14 | RSA * d2i_RSAPublicKey(RSA **a, const unsigned char **pp, long length); | ||
15 | |||
16 | int i2d_RSAPublicKey(RSA *a, unsigned char **pp); | ||
17 | |||
18 | RSA * d2i_RSA_PUBKEY(RSA **a, const unsigned char **pp, long length); | ||
19 | |||
20 | int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp); | ||
21 | |||
22 | RSA * d2i_RSAPrivateKey(RSA **a, const unsigned char **pp, long length); | ||
23 | |||
24 | int i2d_RSAPrivateKey(RSA *a, unsigned char **pp); | ||
25 | |||
26 | int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); | ||
27 | |||
28 | RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)()); | ||
29 | |||
30 | =head1 DESCRIPTION | ||
31 | |||
32 | d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1 | ||
33 | RSAPublicKey structure. | ||
34 | |||
35 | d2i_RSA_PUBKEY() and i2d_RSA_PUBKEY() decode and encode an RSA public key using | ||
36 | a SubjectPublicKeyInfo (certificate public key) structure. | ||
37 | |||
38 | d2i_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1 | ||
39 | RSAPrivateKey structure. | ||
40 | |||
41 | d2i_Netscape_RSA(), i2d_Netscape_RSA() decode and encode an RSA private key in | ||
42 | NET format. | ||
43 | |||
44 | The usage of all of these functions is similar to the d2i_X509() and | ||
45 | i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
46 | |||
47 | =head1 NOTES | ||
48 | |||
49 | The B<RSA> structure passed to the private key encoding functions should have | ||
50 | all the PKCS#1 private key components present. | ||
51 | |||
52 | The data encoded by the private key functions is unencrypted and therefore | ||
53 | offers no private key security. | ||
54 | |||
55 | The NET format functions are present to provide compatibility with certain very | ||
56 | old software. This format has some severe security weaknesses and should be | ||
57 | avoided if possible. | ||
58 | |||
59 | =head1 SEE ALSO | ||
60 | |||
61 | L<d2i_X509(3)|d2i_X509(3)> | ||
62 | |||
63 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_X509.pod b/src/lib/libcrypto/doc/d2i_X509.pod deleted file mode 100644 index fad4e8c35b..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509.pod +++ /dev/null | |||
@@ -1,231 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, | ||
6 | i2d_X509_fp - X509 encode and decode functions | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/x509.h> | ||
11 | |||
12 | X509 *d2i_X509(X509 **px, const unsigned char **in, int len); | ||
13 | int i2d_X509(X509 *x, unsigned char **out); | ||
14 | |||
15 | X509 *d2i_X509_bio(BIO *bp, X509 **x); | ||
16 | X509 *d2i_X509_fp(FILE *fp, X509 **x); | ||
17 | |||
18 | int i2d_X509_bio(BIO *bp, X509 *x); | ||
19 | int i2d_X509_fp(FILE *fp, X509 *x); | ||
20 | |||
21 | =head1 DESCRIPTION | ||
22 | |||
23 | The X509 encode and decode routines encode and parse an | ||
24 | B<X509> structure, which represents an X509 certificate. | ||
25 | |||
26 | d2i_X509() attempts to decode B<len> bytes at B<*in>. If | ||
27 | successful a pointer to the B<X509> structure is returned. If an error | ||
28 | occurred then B<NULL> is returned. If B<px> is not B<NULL> then the | ||
29 | returned structure is written to B<*px>. If B<*px> is not B<NULL> | ||
30 | then it is assumed that B<*px> contains a valid B<X509> | ||
31 | structure and an attempt is made to reuse it. If the call is | ||
32 | successful B<*in> is incremented to the byte following the | ||
33 | parsed data. | ||
34 | |||
35 | i2d_X509() encodes the structure pointed to by B<x> into DER format. | ||
36 | If B<out> is not B<NULL> is writes the DER encoded data to the buffer | ||
37 | at B<*out>, and increments it to point after the data just written. | ||
38 | If the return value is negative an error occurred, otherwise it | ||
39 | returns the length of the encoded data. | ||
40 | |||
41 | For OpenSSL 0.9.7 and later if B<*out> is B<NULL> memory will be | ||
42 | allocated for a buffer and the encoded data written to it. In this | ||
43 | case B<*out> is not incremented and it points to the start of the | ||
44 | data just written. | ||
45 | |||
46 | d2i_X509_bio() is similar to d2i_X509() except it attempts | ||
47 | to parse data from BIO B<bp>. | ||
48 | |||
49 | d2i_X509_fp() is similar to d2i_X509() except it attempts | ||
50 | to parse data from FILE pointer B<fp>. | ||
51 | |||
52 | i2d_X509_bio() is similar to i2d_X509() except it writes | ||
53 | the encoding of the structure B<x> to BIO B<bp> and it | ||
54 | returns 1 for success and 0 for failure. | ||
55 | |||
56 | i2d_X509_fp() is similar to i2d_X509() except it writes | ||
57 | the encoding of the structure B<x> to BIO B<bp> and it | ||
58 | returns 1 for success and 0 for failure. | ||
59 | |||
60 | =head1 NOTES | ||
61 | |||
62 | The letters B<i> and B<d> in for example B<i2d_X509> stand for | ||
63 | "internal" (that is an internal C structure) and "DER". So that | ||
64 | B<i2d_X509> converts from internal to DER. | ||
65 | |||
66 | The functions can also understand B<BER> forms. | ||
67 | |||
68 | The actual X509 structure passed to i2d_X509() must be a valid | ||
69 | populated B<X509> structure it can B<not> simply be fed with an | ||
70 | empty structure such as that returned by X509_new(). | ||
71 | |||
72 | The encoded data is in binary form and may contain embedded zeroes. | ||
73 | Therefore any FILE pointers or BIOs should be opened in binary mode. | ||
74 | Functions such as B<strlen()> will B<not> return the correct length | ||
75 | of the encoded structure. | ||
76 | |||
77 | The ways that B<*in> and B<*out> are incremented after the operation | ||
78 | can trap the unwary. See the B<WARNINGS> section for some common | ||
79 | errors. | ||
80 | |||
81 | The reason for the auto increment behaviour is to reflect a typical | ||
82 | usage of ASN1 functions: after one structure is encoded or decoded | ||
83 | another will processed after it. | ||
84 | |||
85 | =head1 EXAMPLES | ||
86 | |||
87 | Allocate and encode the DER encoding of an X509 structure: | ||
88 | |||
89 | int len; | ||
90 | unsigned char *buf, *p; | ||
91 | |||
92 | len = i2d_X509(x, NULL); | ||
93 | |||
94 | buf = malloc(len); | ||
95 | |||
96 | if (buf == NULL) | ||
97 | /* error */ | ||
98 | |||
99 | p = buf; | ||
100 | |||
101 | i2d_X509(x, &p); | ||
102 | |||
103 | If you are using OpenSSL 0.9.7 or later then this can be | ||
104 | simplified to: | ||
105 | |||
106 | |||
107 | int len; | ||
108 | unsigned char *buf; | ||
109 | |||
110 | buf = NULL; | ||
111 | |||
112 | len = i2d_X509(x, &buf); | ||
113 | |||
114 | if (len < 0) | ||
115 | /* error */ | ||
116 | |||
117 | Attempt to decode a buffer: | ||
118 | |||
119 | X509 *x; | ||
120 | |||
121 | unsigned char *buf, *p; | ||
122 | |||
123 | int len; | ||
124 | |||
125 | /* Something to setup buf and len */ | ||
126 | |||
127 | p = buf; | ||
128 | |||
129 | x = d2i_X509(NULL, &p, len); | ||
130 | |||
131 | if (x == NULL) | ||
132 | /* Some error */ | ||
133 | |||
134 | Alternative technique: | ||
135 | |||
136 | X509 *x; | ||
137 | |||
138 | unsigned char *buf, *p; | ||
139 | |||
140 | int len; | ||
141 | |||
142 | /* Something to setup buf and len */ | ||
143 | |||
144 | p = buf; | ||
145 | |||
146 | x = NULL; | ||
147 | |||
148 | if(!d2i_X509(&x, &p, len)) | ||
149 | /* Some error */ | ||
150 | |||
151 | |||
152 | =head1 WARNINGS | ||
153 | |||
154 | The use of temporary variable is mandatory. A common | ||
155 | mistake is to attempt to use a buffer directly as follows: | ||
156 | |||
157 | int len; | ||
158 | unsigned char *buf; | ||
159 | |||
160 | len = i2d_X509(x, NULL); | ||
161 | |||
162 | buf = malloc(len); | ||
163 | |||
164 | if (buf == NULL) | ||
165 | /* error */ | ||
166 | |||
167 | i2d_X509(x, &buf); | ||
168 | |||
169 | /* Other stuff ... */ | ||
170 | |||
171 | free(buf); | ||
172 | |||
173 | This code will result in B<buf> apparently containing garbage because | ||
174 | it was incremented after the call to point after the data just written. | ||
175 | Also B<buf> will no longer contain the pointer allocated by B<malloc()> | ||
176 | and the subsequent call to B<free()> may well crash. | ||
177 | |||
178 | The auto allocation feature (setting buf to NULL) only works on OpenSSL | ||
179 | 0.9.7 and later. Attempts to use it on earlier versions will typically | ||
180 | cause a segmentation violation. | ||
181 | |||
182 | Another trap to avoid is misuse of the B<xp> argument to B<d2i_X509()>: | ||
183 | |||
184 | X509 *x; | ||
185 | |||
186 | if (!d2i_X509(&x, &p, len)) | ||
187 | /* Some error */ | ||
188 | |||
189 | This will probably crash somewhere in B<d2i_X509()>. The reason for this | ||
190 | is that the variable B<x> is uninitialized and an attempt will be made to | ||
191 | interpret its (invalid) value as an B<X509> structure, typically causing | ||
192 | a segmentation violation. If B<x> is set to NULL first then this will not | ||
193 | happen. | ||
194 | |||
195 | =head1 BUGS | ||
196 | |||
197 | In some versions of OpenSSL the "reuse" behaviour of d2i_X509() when | ||
198 | B<*px> is valid is broken and some parts of the reused structure may | ||
199 | persist if they are not present in the new one. As a result the use | ||
200 | of this "reuse" behaviour is strongly discouraged. | ||
201 | |||
202 | i2d_X509() will not return an error in many versions of OpenSSL, | ||
203 | if mandatory fields are not initialized due to a programming error | ||
204 | then the encoded structure may contain invalid data or omit the | ||
205 | fields entirely and will not be parsed by d2i_X509(). This may be | ||
206 | fixed in future so code should not assume that i2d_X509() will | ||
207 | always succeed. | ||
208 | |||
209 | =head1 RETURN VALUES | ||
210 | |||
211 | d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure | ||
212 | or B<NULL> if an error occurs. The error code that can be obtained by | ||
213 | L<ERR_get_error(3)|ERR_get_error(3)>. | ||
214 | |||
215 | i2d_X509() returns the number of bytes successfully encoded or a negative | ||
216 | value if an error occurs. The error code can be obtained by | ||
217 | L<ERR_get_error(3)|ERR_get_error(3)>. | ||
218 | |||
219 | i2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error | ||
220 | occurs The error code can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. | ||
221 | |||
222 | =head1 SEE ALSO | ||
223 | |||
224 | L<ERR_get_error(3)|ERR_get_error(3)> | ||
225 | |||
226 | =head1 HISTORY | ||
227 | |||
228 | d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp | ||
229 | are available in all versions of SSLeay and OpenSSL. | ||
230 | |||
231 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_X509_ALGOR.pod b/src/lib/libcrypto/doc/d2i_X509_ALGOR.pod deleted file mode 100644 index 68011679fd..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_ALGOR.pod +++ /dev/null | |||
@@ -1,26 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_X509_ALGOR, i2d_X509_ALGOR - AlgorithmIdentifier functions. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/x509.h> | ||
10 | |||
11 | X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length); | ||
12 | int i2d_X509_ALGOR(X509_ALGOR *a, unsigned char **pp); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | These functions decode and encode an B<X509_ALGOR> structure which is | ||
17 | equivalent to the B<AlgorithmIdentifier> structure. | ||
18 | |||
19 | Othewise these behave in a similar way to d2i_X509() and i2d_X509() | ||
20 | described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
21 | |||
22 | =head1 SEE ALSO | ||
23 | |||
24 | L<d2i_X509(3)|d2i_X509(3)> | ||
25 | |||
26 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_X509_CRL.pod b/src/lib/libcrypto/doc/d2i_X509_CRL.pod deleted file mode 100644 index 563e4de8e0..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_CRL.pod +++ /dev/null | |||
@@ -1,33 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_X509_CRL_fp, | ||
6 | i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions. | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/x509.h> | ||
11 | |||
12 | X509_CRL *d2i_X509_CRL(X509_CRL **a, const unsigned char **pp, long length); | ||
13 | int i2d_X509_CRL(X509_CRL *a, unsigned char **pp); | ||
14 | |||
15 | X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x); | ||
16 | X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x); | ||
17 | |||
18 | int i2d_X509_CRL_bio(BIO *bp, X509_CRL *x); | ||
19 | int i2d_X509_CRL_fp(FILE *fp, X509_CRL *x); | ||
20 | |||
21 | =head1 DESCRIPTION | ||
22 | |||
23 | These functions decode and encode an X509 CRL (certificate revocation | ||
24 | list). | ||
25 | |||
26 | Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() | ||
27 | described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
28 | |||
29 | =head1 SEE ALSO | ||
30 | |||
31 | L<d2i_X509(3)|d2i_X509(3)> | ||
32 | |||
33 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_X509_NAME.pod b/src/lib/libcrypto/doc/d2i_X509_NAME.pod deleted file mode 100644 index 2219885338..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_NAME.pod +++ /dev/null | |||
@@ -1,27 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/x509.h> | ||
10 | |||
11 | X509_NAME *d2i_X509_NAME(X509_NAME **a, unsigned char **pp, long length); | ||
12 | int i2d_X509_NAME(X509_NAME *a, unsigned char **pp); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | These functions decode and encode an B<X509_NAME> structure which is the | ||
17 | same as the B<Name> type defined in RFC2459 (and elsewhere) and used | ||
18 | for example in certificate subject and issuer names. | ||
19 | |||
20 | Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() | ||
21 | described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
22 | |||
23 | =head1 SEE ALSO | ||
24 | |||
25 | L<d2i_X509(3)|d2i_X509(3)> | ||
26 | |||
27 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_X509_REQ.pod b/src/lib/libcrypto/doc/d2i_X509_REQ.pod deleted file mode 100644 index baa8ae391e..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_REQ.pod +++ /dev/null | |||
@@ -1,32 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_X509_REQ, i2d_X509_REQ, d2i_X509_REQ_bio, d2i_X509_REQ_fp, | ||
6 | i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions. | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/x509.h> | ||
11 | |||
12 | X509_REQ *d2i_X509_REQ(X509_REQ **a, const unsigned char **pp, long length); | ||
13 | int i2d_X509_REQ(X509_REQ *a, unsigned char **pp); | ||
14 | |||
15 | X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x); | ||
16 | X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x); | ||
17 | |||
18 | int i2d_X509_REQ_bio(BIO *bp, X509_REQ *x); | ||
19 | int i2d_X509_REQ_fp(FILE *fp, X509_REQ *x); | ||
20 | |||
21 | =head1 DESCRIPTION | ||
22 | |||
23 | These functions decode and encode a PKCS#10 certificate request. | ||
24 | |||
25 | Othewise these behave in a similar way to d2i_X509() and i2d_X509() | ||
26 | described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
27 | |||
28 | =head1 SEE ALSO | ||
29 | |||
30 | L<d2i_X509(3)|d2i_X509(3)> | ||
31 | |||
32 | =cut | ||
diff --git a/src/lib/libcrypto/doc/d2i_X509_SIG.pod b/src/lib/libcrypto/doc/d2i_X509_SIG.pod deleted file mode 100644 index 00d03f5ba1..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_SIG.pod +++ /dev/null | |||
@@ -1,26 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/x509.h> | ||
10 | |||
11 | X509_SIG *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length); | ||
12 | int i2d_X509_SIG(X509_SIG *a, unsigned char **pp); | ||
13 | |||
14 | =head1 DESCRIPTION | ||
15 | |||
16 | These functions decode and encode an X509_SIG structure which is | ||
17 | equivalent to the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. | ||
18 | |||
19 | Othewise these behave in a similar way to d2i_X509() and i2d_X509() | ||
20 | described in the L<d2i_X509(3)|d2i_X509(3)> manual page. | ||
21 | |||
22 | =head1 SEE ALSO | ||
23 | |||
24 | L<d2i_X509(3)|d2i_X509(3)> | ||
25 | |||
26 | =cut | ||
diff --git a/src/lib/libcrypto/doc/dh.pod b/src/lib/libcrypto/doc/dh.pod deleted file mode 100644 index 5fb9890a77..0000000000 --- a/src/lib/libcrypto/doc/dh.pod +++ /dev/null | |||
@@ -1,79 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | dh - Diffie-Hellman key agreement | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dh.h> | ||
10 | #include <openssl/engine.h> | ||
11 | |||
12 | DH * DH_new(void); | ||
13 | void DH_free(DH *dh); | ||
14 | |||
15 | int DH_size(const DH *dh); | ||
16 | |||
17 | DH * DH_generate_parameters(int prime_len, int generator, | ||
18 | void (*callback)(int, int, void *), void *cb_arg); | ||
19 | int DH_check(const DH *dh, int *codes); | ||
20 | |||
21 | int DH_generate_key(DH *dh); | ||
22 | int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); | ||
23 | |||
24 | void DH_set_default_method(const DH_METHOD *meth); | ||
25 | const DH_METHOD *DH_get_default_method(void); | ||
26 | int DH_set_method(DH *dh, const DH_METHOD *meth); | ||
27 | DH *DH_new_method(ENGINE *engine); | ||
28 | const DH_METHOD *DH_OpenSSL(void); | ||
29 | |||
30 | int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(), | ||
31 | int (*dup_func)(), void (*free_func)()); | ||
32 | int DH_set_ex_data(DH *d, int idx, char *arg); | ||
33 | char *DH_get_ex_data(DH *d, int idx); | ||
34 | |||
35 | DH * d2i_DHparams(DH **a, unsigned char **pp, long length); | ||
36 | int i2d_DHparams(const DH *a, unsigned char **pp); | ||
37 | |||
38 | int DHparams_print_fp(FILE *fp, const DH *x); | ||
39 | int DHparams_print(BIO *bp, const DH *x); | ||
40 | |||
41 | =head1 DESCRIPTION | ||
42 | |||
43 | These functions implement the Diffie-Hellman key agreement protocol. The | ||
44 | generation of shared DH parameters is described in | ||
45 | L<DH_generate_parameters(3)|DH_generate_parameters(3)>; | ||
46 | L<DH_generate_key(3)|DH_generate_key(3)> describes how to perform a key | ||
47 | agreement. | ||
48 | |||
49 | The B<DH> structure consists of several BIGNUM components. | ||
50 | |||
51 | struct | ||
52 | { | ||
53 | BIGNUM *p; // prime number (shared) | ||
54 | BIGNUM *g; // generator of Z_p (shared) | ||
55 | BIGNUM *priv_key; // private DH value x | ||
56 | BIGNUM *pub_key; // public DH value g^x | ||
57 | // ... | ||
58 | }; | ||
59 | DH | ||
60 | |||
61 | Note that DH keys may use non-standard B<DH_METHOD> implementations, | ||
62 | either directly or by the use of B<ENGINE> modules. In some cases (eg. an | ||
63 | ENGINE providing support for hardware-embedded keys), these BIGNUM values | ||
64 | will not be used by the implementation or may be used for alternative data | ||
65 | storage. For this reason, applications should generally avoid using DH | ||
66 | structure elements directly and instead use API functions to query or | ||
67 | modify keys. | ||
68 | |||
69 | =head1 SEE ALSO | ||
70 | |||
71 | L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, | ||
72 | L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<engine(3)|engine(3)>, | ||
73 | L<DH_set_method(3)|DH_set_method(3)>, L<DH_new(3)|DH_new(3)>, | ||
74 | L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>, | ||
75 | L<DH_generate_parameters(3)|DH_generate_parameters(3)>, | ||
76 | L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>, | ||
77 | L<RSA_print(3)|RSA_print(3)> | ||
78 | |||
79 | =cut | ||
diff --git a/src/lib/libcrypto/doc/dsa.pod b/src/lib/libcrypto/doc/dsa.pod deleted file mode 100644 index da07d2b930..0000000000 --- a/src/lib/libcrypto/doc/dsa.pod +++ /dev/null | |||
@@ -1,114 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | dsa - Digital Signature Algorithm | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/dsa.h> | ||
10 | #include <openssl/engine.h> | ||
11 | |||
12 | DSA * DSA_new(void); | ||
13 | void DSA_free(DSA *dsa); | ||
14 | |||
15 | int DSA_size(const DSA *dsa); | ||
16 | |||
17 | DSA * DSA_generate_parameters(int bits, unsigned char *seed, | ||
18 | int seed_len, int *counter_ret, unsigned long *h_ret, | ||
19 | void (*callback)(int, int, void *), void *cb_arg); | ||
20 | |||
21 | DH * DSA_dup_DH(const DSA *r); | ||
22 | |||
23 | int DSA_generate_key(DSA *dsa); | ||
24 | |||
25 | int DSA_sign(int dummy, const unsigned char *dgst, int len, | ||
26 | unsigned char *sigret, unsigned int *siglen, DSA *dsa); | ||
27 | int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, | ||
28 | BIGNUM **rp); | ||
29 | int DSA_verify(int dummy, const unsigned char *dgst, int len, | ||
30 | const unsigned char *sigbuf, int siglen, DSA *dsa); | ||
31 | |||
32 | void DSA_set_default_method(const DSA_METHOD *meth); | ||
33 | const DSA_METHOD *DSA_get_default_method(void); | ||
34 | int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); | ||
35 | DSA *DSA_new_method(ENGINE *engine); | ||
36 | const DSA_METHOD *DSA_OpenSSL(void); | ||
37 | |||
38 | int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), | ||
39 | int (*dup_func)(), void (*free_func)()); | ||
40 | int DSA_set_ex_data(DSA *d, int idx, char *arg); | ||
41 | char *DSA_get_ex_data(DSA *d, int idx); | ||
42 | |||
43 | DSA_SIG *DSA_SIG_new(void); | ||
44 | void DSA_SIG_free(DSA_SIG *a); | ||
45 | int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); | ||
46 | DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length); | ||
47 | |||
48 | DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); | ||
49 | int DSA_do_verify(const unsigned char *dgst, int dgst_len, | ||
50 | DSA_SIG *sig, DSA *dsa); | ||
51 | |||
52 | DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length); | ||
53 | DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length); | ||
54 | DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length); | ||
55 | int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); | ||
56 | int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); | ||
57 | int i2d_DSAparams(const DSA *a,unsigned char **pp); | ||
58 | |||
59 | int DSAparams_print(BIO *bp, const DSA *x); | ||
60 | int DSAparams_print_fp(FILE *fp, const DSA *x); | ||
61 | int DSA_print(BIO *bp, const DSA *x, int off); | ||
62 | int DSA_print_fp(FILE *bp, const DSA *x, int off); | ||
63 | |||
64 | =head1 DESCRIPTION | ||
65 | |||
66 | These functions implement the Digital Signature Algorithm (DSA). The | ||
67 | generation of shared DSA parameters is described in | ||
68 | L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>; | ||
69 | L<DSA_generate_key(3)|DSA_generate_key(3)> describes how to | ||
70 | generate a signature key. Signature generation and verification are | ||
71 | described in L<DSA_sign(3)|DSA_sign(3)>. | ||
72 | |||
73 | The B<DSA> structure consists of several BIGNUM components. | ||
74 | |||
75 | struct | ||
76 | { | ||
77 | BIGNUM *p; // prime number (public) | ||
78 | BIGNUM *q; // 160-bit subprime, q | p-1 (public) | ||
79 | BIGNUM *g; // generator of subgroup (public) | ||
80 | BIGNUM *priv_key; // private key x | ||
81 | BIGNUM *pub_key; // public key y = g^x | ||
82 | // ... | ||
83 | } | ||
84 | DSA; | ||
85 | |||
86 | In public keys, B<priv_key> is NULL. | ||
87 | |||
88 | Note that DSA keys may use non-standard B<DSA_METHOD> implementations, | ||
89 | either directly or by the use of B<ENGINE> modules. In some cases (eg. an | ||
90 | ENGINE providing support for hardware-embedded keys), these BIGNUM values | ||
91 | will not be used by the implementation or may be used for alternative data | ||
92 | storage. For this reason, applications should generally avoid using DSA | ||
93 | structure elements directly and instead use API functions to query or | ||
94 | modify keys. | ||
95 | |||
96 | =head1 CONFORMING TO | ||
97 | |||
98 | US Federal Information Processing Standard FIPS 186 (Digital Signature | ||
99 | Standard, DSS), ANSI X9.30 | ||
100 | |||
101 | =head1 SEE ALSO | ||
102 | |||
103 | L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, | ||
104 | L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<engine(3)|engine(3)>, | ||
105 | L<DSA_new(3)|DSA_new(3)>, | ||
106 | L<DSA_size(3)|DSA_size(3)>, | ||
107 | L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, | ||
108 | L<DSA_dup_DH(3)|DSA_dup_DH(3)>, | ||
109 | L<DSA_generate_key(3)|DSA_generate_key(3)>, | ||
110 | L<DSA_sign(3)|DSA_sign(3)>, L<DSA_set_method(3)|DSA_set_method(3)>, | ||
111 | L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, | ||
112 | L<RSA_print(3)|RSA_print(3)> | ||
113 | |||
114 | =cut | ||
diff --git a/src/lib/libcrypto/doc/ec.pod b/src/lib/libcrypto/doc/ec.pod deleted file mode 100644 index 891948e4f6..0000000000 --- a/src/lib/libcrypto/doc/ec.pod +++ /dev/null | |||
@@ -1,201 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ec - Elliptic Curve functions | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/ec.h> | ||
10 | #include <openssl/bn.h> | ||
11 | |||
12 | const EC_METHOD *EC_GFp_simple_method(void); | ||
13 | const EC_METHOD *EC_GFp_mont_method(void); | ||
14 | const EC_METHOD *EC_GFp_nist_method(void); | ||
15 | const EC_METHOD *EC_GFp_nistp224_method(void); | ||
16 | const EC_METHOD *EC_GFp_nistp256_method(void); | ||
17 | const EC_METHOD *EC_GFp_nistp521_method(void); | ||
18 | |||
19 | const EC_METHOD *EC_GF2m_simple_method(void); | ||
20 | |||
21 | EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); | ||
22 | void EC_GROUP_free(EC_GROUP *group); | ||
23 | void EC_GROUP_clear_free(EC_GROUP *group); | ||
24 | int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); | ||
25 | EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); | ||
26 | const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); | ||
27 | int EC_METHOD_get_field_type(const EC_METHOD *meth); | ||
28 | int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); | ||
29 | const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); | ||
30 | int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); | ||
31 | int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); | ||
32 | void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); | ||
33 | int EC_GROUP_get_curve_name(const EC_GROUP *group); | ||
34 | void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); | ||
35 | int EC_GROUP_get_asn1_flag(const EC_GROUP *group); | ||
36 | void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); | ||
37 | point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); | ||
38 | unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); | ||
39 | size_t EC_GROUP_get_seed_len(const EC_GROUP *); | ||
40 | size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); | ||
41 | int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
42 | int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
43 | int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
44 | int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); | ||
45 | int EC_GROUP_get_degree(const EC_GROUP *group); | ||
46 | int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); | ||
47 | int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); | ||
48 | int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); | ||
49 | EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
50 | EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); | ||
51 | EC_GROUP *EC_GROUP_new_by_curve_name(int nid); | ||
52 | |||
53 | size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); | ||
54 | |||
55 | EC_POINT *EC_POINT_new(const EC_GROUP *group); | ||
56 | void EC_POINT_free(EC_POINT *point); | ||
57 | void EC_POINT_clear_free(EC_POINT *point); | ||
58 | int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); | ||
59 | EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); | ||
60 | const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); | ||
61 | int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); | ||
62 | int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, | ||
63 | const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); | ||
64 | int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, | ||
65 | const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); | ||
66 | int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, | ||
67 | const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); | ||
68 | int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, | ||
69 | const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | ||
70 | int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, | ||
71 | const BIGNUM *x, int y_bit, BN_CTX *ctx); | ||
72 | int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, | ||
73 | const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); | ||
74 | int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, | ||
75 | const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); | ||
76 | int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, | ||
77 | const BIGNUM *x, int y_bit, BN_CTX *ctx); | ||
78 | size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, | ||
79 | point_conversion_form_t form, | ||
80 | unsigned char *buf, size_t len, BN_CTX *ctx); | ||
81 | int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, | ||
82 | const unsigned char *buf, size_t len, BN_CTX *ctx); | ||
83 | BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, | ||
84 | point_conversion_form_t form, BIGNUM *, BN_CTX *); | ||
85 | EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, | ||
86 | EC_POINT *, BN_CTX *); | ||
87 | char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, | ||
88 | point_conversion_form_t form, BN_CTX *); | ||
89 | EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, | ||
90 | EC_POINT *, BN_CTX *); | ||
91 | |||
92 | int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); | ||
93 | int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); | ||
94 | int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); | ||
95 | int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); | ||
96 | int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); | ||
97 | int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); | ||
98 | int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); | ||
99 | int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); | ||
100 | int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); | ||
101 | int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); | ||
102 | int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); | ||
103 | int EC_GROUP_have_precompute_mult(const EC_GROUP *group); | ||
104 | |||
105 | int EC_GROUP_get_basis_type(const EC_GROUP *); | ||
106 | int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); | ||
107 | int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, | ||
108 | unsigned int *k2, unsigned int *k3); | ||
109 | EC_GROUP *d2i_ECPKParameters(EC_GROUP **, const unsigned char **in, long len); | ||
110 | int i2d_ECPKParameters(const EC_GROUP *, unsigned char **out); | ||
111 | #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) | ||
112 | #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) | ||
113 | #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ | ||
114 | (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) | ||
115 | #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ | ||
116 | (unsigned char *)(x)) | ||
117 | int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); | ||
118 | int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); | ||
119 | |||
120 | EC_KEY *EC_KEY_new(void); | ||
121 | int EC_KEY_get_flags(const EC_KEY *key); | ||
122 | void EC_KEY_set_flags(EC_KEY *key, int flags); | ||
123 | void EC_KEY_clear_flags(EC_KEY *key, int flags); | ||
124 | EC_KEY *EC_KEY_new_by_curve_name(int nid); | ||
125 | void EC_KEY_free(EC_KEY *key); | ||
126 | EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); | ||
127 | EC_KEY *EC_KEY_dup(const EC_KEY *src); | ||
128 | int EC_KEY_up_ref(EC_KEY *key); | ||
129 | const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); | ||
130 | int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); | ||
131 | const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); | ||
132 | int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); | ||
133 | const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); | ||
134 | int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); | ||
135 | unsigned EC_KEY_get_enc_flags(const EC_KEY *key); | ||
136 | void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); | ||
137 | point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); | ||
138 | void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); | ||
139 | void *EC_KEY_get_key_method_data(EC_KEY *key, | ||
140 | void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); | ||
141 | void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, | ||
142 | void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); | ||
143 | void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); | ||
144 | int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); | ||
145 | int EC_KEY_generate_key(EC_KEY *key); | ||
146 | int EC_KEY_check_key(const EC_KEY *key); | ||
147 | int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); | ||
148 | |||
149 | EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); | ||
150 | int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); | ||
151 | |||
152 | EC_KEY *d2i_ECParameters(EC_KEY **key, const unsigned char **in, long len); | ||
153 | int i2d_ECParameters(EC_KEY *key, unsigned char **out); | ||
154 | |||
155 | EC_KEY *o2i_ECPublicKey(EC_KEY **key, const unsigned char **in, long len); | ||
156 | int i2o_ECPublicKey(EC_KEY *key, unsigned char **out); | ||
157 | int ECParameters_print(BIO *bp, const EC_KEY *key); | ||
158 | int EC_KEY_print(BIO *bp, const EC_KEY *key, int off); | ||
159 | int ECParameters_print_fp(FILE *fp, const EC_KEY *key); | ||
160 | int EC_KEY_print_fp(FILE *fp, const EC_KEY *key, int off); | ||
161 | EC_KEY *ECParameters_dup(EC_KEY *key); | ||
162 | #define EVP_PKEY_CTX_set_ec_paramgen_curve_nid(ctx, nid) \ | ||
163 | EVP_PKEY_CTX_ctrl(ctx, EVP_PKEY_EC, EVP_PKEY_OP_PARAMGEN, \ | ||
164 | EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID, nid, NULL) | ||
165 | |||
166 | |||
167 | =head1 DESCRIPTION | ||
168 | |||
169 | This library provides an extensive set of functions for performing operations on elliptic curves over finite fields. | ||
170 | In general an elliptic curve is one with an equation of the form: | ||
171 | |||
172 | y^2 = x^3 + ax + b | ||
173 | |||
174 | An B<EC_GROUP> structure is used to represent the definition of an elliptic curve. Points on a curve are stored using an | ||
175 | B<EC_POINT> structure. An B<EC_KEY> is used to hold a private/public key pair, where a private key is simply a BIGNUM and a | ||
176 | public key is a point on a curve (represented by an B<EC_POINT>). | ||
177 | |||
178 | The library contains a number of alternative implementations of the different functions. Each implementation is optimised | ||
179 | for different scenarios. No matter which implementation is being used, the interface remains the same. The library | ||
180 | handles calling the correct implementation when an interface function is invoked. An implementation is represented by | ||
181 | an B<EC_METHOD> structure. | ||
182 | |||
183 | The creation and destruction of B<EC_GROUP> objects is described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>. Functions for | ||
184 | manipulating B<EC_GROUP> objects are described in L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>. | ||
185 | |||
186 | Functions for creating, destroying and manipulating B<EC_POINT> objects are explained in L<EC_POINT_new(3)|EC_POINT_new(3)>, | ||
187 | whilst functions for performing mathematical operations and tests on B<EC_POINTs> are coverd in L<EC_POINT_add(3)|EC_POINT_add(3)>. | ||
188 | |||
189 | For working with private and public keys refer to L<EC_KEY_new(3)|EC_KEY_new(3)>. Implementations are covered in | ||
190 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>. | ||
191 | |||
192 | For information on encoding and decoding curve parameters to and from ASN1 see L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>. | ||
193 | |||
194 | =head1 SEE ALSO | ||
195 | |||
196 | L<crypto(3)|crypto(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, | ||
197 | L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, | ||
198 | L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> | ||
199 | |||
200 | |||
201 | =cut | ||
diff --git a/src/lib/libcrypto/doc/engine.pod b/src/lib/libcrypto/doc/engine.pod deleted file mode 100644 index 31035af398..0000000000 --- a/src/lib/libcrypto/doc/engine.pod +++ /dev/null | |||
@@ -1,599 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | ENGINE_add, ENGINE_by_id, ENGINE_finish, ENGINE_get_first, | ||
6 | ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, | ||
7 | ENGINE_init, ENGINE_load_builtin_engines, ENGINE_remove | ||
8 | - ENGINE cryptographic module support | ||
9 | |||
10 | =head1 SYNOPSIS | ||
11 | |||
12 | #include <openssl/engine.h> | ||
13 | |||
14 | ENGINE *ENGINE_get_first(void); | ||
15 | ENGINE *ENGINE_get_last(void); | ||
16 | ENGINE *ENGINE_get_next(ENGINE *e); | ||
17 | ENGINE *ENGINE_get_prev(ENGINE *e); | ||
18 | |||
19 | int ENGINE_add(ENGINE *e); | ||
20 | int ENGINE_remove(ENGINE *e); | ||
21 | |||
22 | ENGINE *ENGINE_by_id(const char *id); | ||
23 | |||
24 | int ENGINE_init(ENGINE *e); | ||
25 | int ENGINE_finish(ENGINE *e); | ||
26 | |||
27 | void ENGINE_load_openssl(void); | ||
28 | void ENGINE_load_dynamic(void); | ||
29 | void ENGINE_load_cryptodev(void); | ||
30 | void ENGINE_load_builtin_engines(void); | ||
31 | |||
32 | void ENGINE_cleanup(void); | ||
33 | |||
34 | ENGINE *ENGINE_get_default_RSA(void); | ||
35 | ENGINE *ENGINE_get_default_DSA(void); | ||
36 | ENGINE *ENGINE_get_default_ECDH(void); | ||
37 | ENGINE *ENGINE_get_default_ECDSA(void); | ||
38 | ENGINE *ENGINE_get_default_DH(void); | ||
39 | ENGINE *ENGINE_get_default_RAND(void); | ||
40 | ENGINE *ENGINE_get_cipher_engine(int nid); | ||
41 | ENGINE *ENGINE_get_digest_engine(int nid); | ||
42 | |||
43 | int ENGINE_set_default_RSA(ENGINE *e); | ||
44 | int ENGINE_set_default_DSA(ENGINE *e); | ||
45 | int ENGINE_set_default_ECDH(ENGINE *e); | ||
46 | int ENGINE_set_default_ECDSA(ENGINE *e); | ||
47 | int ENGINE_set_default_DH(ENGINE *e); | ||
48 | int ENGINE_set_default_RAND(ENGINE *e); | ||
49 | int ENGINE_set_default_ciphers(ENGINE *e); | ||
50 | int ENGINE_set_default_digests(ENGINE *e); | ||
51 | int ENGINE_set_default_string(ENGINE *e, const char *list); | ||
52 | |||
53 | int ENGINE_set_default(ENGINE *e, unsigned int flags); | ||
54 | |||
55 | unsigned int ENGINE_get_table_flags(void); | ||
56 | void ENGINE_set_table_flags(unsigned int flags); | ||
57 | |||
58 | int ENGINE_register_RSA(ENGINE *e); | ||
59 | void ENGINE_unregister_RSA(ENGINE *e); | ||
60 | void ENGINE_register_all_RSA(void); | ||
61 | int ENGINE_register_DSA(ENGINE *e); | ||
62 | void ENGINE_unregister_DSA(ENGINE *e); | ||
63 | void ENGINE_register_all_DSA(void); | ||
64 | int ENGINE_register_ECDH(ENGINE *e); | ||
65 | void ENGINE_unregister_ECDH(ENGINE *e); | ||
66 | void ENGINE_register_all_ECDH(void); | ||
67 | int ENGINE_register_ECDSA(ENGINE *e); | ||
68 | void ENGINE_unregister_ECDSA(ENGINE *e); | ||
69 | void ENGINE_register_all_ECDSA(void); | ||
70 | int ENGINE_register_DH(ENGINE *e); | ||
71 | void ENGINE_unregister_DH(ENGINE *e); | ||
72 | void ENGINE_register_all_DH(void); | ||
73 | int ENGINE_register_RAND(ENGINE *e); | ||
74 | void ENGINE_unregister_RAND(ENGINE *e); | ||
75 | void ENGINE_register_all_RAND(void); | ||
76 | int ENGINE_register_STORE(ENGINE *e); | ||
77 | void ENGINE_unregister_STORE(ENGINE *e); | ||
78 | void ENGINE_register_all_STORE(void); | ||
79 | int ENGINE_register_ciphers(ENGINE *e); | ||
80 | void ENGINE_unregister_ciphers(ENGINE *e); | ||
81 | void ENGINE_register_all_ciphers(void); | ||
82 | int ENGINE_register_digests(ENGINE *e); | ||
83 | void ENGINE_unregister_digests(ENGINE *e); | ||
84 | void ENGINE_register_all_digests(void); | ||
85 | int ENGINE_register_complete(ENGINE *e); | ||
86 | int ENGINE_register_all_complete(void); | ||
87 | |||
88 | int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); | ||
89 | int ENGINE_cmd_is_executable(ENGINE *e, int cmd); | ||
90 | int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, | ||
91 | long i, void *p, void (*f)(void), int cmd_optional); | ||
92 | int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, | ||
93 | int cmd_optional); | ||
94 | |||
95 | int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); | ||
96 | void *ENGINE_get_ex_data(const ENGINE *e, int idx); | ||
97 | |||
98 | int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, | ||
99 | CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); | ||
100 | |||
101 | ENGINE *ENGINE_new(void); | ||
102 | int ENGINE_free(ENGINE *e); | ||
103 | int ENGINE_up_ref(ENGINE *e); | ||
104 | |||
105 | int ENGINE_set_id(ENGINE *e, const char *id); | ||
106 | int ENGINE_set_name(ENGINE *e, const char *name); | ||
107 | int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); | ||
108 | int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); | ||
109 | int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth); | ||
110 | int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth); | ||
111 | int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); | ||
112 | int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); | ||
113 | int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth); | ||
114 | int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); | ||
115 | int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); | ||
116 | int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); | ||
117 | int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); | ||
118 | int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); | ||
119 | int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); | ||
120 | int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); | ||
121 | int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); | ||
122 | int ENGINE_set_flags(ENGINE *e, int flags); | ||
123 | int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); | ||
124 | |||
125 | const char *ENGINE_get_id(const ENGINE *e); | ||
126 | const char *ENGINE_get_name(const ENGINE *e); | ||
127 | const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); | ||
128 | const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); | ||
129 | const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e); | ||
130 | const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e); | ||
131 | const DH_METHOD *ENGINE_get_DH(const ENGINE *e); | ||
132 | const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); | ||
133 | const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e); | ||
134 | ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); | ||
135 | ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); | ||
136 | ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); | ||
137 | ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); | ||
138 | ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); | ||
139 | ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); | ||
140 | ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); | ||
141 | ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); | ||
142 | const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); | ||
143 | const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); | ||
144 | int ENGINE_get_flags(const ENGINE *e); | ||
145 | const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); | ||
146 | |||
147 | EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, | ||
148 | UI_METHOD *ui_method, void *callback_data); | ||
149 | EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, | ||
150 | UI_METHOD *ui_method, void *callback_data); | ||
151 | |||
152 | void ENGINE_add_conf_module(void); | ||
153 | |||
154 | =head1 DESCRIPTION | ||
155 | |||
156 | These functions create, manipulate, and use cryptographic modules in the | ||
157 | form of B<ENGINE> objects. These objects act as containers for | ||
158 | implementations of cryptographic algorithms, and support a | ||
159 | reference-counted mechanism to allow them to be dynamically loaded in and | ||
160 | out of the running application. | ||
161 | |||
162 | The cryptographic functionality that can be provided by an B<ENGINE> | ||
163 | implementation includes the following abstractions; | ||
164 | |||
165 | RSA_METHOD - for providing alternative RSA implementations | ||
166 | DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, | ||
167 | STORE_METHOD - similarly for other OpenSSL APIs | ||
168 | EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') | ||
169 | EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') | ||
170 | key-loading - loading public and/or private EVP_PKEY keys | ||
171 | |||
172 | =head2 Reference counting and handles | ||
173 | |||
174 | Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be | ||
175 | treated as handles - ie. not only as pointers, but also as references to | ||
176 | the underlying ENGINE object. Ie. one should obtain a new reference when | ||
177 | making copies of an ENGINE pointer if the copies will be used (and | ||
178 | released) independently. | ||
179 | |||
180 | ENGINE objects have two levels of reference-counting to match the way in | ||
181 | which the objects are used. At the most basic level, each ENGINE pointer is | ||
182 | inherently a B<structural> reference - a structural reference is required | ||
183 | to use the pointer value at all, as this kind of reference is a guarantee | ||
184 | that the structure can not be deallocated until the reference is released. | ||
185 | |||
186 | However, a structural reference provides no guarantee that the ENGINE is | ||
187 | initialised and able to use any of its cryptographic | ||
188 | implementations. Indeed it's quite possible that most ENGINEs will not | ||
189 | initialise at all in typical environments, as ENGINEs are typically used to | ||
190 | support specialised hardware. To use an ENGINE's functionality, you need a | ||
191 | B<functional> reference. This kind of reference can be considered a | ||
192 | specialised form of structural reference, because each functional reference | ||
193 | implicitly contains a structural reference as well - however to avoid | ||
194 | difficult-to-find programming bugs, it is recommended to treat the two | ||
195 | kinds of reference independently. If you have a functional reference to an | ||
196 | ENGINE, you have a guarantee that the ENGINE has been initialised ready to | ||
197 | perform cryptographic operations and will remain uninitialised | ||
198 | until after you have released your reference. | ||
199 | |||
200 | I<Structural references> | ||
201 | |||
202 | This basic type of reference is used for instantiating new ENGINEs, | ||
203 | iterating across OpenSSL's internal linked-list of loaded | ||
204 | ENGINEs, reading information about an ENGINE, etc. Essentially a structural | ||
205 | reference is sufficient if you only need to query or manipulate the data of | ||
206 | an ENGINE implementation rather than use its functionality. | ||
207 | |||
208 | The ENGINE_new() function returns a structural reference to a new (empty) | ||
209 | ENGINE object. There are other ENGINE API functions that return structural | ||
210 | references such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), | ||
211 | ENGINE_get_next(), ENGINE_get_prev(). All structural references should be | ||
212 | released by a corresponding to call to the ENGINE_free() function - the | ||
213 | ENGINE object itself will only actually be cleaned up and deallocated when | ||
214 | the last structural reference is released. | ||
215 | |||
216 | It should also be noted that many ENGINE API function calls that accept a | ||
217 | structural reference will internally obtain another reference - typically | ||
218 | this happens whenever the supplied ENGINE will be needed by OpenSSL after | ||
219 | the function has returned. Eg. the function to add a new ENGINE to | ||
220 | OpenSSL's internal list is ENGINE_add() - if this function returns success, | ||
221 | then OpenSSL will have stored a new structural reference internally so the | ||
222 | caller is still responsible for freeing their own reference with | ||
223 | ENGINE_free() when they are finished with it. In a similar way, some | ||
224 | functions will automatically release the structural reference passed to it | ||
225 | if part of the function's job is to do so. Eg. the ENGINE_get_next() and | ||
226 | ENGINE_get_prev() functions are used for iterating across the internal | ||
227 | ENGINE list - they will return a new structural reference to the next (or | ||
228 | previous) ENGINE in the list or NULL if at the end (or beginning) of the | ||
229 | list, but in either case the structural reference passed to the function is | ||
230 | released on behalf of the caller. | ||
231 | |||
232 | To clarify a particular function's handling of references, one should | ||
233 | always consult that function's documentation "man" page, or failing that | ||
234 | the openssl/engine.h header file includes some hints. | ||
235 | |||
236 | I<Functional references> | ||
237 | |||
238 | As mentioned, functional references exist when the cryptographic | ||
239 | functionality of an ENGINE is required to be available. A functional | ||
240 | reference can be obtained in one of two ways; from an existing structural | ||
241 | reference to the required ENGINE, or by asking OpenSSL for the default | ||
242 | operational ENGINE for a given cryptographic purpose. | ||
243 | |||
244 | To obtain a functional reference from an existing structural reference, | ||
245 | call the ENGINE_init() function. This returns zero if the ENGINE was not | ||
246 | already operational and couldn't be successfully initialised (eg. lack of | ||
247 | system drivers, no special hardware attached, etc), otherwise it will | ||
248 | return non-zero to indicate that the ENGINE is now operational and will | ||
249 | have allocated a new B<functional> reference to the ENGINE. All functional | ||
250 | references are released by calling ENGINE_finish() (which removes the | ||
251 | implicit structural reference as well). | ||
252 | |||
253 | The second way to get a functional reference is by asking OpenSSL for a | ||
254 | default implementation for a given task, eg. by ENGINE_get_default_RSA(), | ||
255 | ENGINE_get_default_cipher_engine(), etc. These are discussed in the next | ||
256 | section, though they are not usually required by application programmers as | ||
257 | they are used automatically when creating and using the relevant | ||
258 | algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc. | ||
259 | |||
260 | =head2 Default implementations | ||
261 | |||
262 | For each supported abstraction, the ENGINE code maintains an internal table | ||
263 | of state to control which implementations are available for a given | ||
264 | abstraction and which should be used by default. These implementations are | ||
265 | registered in the tables and indexed by an 'nid' value, because | ||
266 | abstractions like EVP_CIPHER and EVP_DIGEST support many distinct | ||
267 | algorithms and modes, and ENGINEs can support arbitrarily many of them. | ||
268 | In the case of other abstractions like RSA, DSA, etc, there is only one | ||
269 | "algorithm" so all implementations implicitly register using the same 'nid' | ||
270 | index. | ||
271 | |||
272 | When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg. | ||
273 | when calling RSA_new_method(NULL)), a "get_default" call will be made to the | ||
274 | ENGINE subsystem to process the corresponding state table and return a | ||
275 | functional reference to an initialised ENGINE whose implementation should be | ||
276 | used. If no ENGINE should (or can) be used, it will return NULL and the caller | ||
277 | will operate with a NULL ENGINE handle - this usually equates to using the | ||
278 | conventional software implementation. In the latter case, OpenSSL will from | ||
279 | then on behave the way it used to before the ENGINE API existed. | ||
280 | |||
281 | Each state table has a flag to note whether it has processed this | ||
282 | "get_default" query since the table was last modified, because to process | ||
283 | this question it must iterate across all the registered ENGINEs in the | ||
284 | table trying to initialise each of them in turn, in case one of them is | ||
285 | operational. If it returns a functional reference to an ENGINE, it will | ||
286 | also cache another reference to speed up processing future queries (without | ||
287 | needing to iterate across the table). Likewise, it will cache a NULL | ||
288 | response if no ENGINE was available so that future queries won't repeat the | ||
289 | same iteration unless the state table changes. This behaviour can also be | ||
290 | changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using | ||
291 | ENGINE_set_table_flags()), no attempted initialisations will take place, | ||
292 | instead the only way for the state table to return a non-NULL ENGINE to the | ||
293 | "get_default" query will be if one is expressly set in the table. Eg. | ||
294 | ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except | ||
295 | that it also sets the state table's cached response for the "get_default" | ||
296 | query. In the case of abstractions like EVP_CIPHER, where implementations are | ||
297 | indexed by 'nid', these flags and cached-responses are distinct for each 'nid' | ||
298 | value. | ||
299 | |||
300 | =head2 Application requirements | ||
301 | |||
302 | This section will explain the basic things an application programmer should | ||
303 | support to make the most useful elements of the ENGINE functionality | ||
304 | available to the user. The first thing to consider is whether the | ||
305 | programmer wishes to make alternative ENGINE modules available to the | ||
306 | application and user. OpenSSL maintains an internal linked list of | ||
307 | "visible" ENGINEs from which it has to operate - at start-up, this list is | ||
308 | empty and in fact if an application does not call any ENGINE API calls and | ||
309 | it uses static linking against openssl, then the resulting application | ||
310 | binary will not contain any alternative ENGINE code at all. So the first | ||
311 | consideration is whether any/all available ENGINE implementations should be | ||
312 | made visible to OpenSSL - this is controlled by calling the various "load" | ||
313 | functions, eg. | ||
314 | |||
315 | /* Make ALL ENGINE implementations bundled with OpenSSL available */ | ||
316 | ENGINE_load_builtin_engines(); | ||
317 | |||
318 | Note that ENGINE_load_dynamic(void) is a placeholder and does not enable | ||
319 | dynamic engine loading support. | ||
320 | |||
321 | Having called any of these functions, ENGINE objects would have been | ||
322 | dynamically allocated and populated with these implementations and linked | ||
323 | into OpenSSL's internal linked list. At this point it is important to | ||
324 | mention an important API function; | ||
325 | |||
326 | void ENGINE_cleanup(void); | ||
327 | |||
328 | If no ENGINE API functions are called at all in an application, then there | ||
329 | are no inherent memory leaks to worry about from the ENGINE functionality, | ||
330 | however if any ENGINEs are loaded, even if they are never registered or | ||
331 | used, it is necessary to use the ENGINE_cleanup() function to | ||
332 | correspondingly cleanup before program exit, if the caller wishes to avoid | ||
333 | memory leaks. This mechanism uses an internal callback registration table | ||
334 | so that any ENGINE API functionality that knows it requires cleanup can | ||
335 | register its cleanup details to be called during ENGINE_cleanup(). This | ||
336 | approach allows ENGINE_cleanup() to clean up after any ENGINE functionality | ||
337 | at all that your program uses, yet doesn't automatically create linker | ||
338 | dependencies to all possible ENGINE functionality - only the cleanup | ||
339 | callbacks required by the functionality you do use will be required by the | ||
340 | linker. | ||
341 | |||
342 | The fact that ENGINEs are made visible to OpenSSL (and thus are linked into | ||
343 | the program and loaded into memory at run-time) does not mean they are | ||
344 | "registered" or called into use by OpenSSL automatically - that behaviour | ||
345 | is something for the application to control. Some applications | ||
346 | will want to allow the user to specify exactly which ENGINE they want used | ||
347 | if any is to be used at all. Others may prefer to load all support and have | ||
348 | OpenSSL automatically use at run-time any ENGINE that is able to | ||
349 | successfully initialise - ie. to assume that this corresponds to | ||
350 | acceleration hardware attached to the machine or some such thing. There are | ||
351 | probably numerous other ways in which applications may prefer to handle | ||
352 | things, so we will simply illustrate the consequences as they apply to a | ||
353 | couple of simple cases and leave developers to consider these and the | ||
354 | source code to openssl's builtin utilities as guides. | ||
355 | |||
356 | I<Using a specific ENGINE implementation> | ||
357 | |||
358 | Here we'll assume an application has been configured by its user or admin | ||
359 | to want to use the "ACME" ENGINE if it is available in the version of | ||
360 | OpenSSL the application was compiled with. If it is available, it should be | ||
361 | used by default for all RSA, DSA, and symmetric cipher operation, otherwise | ||
362 | OpenSSL should use its builtin software as per usual. The following code | ||
363 | illustrates how to approach this; | ||
364 | |||
365 | ENGINE *e; | ||
366 | const char *engine_id = "ACME"; | ||
367 | ENGINE_load_builtin_engines(); | ||
368 | e = ENGINE_by_id(engine_id); | ||
369 | if (!e) | ||
370 | /* the engine isn't available */ | ||
371 | return; | ||
372 | if (!ENGINE_init(e)) { | ||
373 | /* the engine couldn't initialise, release 'e' */ | ||
374 | ENGINE_free(e); | ||
375 | return; | ||
376 | } | ||
377 | if (!ENGINE_set_default_RSA(e)) | ||
378 | /* This should only happen when 'e' can't initialise, but the previous | ||
379 | * statement suggests it did. */ | ||
380 | abort(); | ||
381 | ENGINE_set_default_DSA(e); | ||
382 | ENGINE_set_default_ciphers(e); | ||
383 | /* Release the functional reference from ENGINE_init() */ | ||
384 | ENGINE_finish(e); | ||
385 | /* Release the structural reference from ENGINE_by_id() */ | ||
386 | ENGINE_free(e); | ||
387 | |||
388 | I<Automatically using builtin ENGINE implementations> | ||
389 | |||
390 | Here we'll assume we want to load and register all ENGINE implementations | ||
391 | bundled with OpenSSL, such that for any cryptographic algorithm required by | ||
392 | OpenSSL - if there is an ENGINE that implements it and can be initialise, | ||
393 | it should be used. The following code illustrates how this can work; | ||
394 | |||
395 | /* Load all bundled ENGINEs into memory and make them visible */ | ||
396 | ENGINE_load_builtin_engines(); | ||
397 | /* Register all of them for every algorithm they collectively implement */ | ||
398 | ENGINE_register_all_complete(); | ||
399 | |||
400 | That's all that's required. Eg. the next time OpenSSL tries to set up an | ||
401 | RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to | ||
402 | ENGINE_init() and if any of those succeed, that ENGINE will be set as the | ||
403 | default for RSA use from then on. | ||
404 | |||
405 | =head2 Advanced configuration support | ||
406 | |||
407 | There is a mechanism supported by the ENGINE framework that allows each | ||
408 | ENGINE implementation to define an arbitrary set of configuration | ||
409 | "commands" and expose them to OpenSSL and any applications based on | ||
410 | OpenSSL. This mechanism is entirely based on the use of name-value pairs | ||
411 | and assumes ASCII input (no unicode or UTF for now!), so it is ideal if | ||
412 | applications want to provide a transparent way for users to provide | ||
413 | arbitrary configuration "directives" directly to such ENGINEs. It is also | ||
414 | possible for the application to dynamically interrogate the loaded ENGINE | ||
415 | implementations for the names, descriptions, and input flags of their | ||
416 | available "control commands", providing a more flexible configuration | ||
417 | scheme. However, if the user is expected to know which ENGINE device he/she | ||
418 | is using (in the case of specialised hardware, this goes without saying) | ||
419 | then applications may not need to concern themselves with discovering the | ||
420 | supported control commands and simply prefer to pass settings into ENGINEs | ||
421 | exactly as they are provided by the user. | ||
422 | |||
423 | Before illustrating how control commands work, it is worth mentioning what | ||
424 | they are typically used for. Broadly speaking there are two uses for | ||
425 | control commands; the first is to provide the necessary details to the | ||
426 | implementation (which may know nothing at all specific to the host system) | ||
427 | so that it can be initialised for use. This could include the path to any | ||
428 | driver or config files it needs to load, required network addresses, | ||
429 | smart-card identifiers, passwords to initialise protected devices, | ||
430 | logging information, etc etc. This class of commands typically needs to be | ||
431 | passed to an ENGINE B<before> attempting to initialise it, ie. before | ||
432 | calling ENGINE_init(). The other class of commands consist of settings or | ||
433 | operations that tweak certain behaviour or cause certain operations to take | ||
434 | place, and these commands may work either before or after ENGINE_init(), or | ||
435 | in some cases both. ENGINE implementations should provide indications of | ||
436 | this in the descriptions attached to builtin control commands and/or in | ||
437 | external product documentation. | ||
438 | |||
439 | I<Issuing control commands to an ENGINE> | ||
440 | |||
441 | Let's illustrate by example; a function for which the caller supplies the | ||
442 | name of the ENGINE it wishes to use, a table of string-pairs for use before | ||
443 | initialisation, and another table for use after initialisation. Note that | ||
444 | the string-pairs used for control commands consist of a command "name" | ||
445 | followed by the command "parameter" - the parameter could be NULL in some | ||
446 | cases but the name can not. This function should initialise the ENGINE | ||
447 | (issuing the "pre" commands beforehand and the "post" commands afterwards) | ||
448 | and set it as the default for everything except RAND and then return a | ||
449 | boolean success or failure. | ||
450 | |||
451 | int | ||
452 | generic_load_engine_fn(const char *engine_id, | ||
453 | const char **pre_cmds, int pre_num, | ||
454 | const char **post_cmds, int post_num) | ||
455 | { | ||
456 | ENGINE *e = ENGINE_by_id(engine_id); | ||
457 | |||
458 | if (!e) | ||
459 | return 0; | ||
460 | while (pre_num--) { | ||
461 | if (!ENGINE_ctrl_cmd_string(e, | ||
462 | pre_cmds[0], pre_cmds[1], 0)) { | ||
463 | fprintf(stderr, | ||
464 | "Failed command (%s - %s:%s)\n", | ||
465 | engine_id, pre_cmds[0], | ||
466 | pre_cmds[1] ? pre_cmds[1] : "(NULL)"); | ||
467 | ENGINE_free(e); | ||
468 | return 0; | ||
469 | } | ||
470 | pre_cmds += 2; | ||
471 | } | ||
472 | if (!ENGINE_init(e)) { | ||
473 | fprintf(stderr, "Failed initialisation\n"); | ||
474 | ENGINE_free(e); | ||
475 | return 0; | ||
476 | } | ||
477 | /* | ||
478 | * ENGINE_init() returned a functional reference, | ||
479 | * so free the structural reference from | ||
480 | * ENGINE_by_id(). | ||
481 | */ | ||
482 | ENGINE_free(e); | ||
483 | while (post_num--) { | ||
484 | if (!ENGINE_ctrl_cmd_string(e, | ||
485 | post_cmds[0], post_cmds[1], 0)) { | ||
486 | fprintf(stderr, | ||
487 | "Failed command (%s - %s:%s)\n", | ||
488 | engine_id, post_cmds[0], | ||
489 | post_cmds[1] ? post_cmds[1] : "(NULL)"); | ||
490 | ENGINE_finish(e); | ||
491 | return 0; | ||
492 | } | ||
493 | post_cmds += 2; | ||
494 | } | ||
495 | ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); | ||
496 | /* Success */ | ||
497 | return 1; | ||
498 | } | ||
499 | |||
500 | Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can | ||
501 | relax the semantics of the function - if set non-zero it will only return | ||
502 | failure if the ENGINE supported the given command name but failed while | ||
503 | executing it, if the ENGINE doesn't support the command name it will simply | ||
504 | return success without doing anything. In this case we assume the user is | ||
505 | only supplying commands specific to the given ENGINE so we set this to | ||
506 | FALSE. | ||
507 | |||
508 | I<Discovering supported control commands> | ||
509 | |||
510 | It is possible to discover at run-time the names, numerical-ids, descriptions | ||
511 | and input parameters of the control commands supported by an ENGINE using a | ||
512 | structural reference. Note that some control commands are defined by OpenSSL | ||
513 | itself and it will intercept and handle these control commands on behalf of the | ||
514 | ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command. | ||
515 | openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands | ||
516 | implemented by ENGINEs should be numbered from. Any command value lower than | ||
517 | this symbol is considered a "generic" command is handled directly by the | ||
518 | OpenSSL core routines. | ||
519 | |||
520 | It is using these "core" control commands that one can discover the control | ||
521 | commands implemented by a given ENGINE, specifically the commands; | ||
522 | |||
523 | #define ENGINE_HAS_CTRL_FUNCTION 10 | ||
524 | #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 | ||
525 | #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 | ||
526 | #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 | ||
527 | #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 | ||
528 | #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 | ||
529 | #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 | ||
530 | #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 | ||
531 | #define ENGINE_CTRL_GET_CMD_FLAGS 18 | ||
532 | |||
533 | Whilst these commands are automatically processed by the OpenSSL framework code, | ||
534 | they use various properties exposed by each ENGINE to process these | ||
535 | queries. An ENGINE has 3 properties it exposes that can affect how this behaves; | ||
536 | it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in | ||
537 | the ENGINE's flags, and it can expose an array of control command descriptions. | ||
538 | If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will | ||
539 | simply pass all these "core" control commands directly to the ENGINE's ctrl() | ||
540 | handler (and thus, it must have supplied one), so it is up to the ENGINE to | ||
541 | reply to these "discovery" commands itself. If that flag is not set, then the | ||
542 | OpenSSL framework code will work with the following rules; | ||
543 | |||
544 | if no ctrl() handler supplied; | ||
545 | ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), | ||
546 | all other commands fail. | ||
547 | if a ctrl() handler was supplied but no array of control commands; | ||
548 | ENGINE_HAS_CTRL_FUNCTION returns TRUE, | ||
549 | all other commands fail. | ||
550 | if a ctrl() handler and array of control commands was supplied; | ||
551 | ENGINE_HAS_CTRL_FUNCTION returns TRUE, | ||
552 | all other commands proceed processing ... | ||
553 | |||
554 | If the ENGINE's array of control commands is empty then all other commands will | ||
555 | fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of | ||
556 | the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the | ||
557 | identifier of a command supported by the ENGINE and returns the next command | ||
558 | identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string | ||
559 | name for a command and returns the corresponding identifier or fails if no such | ||
560 | command name exists, and the remaining commands take a command identifier and | ||
561 | return properties of the corresponding commands. All except | ||
562 | ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, | ||
563 | or populate a supplied character buffer with a copy of the command name or | ||
564 | description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following | ||
565 | possible values; | ||
566 | |||
567 | #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 | ||
568 | #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 | ||
569 | #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 | ||
570 | #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 | ||
571 | |||
572 | If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely | ||
573 | informational to the caller - this flag will prevent the command being usable | ||
574 | for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). | ||
575 | "INTERNAL" commands are not intended to be exposed to text-based configuration | ||
576 | by applications, administrations, users, etc. These can support arbitrary | ||
577 | operations via ENGINE_ctrl(), including passing to and/or from the control | ||
578 | commands data of any arbitrary type. These commands are supported in the | ||
579 | discovery mechanisms simply allow applications to determine if an ENGINE | ||
580 | supports certain specific commands it might want to use (eg. application "foo" | ||
581 | might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - | ||
582 | and ENGINE could therefore decide whether or not to support this "foo"-specific | ||
583 | extension). | ||
584 | |||
585 | =head2 Future developments | ||
586 | |||
587 | The ENGINE API and internal architecture is currently being reviewed. Slated for | ||
588 | possible release in 0.9.8 is support for transparent loading of "dynamic" | ||
589 | ENGINEs (built as self-contained shared-libraries). This would allow ENGINE | ||
590 | implementations to be provided independently of OpenSSL libraries and/or | ||
591 | OpenSSL-based applications, and would also remove any requirement for | ||
592 | applications to explicitly use the "dynamic" ENGINE to bind to shared-library | ||
593 | implementations. | ||
594 | |||
595 | =head1 SEE ALSO | ||
596 | |||
597 | L<rsa(3)|rsa(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rand(3)|rand(3)> | ||
598 | |||
599 | =cut | ||
diff --git a/src/lib/libcrypto/doc/evp.pod b/src/lib/libcrypto/doc/evp.pod deleted file mode 100644 index dfd96d3b98..0000000000 --- a/src/lib/libcrypto/doc/evp.pod +++ /dev/null | |||
@@ -1,107 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | evp - high-level cryptographic functions | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/evp.h> | ||
10 | |||
11 | =head1 DESCRIPTION | ||
12 | |||
13 | The EVP library provides a high-level interface to cryptographic | ||
14 | functions. | ||
15 | |||
16 | L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and L<B<EVP_Open>I<...>|EVP_OpenInit(3)> | ||
17 | provide public key encryption and decryption to implement digital "envelopes". | ||
18 | |||
19 | The L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> and | ||
20 | L<B<EVP_DigestVerify>I<...>|EVP_DigestVerifyInit(3)> functions implement | ||
21 | digital signatures and Message Authentication Codes (MACs). Also see the older | ||
22 | L<B<EVP_Sign>I<...>|EVP_SignInit(3)> and L<B<EVP_Verify>I<...>|EVP_VerifyInit(3)> | ||
23 | functions. | ||
24 | |||
25 | Symmetric encryption is available with the L<B<EVP_Encrypt>I<...>|EVP_EncryptInit(3)> | ||
26 | functions. The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide message digests. | ||
27 | |||
28 | Authenticated encryption with additional data (AEAD) is available with | ||
29 | the L<B<EVP_AEAD>I<...>|EVP_AEAD_CTX_init(3)> functions. | ||
30 | |||
31 | The B<EVP_PKEY>I<...> functions provide a high level interface to | ||
32 | asymmetric algorithms. To create a new EVP_PKEY see | ||
33 | L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>. EVP_PKEYs can be associated | ||
34 | with a private key of a particular algorithm by using the functions | ||
35 | described on the L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> page, or | ||
36 | new keys can be generated using L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>. | ||
37 | EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)|EVP_PKEY_cmp(3)>, or printed using | ||
38 | L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>. | ||
39 | |||
40 | The EVP_PKEY functions support the full range of asymmetric algorithm operations: | ||
41 | |||
42 | =over | ||
43 | |||
44 | =item For key agreement see L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> | ||
45 | |||
46 | =item For signing and verifying see L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
47 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>. | ||
48 | However, note that | ||
49 | these functions do not perform a digest of the data to be signed. Therefore | ||
50 | normally you would use the L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> | ||
51 | functions for this purpose. | ||
52 | |||
53 | =item For encryption and decryption see L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)> | ||
54 | and L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)> respectively. However, note that | ||
55 | these functions perform encryption and decryption only. As public key | ||
56 | encryption is an expensive operation, normally you would wrap | ||
57 | an encrypted message in a "digital envelope" using the L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and | ||
58 | L<B<EVP_Open>I<...>|EVP_OpenInit(3)> functions. | ||
59 | |||
60 | =back | ||
61 | |||
62 | The L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> function provides some limited support for password | ||
63 | based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible | ||
64 | implementation. However, new applications should not typically use this (preferring, for example, | ||
65 | PBKDF2 from PCKS#5). | ||
66 | |||
67 | Algorithms are loaded with L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>. | ||
68 | |||
69 | All the symmetric algorithms (ciphers), digests and asymmetric algorithms | ||
70 | (public key algorithms) can be replaced by L<ENGINE|engine(3)> modules providing alternative | ||
71 | implementations. If ENGINE implementations of ciphers or digests are registered | ||
72 | as defaults, then the various EVP functions will automatically use those | ||
73 | implementations automatically in preference to built in software | ||
74 | implementations. For more information, consult the engine(3) man page. | ||
75 | |||
76 | Although low level algorithm specific functions exist for many algorithms | ||
77 | their use is discouraged. They cannot be used with an ENGINE and ENGINE | ||
78 | versions of new algorithms cannot be accessed using the low level functions. | ||
79 | Also makes code harder to adapt to new algorithms and some options are not | ||
80 | cleanly supported at the low level and some operations are more efficient | ||
81 | using the high level interface. | ||
82 | |||
83 | =head1 SEE ALSO | ||
84 | |||
85 | L<EVP_DigestInit(3)|EVP_DigestInit(3)>, | ||
86 | L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, | ||
87 | L<EVP_AEAD_CTX_init(3)|EVP_AEAD_CTX_init(3)>, | ||
88 | L<EVP_OpenInit(3)|EVP_OpenInit(3)>, | ||
89 | L<EVP_SealInit(3)|EVP_SealInit(3)>, | ||
90 | L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>, | ||
91 | L<EVP_SignInit(3)|EVP_SignInit(3)>, | ||
92 | L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, | ||
93 | L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>, | ||
94 | L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)>, | ||
95 | L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>, | ||
96 | L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>, | ||
97 | L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, | ||
98 | L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, | ||
99 | L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, | ||
100 | L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, | ||
101 | L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, | ||
102 | L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>, | ||
103 | L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>, | ||
104 | L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>, | ||
105 | L<engine(3)|engine(3)> | ||
106 | |||
107 | =cut | ||
diff --git a/src/lib/libcrypto/doc/i2d_CMS_bio_stream.pod b/src/lib/libcrypto/doc/i2d_CMS_bio_stream.pod deleted file mode 100644 index 558bdd0812..0000000000 --- a/src/lib/libcrypto/doc/i2d_CMS_bio_stream.pod +++ /dev/null | |||
@@ -1,44 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/cms.h> | ||
10 | |||
11 | int i2d_CMS_bio_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | i2d_CMS_bio_stream() outputs a CMS_ContentInfo structure in BER format. | ||
16 | |||
17 | It is otherwise identical to the function SMIME_write_CMS(). | ||
18 | |||
19 | =head1 NOTES | ||
20 | |||
21 | This function is effectively a version of the i2d_CMS_bio() supporting | ||
22 | streaming. | ||
23 | |||
24 | =head1 BUGS | ||
25 | |||
26 | The prefix "i2d" is arguably wrong because the function outputs BER format. | ||
27 | |||
28 | =head1 RETURN VALUES | ||
29 | |||
30 | i2d_CMS_bio_stream() returns 1 for success or 0 for failure. | ||
31 | |||
32 | =head1 SEE ALSO | ||
33 | |||
34 | L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, | ||
35 | L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> | ||
36 | L<CMS_decrypt(3)|CMS_decrypt(3)>, | ||
37 | L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>, | ||
38 | L<PEM_write_bio_CMS_stream(3)|PEM_write_bio_CMS_stream(3)> | ||
39 | |||
40 | =head1 HISTORY | ||
41 | |||
42 | i2d_CMS_bio_stream() was added to OpenSSL 1.0.0 | ||
43 | |||
44 | =cut | ||
diff --git a/src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod b/src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod deleted file mode 100644 index a37231e267..0000000000 --- a/src/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod +++ /dev/null | |||
@@ -1,44 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | i2d_PKCS7_bio_stream - output PKCS7 structure in BER format. | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/pkcs7.h> | ||
10 | |||
11 | int i2d_PKCS7_bio_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); | ||
12 | |||
13 | =head1 DESCRIPTION | ||
14 | |||
15 | i2d_PKCS7_bio_stream() outputs a PKCS7 structure in BER format. | ||
16 | |||
17 | It is otherwise identical to the function SMIME_write_PKCS7(). | ||
18 | |||
19 | =head1 NOTES | ||
20 | |||
21 | This function is effectively a version of the d2i_PKCS7_bio() supporting | ||
22 | streaming. | ||
23 | |||
24 | =head1 BUGS | ||
25 | |||
26 | The prefix "i2d" is arguably wrong because the function outputs BER format. | ||
27 | |||
28 | =head1 RETURN VALUES | ||
29 | |||
30 | i2d_PKCS7_bio_stream() returns 1 for success or 0 for failure. | ||
31 | |||
32 | =head1 SEE ALSO | ||
33 | |||
34 | L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, | ||
35 | L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> | ||
36 | L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, | ||
37 | L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, | ||
38 | L<PEM_write_bio_PKCS7_stream(3)|PEM_write_bio_PKCS7_stream(3)> | ||
39 | |||
40 | =head1 HISTORY | ||
41 | |||
42 | i2d_PKCS7_bio_stream() was added to OpenSSL 1.0.0 | ||
43 | |||
44 | =cut | ||
diff --git a/src/lib/libcrypto/doc/lh_stats.pod b/src/lib/libcrypto/doc/lh_stats.pod deleted file mode 100644 index 15f97b5545..0000000000 --- a/src/lib/libcrypto/doc/lh_stats.pod +++ /dev/null | |||
@@ -1,60 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio, | ||
6 | lh_node_stats_bio, lh_node_usage_stats_bio - LHASH statistics | ||
7 | |||
8 | =head1 SYNOPSIS | ||
9 | |||
10 | #include <openssl/lhash.h> | ||
11 | |||
12 | void lh_stats(LHASH *table, FILE *out); | ||
13 | void lh_node_stats(LHASH *table, FILE *out); | ||
14 | void lh_node_usage_stats(LHASH *table, FILE *out); | ||
15 | |||
16 | void lh_stats_bio(LHASH *table, BIO *out); | ||
17 | void lh_node_stats_bio(LHASH *table, BIO *out); | ||
18 | void lh_node_usage_stats_bio(LHASH *table, BIO *out); | ||
19 | |||
20 | =head1 DESCRIPTION | ||
21 | |||
22 | The B<LHASH> structure records statistics about most aspects of | ||
23 | accessing the hash table. This is mostly a legacy of Eric Young | ||
24 | writing this library for the reasons of implementing what looked like | ||
25 | a nice algorithm rather than for a particular software product. | ||
26 | |||
27 | lh_stats() prints out statistics on the size of the hash table, how | ||
28 | many entries are in it, and the number and result of calls to the | ||
29 | routines in this library. | ||
30 | |||
31 | lh_node_stats() prints the number of entries for each 'bucket' in the | ||
32 | hash table. | ||
33 | |||
34 | lh_node_usage_stats() prints out a short summary of the state of the | ||
35 | hash table. It prints the 'load' and the 'actual load'. The load is | ||
36 | the average number of data items per 'bucket' in the hash table. The | ||
37 | 'actual load' is the average number of items per 'bucket', but only | ||
38 | for buckets which contain entries. So the 'actual load' is the | ||
39 | average number of searches that will need to find an item in the hash | ||
40 | table, while the 'load' is the average number that will be done to | ||
41 | record a miss. | ||
42 | |||
43 | lh_stats_bio(), lh_node_stats_bio() and lh_node_usage_stats_bio() | ||
44 | are the same as the above, except that the output goes to a B<BIO>. | ||
45 | |||
46 | =head1 RETURN VALUES | ||
47 | |||
48 | These functions do not return values. | ||
49 | |||
50 | =head1 SEE ALSO | ||
51 | |||
52 | L<bio(3)|bio(3)>, L<lh_new(3)|lh_new(3)> | ||
53 | |||
54 | =head1 HISTORY | ||
55 | |||
56 | These functions are available in all versions of SSLeay and OpenSSL. | ||
57 | |||
58 | This manpage is derived from the SSLeay documentation. | ||
59 | |||
60 | =cut | ||
diff --git a/src/lib/libcrypto/doc/rsa.pod b/src/lib/libcrypto/doc/rsa.pod deleted file mode 100644 index 829ce24701..0000000000 --- a/src/lib/libcrypto/doc/rsa.pod +++ /dev/null | |||
@@ -1,123 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | rsa - RSA public key cryptosystem | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/rsa.h> | ||
10 | #include <openssl/engine.h> | ||
11 | |||
12 | RSA * RSA_new(void); | ||
13 | void RSA_free(RSA *rsa); | ||
14 | |||
15 | int RSA_public_encrypt(int flen, unsigned char *from, | ||
16 | unsigned char *to, RSA *rsa, int padding); | ||
17 | int RSA_private_decrypt(int flen, unsigned char *from, | ||
18 | unsigned char *to, RSA *rsa, int padding); | ||
19 | int RSA_private_encrypt(int flen, unsigned char *from, | ||
20 | unsigned char *to, RSA *rsa,int padding); | ||
21 | int RSA_public_decrypt(int flen, unsigned char *from, | ||
22 | unsigned char *to, RSA *rsa,int padding); | ||
23 | |||
24 | int RSA_sign(int type, unsigned char *m, unsigned int m_len, | ||
25 | unsigned char *sigret, unsigned int *siglen, RSA *rsa); | ||
26 | int RSA_verify(int type, unsigned char *m, unsigned int m_len, | ||
27 | unsigned char *sigbuf, unsigned int siglen, RSA *rsa); | ||
28 | |||
29 | int RSA_size(const RSA *rsa); | ||
30 | |||
31 | RSA *RSA_generate_key(int num, unsigned long e, | ||
32 | void (*callback)(int,int,void *), void *cb_arg); | ||
33 | |||
34 | int RSA_check_key(RSA *rsa); | ||
35 | |||
36 | int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); | ||
37 | void RSA_blinding_off(RSA *rsa); | ||
38 | |||
39 | void RSA_set_default_method(const RSA_METHOD *meth); | ||
40 | const RSA_METHOD *RSA_get_default_method(void); | ||
41 | int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); | ||
42 | const RSA_METHOD *RSA_get_method(const RSA *rsa); | ||
43 | RSA_METHOD *RSA_PKCS1_SSLeay(void); | ||
44 | RSA_METHOD *RSA_null_method(void); | ||
45 | int RSA_flags(const RSA *rsa); | ||
46 | RSA *RSA_new_method(ENGINE *engine); | ||
47 | |||
48 | int RSA_print(BIO *bp, RSA *x, int offset); | ||
49 | int RSA_print_fp(FILE *fp, RSA *x, int offset); | ||
50 | |||
51 | int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), | ||
52 | int (*dup_func)(), void (*free_func)()); | ||
53 | int RSA_set_ex_data(RSA *r,int idx,char *arg); | ||
54 | char *RSA_get_ex_data(RSA *r, int idx); | ||
55 | |||
56 | int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, | ||
57 | unsigned int m_len, unsigned char *sigret, unsigned int *siglen, | ||
58 | RSA *rsa); | ||
59 | int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, | ||
60 | unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, | ||
61 | RSA *rsa); | ||
62 | |||
63 | =head1 DESCRIPTION | ||
64 | |||
65 | These functions implement RSA public key encryption and signatures | ||
66 | as defined in PKCS #1 v2.0 [RFC 2437]. | ||
67 | |||
68 | The B<RSA> structure consists of several BIGNUM components. It can | ||
69 | contain public as well as private RSA keys: | ||
70 | |||
71 | struct | ||
72 | { | ||
73 | BIGNUM *n; // public modulus | ||
74 | BIGNUM *e; // public exponent | ||
75 | BIGNUM *d; // private exponent | ||
76 | BIGNUM *p; // secret prime factor | ||
77 | BIGNUM *q; // secret prime factor | ||
78 | BIGNUM *dmp1; // d mod (p-1) | ||
79 | BIGNUM *dmq1; // d mod (q-1) | ||
80 | BIGNUM *iqmp; // q^-1 mod p | ||
81 | // ... | ||
82 | }; | ||
83 | RSA | ||
84 | |||
85 | In public keys, the private exponent and the related secret values are | ||
86 | B<NULL>. | ||
87 | |||
88 | B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private | ||
89 | keys, but the RSA operations are much faster when these values are | ||
90 | available. | ||
91 | |||
92 | Note that RSA keys may use non-standard B<RSA_METHOD> implementations, | ||
93 | either directly or by the use of B<ENGINE> modules. In some cases (eg. an | ||
94 | ENGINE providing support for hardware-embedded keys), these BIGNUM values | ||
95 | will not be used by the implementation or may be used for alternative data | ||
96 | storage. For this reason, applications should generally avoid using RSA | ||
97 | structure elements directly and instead use API functions to query or | ||
98 | modify keys. | ||
99 | |||
100 | =head1 CONFORMING TO | ||
101 | |||
102 | SSL, PKCS #1 v2.0 | ||
103 | |||
104 | =head1 PATENTS | ||
105 | |||
106 | RSA was covered by a US patent which expired in September 2000. | ||
107 | |||
108 | =head1 SEE ALSO | ||
109 | |||
110 | L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, | ||
111 | L<rand(3)|rand(3)>, L<engine(3)|engine(3)>, L<RSA_new(3)|RSA_new(3)>, | ||
112 | L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, | ||
113 | L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>, | ||
114 | L<RSA_generate_key(3)|RSA_generate_key(3)>, | ||
115 | L<RSA_check_key(3)|RSA_check_key(3)>, | ||
116 | L<RSA_blinding_on(3)|RSA_blinding_on(3)>, | ||
117 | L<RSA_set_method(3)|RSA_set_method(3)>, L<RSA_print(3)|RSA_print(3)>, | ||
118 | L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, | ||
119 | L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, | ||
120 | L<RSA_sign_ASN1_OCTET_STRING(3)|RSA_sign_ASN1_OCTET_STRING(3)>, | ||
121 | L<RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)> | ||
122 | |||
123 | =cut | ||
diff --git a/src/lib/libcrypto/doc/x509.pod b/src/lib/libcrypto/doc/x509.pod deleted file mode 100644 index f9e58e0e41..0000000000 --- a/src/lib/libcrypto/doc/x509.pod +++ /dev/null | |||
@@ -1,64 +0,0 @@ | |||
1 | =pod | ||
2 | |||
3 | =head1 NAME | ||
4 | |||
5 | x509 - X.509 certificate handling | ||
6 | |||
7 | =head1 SYNOPSIS | ||
8 | |||
9 | #include <openssl/x509.h> | ||
10 | |||
11 | =head1 DESCRIPTION | ||
12 | |||
13 | A X.509 certificate is a structured grouping of information about | ||
14 | an individual, a device, or anything one can imagine. A X.509 CRL | ||
15 | (certificate revocation list) is a tool to help determine if a | ||
16 | certificate is still valid. The exact definition of those can be | ||
17 | found in the X.509 document from ITU-T, or in RFC3280 from PKIX. | ||
18 | In OpenSSL, the type X509 is used to express such a certificate, and | ||
19 | the type X509_CRL is used to express a CRL. | ||
20 | |||
21 | A related structure is a certificate request, defined in PKCS#10 from | ||
22 | RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type | ||
23 | X509_REQ is used to express such a certificate request. | ||
24 | |||
25 | To handle some complex parts of a certificate, there are the types | ||
26 | X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express | ||
27 | a certificate attributes), X509_EXTENSION (to express a certificate | ||
28 | extension) and a few more. | ||
29 | |||
30 | Finally, there's the supertype X509_INFO, which can contain a CRL, a | ||
31 | certificate and a corresponding private key. | ||
32 | |||
33 | B<X509_>I<...>, B<d2i_X509_>I<...> and B<i2d_X509_>I<...> handle X.509 | ||
34 | certificates, with some exceptions, shown below. | ||
35 | |||
36 | B<X509_CRL_>I<...>, B<d2i_X509_CRL_>I<...> and B<i2d_X509_CRL_>I<...> | ||
37 | handle X.509 CRLs. | ||
38 | |||
39 | B<X509_REQ_>I<...>, B<d2i_X509_REQ_>I<...> and B<i2d_X509_REQ_>I<...> | ||
40 | handle PKCS#10 certificate requests. | ||
41 | |||
42 | B<X509_NAME_>I<...> handle certificate names. | ||
43 | |||
44 | B<X509_ATTRIBUTE_>I<...> handle certificate attributes. | ||
45 | |||
46 | B<X509_EXTENSION_>I<...> handle certificate extensions. | ||
47 | |||
48 | =head1 SEE ALSO | ||
49 | |||
50 | L<X509_NAME_ENTRY_get_object(3)|X509_NAME_ENTRY_get_object(3)>, | ||
51 | L<X509_NAME_add_entry_by_txt(3)|X509_NAME_add_entry_by_txt(3)>, | ||
52 | L<X509_NAME_add_entry_by_NID(3)|X509_NAME_add_entry_by_NID(3)>, | ||
53 | L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>, | ||
54 | L<X509_NAME_new(3)|X509_NAME_new(3)>, | ||
55 | L<d2i_X509(3)|d2i_X509(3)>, | ||
56 | L<d2i_X509_ALGOR(3)|d2i_X509_ALGOR(3)>, | ||
57 | L<d2i_X509_CRL(3)|d2i_X509_CRL(3)>, | ||
58 | L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>, | ||
59 | L<d2i_X509_REQ(3)|d2i_X509_REQ(3)>, | ||
60 | L<d2i_X509_SIG(3)|d2i_X509_SIG(3)>, | ||
61 | L<crypto(3)|crypto(3)>, | ||
62 | L<x509v3(3)|x509v3(3)> | ||
63 | |||
64 | =cut | ||