From b50ac7faef96a45291b0c3201b82185f7579e826 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 2 Nov 2016 09:11:53 +0000 Subject: convert DES and DH manuals from pod to mdoc --- src/lib/libcrypto/doc/DES_set_key.pod | 339 ----------- src/lib/libcrypto/doc/DH_generate_key.pod | 51 -- src/lib/libcrypto/doc/DH_generate_parameters.pod | 80 --- src/lib/libcrypto/doc/DH_get_ex_new_index.pod | 37 -- src/lib/libcrypto/doc/DH_new.pod | 38 -- src/lib/libcrypto/doc/DH_set_method.pod | 129 ----- src/lib/libcrypto/doc/DH_size.pod | 33 -- src/lib/libcrypto/man/DES_set_key.3 | 697 +++++++++++++++++++++++ src/lib/libcrypto/man/DH_generate_key.3 | 71 +++ src/lib/libcrypto/man/DH_generate_parameters.3 | 125 ++++ src/lib/libcrypto/man/DH_get_ex_new_index.3 | 47 ++ src/lib/libcrypto/man/DH_new.3 | 44 ++ src/lib/libcrypto/man/DH_set_method.3 | 223 ++++++++ src/lib/libcrypto/man/DH_size.3 | 29 + src/lib/libcrypto/man/Makefile | 16 +- 15 files changed, 1244 insertions(+), 715 deletions(-) delete mode 100644 src/lib/libcrypto/doc/DES_set_key.pod delete mode 100644 src/lib/libcrypto/doc/DH_generate_key.pod delete mode 100644 src/lib/libcrypto/doc/DH_generate_parameters.pod delete mode 100644 src/lib/libcrypto/doc/DH_get_ex_new_index.pod delete mode 100644 src/lib/libcrypto/doc/DH_new.pod delete mode 100644 src/lib/libcrypto/doc/DH_set_method.pod delete mode 100644 src/lib/libcrypto/doc/DH_size.pod create mode 100644 src/lib/libcrypto/man/DES_set_key.3 create mode 100644 src/lib/libcrypto/man/DH_generate_key.3 create mode 100644 src/lib/libcrypto/man/DH_generate_parameters.3 create mode 100644 src/lib/libcrypto/man/DH_get_ex_new_index.3 create mode 100644 src/lib/libcrypto/man/DH_new.3 create mode 100644 src/lib/libcrypto/man/DH_set_method.3 create mode 100644 src/lib/libcrypto/man/DH_size.3 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 @@ -=pod - -=head1 NAME - -DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked, -DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key, -DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt, -DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt, -DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, -DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, -DES_ede3_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, -DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, -DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption - -=head1 SYNOPSIS - - #include - - void DES_random_key(DES_cblock *ret); - - int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule); - int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule); - int DES_set_key_checked(const_DES_cblock *key, - DES_key_schedule *schedule); - void DES_set_key_unchecked(const_DES_cblock *key, - DES_key_schedule *schedule); - - void DES_set_odd_parity(DES_cblock *key); - int DES_is_weak_key(const_DES_cblock *key); - - void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output, - DES_key_schedule *ks, int enc); - void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output, - DES_key_schedule *ks1, DES_key_schedule *ks2, int enc); - void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output, - DES_key_schedule *ks1, DES_key_schedule *ks2, - DES_key_schedule *ks3, int enc); - - void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output, - long length, DES_key_schedule *schedule, DES_cblock *ivec, - int enc); - void DES_cfb_encrypt(const unsigned char *in, unsigned char *out, - int numbits, long length, DES_key_schedule *schedule, - DES_cblock *ivec, int enc); - void DES_ofb_encrypt(const unsigned char *in, unsigned char *out, - int numbits, long length, DES_key_schedule *schedule, - DES_cblock *ivec); - void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output, - long length, DES_key_schedule *schedule, DES_cblock *ivec, - int enc); - void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *schedule, DES_cblock *ivec, - int *num, int enc); - void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *schedule, DES_cblock *ivec, - int *num); - - void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output, - long length, DES_key_schedule *schedule, DES_cblock *ivec, - const_DES_cblock *inw, const_DES_cblock *outw, int enc); - - void DES_ede2_cbc_encrypt(const unsigned char *input, - unsigned char *output, long length, DES_key_schedule *ks1, - DES_key_schedule *ks2, DES_cblock *ivec, int enc); - void DES_ede2_cfb64_encrypt(const unsigned char *in, - unsigned char *out, long length, DES_key_schedule *ks1, - DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc); - void DES_ede2_ofb64_encrypt(const unsigned char *in, - unsigned char *out, long length, DES_key_schedule *ks1, - DES_key_schedule *ks2, DES_cblock *ivec, int *num); - - void DES_ede3_cbc_encrypt(const unsigned char *input, - unsigned char *output, long length, DES_key_schedule *ks1, - DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec, - int enc); - void DES_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *ks1, DES_key_schedule *ks2, - DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2, - int enc); - void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *ks1, DES_key_schedule *ks2, - DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc); - void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *ks1, - DES_key_schedule *ks2, DES_key_schedule *ks3, - DES_cblock *ivec, int *num); - - DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output, - long length, DES_key_schedule *schedule, - const_DES_cblock *ivec); - DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[], - long length, int out_count, DES_cblock *seed); - void DES_string_to_key(const char *str, DES_cblock *key); - void DES_string_to_2keys(const char *str, DES_cblock *key1, - DES_cblock *key2); - - char *DES_fcrypt(const char *buf, const char *salt, char *ret); - char *DES_crypt(const char *buf, const char *salt); - - int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched, - DES_cblock *iv); - int DES_enc_write(int fd, const void *buf, int len, - DES_key_schedule *sched, DES_cblock *iv); - -=head1 DESCRIPTION - -This library contains a fast implementation of the DES encryption -algorithm. - -There are two phases to the use of DES encryption. The first is the -generation of a I from a key, the second is the -actual encryption. A DES key is of type I. This type is -consists of 8 bytes with odd parity. The least significant bit in -each byte is the parity bit. The key schedule is an expanded form of -the key; it is used to speed the encryption process. - -DES_random_key() generates a random key in odd parity. - -Before a DES key can be used, it must be converted into the -architecture dependent I via the -DES_set_key_checked() or DES_set_key_unchecked() function. - -DES_set_key_checked() will check that the key passed is of odd parity -and is not a week or semi-weak key. If the parity is wrong, then -1 -is returned. If the key is a weak key, then -2 is returned. If an -error is returned, the key schedule is not generated. - -DES_set_key() works like -DES_set_key_checked() if the I flag is non-zero, -otherwise like DES_set_key_unchecked(). These functions are available -for compatibility; it is recommended to use a function that does not -depend on a global variable. - -DES_set_odd_parity() sets the parity of the passed I to odd. - -DES_is_weak_key() returns 1 is the passed key is a weak key, 0 if it -is ok. - -The following routines mostly operate on an input and output stream of -Is. - -DES_ecb_encrypt() is the basic DES encryption routine that encrypts or -decrypts a single 8-byte I in I -(ECB) mode. It always transforms the input data, pointed to by -I, into the output data, pointed to by the I argument. -If the I argument is non-zero (DES_ENCRYPT), the I -(cleartext) is encrypted in to the I (ciphertext) using the -key_schedule specified by the I argument, previously set via -I. If I is zero (DES_DECRYPT), the I (now -ciphertext) is decrypted into the I (now cleartext). Input -and output may overlap. DES_ecb_encrypt() does not return a value. - -DES_ecb3_encrypt() encrypts/decrypts the I block by using -three-key Triple-DES encryption in ECB mode. This involves encrypting -the input with I, decrypting with the key schedule I, and -then encrypting with I. This routine greatly reduces the chances -of brute force breaking of DES and has the advantage of if I, -I and I are the same, it is equivalent to just encryption -using ECB mode and I as the key. - -The macro DES_ecb2_encrypt() is provided to perform two-key Triple-DES -encryption by using I for the final encryption. - -DES_ncbc_encrypt() encrypts/decrypts using the I -(CBC) mode of DES. If the I argument is non-zero, the -routine cipher-block-chain encrypts the cleartext data pointed to by -the I argument into the ciphertext pointed to by the I -argument, using the key schedule provided by the I argument, -and initialization vector provided by the I argument. If the -I argument is not an integral multiple of eight bytes, the -last block is copied to a temporary area and zero filled. The output -is always an integral multiple of eight bytes. - -DES_xcbc_encrypt() is RSA's DESX mode of DES. It uses I and -I to 'whiten' the encryption. I and I are secret -(unlike the iv) and are as such, part of the key. So the key is sort -of 24 bytes. This is much better than CBC DES. - -DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with -three keys. This means that each DES operation inside the CBC mode is -really an C. This mode is used by SSL. - -The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by -reusing I for the final encryption. C. -This form of Triple-DES is used by the RSAREF library. - -DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block -chaining mode used by Kerberos v4. Its parameters are the same as -DES_ncbc_encrypt(). - -DES_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This -method takes an array of characters as input and outputs and array of -characters. It does not require any padding to 8 character groups. -Note: the I variable is changed and the new changed value needs to -be passed to the next call to this function. Since this function runs -a complete DES ECB encryption per I, this function is only -suggested for use when sending small numbers of characters. - -DES_cfb64_encrypt() -implements CFB mode of DES with 64bit feedback. Why is this -useful you ask? Because this routine will allow you to encrypt an -arbitrary number of bytes, no 8 byte padding. Each call to this -routine will encrypt the input bytes to output and then update ivec -and num. num contains 'how far' we are though ivec. If this does -not make much sense, read more about cfb mode of DES :-). - -DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as -DES_cfb64_encrypt() except that Triple-DES is used. - -DES_ofb_encrypt() encrypts using output feedback mode. This method -takes an array of characters as input and outputs and array of -characters. It does not require any padding to 8 character groups. -Note: the I variable is changed and the new changed value needs to -be passed to the next call to this function. Since this function runs -a complete DES ECB encryption per numbits, this function is only -suggested for use when sending small numbers of characters. - -DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output -Feed Back mode. - -DES_ede3_ofb64_encrypt() and DES_ede2_ofb64_encrypt() is the same as -DES_ofb64_encrypt(), using Triple-DES. - -The following functions are included in the DES library for -compatibility with the MIT Kerberos library. - -DES_cbc_cksum() produces an 8 byte checksum based on the input stream -(via CBC encryption). The last 4 bytes of the checksum are returned -and the complete 8 bytes are placed in I. This function is -used by Kerberos v4. Other applications should use -L etc. instead. - -DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte -checksum from the input bytes. The algorithm can be iterated over the -input, depending on I, 1, 2, 3 or 4 times. If I is -non-NULL, the 8 bytes generated by each pass are written into -I. - -The following are DES-based transformations: - -DES_fcrypt() is a fast version of the Unix crypt(3) function. This -version takes only a small amount of space relative to other fast -crypt() implementations. This is different to the normal crypt in -that the third parameter is the buffer that the return value is -written into. It needs to be at least 14 bytes long. This function -is thread safe, unlike the normal crypt. - -DES_crypt() is a faster replacement for the normal system crypt(). -This function calls DES_fcrypt() with a static array passed as the -third parameter. This emulates the normal non-thread safe semantics -of crypt(3). - -DES_enc_write() writes I bytes to file descriptor I from -buffer I. The data is encrypted via I (default) -using I for the key and I as a starting vector. The actual -data send down I consists of 4 bytes (in network byte order) -containing the length of the following encrypted data. The encrypted -data then follows, padded with random data out to a multiple of 8 -bytes. - -DES_enc_read() is used to read I bytes from file descriptor -I into buffer I. The data being read from I is assumed to -have come from DES_enc_write() and is decrypted using I for -the key schedule and I for the initial vector. - -B The data format used by DES_enc_write() and DES_enc_read() -has a cryptographic weakness: When asked to write more than MAXWRITE -bytes, DES_enc_write() will split the data into several chunks that -are all encrypted using the same IV. So don't use these functions -unless you are sure you know what you do (in which case you might not -want to use them anyway). They cannot handle non-blocking sockets. -DES_enc_read() uses an internal state and thus cannot be used on -multiple files. - -I is used to specify the encryption mode to use with -DES_enc_read() and DES_end_write(). If set to I (the -default), DES_pcbc_encrypt is used. If set to I -DES_cbc_encrypt is used. - -=head1 NOTES - -Single-key DES is insecure due to its short key size. ECB mode is -not suitable for most applications. - -The L library provides higher-level encryption functions. - -=head1 BUGS - -DES_cbc_encrypt() does not modify B; use DES_ncbc_encrypt() -instead. - -DES_cfb_encrypt() and DES_ofb_encrypt() operates on input of 8 bits. -What this means is that if you set numbits to 12, and length to 2, the -first 12 bits will come from the 1st input byte and the low half of -the second input byte. The second 12 bits will have the low 8 bits -taken from the 3rd input byte and the top 4 bits taken from the 4th -input byte. The same holds for output. This function has been -implemented this way because most people will be using a multiple of 8 -and because once you get into pulling bytes input bytes apart things -get ugly! - -DES_string_to_key() is available for backward compatibility with the -MIT library. New applications should use a cryptographic hash function. -The same applies for DES_string_to_2key(). - -=head1 CONFORMING TO - -ANSI X3.106 - -The B library was initially written to be source code compatible with -the MIT Kerberos library. - -=head1 SEE ALSO - -crypt(3), L, L - -=head1 HISTORY - -In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid -clashes with older versions of libdes. - -DES_set_key_checked() and DES_set_key_unchecked() were added in -OpenSSL 0.9.5. - -des_generate_random_block(), des_init_random_number_generator(), -des_new_random_key(), des_set_random_generator_seed() and -des_set_sequence_number() and des_rand_data() are used in newer -versions of Kerberos but are not implemented here. - -DES_random_key() generated cryptographically weak random data in -SSLeay and in OpenSSL prior version 0.9.5, as well as in the original -MIT library. - -=head1 AUTHOR - -Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project -(http://www.openssl.org). - -=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 @@ -=pod - -=head1 NAME - -DH_generate_key, DH_compute_key - perform Diffie-Hellman key exchange - -=head1 SYNOPSIS - - #include - - int DH_generate_key(DH *dh); - - int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); - -=head1 DESCRIPTION - -DH_generate_key() performs the first step of a Diffie-Hellman key -exchange by generating private and public DH values. By calling -DH_compute_key(), these are combined with the other party's public -value to compute the shared key. - -DH_generate_key() expects B to contain the shared parameters -Bp> and Bg>. It generates a random private DH value -unless Bpriv_key> is already set, and computes the -corresponding public value Bpub_key>, which can then be -published. - -DH_compute_key() computes the shared secret from the private DH value -in B and the other party's public value in B and stores -it in B. B must point to B bytes of memory. - -=head1 RETURN VALUES - -DH_generate_key() returns 1 on success, 0 otherwise. - -DH_compute_key() returns the size of the shared secret on success, -1 -on error. - -The error codes can be obtained by L. - -=head1 SEE ALSO - -L, L, L, -L - -=head1 HISTORY - -DH_generate_key() and DH_compute_key() are available in all versions -of SSLeay and OpenSSL. - -=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 @@ -=pod - -=head1 NAME - -DH_generate_parameters_ex, DH_generate_parameters, -DH_check - generate and check Diffie-Hellman parameters - -=head1 SYNOPSIS - - #include - - int DH_generate_parameters_ex(DH *dh, int prime_len,int generator, BN_GENCB *cb); - - int DH_check(DH *dh, int *codes); - -Deprecated: - - DH *DH_generate_parameters(int prime_len, int generator, - void (*callback)(int, int, void *), void *cb_arg); - -=head1 DESCRIPTION - -DH_generate_parameters_ex() generates Diffie-Hellman parameters that can -be shared among a group of users, and stores them in the provided B -structure. - -B is the length in bits of the safe prime to be generated. -B is a small number E 1, typically 2 or 5. - -A callback function may be used to provide feedback about the progress -of the key generation. If B is not B, it will be -called as described in L while a random prime number is -generated, and when a prime has been found, B is -called. See L for information on -the BN_GENCB_call() function. - -DH_check() validates Diffie-Hellman parameters. It checks that B

