diff options
Diffstat (limited to 'src/lib/libcrypto/doc')
| -rw-r--r-- | src/lib/libcrypto/doc/DES_set_key.pod | 339 | ||||
| -rw-r--r-- | src/lib/libcrypto/doc/DH_generate_key.pod | 51 | ||||
| -rw-r--r-- | src/lib/libcrypto/doc/DH_generate_parameters.pod | 80 | ||||
| -rw-r--r-- | src/lib/libcrypto/doc/DH_get_ex_new_index.pod | 37 | ||||
| -rw-r--r-- | src/lib/libcrypto/doc/DH_new.pod | 38 | ||||
| -rw-r--r-- | src/lib/libcrypto/doc/DH_set_method.pod | 129 | ||||
| -rw-r--r-- | src/lib/libcrypto/doc/DH_size.pod | 33 |
7 files changed, 0 insertions, 707 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 | ||