is -a safe prime, and that B is a suitable generator. In the case of an -error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or -DH_NOT_SUITABLE_GENERATOR are set in B<*codes>. -DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be -checked, i.e. it does not equal 2 or 5. - -=head1 RETURN VALUES - -DH_generate_parameters_ex() and DH_check() return 1 if the check could be -performed, 0 otherwise. - -DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or -NULL if the parameter generation fails. - -The error codes can be obtained by L. - -=head1 NOTES - -DH_generate_parameters_ex() and DH_generate_parameters() may run for several -hours before finding a suitable prime. - -The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters() -are not to be used in signature schemes. - -=head1 BUGS - -If B is not 2 or 5, Bg>=B is not -a usable generator. - -=head1 SEE ALSO - -L, L, L, -L - -=head1 HISTORY - -DH_check() is available in all versions of SSLeay and OpenSSL. -The B argument to DH_generate_parameters() was added in SSLeay 0.9.0. - -In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used -instead of DH_CHECK_P_NOT_SAFE_PRIME. - -=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 @@ -=pod - -=head1 NAME - -DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific -data to DH structures - -=head1 SYNOPSIS - - #include - - int DH_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DH_set_ex_data(DH *d, int idx, void *arg); - - char *DH_get_ex_data(DH *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DH -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are -available since OpenSSL 0.9.5. - -=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 @@ -=pod - -=head1 NAME - -DH_new, DH_free - allocate and free DH objects - -=head1 SYNOPSIS - - #include - - DH* DH_new(void); - - void DH_free(DH *dh); - -=head1 DESCRIPTION - -DH_new() allocates and initializes a B structure. - -DH_free() frees the B structure and its components. The values are -erased before the memory is returned to the system. - -=head1 RETURN VALUES - -If the allocation fails, DH_new() returns B and sets an error code that -can be obtained by L. Otherwise it returns a -pointer to the newly allocated structure. - -=head1 SEE ALSO - -L, L, -L, -L - -=head1 HISTORY - -DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL. - -=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 @@ -=pod - -=head1 NAME - -DH_set_default_method, DH_get_default_method, -DH_set_method, DH_new_method, DH_OpenSSL, -DH_set_default_openssl_method, DH_get_default_openssl_method -- select DH method - -=head1 SYNOPSIS - - #include - #include - - void DH_set_default_method(const DH_METHOD *meth); - - const DH_METHOD *DH_get_default_method(void); - - int DH_set_method(DH *dh, const DH_METHOD *meth); - - DH *DH_new_method(ENGINE *engine); - - const DH_METHOD *DH_OpenSSL(void); - -=head1 DESCRIPTION - -A B specifies the functions that OpenSSL uses for Diffie-Hellman -operations. By modifying the method, alternative implementations -such as hardware accelerators may be used. IMPORTANT: See the NOTES section for -important information about how these DH API functions are affected by the use -of B API calls. - -Initially, the default DH_METHOD is the OpenSSL internal implementation, as -returned by DH_OpenSSL(). - -DH_set_default_method() makes B the default method for all DH -structures created later. B: This is true only whilst no ENGINE has been set -as a default for DH, so this function is no longer recommended. - -DH_get_default_method() returns a pointer to the current default DH_METHOD. -However, the meaningfulness of this result is dependent on whether the ENGINE -API is being used, so this function is no longer recommended. - -DH_set_method() selects B to perform all operations using the key B. -This will replace the DH_METHOD used by the DH key and if the previous method -was supplied by an ENGINE, the handle to that ENGINE will be released during the -change. It is possible to have DH keys that only work with certain DH_METHOD -implementations (eg. from an ENGINE module that supports embedded -hardware-protected keys), and in such cases attempting to change the DH_METHOD -for the key can have unexpected results. - -DH_new_method() allocates and initializes a DH structure so that B will -be used for the DH operations. If B is NULL, the default ENGINE for DH -operations is used, and if no default ENGINE is set, the DH_METHOD controlled by -DH_set_default_method() is used. - -=head1 THE DH_METHOD STRUCTURE - - typedef struct dh_meth_st - { - /* name of the implementation */ - const char *name; - - /* generate private and public DH values for key agreement */ - int (*generate_key)(DH *dh); - - /* compute shared secret */ - int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, - BN_MONT_CTX *m_ctx); - - /* called at DH_new */ - int (*init)(DH *dh); - - /* called at DH_free */ - int (*finish)(DH *dh); - - int flags; - - char *app_data; /* ?? */ - - } DH_METHOD; - -=head1 RETURN VALUES - -DH_OpenSSL() and DH_get_default_method() return pointers to the respective -Bs. - -DH_set_method() returns non-zero if the provided B was successfully set as -the method for B (including unloading the ENGINE handle if the previous -method was supplied by an ENGINE). - -DH_new_method() returns NULL and sets an error code that can be obtained by -L if the allocation fails. Otherwise it -returns a pointer to the newly allocated structure. - -=head1 NOTES - -As of version 0.9.7, DH_METHOD implementations are grouped together with other -algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B modules. If a -default ENGINE is specified for DH functionality using an ENGINE API function, -that will override any DH defaults set using the DH API (ie. -DH_set_default_method()). For this reason, the ENGINE API is the recommended way -to control default implementations for use in DH and other cryptographic -algorithms. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -DH_set_default_method(), DH_get_default_method(), DH_set_method(), -DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4. - -DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced -DH_set_default_method() and DH_get_default_method() respectively, and -DH_set_method() and DH_new_method() were altered to use Bs rather than -Bs during development of the engine version of OpenSSL 0.9.6. For -0.9.7, the handling of defaults in the ENGINE API was restructured so that this -change was reversed, and behaviour of the other functions resembled more closely -the previous behaviour. The behaviour of defaults in the ENGINE API now -transparently overrides the behaviour of defaults in the DH API without -requiring changing these function prototypes. - -=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 @@ -=pod - -=head1 NAME - -DH_size - get Diffie-Hellman prime size - -=head1 SYNOPSIS - - #include - - int DH_size(DH *dh); - -=head1 DESCRIPTION - -This function returns the Diffie-Hellman size in bytes. It can be used -to determine how much memory must be allocated for the shared secret -computed by DH_compute_key(). - -Bp> must not be B. - -=head1 RETURN VALUE - -The size in bytes. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -DH_size() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/man/DES_set_key.3 b/src/lib/libcrypto/man/DES_set_key.3 new file mode 100644 index 0000000000..9c33bf29e6 --- /dev/null +++ b/src/lib/libcrypto/man/DES_set_key.3 @@ -0,0 +1,697 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DES_SET_KEY 3 +.Os +.Sh NAME +.Nm DES_random_key , +.Nm DES_set_key , +.Nm DES_key_sched , +.Nm DES_set_key_checked , +.Nm DES_set_key_unchecked , +.Nm DES_set_odd_parity , +.Nm DES_is_weak_key , +.Nm DES_ecb_encrypt , +.Nm DES_ecb2_encrypt , +.Nm DES_ecb3_encrypt , +.Nm DES_ncbc_encrypt , +.Nm DES_cfb_encrypt , +.Nm DES_ofb_encrypt , +.Nm DES_pcbc_encrypt , +.Nm DES_cfb64_encrypt , +.Nm DES_ofb64_encrypt , +.Nm DES_xcbc_encrypt , +.Nm DES_ede2_cbc_encrypt , +.Nm DES_ede2_cfb64_encrypt , +.Nm DES_ede2_ofb64_encrypt , +.Nm DES_ede3_cbc_encrypt , +.Nm DES_ede3_cbcm_encrypt , +.Nm DES_ede3_cfb64_encrypt , +.Nm DES_ede3_ofb64_encrypt , +.Nm DES_cbc_cksum , +.Nm DES_quad_cksum , +.Nm DES_string_to_key , +.Nm DES_string_to_2keys , +.Nm DES_fcrypt , +.Nm DES_crypt , +.Nm DES_enc_read , +.Nm DES_enc_write +.Nd DES encryption +.Sh SYNOPSIS +.In openssl/des.h +.Ft void +.Fo DES_random_key +.Fa "DES_cblock *ret" +.Fc +.Ft int +.Fo DES_set_key +.Fa "const_DES_cblock *key" +.Fa "DES_key_schedule *schedule" +.Fc +.Ft int +.Fo DES_key_sched +.Fa "const_DES_cblock *key" +.Fa "DES_key_schedule *schedule" +.Fc +.Ft int +.Fo DES_set_key_checked +.Fa "const_DES_cblock *key" +.Fa "DES_key_schedule *schedule" +.Fc +.Ft void +.Fo DES_set_key_unchecked +.Fa "const_DES_cblock *key" +.Fa "DES_key_schedule *schedule" +.Fc +.Ft void +.Fo DES_set_odd_parity +.Fa "DES_cblock *key" +.Fc +.Ft int +.Fo DES_is_weak_key +.Fa "const_DES_cblock *key" +.Fc +.Ft void +.Fo DES_ecb_encrypt +.Fa "const_DES_cblock *input" +.Fa "DES_cblock *output" +.Fa "DES_key_schedule *ks" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ecb2_encrypt +.Fa "const_DES_cblock *input" +.Fa "DES_cblock *output" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ecb3_encrypt +.Fa "const_DES_cblock *input" +.Fa "DES_cblock *output" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ncbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_cfb_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "int numbits" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ofb_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "int numbits" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fc +.Ft void +.Fo DES_pcbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_cfb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ofb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fc +.Ft void +.Fo DES_xcbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "DES_cblock *ivec" +.Fa "const_DES_cblock *inw" +.Fa "const_DES_cblock *outw" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede2_cbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede2_cfb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede2_ofb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fc +.Ft void +.Fo DES_ede3_cbc_encrypt +.Fa "const unsigned char *input" +.Fa "unsigned char *output" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "DES_cblock *ivec" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede3_cbcm_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "DES_cblock *ivec1" +.Fa "DES_cblock *ivec2" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede3_cfb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fa "int enc" +.Fc +.Ft void +.Fo DES_ede3_ofb64_encrypt +.Fa "const unsigned char *in" +.Fa "unsigned char *out" +.Fa "long length" +.Fa "DES_key_schedule *ks1" +.Fa "DES_key_schedule *ks2" +.Fa "DES_key_schedule *ks3" +.Fa "DES_cblock *ivec" +.Fa "int *num" +.Fc +.Ft DES_LONG +.Fo DES_cbc_cksum +.Fa "const unsigned char *input" +.Fa "DES_cblock *output" +.Fa "long length" +.Fa "DES_key_schedule *schedule" +.Fa "const_DES_cblock *ivec" +.Fc +.Ft DES_LONG +.Fo DES_quad_cksum +.Fa "const unsigned char *input" +.Fa "DES_cblock output[]" +.Fa "long length" +.Fa "int out_count" +.Fa "DES_cblock *seed" +.Fc +.Ft void +.Fo DES_string_to_key +.Fa "const char *str" +.Fa "DES_cblock *key" +.Fc +.Ft void +.Fo DES_string_to_2keys +.Fa "const char *str" +.Fa "DES_cblock *key1" +.Fa "DES_cblock *key2" +.Fc +.Ft char * +.Fo DES_fcrypt +.Fa "const char *buf" +.Fa "const char *salt" +.Fa "char *ret" +.Fc +.Ft char * +.Fo DES_crypt +.Fa "const char *buf" +.Fa "const char *salt" +.Fc +.Ft int +.Fo DES_enc_read +.Fa "int fd" +.Fa "void *buf" +.Fa "int len" +.Fa "DES_key_schedule *sched" +.Fa "DES_cblock *iv" +.Fc +.Ft int +.Fo DES_enc_write +.Fa "int fd" +.Fa "const void *buf" +.Fa "int len" +.Fa "DES_key_schedule *sched" +.Fa "DES_cblock *iv" +.Fc +.Sh DESCRIPTION +This library contains a fast implementation of the DES encryption +algorithm. +.Pp +There are two phases to the use of DES encryption. +The first is the generation of a +.Vt DES_key_schedule +from a key, the second is the actual encryption. +A DES key is of type +.Vt DES_cblock . +This type is consists of 8 bytes with odd parity. +The least significant bit in each byte is the parity bit. +The key schedule is an expanded form of the key; it is used to speed the +encryption process. +.Pp +.Fn DES_random_key +generates a random key in odd parity. +.Pp +Before a DES key can be used, it must be converted into the architecture +dependent +.Vt DES_key_schedule +via the +.Fn DES_set_key_checked +or +.Fn DES_set_key_unchecked +function. +.Pp +.Fn DES_set_key_checked +will check that the key passed is of odd parity and is not a week or +semi-weak key. +If the parity is wrong, then -1 is returned. +If the key is a weak key, then -2 is returned. +If an error is returned, the key schedule is not generated. +.Pp +.Fn DES_set_key +works like +.Fn DES_set_key_checked +if the +.Em DES_check_key +flag is non-zero, otherwise like +.Fn DES_set_key_unchecked . +These functions are available for compatibility; it is recommended to +use a function that does not depend on a global variable. +.Pp +.Fn DES_set_odd_parity +sets the parity of the passed +.Fa key +to odd. +.Pp +.Fn DES_is_weak_key +returns 1 is the passed key is a weak key, 0 if it is ok. +.Pp +The following routines mostly operate on an input and output stream of +.Vt DES_cblock Ns s. +.Pp +.Fn DES_ecb_encrypt +is the basic DES encryption routine that encrypts or decrypts a single +8-byte +.Vt DES_cblock +in electronic code book (ECB) mode. +It always transforms the input data, pointed to by +.Fa input , +into the output data, pointed to by the +.Fa output +argument. +If the +.Fa enc +argument is non-zero +.Pq Dv DES_ENCRYPT , +the +.Fa input +(cleartext) is encrypted in to the +.Fa output +(ciphertext) using the key_schedule specified by the +.Fa schedule +argument, previously set via +.Fn DES_set_key . +If +.Fa enc +is zero +.Pq Dv DES_DECRYPT , +the +.Fa input +(now ciphertext) is decrypted into the +.Fa output +(now cleartext). +Input and output may overlap. +.Fn DES_ecb_encrypt +does not return a value. +.Pp +.Fn DES_ecb3_encrypt +encrypts/decrypts the +.Fa input +block by using three-key Triple-DES encryption in ECB mode. +This involves encrypting the input with +.Fa ks1 , +decrypting with the key schedule +.Fa ks2 , +and then encrypting with +.Fa ks3 . +This routine greatly reduces the chances of brute force breaking of DES +and has the advantage of if +.Fa ks1 , +.Fa ks2 , +and +.Fa ks3 +are the same, it is equivalent to just encryption using ECB mode and +.Fa ks1 +as the key. +.Pp +The macro +.Fn DES_ecb2_encrypt +is provided to perform two-key Triple-DES encryption by using +.Fa ks1 +for the final encryption. +.Pp +.Fn DES_ncbc_encrypt +encrypts/decrypts using the cipher-block-chaining (CBC) mode of DES. +If the +.Fa enc +argument is non-zero, the routine cipher-block-chain encrypts the +cleartext data pointed to by the +.Fa input +argument into the ciphertext pointed to by the +.Fa output +argument, using the key schedule provided by the +.Fa schedule +argument, and initialization vector provided by the +.Fa ivec +argument. +If the +.Fa length +argument is not an integral multiple of eight bytes, the last block is +copied to a temporary area and zero filled. +The output is always an integral multiple of eight bytes. +.Pp +.Fn DES_xcbc_encrypt +is RSA's DESX mode of DES. +It uses +.Fa inw +and +.Fa outw +to 'whiten' the encryption. +.Fa inw +and +.Fa outw +are secret (unlike the iv) and are as such, part of the key. +So the key is sort of 24 bytes. +This is much better than CBC DES. +.Pp +.Fn DES_ede3_cbc_encrypt +implements outer triple CBC DES encryption with three keys. +This means that each DES operation inside the CBC mode is really an +.Qq Li C=E(ks3,D(ks2,E(ks1,M))) . +This mode is used by SSL. +.Pp +The +.Fn DES_ede2_cbc_encrypt +macro implements two-key Triple-DES by reusing +.Fa ks1 +for the final encryption. +.Qq Li C=E(ks1,D(ks2,E(ks1,M))) . +This form of Triple-DES is used by the RSAREF library. +.Pp +.Fn DES_pcbc_encrypt +encrypt/decrypts using the propagating cipher block chaining mode used +by Kerberos v4. +Its parameters are the same as +.Fn DES_ncbc_encrypt . +.Pp +.Fn DES_cfb_encrypt +encrypt/decrypts using cipher feedback mode. +This method takes an array of characters as input and outputs and array +of characters. +It does not require any padding to 8 character groups. +Note: the +.Fa ivec +variable is changed and the new changed value needs to be passed to the +next call to this function. +Since this function runs a complete DES ECB encryption per +.Fa numbits , +this function is only suggested for use when sending small numbers of +characters. +.Pp +.Fn DES_cfb64_encrypt +implements CFB mode of DES with 64bit feedback. +Why is this useful you ask? +Because this routine will allow you to encrypt an arbitrary number of +bytes, no 8 byte padding. +Each call to this routine will encrypt the input bytes to output and +then update ivec and num. +num contains 'how far' we are though ivec. +If this does not make much sense, read more about cfb mode of DES :-). +.Pp +.Fn DES_ede3_cfb64_encrypt +and +.Fn DES_ede2_cfb64_encrypt +is the same as +.Fn DES_cfb64_encrypt +except that Triple-DES is used. +.Pp +.Fn DES_ofb_encrypt +encrypts using output feedback mode. +This method takes an array of characters as input and outputs and array +of characters. +It does not require any padding to 8 character groups. +Note: the +.Fa ivec +variable is changed and the new changed value needs to be passed to the +next call to this function. +Since this function runs a complete DES ECB encryption per numbits, this +function is only suggested for use when sending small numbers of +characters. +.Pp +.Fn DES_ofb64_encrypt +is the same as +.Fn DES_cfb64_encrypt +using Output Feed Back mode. +.Pp +.Fn DES_ede3_ofb64_encrypt +and +.Fn DES_ede2_ofb64_encrypt +is the same as +.Fn DES_ofb64_encrypt , +using Triple-DES. +.Pp +The following functions are included in the DES library for +compatibility with the MIT Kerberos library. +.Pp +.Fn DES_cbc_cksum +produces an 8 byte checksum based on the input stream (via CBC +encryption). +The last 4 bytes of the checksum are returned and the complete 8 bytes +are placed in +.Fa output . +This function is used by Kerberos v4. +Other applications should use +.Xr EVP_DigestInit 3 +etc. instead. +.Pp +.Fn DES_quad_cksum +is a Kerberos v4 function. +It returns a 4 byte checksum from the input bytes. +The algorithm can be iterated over the input, depending on +.Fa out_count , +1, 2, 3 or 4 times. +If +.Fa output +is +.Pf non- Dv NULL , +the 8 bytes generated by each pass are written into +.Fa output . +.Pp +The following are DES-based transformations: +.Pp +.Fn DES_fcrypt +is a fast version of the Unix +.Xr crypt 3 +function. +This version takes only a small amount of space relative to other +fast crypt implementations. +This is different to the normal crypt in that the third parameter is the +buffer that the return value is written into. +It needs to be at least 14 bytes long. +This function is thread safe, unlike the normal crypt. +.Pp +.Fn DES_crypt +is a faster replacement for the normal system +.Xr crypt 3 . +This function calls +.Fn DES_fcrypt +with a static array passed as the third parameter. +This emulates the normal non-thread safe semantics of +.Xr crypt 3 . +.Pp +.Fn DES_enc_write +writes +.Fa len +bytes to file descriptor +.Fa fd +from buffer +.Fa buf . +The data is encrypted via +.Em pcbc_encrypt +(default) using +.Fa sched +for the key and +.Fa iv +as a starting vector. +The actual data send down +.Fa fd +consists of 4 bytes (in network byte order) containing the length of the +following encrypted data. +The encrypted data then follows, padded with random data out to a +multiple of 8 bytes. +.Pp +.Fn DES_enc_read +is used to read +.Fa len +bytes from file descriptor +.Fa fd +into buffer +.Fa buf . +The data being read from +.Fa fd +is assumed to have come from +.Fn DES_enc_write +and is decrypted using +.Fa sched +for the key schedule and +.Fa iv +for the initial vector. +.Pp +.Sy Warning: +The data format used by +.Fn DES_enc_write +and +.Fn DES_enc_read +has a cryptographic weakness: When asked to write more than +.Dv MAXWRITE +bytes, +.Fn DES_enc_write +will split the data into several chunks that are all encrypted using the +same IV. +So don't use these functions unless you are sure you know what +you do (in which case you might not want to use them anyway). +They cannot handle non-blocking sockets. +.Fn DES_enc_read +uses an internal state and thus cannot be used on multiple files. +.Pp +.Em DES_rw_mode +is used to specify the encryption mode to use with +.Fn DES_enc_read . +If set to +.Dv DES_PCBC_MODE +(the default), DES_pcbc_encrypt is used. +If set to +.Dv DES_CBC_MODE +DES_cbc_encrypt is used. +.Sh SEE ALSO +.Xr crypt 3 , +.Xr rand 3 +.Pp +The +.Xr evp 3 +library provides higher-level encryption functions. +.Sh STANDARDS +ANSI X3.106 +.Pp +The DES library was initially written to be source code compatible +with the MIT Kerberos library. +.Sh HISTORY +In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid +clashes with older versions of libdes. +.Pp +.Fn DES_set_key_checked +and +.Fn DES_set_key_unchecked +were added in OpenSSL 0.9.5. +.Pp +.Fn des_generate_random_block , +.Fn des_init_random_number_generator , +.Fn des_new_random_key , +.Fn des_set_random_generator_seed , +.Xr des_set_sequence_number , +and +.Fn des_rand_data 3 +are used in newer versions of Kerberos but are not implemented here. +.Pp +.Fn DES_random_key +generated cryptographically weak random data in SSLeay and in OpenSSL +prior version 0.9.5, as well as in the original MIT library. +.Sh AUTHORS +.An Eric Young Aq Mt eay@cryptsoft.com +.Sh CAVEATS +Single-key DES is insecure due to its short key size. +ECB mode is not suitable for most applications. +.Sh BUGS +.Xr DES_cbc_encrypt 3 +does not modify +.Fa ivec ; +use +.Fn DES_ncbc_encrypt +instead. +.Pp +.Fn DES_cfb_encrypt +and +.Fn DES_ofb_encrypt +operates on input of 8 bits. +What this means is that if you set numbits to 12, and length to 2, the +first 12 bits will come from the 1st input byte and the low half of the +second input byte. +The second 12 bits will have the low 8 bits taken from the 3rd input +byte and the top 4 bits taken from the 4th input byte. +The same holds for output. +This function has been implemented this way because most people will be +using a multiple of 8 and because once you get into pulling bytes input +bytes apart things get ugly! +.Pp +.Fn DES_string_to_key +is available for backward compatibility with the MIT library. +New applications should use a cryptographic hash function. +The same applies for +.Fn DES_string_to_2key . diff --git a/src/lib/libcrypto/man/DH_generate_key.3 b/src/lib/libcrypto/man/DH_generate_key.3 new file mode 100644 index 0000000000..6e2edbadb3 --- /dev/null +++ b/src/lib/libcrypto/man/DH_generate_key.3 @@ -0,0 +1,71 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DH_GENERATE_KEY 3 +.Os +.Sh NAME +.Nm DH_generate_key , +.Nm DH_compute_key +.Nd perform Diffie-Hellman key exchange +.Sh SYNOPSIS +.In openssl/dh.h +.Ft int +.Fo DH_generate_key +.Fa "DH *dh" +.Fc +.Ft int +.Fo DH_compute_key +.Fa "unsigned char *key" +.Fa "BIGNUM *pub_key" +.Fa "DH *dh" +.Fc +.Sh DESCRIPTION +.Fn DH_generate_key +performs the first step of a Diffie-Hellman key exchange by generating +private and public DH values. +By calling +.Fn DH_compute_key , +these are combined with the other party's public value to compute the +shared key. +.Pp +.Fn DH_generate_key +expects +.Fa dh +to contain the shared parameters +.Sy dh->p +and +.Sy dh->g . +It generates a random private DH value unless +.Sy dh->priv_key +is already set, and computes the corresponding public value +.Sy dh->pub_key , +which can then be published. +.Pp +.Fn DH_compute_key +computes the shared secret from the private DH value in +.Fa dh +and the other party's public value in +.Fa pub_key +and stores it in +.Fa key . +.Fa key +must point to +.Fn DH_size dh +bytes of memory. +.Sh RETURN VALUES +.Fn DH_generate_key +returns 1 on success, 0 otherwise. +.Pp +.Fn DH_compute_key +returns the size of the shared secret on success, -1 on error. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr dh 3 , +.Xr DH_size 3 , +.Xr ERR_get_error 3 , +.Xr rand 3 +.Sh HISTORY +.Fn DH_generate_key +and +.Fn DH_compute_key +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/DH_generate_parameters.3 b/src/lib/libcrypto/man/DH_generate_parameters.3 new file mode 100644 index 0000000000..431ffd634c --- /dev/null +++ b/src/lib/libcrypto/man/DH_generate_parameters.3 @@ -0,0 +1,125 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DH_GENERATE_PARAMETERS 3 +.Os +.Sh NAME +.Nm DH_generate_parameters_ex , +.Nm DH_generate_parameters , +.Nm DH_check +.Nd generate and check Diffie-Hellman parameters +.Sh SYNOPSIS +.In openssl/dh.h +.Ft int +.Fo DH_generate_parameters_ex +.Fa "DH *dh" +.Fa "int prime_len" +.Fa "int generator" +.Fa "BN_GENCB *cb" +.Fc +.Ft int +.Fo DH_check +.Fa "DH *dh" +.Fa "int *codes" +.Fc +.Pp +Deprecated: +.Pp +.Ft DH * +.Fo DH_generate_parameters +.Fa "int prime_len" +.Fa "int generator" +.Fa "void (*callback)(int" +.Fa int +.Fa "void *)" +.Fa "void *cb_arg" +.Fc +.Sh DESCRIPTION +.Fn DH_generate_parameters_ex +generates Diffie-Hellman parameters that can be shared among a group of +users, and stores them in the provided +.Vt DH +structure. +.Pp +.Fa prime_len +is the length in bits of the safe prime to be generated. +.Fa generator +is a small number > 1, typically 2 or 5. +.Pp +A callback function may be used to provide feedback about the progress +of the key generation. +If +.Fa cb +is not +.Dv NULL , +it will be called as described in +.Xr BN_generate_prime 3 +while a random prime number is generated, and when a prime has been +found, +.Fn BN_GENCB_call cb 3 0 +is called; see +.Xr BN_GENCB_call 3 . +.Pp +.Fn DH_check +validates Diffie-Hellman parameters. +It checks that +.Fa dh->p +is a safe prime, and that +.Fa dh->g +is a suitable generator. +In the case of an error, the bit flags +.Dv DH_CHECK_P_NOT_SAFE_PRIME +or +.Dv DH_NOT_SUITABLE_GENERATOR +are set in +.Pf * Fa codes . +.Dv DH_UNABLE_TO_CHECK_GENERATOR +is set if the generator cannot be checked, i.e. if it does not equal 2 or 5. +.Sh RETURN VALUES +.Fn DH_generate_parameters_ex +and +.Fn DH_check +return 1 if the check could be performed, 0 otherwise. +.Pp +.Fn DH_generate_parameters +(deprecated) returns a pointer to the +.Vt DH +structure, or +.Dv NULL +if the parameter generation fails. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr dh 3 , +.Xr DH_free 3 , +.Xr ERR_get_error 3 , +.Xr rand 3 +.Sh HISTORY +.Fn DH_check +is available in all versions of SSLeay and OpenSSL. +The +.Fa cb_arg +argument to +.Fn DH_generate_parameters +was added in SSLeay 0.9.0. +.Pp +In versions before OpenSSL 0.9.5, +.Dv DH_CHECK_P_NOT_STRONG_PRIME +is used instead of +.Dv DH_CHECK_P_NOT_SAFE_PRIME . +.Sh CAVEATS +.Fn DH_generate_parameters_ex +and +.Fn DH_generate_parameters +may run for several hours before finding a suitable prime. +.Pp +The parameters generated by +.Fn DH_generate_parameters_ex +and +.Fn DH_generate_parameters +are not to be used in signature schemes. +.Sh BUGS +If +.Fa generator +is not 2 or 5, +.Fa dh->g Ns = Ns Fa generator +is not a usable generator. diff --git a/src/lib/libcrypto/man/DH_get_ex_new_index.3 b/src/lib/libcrypto/man/DH_get_ex_new_index.3 new file mode 100644 index 0000000000..c93efa73d6 --- /dev/null +++ b/src/lib/libcrypto/man/DH_get_ex_new_index.3 @@ -0,0 +1,47 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DH_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm DH_get_ex_new_index , +.Nm DH_set_ex_data , +.Nm DH_get_ex_data +.Nd add application specific data to DH structures +.Sh SYNOPSIS +.In openssl/dh.h +.Ft int +.Fo DH_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo DH_set_ex_data +.Fa "DH *d" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft char * +.Fo DH_get_ex_data +.Fa "DH *d" +.Fa "int idx" +.Fc +.Sh DESCRIPTION +These functions handle application specific data in +.Vt DH +structures. +Their usage is identical to that of +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_set_ex_data 3 , +and +.Xr RSA_get_ex_data 3 . +.Sh SEE ALSO +.Xr dh 3 , +.Xr RSA_get_ex_new_index 3 +.Sh HISTORY +.Fn DH_get_ex_new_index , +.Fn DH_set_ex_data , +and +.Fn DH_get_ex_data +are available since OpenSSL 0.9.5. diff --git a/src/lib/libcrypto/man/DH_new.3 b/src/lib/libcrypto/man/DH_new.3 new file mode 100644 index 0000000000..46b1570765 --- /dev/null +++ b/src/lib/libcrypto/man/DH_new.3 @@ -0,0 +1,44 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DH_NEW 3 +.Os +.Sh NAME +.Nm DH_new , +.Nm DH_free +.Nd allocate and free DH objects +.Sh SYNOPSIS +.In openssl/dh.h +.Ft DH* +.Fn DH_new void +.Ft void +.Fo DH_free +.Fa "DH *dh" +.Fc +.Sh DESCRIPTION +.Fn DH_new +allocates and initializes a +.Vt DH +structure. +.Pp +.Fn DH_free +frees the +.Vt DH +structure and its components. +The values are erased before the memory is returned to the system. +.Sh RETURN VALUES +If the allocation fails, +.Fn DH_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr dh 3 , +.Xr DH_generate_key 3 , +.Xr DH_generate_parameters 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn DH_new +and +.Fn DH_free +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/DH_set_method.3 b/src/lib/libcrypto/man/DH_set_method.3 new file mode 100644 index 0000000000..86dae1728c --- /dev/null +++ b/src/lib/libcrypto/man/DH_set_method.3 @@ -0,0 +1,223 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DH_SET_METHOD 3 +.Os +.Sh NAME +.Nm DH_set_default_method , +.Nm DH_get_default_method , +.Nm DH_set_method , +.Nm DH_new_method , +.Nm DH_OpenSSL , +.Nm DH_set_default_openssl_method , +.Nm DH_get_default_openssl_method +.Nd select DH method +.Sh SYNOPSIS +.In openssl/dh.h +.In openssl/engine.h +.Ft void +.Fo DH_set_default_method +.Fa "const DH_METHOD *meth" +.Fc +.Ft const DH_METHOD * +.Fo DH_get_default_method +.Fa void +.Fc +.Ft int +.Fo DH_set_method +.Fa "DH *dh" +.Fa "const DH_METHOD *meth" +.Fc +.Ft DH * +.Fo DH_new_method +.Fa "ENGINE *engine" +.Fc +.Ft const DH_METHOD * +.Fo DH_OpenSSL +.Fa void +.Fc +.Sh DESCRIPTION +A +.Vt DH_METHOD +specifies the functions that OpenSSL uses for Diffie-Hellman operations. +By modifying the method, alternative implementations such as hardware +accelerators may be used. +See the +.Sx CAVEATS +section for how these DH API functions are affected by the use of +.Xr engine 3 +API calls. +.Pp +Initially, the default +.Vt DH_METHOD +is the OpenSSL internal implementation as returned by +.Fn DH_OpenSSL . +.Pp +.Fn DH_set_default_method +makes +.Fa meth +the default method for all +.Vt DH +structures created later. +.Sy NB : +This is true only whilst no +.Vt ENGINE +has been set as a default for DH, so this function is no longer +recommended. +.Pp +.Fn DH_get_default_method +returns a pointer to the current default +.Vt DH_METHOD . +However, the meaningfulness of this result is dependent on whether the +.Xr engine 3 +API is being used, so this function is no longer recommended. +.Pp +.Fn DH_set_method +selects +.Fa meth +to perform all operations using the key +.Fa dh . +This will replace the +.Vt DH_METHOD +used by the +.Fa dh +key and if the previous method was supplied by an +.Vt ENGINE , +the handle to that +.Vt ENGINE +will be released during the change. +It is possible to have +.Vt DH +keys that only work with certain +.Vt DH_METHOD +implementations (eg. from an +.Vt ENGINE +module that supports embedded hardware-protected keys), +and in such cases attempting to change the +.Vt DH_METHOD +for the key can have unexpected results. +.Pp +.Fn DH_new_method +allocates and initializes a +.Vt DH +structure so that +.Fa engine +will be used for the DH operations. +If +.Fa engine +is +.Dv NULL , +the default +.Vt ENGINE +for DH operations is used, and if no default +.Vt ENGINE +is set, the +.Vt DH_METHOD +controlled by +.Fn DH_set_default_method +is used. +.Sh THE DH_METHOD STRUCTURE +.Bd -literal +typedef struct dh_meth_st +{ + /* name of the implementation */ + const char *name; + + /* generate private and public DH values for key agreement */ + int (*generate_key)(DH *dh); + + /* compute shared secret */ + int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); + + /* compute r = a ^ p mod m (May be NULL for some implementations) */ + int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, + BN_MONT_CTX *m_ctx); + + /* called at DH_new */ + int (*init)(DH *dh); + + /* called at DH_free */ + int (*finish)(DH *dh); + + int flags; + + char *app_data; /* ?? */ + +} DH_METHOD; +.Ed +.Sh RETURN VALUES +.Fn DH_OpenSSL +and +.Fn DH_get_default_method +return pointers to the respective +.Sy DH_METHOD Ns s. +.Pp +.Fn DH_set_method +returns non-zero if the provided +.Fa meth +was successfully set as the method for +.Fa dh +(including unloading the +.Vt ENGINE +handle if the previous method was supplied by an +.Vt ENGINE ) . +.Pp +.Fn DH_new_method +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 +if the allocation fails. +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr dh 3 , +.Xr DH_new 3 +.Sh HISTORY +.Fn DH_set_default_method , +.Fn DH_get_default_method , +.Fn DH_set_method , +.Fn DH_new_method +and +.Fn DH_OpenSSL +were added in OpenSSL 0.9.4. +.Pp +.Fn DH_set_default_openssl_method +and +.Fn DH_get_default_openssl_method +replaced +.Fn DH_set_default_method +and +.Fn DH_get_default_method +respectively, and +.Fn DH_set_method +and +.Fn DH_new_method +were altered to use +.Vt ENGINE Ns s +rather than +.Vt DH_METHOD Ns s +during development of the engine version of OpenSSL 0.9.6. +For 0.9.7, the handling of defaults in the +.Xr engine 3 +API was restructured so that this change was reversed, and behaviour +of the other functions resembled more closely the previous behaviour. +The behaviour of defaults in the +.Xr engine 3 +API now transparently overrides the behaviour of defaults in the +DH API without requiring changing these function prototypes. +.Sh CAVEATS +As of version 0.9.7, +.Vt DH_METHOD +implementations are grouped together with other algorithmic APIs +(eg. RSA_METHOD, EVP_CIPHER, etc) in +.Vt ENGINE +modules. +If a default +.Vt ENGINE +is specified for DH functionality using an +.Xr engine 3 +API function, that will override any DH defaults set using the DH API +.Pq ie. Fn DH_set_default_method . +For this reason, the +.Xr engine 3 +API is the recommended way to control default implementations +for use in DH and other cryptographic algorithms. diff --git a/src/lib/libcrypto/man/DH_size.3 b/src/lib/libcrypto/man/DH_size.3 new file mode 100644 index 0000000000..3675f7b12b --- /dev/null +++ b/src/lib/libcrypto/man/DH_size.3 @@ -0,0 +1,29 @@ +.Dd $Mdocdate: November 2 2016 $ +.Dt DH_SIZE 3 +.Os +.Sh NAME +.Nm DH_size +.Nd get Diffie-Hellman prime size +.Sh SYNOPSIS +.In openssl/dh.h +.Ft int +.Fo DH_size +.Fa "DH *dh" +.Fc +.Sh DESCRIPTION +This function returns the Diffie-Hellman size in bytes. +It can be used to determine how much memory must be allocated for the +shared secret computed by +.Xr DH_compute_key 3 . +.Pp +.Fa dh->p +must not be +.Dv NULL . +.Sh RETURN VALUE +The size in bytes. +.Sh SEE ALSO +.Xr dh 3 , +.Xr DH_generate_key 3 +.Sh HISTORY +.Fn DH_size +is available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 1dfcf8700d..a40bb39167 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.34 2016/09/05 10:43:42 schwarze Exp $ +# $OpenBSD: Makefile,v 1.35 2016/11/02 09:11:53 schwarze Exp $ .include # for NOMAN @@ -56,6 +56,13 @@ MAN= \ CONF_modules_load_file.3 \ CRYPTO_set_ex_data.3 \ CRYPTO_set_locking_callback.3 \ + DES_set_key.3 \ + DH_generate_key.3 \ + DH_generate_parameters.3 \ + DH_get_ex_new_index.3 \ + DH_new.3 \ + DH_set_method.3 \ + DH_size.3 \ ECDSA_SIG_new.3 \ EVP_AEAD_CTX_init.3 \ UI_new.3 \ @@ -66,13 +73,6 @@ MAN= \ lh_new.3 \ GENMAN= \ - DES_set_key.3 \ - DH_generate_key.3 \ - DH_generate_parameters.3 \ - DH_get_ex_new_index.3 \ - DH_new.3 \ - DH_set_method.3 \ - DH_size.3 \ DSA_SIG_new.3 \ DSA_do_sign.3 \ DSA_dup_DH.3 \ -- cgit v1.2.3-55-g6feb