From 27c3c9e543412112b877fdf1f01c5fe54d220138 Mon Sep 17 00:00:00 2001 From: mpi <> Date: Wed, 16 Apr 2014 09:50:10 +0000 Subject: Sync the list of man pages for libcrypto, explicity rename conflicting pages instead of doing it in the Makefiles and move a libssl page where it belongs. ok miod@ --- src/lib/libcrypto/doc/DES_set_key.pod | 358 ++++++++++++++++ src/lib/libcrypto/doc/ERR.pod | 187 ++++++++ src/lib/libcrypto/doc/HMAC.pod | 106 +++++ src/lib/libcrypto/doc/MD5.pod | 101 +++++ src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod | 476 +++++++++++++++++++++ src/lib/libcrypto/doc/RAND.pod | 74 ++++ src/lib/libcrypto/doc/RC4.pod | 62 +++ src/lib/libcrypto/doc/RIPEMD160.pod | 66 +++ src/lib/libcrypto/doc/SHA1.pod | 70 +++ src/lib/libcrypto/man/Makefile | 132 +++--- src/lib/libssl/man/Makefile | 209 ++++----- src/lib/libssl/src/doc/crypto/BF_set_key.pod | 112 +++++ src/lib/libssl/src/doc/crypto/BIO.pod | 54 +++ src/lib/libssl/src/doc/crypto/BIO_f_ssl.pod | 322 -------------- src/lib/libssl/src/doc/crypto/BUF_MEM_new.pod | 73 ++++ .../src/doc/crypto/CRYPTO_set_locking_callback.pod | 210 +++++++++ src/lib/libssl/src/doc/crypto/DES_set_key.pod | 358 ++++++++++++++++ src/lib/libssl/src/doc/crypto/ERR.pod | 187 ++++++++ src/lib/libssl/src/doc/crypto/HMAC.pod | 106 +++++ src/lib/libssl/src/doc/crypto/MD5.pod | 101 +++++ .../src/doc/crypto/PEM_read_bio_PrivateKey.pod | 476 +++++++++++++++++++++ src/lib/libssl/src/doc/crypto/RAND.pod | 74 ++++ src/lib/libssl/src/doc/crypto/RC4.pod | 62 +++ src/lib/libssl/src/doc/crypto/RIPEMD160.pod | 66 +++ src/lib/libssl/src/doc/crypto/SHA1.pod | 70 +++ src/lib/libssl/src/doc/crypto/bio.pod | 54 --- src/lib/libssl/src/doc/crypto/blowfish.pod | 112 ----- src/lib/libssl/src/doc/crypto/buffer.pod | 73 ---- src/lib/libssl/src/doc/crypto/des.pod | 358 ---------------- src/lib/libssl/src/doc/crypto/err.pod | 187 -------- src/lib/libssl/src/doc/crypto/hmac.pod | 106 ----- src/lib/libssl/src/doc/crypto/md5.pod | 101 ----- src/lib/libssl/src/doc/crypto/pem.pod | 476 --------------------- src/lib/libssl/src/doc/crypto/rand.pod | 74 ---- src/lib/libssl/src/doc/crypto/rc4.pod | 62 --- src/lib/libssl/src/doc/crypto/ripemd.pod | 66 --- src/lib/libssl/src/doc/crypto/sha.pod | 70 --- src/lib/libssl/src/doc/crypto/threads.pod | 210 --------- src/lib/libssl/src/doc/ssl/BIO_f_ssl.pod | 322 ++++++++++++++ 39 files changed, 3933 insertions(+), 2450 deletions(-) create mode 100644 src/lib/libcrypto/doc/DES_set_key.pod create mode 100644 src/lib/libcrypto/doc/ERR.pod create mode 100644 src/lib/libcrypto/doc/HMAC.pod create mode 100644 src/lib/libcrypto/doc/MD5.pod create mode 100644 src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod create mode 100644 src/lib/libcrypto/doc/RAND.pod create mode 100644 src/lib/libcrypto/doc/RC4.pod create mode 100644 src/lib/libcrypto/doc/RIPEMD160.pod create mode 100644 src/lib/libcrypto/doc/SHA1.pod create mode 100644 src/lib/libssl/src/doc/crypto/BF_set_key.pod create mode 100644 src/lib/libssl/src/doc/crypto/BIO.pod delete mode 100644 src/lib/libssl/src/doc/crypto/BIO_f_ssl.pod create mode 100644 src/lib/libssl/src/doc/crypto/BUF_MEM_new.pod create mode 100644 src/lib/libssl/src/doc/crypto/CRYPTO_set_locking_callback.pod create mode 100644 src/lib/libssl/src/doc/crypto/DES_set_key.pod create mode 100644 src/lib/libssl/src/doc/crypto/ERR.pod create mode 100644 src/lib/libssl/src/doc/crypto/HMAC.pod create mode 100644 src/lib/libssl/src/doc/crypto/MD5.pod create mode 100644 src/lib/libssl/src/doc/crypto/PEM_read_bio_PrivateKey.pod create mode 100644 src/lib/libssl/src/doc/crypto/RAND.pod create mode 100644 src/lib/libssl/src/doc/crypto/RC4.pod create mode 100644 src/lib/libssl/src/doc/crypto/RIPEMD160.pod create mode 100644 src/lib/libssl/src/doc/crypto/SHA1.pod delete mode 100644 src/lib/libssl/src/doc/crypto/bio.pod delete mode 100644 src/lib/libssl/src/doc/crypto/blowfish.pod delete mode 100644 src/lib/libssl/src/doc/crypto/buffer.pod delete mode 100644 src/lib/libssl/src/doc/crypto/des.pod delete mode 100644 src/lib/libssl/src/doc/crypto/err.pod delete mode 100644 src/lib/libssl/src/doc/crypto/hmac.pod delete mode 100644 src/lib/libssl/src/doc/crypto/md5.pod delete mode 100644 src/lib/libssl/src/doc/crypto/pem.pod delete mode 100644 src/lib/libssl/src/doc/crypto/rand.pod delete mode 100644 src/lib/libssl/src/doc/crypto/rc4.pod delete mode 100644 src/lib/libssl/src/doc/crypto/ripemd.pod delete mode 100644 src/lib/libssl/src/doc/crypto/sha.pod delete mode 100644 src/lib/libssl/src/doc/crypto/threads.pod create mode 100644 src/lib/libssl/src/doc/ssl/BIO_f_ssl.pod (limited to 'src/lib') diff --git a/src/lib/libcrypto/doc/DES_set_key.pod b/src/lib/libcrypto/doc/DES_set_key.pod new file mode 100644 index 0000000000..6f0cf1cc5e --- /dev/null +++ b/src/lib/libcrypto/doc/DES_set_key.pod @@ -0,0 +1,358 @@ +=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. The PRNG must be seeded +prior to using this function (see L). If the PRNG +could not generate a secure key, 0 is returned. + +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 probability that a randomly generated key is weak is +1/2^52, so it is not really worth checking for them. + +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; see L. + +The L library provides higher-level encryption functions. + +=head1 BUGS + +DES_3cbc_encrypt() is flawed and must not be used in applications. + +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 written to be source code compatible with +the MIT Kerberos library. + +=head1 SEE ALSO + +crypt(3), L, L, L + +=head1 HISTORY + +In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid +clashes with older versions of libdes. Compatibility des_ functions +are provided for a short while, as well as crypt(). +Declarations for these are in . There is no DES_ +variant for des_random_seed(). +This will happen to other functions +as well if they are deemed redundant (des_random_seed() just calls +RAND_seed() and is present for backward compatibility only), buggy or +already scheduled for removal. + +des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(), +des_is_weak_key(), des_key_sched(), des_pcbc_encrypt(), +des_quad_cksum(), des_random_key() and des_string_to_key() +are available in the MIT Kerberos library; +des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key() +are available in newer versions of that library. + +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/ERR.pod b/src/lib/libcrypto/doc/ERR.pod new file mode 100644 index 0000000000..6f729554d2 --- /dev/null +++ b/src/lib/libcrypto/doc/ERR.pod @@ -0,0 +1,187 @@ +=pod + +=head1 NAME + +err - error codes + +=head1 SYNOPSIS + + #include + + unsigned long ERR_get_error(void); + unsigned long ERR_peek_error(void); + unsigned long ERR_get_error_line(const char **file, int *line); + unsigned long ERR_peek_error_line(const char **file, int *line); + unsigned long ERR_get_error_line_data(const char **file, int *line, + const char **data, int *flags); + unsigned long ERR_peek_error_line_data(const char **file, int *line, + const char **data, int *flags); + + int ERR_GET_LIB(unsigned long e); + int ERR_GET_FUNC(unsigned long e); + int ERR_GET_REASON(unsigned long e); + + void ERR_clear_error(void); + + char *ERR_error_string(unsigned long e, char *buf); + const char *ERR_lib_error_string(unsigned long e); + const char *ERR_func_error_string(unsigned long e); + const char *ERR_reason_error_string(unsigned long e); + + void ERR_print_errors(BIO *bp); + void ERR_print_errors_fp(FILE *fp); + + void ERR_load_crypto_strings(void); + void ERR_free_strings(void); + + void ERR_remove_state(unsigned long pid); + + void ERR_put_error(int lib, int func, int reason, const char *file, + int line); + void ERR_add_error_data(int num, ...); + + void ERR_load_strings(int lib,ERR_STRING_DATA str[]); + unsigned long ERR_PACK(int lib, int func, int reason); + int ERR_get_next_error_library(void); + +=head1 DESCRIPTION + +When a call to the OpenSSL library fails, this is usually signalled +by the return value, and an error code is stored in an error queue +associated with the current thread. The B library provides +functions to obtain these error codes and textual error messages. + +The L manpage describes how to +access error codes. + +Error codes contain information about where the error occurred, and +what went wrong. L describes how to +extract this information. A method to obtain human-readable error +messages is described in L. + +L can be used to clear the +error queue. + +Note that L should be used to +avoid memory leaks when threads are terminated. + +=head1 ADDING NEW ERROR CODES TO OPENSSL + +See L if you want to record error codes in the +OpenSSL error system from within your application. + +The remainder of this section is of interest only if you want to add +new error codes to OpenSSL or add error codes from external libraries. + +=head2 Reporting errors + +Each sub-library has a specific macro XXXerr() that is used to report +errors. Its first argument is a function code B, the second +argument is a reason code B. Function codes are derived +from the function names; reason codes consist of textual error +descriptions. For example, the function ssl23_read() reports a +"handshake failure" as follows: + + SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); + +Function and reason codes should consist of upper case characters, +numbers and underscores only. The error file generation script translates +function codes into function names by looking in the header files +for an appropriate function name, if none is found it just uses +the capitalized form such as "SSL23_READ" in the above example. + +The trailing section of a reason code (after the "_R_") is translated +into lower case and underscores changed to spaces. + +When you are using new function or reason codes, run B. +The necessary B<#define>s will then automatically be added to the +sub-library's header file. + +Although a library will normally report errors using its own specific +XXXerr macro, another library's macro can be used. This is normally +only done when a library wants to include ASN1 code which must use +the ASN1err() macro. + +=head2 Adding new libraries + +When adding a new sub-library to OpenSSL, assign it a library number +B, define a macro XXXerr() (both in B), add its +name to B (in B), and add +C to the ERR_load_crypto_strings() function +(in B). Finally, add an entry + + L XXX xxx.h xxx_err.c + +to B, and add B to the Makefile. +Running B will then generate a file B, and +add all error codes used in the library to B. + +Additionally the library include file must have a certain form. +Typically it will initially look like this: + + #ifndef HEADER_XXX_H + #define HEADER_XXX_H + + #ifdef __cplusplus + extern "C" { + #endif + + /* Include files */ + + #include + #include + + /* Macros, structures and function prototypes */ + + + /* BEGIN ERROR CODES */ + +The B sequence is used by the error code +generation script as the point to place new error codes, any text +after this point will be overwritten when B is run. +The closing #endif etc will be automatically added by the script. + +The generated C error code file B will load the header +files B, B and B so the +header file must load any additional header files containing any +definitions it uses. + +=head1 USING ERROR CODES IN EXTERNAL LIBRARIES + +It is also possible to use OpenSSL's error code scheme in external +libraries. The library needs to load its own codes and call the OpenSSL +error code insertion script B explicitly to add codes to +the header file and generate the C error code file. This will normally +be done if the external library needs to generate new ASN1 structures +but it can also be used to add more general purpose error code handling. + +TBA more details + +=head1 INTERNALS + +The error queues are stored in a hash table with one B +entry for each pid. ERR_get_state() returns the current thread's +B. An B can hold up to B error +codes. When more error codes are added, the old ones are overwritten, +on the assumption that the most recent errors are most important. + +Error strings are also stored in hash table. The hash tables can +be obtained by calling ERR_get_err_state_table(void) and +ERR_get_string_table(void) respectively. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/src/lib/libcrypto/doc/HMAC.pod b/src/lib/libcrypto/doc/HMAC.pod new file mode 100644 index 0000000000..d92138d273 --- /dev/null +++ b/src/lib/libcrypto/doc/HMAC.pod @@ -0,0 +1,106 @@ +=pod + +=head1 NAME + +HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message +authentication code + +=head1 SYNOPSIS + + #include + + unsigned char *HMAC(const EVP_MD *evp_md, const void *key, + int key_len, const unsigned char *d, int n, + unsigned char *md, unsigned int *md_len); + + void HMAC_CTX_init(HMAC_CTX *ctx); + + int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, + const EVP_MD *md); + int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, + const EVP_MD *md, ENGINE *impl); + int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); + int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); + + void HMAC_CTX_cleanup(HMAC_CTX *ctx); + void HMAC_cleanup(HMAC_CTX *ctx); + +=head1 DESCRIPTION + +HMAC is a MAC (message authentication code), i.e. a keyed hash +function used for message authentication, which is based on a hash +function. + +HMAC() computes the message authentication code of the B bytes at +B using the hash function B and the key B which is +B bytes long. + +It places the result in B (which must have space for the output of +the hash function, which is no more than B bytes). +If B is NULL, the digest is placed in a static array. The size of +the output is placed in B, unless it is B. + +B can be EVP_sha1(), EVP_ripemd160() etc. + +HMAC_CTX_init() initialises a B before first use. It must be +called. + +HMAC_CTX_cleanup() erases the key and other data from the B +and releases any associated resources. It must be called when an +B is no longer required. + +HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back +compatibility with 0.9.6b, it is deprecated. + +The following functions may be used if the message is not completely +stored in memory: + +HMAC_Init() initializes a B structure to use the hash +function B and the key B which is B bytes +long. It is deprecated and only included for backward compatibility +with OpenSSL 0.9.6b. + +HMAC_Init_ex() initializes or reuses a B structure to use +the function B and key B. Either can be NULL, in which +case the existing one will be reused. HMAC_CTX_init() must have been +called before the first use of an B in this +function. B. + +HMAC_Update() can be called repeatedly with chunks of the message to +be authenticated (B bytes at B). + +HMAC_Final() places the message authentication code in B, which +must have space for the hash function output. + +=head1 RETURN VALUES + +HMAC() returns a pointer to the message authentication code or NULL if +an error occurred. + +HMAC_Init_ex(), HMAC_Update() and HMAC_Final() return 1 for success or 0 if +an error occurred. + +HMAC_CTX_init() and HMAC_CTX_cleanup() do not return values. + +=head1 CONFORMING TO + +RFC 2104 + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() +are available since SSLeay 0.9.0. + +HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available +since OpenSSL 0.9.7. + +HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in +versions of OpenSSL before 1.0.0. + +=cut diff --git a/src/lib/libcrypto/doc/MD5.pod b/src/lib/libcrypto/doc/MD5.pod new file mode 100644 index 0000000000..d11d5c32cb --- /dev/null +++ b/src/lib/libcrypto/doc/MD5.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + +MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, +MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions + +=head1 SYNOPSIS + + #include + + unsigned char *MD2(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MD2_Init(MD2_CTX *c); + int MD2_Update(MD2_CTX *c, const unsigned char *data, + unsigned long len); + int MD2_Final(unsigned char *md, MD2_CTX *c); + + + #include + + unsigned char *MD4(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MD4_Init(MD4_CTX *c); + int MD4_Update(MD4_CTX *c, const void *data, + unsigned long len); + int MD4_Final(unsigned char *md, MD4_CTX *c); + + + #include + + unsigned char *MD5(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MD5_Init(MD5_CTX *c); + int MD5_Update(MD5_CTX *c, const void *data, + unsigned long len); + int MD5_Final(unsigned char *md, MD5_CTX *c); + +=head1 DESCRIPTION + +MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. + +MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest +of the B bytes at B and place it in B (which must have space +for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 +bytes of output). If B is NULL, the digest is placed in a static +array. + +The following functions may be used if the message is not completely +stored in memory: + +MD2_Init() initializes a B structure. + +MD2_Update() can be called repeatedly with chunks of the message to +be hashed (B bytes at B). + +MD2_Final() places the message digest in B, which must have space +for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B. + +MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and +MD5_Final() are analogous using an B and B structure. + +Applications should use the higher level functions +L +etc. instead of calling the hash functions directly. + +=head1 NOTE + +MD2, MD4, and MD5 are recommended only for compatibility with existing +applications. In new applications, SHA-1 or RIPEMD-160 should be +preferred. + +=head1 RETURN VALUES + +MD2(), MD4(), and MD5() return pointers to the hash value. + +MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), +MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for +success, 0 otherwise. + +=head1 CONFORMING TO + +RFC 1319, RFC 1320, RFC 1321 + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), +MD5_Update() and MD5_Final() are available in all versions of SSLeay +and OpenSSL. + +MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and +above. + +=cut diff --git a/src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod b/src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod new file mode 100644 index 0000000000..54414a3f6f --- /dev/null +++ b/src/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod @@ -0,0 +1,476 @@ +=pod + +=head1 NAME + +PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines + +=head1 SYNOPSIS + + #include + + EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + + EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + + EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); + int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); + + RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, + pem_password_cb *cb, void *u); + + RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, + pem_password_cb *cb, void *u); + + RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); + + int PEM_write_RSAPublicKey(FILE *fp, RSA *x); + + RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, + pem_password_cb *cb, void *u); + + RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); + + int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); + + DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, + pem_password_cb *cb, void *u); + + DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, + pem_password_cb *cb, void *u); + + DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); + + int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); + + DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); + + DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_DSAparams(BIO *bp, DSA *x); + + int PEM_write_DSAparams(FILE *fp, DSA *x); + + DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); + + DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_DHparams(BIO *bp, DH *x); + + int PEM_write_DHparams(FILE *fp, DH *x); + + X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); + + X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_X509(BIO *bp, X509 *x); + + int PEM_write_X509(FILE *fp, X509 *x); + + X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); + + X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); + + int PEM_write_X509_AUX(FILE *fp, X509 *x); + + X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, + pem_password_cb *cb, void *u); + + X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); + + int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); + + int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); + + int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); + + X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, + pem_password_cb *cb, void *u); + X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); + int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); + + PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); + + PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); + + int PEM_write_PKCS7(FILE *fp, PKCS7 *x); + + NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, + NETSCAPE_CERT_SEQUENCE **x, + pem_password_cb *cb, void *u); + + NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp, + NETSCAPE_CERT_SEQUENCE **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x); + + int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x); + +=head1 DESCRIPTION + +The PEM functions read or write structures in PEM format. In +this sense PEM format is simply base64 encoded data surrounded +by header lines. + +For more details about the meaning of arguments see the +B section. + +Each operation has four functions associated with it. For +clarity the term "B functions" will be used to collectively +refer to the PEM_read_bio_foobar(), PEM_read_foobar(), +PEM_write_bio_foobar() and PEM_write_foobar() functions. + +The B functions read or write a private key in +PEM format using an EVP_PKEY structure. The write routines use +"traditional" private key format and can handle both RSA and DSA +private keys. The read functions can additionally transparently +handle PKCS#8 format encrypted and unencrypted keys too. + +PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() +write a private key in an EVP_PKEY structure in PKCS#8 +EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption +algorithms. The B argument specifies the encryption algorithm to +use: unlike all other PEM routines the encryption is applied at the +PKCS#8 level and not in the PEM headers. If B is NULL then no +encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. + +PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() +also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however +it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm +to use is specified in the B parameter and should be the NID of the +corresponding OBJECT IDENTIFIER (see NOTES section). + +The B functions process a public key using an EVP_PKEY +structure. The public key is encoded as a SubjectPublicKeyInfo +structure. + +The B functions process an RSA private key using an +RSA structure. It handles the same formats as the B +functions but an error occurs if the private key is not RSA. + +The B functions process an RSA public key using an +RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey +structure. + +The B functions also process an RSA public key using +an RSA structure. However the public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not RSA. + +The B functions process a DSA private key using a +DSA structure. It handles the same formats as the B +functions but an error occurs if the private key is not DSA. + +The B functions process a DSA public key using +a DSA structure. The public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not DSA. + +The B functions process DSA parameters using a DSA +structure. The parameters are encoded using a foobar structure. + +The B functions process DH parameters using a DH +structure. The parameters are encoded using a PKCS#3 DHparameter +structure. + +The B functions process an X509 certificate using an X509 +structure. They will also process a trusted X509 certificate but +any trust settings are discarded. + +The B functions process a trusted X509 certificate using +an X509 structure. + +The B and B functions process a PKCS#10 +certificate request using an X509_REQ structure. The B +write functions use B in the header whereas +the B functions use B +(as required by some CAs). The B read functions will +handle either form so there are no B read functions. + +The B functions process an X509 CRL using an X509_CRL +structure. + +The B functions process a PKCS#7 ContentInfo using a PKCS7 +structure. + +The B functions process a Netscape Certificate +Sequence using a NETSCAPE_CERT_SEQUENCE structure. + +=head1 PEM FUNCTION ARGUMENTS + +The PEM functions have many common arguments. + +The B BIO parameter (if present) specifies the BIO to read from +or write to. + +The B FILE parameter (if present) specifies the FILE pointer to +read from or write to. + +The PEM read functions all take an argument B and return +a B pointer. Where B is whatever structure the function +uses. If B is NULL then the parameter is ignored. If B is not +NULL but B<*x> is NULL then the structure returned will be written +to B<*x>. If neither B nor B<*x> is NULL then an attempt is made +to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections). +Irrespective of the value of B a pointer to the structure is always +returned (or NULL if an error occurred). + +The PEM functions which write private keys take an B parameter +which specifies the encryption algorithm to use, encryption is done +at the PEM level. If this parameter is set to NULL then the private +key is written in unencrypted form. + +The B argument is the callback to use when querying for the pass +phrase used for encrypted PEM structures (normally only private keys). + +For the PEM write routines if the B parameter is not NULL then +B bytes at B are used as the passphrase and B is +ignored. + +If the B parameters is set to NULL and the B parameter is not +NULL then the B parameter is interpreted as a null terminated string +to use as the passphrase. If both B and B are NULL then the +default callback routine is used which will typically prompt for the +passphrase on the current terminal with echoing turned off. + +The default passphrase callback is sometimes inappropriate (for example +in a GUI application) so an alternative can be supplied. The callback +routine has the following form: + + int cb(char *buf, int size, int rwflag, void *u); + +B is the buffer to write the passphrase to. B is the maximum +length of the passphrase (i.e. the size of buf). B is a flag +which is set to 0 when reading and 1 when writing. A typical routine +will ask the user to verify the passphrase (for example by prompting +for it twice) if B is 1. The B parameter has the same +value as the B parameter passed to the PEM routine. It allows +arbitrary data to be passed to the callback by the application +(for example a window handle in a GUI application). The callback +B return the number of characters in the passphrase or 0 if +an error occurred. + +=head1 EXAMPLES + +Although the PEM routines take several arguments in almost all applications +most of them are set to 0 or NULL. + +Read a certificate in PEM format from a BIO: + + X509 *x; + x = PEM_read_bio_X509(bp, NULL, 0, NULL); + if (x == NULL) + { + /* Error */ + } + +Alternative method: + + X509 *x = NULL; + if (!PEM_read_bio_X509(bp, &x, 0, NULL)) + { + /* Error */ + } + +Write a certificate to a BIO: + + if (!PEM_write_bio_X509(bp, x)) + { + /* Error */ + } + +Write an unencrypted private key to a FILE pointer: + + if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) + { + /* Error */ + } + +Write a private key (using traditional format) to a BIO using +triple DES encryption, the pass phrase is prompted for: + + if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) + { + /* Error */ + } + +Write a private key (using PKCS#8 format) to a BIO using triple +DES encryption, using the pass phrase "hello": + + if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) + { + /* Error */ + } + +Read a private key from a BIO using the pass phrase "hello": + + key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); + if (key == NULL) + { + /* Error */ + } + +Read a private key from a BIO using a pass phrase callback: + + key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); + if (key == NULL) + { + /* Error */ + } + +Skeleton pass phrase callback: + + int pass_cb(char *buf, int size, int rwflag, void *u); + { + int len; + char *tmp; + /* We'd probably do something else if 'rwflag' is 1 */ + printf("Enter pass phrase for \"%s\"\n", u); + + /* get pass phrase, length 'len' into 'tmp' */ + tmp = "hello"; + len = strlen(tmp); + + if (len <= 0) return 0; + /* if too long, truncate */ + if (len > size) len = size; + memcpy(buf, tmp, len); + return len; + } + +=head1 NOTES + +The old B write routines are retained for compatibility. +New applications should write private keys using the +PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines +because they are more secure (they use an iteration count of 2048 whereas +the traditional routines use a count of 1) unless compatibility with older +versions of OpenSSL is important. + +The B read routines can be used in all applications because +they handle all formats transparently. + +A frequent cause of problems is attempting to use the PEM routines like +this: + + X509 *x; + PEM_read_bio_X509(bp, &x, 0, NULL); + +this is a bug because an attempt will be made to reuse the data at B +which is an uninitialised pointer. + +=head1 PEM ENCRYPTION FORMAT + +This old B routines use a non standard technique for encryption. + +The private key (or other data) takes the following form: + + -----BEGIN RSA PRIVATE KEY----- + Proc-Type: 4,ENCRYPTED + DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 + + ...base64 encoded data... + -----END RSA PRIVATE KEY----- + +The line beginning DEK-Info contains two comma separated pieces of information: +the encryption algorithm name as used by EVP_get_cipherbyname() and an 8 +byte B encoded as a set of hexadecimal digits. + +After this is the base64 encoded encrypted data. + +The encryption key is determined using EVP_bytestokey(), using B and an +iteration count of 1. The IV used is the value of B and *not* the IV +returned by EVP_bytestokey(). + +=head1 BUGS + +The PEM read routines in some versions of OpenSSL will not correctly reuse +an existing structure. Therefore the following: + + PEM_read_bio_X509(bp, &x, 0, NULL); + +where B already contains a valid certificate, may not work, whereas: + + X509_free(x); + x = PEM_read_bio_X509(bp, NULL, 0, NULL); + +is guaranteed to work. + +=head1 RETURN CODES + +The read routines return either a pointer to the structure read or NULL +if an error occurred. + +The write routines return 1 for success or 0 for failure. diff --git a/src/lib/libcrypto/doc/RAND.pod b/src/lib/libcrypto/doc/RAND.pod new file mode 100644 index 0000000000..e987414477 --- /dev/null +++ b/src/lib/libcrypto/doc/RAND.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +rand - pseudo-random number generator + +=head1 SYNOPSIS + + #include + + int RAND_set_rand_engine(ENGINE *engine); + + int RAND_bytes(unsigned char *buf, int num); + int RAND_pseudo_bytes(unsigned char *buf, int num); + + void RAND_seed(const void *buf, int num); + void RAND_add(const void *buf, int num, int entropy); + int RAND_status(void); + + int RAND_load_file(const char *file, long max_bytes); + int RAND_write_file(const char *file); + const char *RAND_file_name(char *file, size_t num); + + int RAND_egd(const char *path); + + void RAND_set_rand_method(const RAND_METHOD *meth); + const RAND_METHOD *RAND_get_rand_method(void); + RAND_METHOD *RAND_SSLeay(void); + + void RAND_cleanup(void); + +=head1 DESCRIPTION + +Since the introduction of the ENGINE API, the recommended way of controlling +default implementations is by using the ENGINE API functions. The default +B, as set by RAND_set_rand_method() and returned by +RAND_get_rand_method(), is only used if no ENGINE has been set as the default +"rand" implementation. Hence, these two functions are no longer the recommened +way to control defaults. + +If an alternative B implementation is being used (either set +directly or as provided by an ENGINE module), then it is entirely responsible +for the generation and management of a cryptographically secure PRNG stream. The +mechanisms described below relate solely to the software PRNG implementation +built in to OpenSSL and used by default. + +These functions implement a cryptographically secure pseudo-random +number generator (PRNG). It is used by other library functions for +example to generate random keys, and applications can use it when they +need randomness. + +A cryptographic PRNG must be seeded with unpredictable data such as +mouse movements or keys pressed at random by the user. This is +described in L. Its state can be saved in a seed file +(see L) to avoid having to go through the +seeding process whenever the application is started. + +L describes how to obtain random data from the +PRNG. + +=head1 INTERNALS + +The RAND_SSLeay() method implements a PRNG based on the systems' +L random number generator. + +=head1 SEE ALSO + +L, L, +L, L, +L, +L, +L + +=cut diff --git a/src/lib/libcrypto/doc/RC4.pod b/src/lib/libcrypto/doc/RC4.pod new file mode 100644 index 0000000000..b6d3a4342c --- /dev/null +++ b/src/lib/libcrypto/doc/RC4.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +RC4_set_key, RC4 - RC4 encryption + +=head1 SYNOPSIS + + #include + + void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); + + void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, + unsigned char *outdata); + +=head1 DESCRIPTION + +This library implements the Alleged RC4 cipher, which is described for +example in I. It is believed to be compatible +with RC4[TM], a proprietary cipher of RSA Security Inc. + +RC4 is a stream cipher with variable key length. Typically, 128 bit +(16 byte) keys are used for strong encryption, but shorter insecure +key sizes have been widely used due to export restrictions. + +RC4 consists of a key setup phase and the actual encryption or +decryption phase. + +RC4_set_key() sets up the B B using the B bytes long +key at B. + +RC4() encrypts or decrypts the B bytes of data at B using +B and places the result at B. Repeated RC4() calls with +the same B yield a continuous key stream. + +Since RC4 is a stream cipher (the input is XORed with a pseudo-random +key stream to produce the output), decryption uses the same function +calls as encryption. + +Applications should use the higher level functions +L +etc. instead of calling the RC4 functions directly. + +=head1 RETURN VALUES + +RC4_set_key() and RC4() do not return values. + +=head1 NOTE + +Certain conditions have to be observed to securely use stream ciphers. +It is not permissible to perform multiple encryptions using the same +key stream. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/src/lib/libcrypto/doc/RIPEMD160.pod b/src/lib/libcrypto/doc/RIPEMD160.pod new file mode 100644 index 0000000000..264bb99ae7 --- /dev/null +++ b/src/lib/libcrypto/doc/RIPEMD160.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - +RIPEMD-160 hash function + +=head1 SYNOPSIS + + #include + + unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, + unsigned char *md); + + int RIPEMD160_Init(RIPEMD160_CTX *c); + int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, + unsigned long len); + int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); + +=head1 DESCRIPTION + +RIPEMD-160 is a cryptographic hash function with a +160 bit output. + +RIPEMD160() computes the RIPEMD-160 message digest of the B +bytes at B and places it in B (which must have space for +RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +RIPEMD160_Init() initializes a B structure. + +RIPEMD160_Update() can be called repeatedly with chunks of the message to +be hashed (B bytes at B). + +RIPEMD160_Final() places the message digest in B, which must have +space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases +the B. + +Applications should use the higher level functions +L etc. instead of calling the +hash functions directly. + +=head1 RETURN VALUES + +RIPEMD160() returns a pointer to the hash value. + +RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for +success, 0 otherwise. + +=head1 CONFORMING TO + +ISO/IEC 10118-3 (draft) (??) + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and +RIPEMD160_Final() are available since SSLeay 0.9.0. + +=cut diff --git a/src/lib/libcrypto/doc/SHA1.pod b/src/lib/libcrypto/doc/SHA1.pod new file mode 100644 index 0000000000..94ab7bc724 --- /dev/null +++ b/src/lib/libcrypto/doc/SHA1.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm + +=head1 SYNOPSIS + + #include + + unsigned char *SHA1(const unsigned char *d, unsigned long n, + unsigned char *md); + + int SHA1_Init(SHA_CTX *c); + int SHA1_Update(SHA_CTX *c, const void *data, + unsigned long len); + int SHA1_Final(unsigned char *md, SHA_CTX *c); + +=head1 DESCRIPTION + +SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a +160 bit output. + +SHA1() computes the SHA-1 message digest of the B +bytes at B and places it in B (which must have space for +SHA_DIGEST_LENGTH == 20 bytes of output). If B is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +SHA1_Init() initializes a B structure. + +SHA1_Update() can be called repeatedly with chunks of the message to +be hashed (B bytes at B). + +SHA1_Final() places the message digest in B, which must have space +for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B. + +Applications should use the higher level functions +L +etc. instead of calling the hash functions directly. + +The predecessor of SHA-1, SHA, is also implemented, but it should be +used only when backward compatibility is required. + +=head1 RETURN VALUES + +SHA1() returns a pointer to the hash value. + +SHA1_Init(), SHA1_Update() and SHA1_Final() return 1 for success, 0 otherwise. + +=head1 CONFORMING TO + +SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash +Standard), +SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash +Standard), +ANSI X9.30 + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all +versions of SSLeay and OpenSSL. + +=cut diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 503829ae8d..826d161c23 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.1 2014/04/11 22:51:53 miod Exp $ +# $OpenBSD: Makefile,v 1.2 2014/04/16 09:50:10 mpi Exp $ .include # for NOMAN @@ -11,6 +11,8 @@ MAN= \ ASN1_STRING_new.3 \ ASN1_STRING_print_ex.3 \ ASN1_generate_nconf.3 \ + BF_set_key.3 \ + BIO.3 \ BIO_ctrl.3 \ BIO_f_base64.3 \ BIO_f_buffer.3 \ @@ -49,9 +51,12 @@ MAN= \ BN_set_bit.3 \ BN_swap.3 \ BN_zero.3 \ + BUF_MEM_new.3 \ CONF_modules_free.3 \ 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 \ @@ -68,6 +73,7 @@ MAN= \ DSA_set_method.3 \ DSA_sign.3 \ DSA_size.3 \ + ERR.3 \ ERR_GET_LIB.3 \ ERR_clear_error.3 \ ERR_error_string.3 \ @@ -84,28 +90,48 @@ MAN= \ EVP_DigestVerifyInit.3 \ EVP_EncryptInit.3 \ EVP_OpenInit.3 \ + EVP_PKEY_CTX_ctrl.3 \ + EVP_PKEY_CTX_new.3 \ + EVP_PKEY_cmp.3 \ + EVP_PKEY_decrypt.3 \ + EVP_PKEY_derive.3 \ + EVP_PKEY_encrypt.3 \ + EVP_PKEY_get_default_digest.3 \ + EVP_PKEY_keygen.3 \ EVP_PKEY_new.3 \ + EVP_PKEY_print_private.3 \ EVP_PKEY_set1_RSA.3 \ + EVP_PKEY_sign.3 \ + EVP_PKEY_verify.3 \ + EVP_PKEY_verify_recover.3 \ EVP_SealInit.3 \ EVP_SignInit.3 \ EVP_VerifyInit.3 \ + HMAC.3 \ + MD5.3 \ OBJ_nid2obj.3 \ OPENSSL_VERSION_NUMBER.3 \ OPENSSL_config.3 \ OPENSSL_load_builtin_modules.3 \ OpenSSL_add_all_algorithms.3 \ + PEM_read_bio_PrivateKey.3 \ + PEM_write_bio_PKCS7_stream.3 \ PKCS12_create.3 \ PKCS12_parse.3 \ PKCS7_decrypt.3 \ PKCS7_encrypt.3 \ PKCS7_sign.3 \ + PKCS7_sign_add_signer.3 \ PKCS7_verify.3 \ + RAND.3 \ RAND_add.3 \ RAND_bytes.3 \ RAND_cleanup.3 \ RAND_egd.3 \ RAND_load_file.3 \ RAND_set_rand_method.3 \ + RC4.3 \ + RIPEMD160.3 \ RSA_blinding_on.3 \ RSA_check_key.3 \ RSA_generate_key.3 \ @@ -119,19 +145,20 @@ MAN= \ RSA_sign.3 \ RSA_sign_ASN1_OCTET_STRING.3 \ RSA_size.3 \ + SHA1.3 \ SMIME_read_PKCS7.3 \ SMIME_write_PKCS7.3 \ X509_NAME_ENTRY_get_object.3 \ X509_NAME_add_entry_by_txt.3 \ X509_NAME_get_index_by_NID.3 \ X509_NAME_print_ex.3 \ - X509_new.3 \ X509_STORE_CTX_get_error.3 \ X509_STORE_CTX_get_ex_new_index.3 \ X509_STORE_CTX_new.3 \ X509_STORE_CTX_set_verify_cb.3 \ X509_STORE_set_verify_cb_func.3 \ X509_VERIFY_PARAM_set_flags.3 \ + X509_new.3 \ X509_verify_cert.3 \ bn.3 \ bn_internal.3 \ @@ -152,66 +179,35 @@ MAN= \ ecdsa.3 \ engine.3 \ evp.3 \ + i2d_PKCS7_bio_stream.3 \ lh_stats.3 \ lhash.3 \ - pem.3 \ rsa.3 \ ui.3 \ ui_compat.3 \ x509.3 \ - BF_set_key.3 \ - BIO.3 \ - BUF_MEM_new.3 \ - CRYPTO_set_locking_callback.3 \ - DES_set_key.3 \ - ERR.3 \ - HMAC.3 \ - MD5.3 \ - PEM_read_bio_PrivateKey.3 \ - RAND.3 \ - RC4.3 \ - RIPEMD160.3 \ - SHA1.3 - -# These pages removed/renamed -# OPENSSL_ia32cap.cat3 \ # i386-only, internal API -# OPENSSL_Applink.cat3 \ # Win32 only -# bio.cat3 \ # conflict; see below -# blowfish.cat3 \ # conflict; see below -# buffer.cat3 \ # conflict; see below -# des.cat3 \ # conflict; see below -# des_modes.cat3 \ # fairly pointless -# hmac.cat3 \ # conflict; see below -# md5.cat3 \ # conflict; see below -# mdc2.cat3 \ # patents; removed -# rand.cat3 \ # conflict; see below -# rc4.cat3 \ # conflict; see below -# ripemd.cat3 \ # conflict; see below -# sha.cat3 \ # conflict; see below - -# these are a real problem, since they re-document functions described in -# other pages. - -.for page src in \ - BF_set_key blowfish \ - BIO bio \ - BUF_MEM_new buffer \ - CRYPTO_set_locking_callback threads \ - DES_set_key des \ - ERR err \ - HMAC hmac \ - MD5 md5 \ - PEM_read_bio_PrivateKey pem \ - RAND rand \ - RC4 rc4 \ - RIPEMD160 ripemd \ - SHA1 sha - -${page}.3: ${src}.pod - @echo '${POD2MAN} --section=3 --name=${page:U} $? > $@' - @${POD2MAN} --section=3 --name=${page:U} $? > $@.tmp && mv $@.tmp $@ -.endfor +#MAN+= BIO_new_CMS.3 \ +# CMS_add0_cert.3 \ +# CMS_add1_recipient_cert.3 \ +# CMS_compress.3 \ +# CMS_decrypt.3 \ +# CMS_encrypt.3 \ +# CMS_final.3 \ +# CMS_get0_RecipientInfos.3 \ +# CMS_get0_SignerInfos.3 \ +# CMS_get0_type.3 \ +# CMS_get1_ReceiptRequest.3 \ +# CMS_sign.3 \ +# CMS_sign_add1_signer.3 \ +# CMS_sign_receipt.3 \ +# CMS_uncompress.3 \ +# CMS_verify.3 \ +# CMS_verify_receipt.3 \ +# PEM_write_bio_CMS_stream.3 \ +# SMIME_read_CMS.3 \ +# SMIME_write_CMS.3 \ +# i2d_CMS_bio_stream.3 \ MLINKS+=\ ASN1_OBJECT_new.3 ASN1_OBJECT_free.3 \ @@ -520,7 +516,32 @@ MLINKS+=\ EVP_EncryptInit.3 OBJ_obj2nid.3 \ EVP_OpenInit.3 EVP_OpenFinal.3 \ EVP_OpenInit.3 EVP_OpenUpdate.3 \ + EVP_PKEY_CTX_ctrl.3 EVP_PKEY_ctrl_str.3 \ + EVP_PKEY_CTX_new.3 EVP_PKEY_CTX_new_id.3 \ + EVP_PKEY_CTX_new.3 EVP_PKEY_CTX_dup.3 \ + EVP_PKEY_CTX_new.3 EVP_PKEY_CTX_free.3 \ + EVP_PKEY_cmp.3 EVP_PKEY_copy_parameters.3 \ + EVP_PKEY_cmp.3 EVP_PKEY_missing_parameters.3 \ + EVP_PKEY_cmp.3 EVP_PKEY_cmp_parameters.3 \ EVP_PKEY_new.3 EVP_PKEY_free.3 \ + EVP_PKEY_decrypt.3 EVP_PKEY_decrypt_init.3 \ + EVP_PKEY_derive.3 EVP_PKEY_derive_init.3 \ + EVP_PKEY_derive.3 EVP_PKEY_derive_set_peer.3 \ + EVP_PKEY_get_default_digest.3 EVP_PKEY_get_default_digest_nid.3 \ + EVP_PKEY_encrypt.3 EVP_PKEY_encrypt_init.3 \ + EVP_PKEY_keygen.3 EVP_PKEY_keygen_init.3 \ + EVP_PKEY_keygen.3 EVP_PKEY_paramgen_init.3 \ + EVP_PKEY_keygen.3 EVP_PKEY_paramgen.3 \ + EVP_PKEY_keygen.3 EVP_PKEY_CTX_set_cb.3 \ + EVP_PKEY_keygen.3 EVP_PKEY_CTX_get_cb.3 \ + EVP_PKEY_keygen.3 EVP_PKEY_CTX_get_keygen_info.3 \ + EVP_PKEY_keygen.3 EVP_PKEY_CTX_set_app_data.3 \ + EVP_PKEY_keygen.3 EVP_PKEY_CTX_get_app_data.3 \ + EVP_PKEY_print_private.3 EVP_PKEY_print_private.3 \ + EVP_PKEY_print_private.3 EVP_PKEY_print_params.3 \ + EVP_PKEY_sign.3 EVP_PKEY_sign_init.3 \ + EVP_PKEY_verify.3 EVP_PKEY_verify_init.3 \ + EVP_PKEY_verify_recover.3 EVP_PKEY_verify_recover_init.3 \ EVP_PKEY_set1_RSA.3 EVP_PKEY_assign_DH.3 \ EVP_PKEY_set1_RSA.3 EVP_PKEY_assign_DSA.3 \ EVP_PKEY_set1_RSA.3 EVP_PKEY_assign_EC_KEY.3 \ @@ -887,7 +908,6 @@ maninstall: .endif -# XXX .PATH order is critical because of non-unique filenames .PATH: ${.CURDIR}/../../libssl/src/doc/crypto .SUFFIXES: .pod .1 .3 .7 .for sect in 1 3 7 diff --git a/src/lib/libssl/man/Makefile b/src/lib/libssl/man/Makefile index b3b5369cd8..00414ad322 100644 --- a/src/lib/libssl/man/Makefile +++ b/src/lib/libssl/man/Makefile @@ -1,129 +1,94 @@ -# $OpenBSD: Makefile,v 1.24 2014/04/14 08:18:40 mpi Exp $ +# $OpenBSD: Makefile,v 1.25 2014/04/16 09:50:10 mpi Exp $ .include # for NOMAN POD2MAN=pod2man --official --release="OpenBSD ${OSREV}" --center=OpenSSL .ifndef NOMAN - -# libcrypto -MAN= ASN1_OBJECT_new.3 ASN1_STRING_length.3 ASN1_STRING_new.3 \ - ASN1_STRING_print_ex.3 ASN1_generate_nconf.3 - -MAN+= BIO_ctrl.3 BIO_f_base64.3 BIO_f_buffer.3 BIO_f_cipher.3 BIO_f_md.3 \ - BIO_f_null.3 BIO_f_ssl.3 BIO_find_type.3 BIO_new.3 BIO_new_CMS.3 \ - BIO_push.3 BIO_read.3 BIO_s_accept.3 BIO_s_bio.3 BIO_s_connect.3 \ - BIO_s_fd.3 BIO_s_file.3 BIO_s_mem.3 BIO_s_null.3 BIO_s_socket.3 \ - BIO_set_callback.3 BIO_should_retry.3 - -MAN+= BN_BLINDING_new.3 BN_CTX_new.3 BN_CTX_start.3 BN_add.3 BN_add_word.3 \ - BN_bn2bin.3 BN_cmp.3 BN_copy.3 BN_generate_prime.3 BN_mod_inverse.3 \ - BN_mod_mul_montgomery.3 BN_mod_mul_reciprocal.3 BN_new.3 \ - BN_num_bytes.3 BN_rand.3 BN_set_bit.3 BN_swap.3 BN_zero.3 - -MAN+= CMS_add0_cert.3 CMS_add1_recipient_cert.3 CMS_compress.3 CMS_decrypt.3 \ - CMS_encrypt.3 CMS_final.3 CMS_get0_RecipientInfos.3 \ - CMS_get0_SignerInfos.3 CMS_get0_type.3 CMS_get1_ReceiptRequest.3 \ - CMS_sign.3 CMS_sign_add1_signer.3 CMS_sign_receipt.3 CMS_uncompress.3 \ - CMS_verify.3 CMS_verify_receipt.3 - -MAN+= CONF_modules_free.3 CONF_modules_load_file.3 - -MAN+= CRYPTO_set_ex_data.3 - -MAN+= DH_generate_key.3 DH_generate_parameters.3 DH_get_ex_new_index.3 \ - DH_new.3 DH_set_method.3 DH_size.3 - -MAN+= DSA_SIG_new.3 DSA_do_sign.3 DSA_dup_DH.3 DSA_generate_key.3 \ - DSA_generate_parameters.3 DSA_get_ex_new_index.3 DSA_new.3 \ - DSA_set_method.3 DSA_sign.3 DSA_size.3 - -MAN+= ERR_GET_LIB.3 ERR_clear_error.3 ERR_error_string.3 ERR_get_error.3 \ - ERR_load_crypto_strings.3 ERR_load_strings.3 ERR_print_errors.3 \ - ERR_put_error.3 ERR_remove_state.3 ERR_set_mark.3 - -MAN+= EVP_BytesToKey.3 EVP_DigestInit.3 EVP_DigestSignInit.3 \ - EVP_DigestVerifyInit.3 EVP_EncryptInit.3 EVP_OpenInit.3 \ - EVP_PKEY_CTX_ctrl.3 EVP_PKEY_CTX_new.3 EVP_PKEY_cmp.3 \ - EVP_PKEY_decrypt.3 EVP_PKEY_derive.3 EVP_PKEY_encrypt.3 \ - EVP_PKEY_get_default_digest.3 EVP_PKEY_keygen.3 EVP_PKEY_new.3 \ - EVP_PKEY_print_private.3 EVP_PKEY_set1_RSA.3 EVP_PKEY_sign.3 \ - EVP_PKEY_verify.3 EVP_PKEY_verify_recover.3 EVP_SealInit.3 \ - EVP_SignInit.3 EVP_VerifyInit.3 - -MAN+= OBJ_nid2obj.3 - -MAN+= OPENSSL_Applink.3 OPENSSL_VERSION_NUMBER.3 OPENSSL_config.3 \ - OPENSSL_ia32cap.3 OPENSSL_load_builtin_modules.3 \ - OpenSSL_add_all_algorithms.3 - -MAN+= PEM_write_bio_CMS_stream.3 PEM_write_bio_PKCS7_stream.3 - -MAN+= PKCS12_create.3 PKCS12_parse.3 PKCS7_decrypt.3 PKCS7_encrypt.3 \ - PKCS7_sign.3 PKCS7_sign_add_signer.3 PKCS7_verify.3 - -MAN+= RAND_add.3 RAND_bytes.3 RAND_cleanup.3 RAND_egd.3 RAND_load_file.3 \ - RAND_set_rand_method.3 - -MAN+= RSA_blinding_on.3 RSA_check_key.3 RSA_generate_key.3 \ - RSA_get_ex_new_index.3 RSA_new.3 RSA_padding_add_PKCS1_type_1.3 \ - RSA_print.3 RSA_private_encrypt.3 RSA_public_encrypt.3 \ - RSA_set_method.3 RSA_sign.3 RSA_sign_ASN1_OCTET_STRING.3 RSA_size.3 - -MAN+= SMIME_read_CMS.3 SMIME_read_PKCS7.3 SMIME_write_CMS.3 \ - SMIME_write_PKCS7.3 - -MAN+= X509_NAME_ENTRY_get_object.3 X509_NAME_add_entry_by_txt.3 \ - X509_NAME_get_index_by_NID.3 X509_NAME_print_ex.3 \ - X509_STORE_CTX_get_error.3 X509_STORE_CTX_get_ex_new_index.3 \ - X509_STORE_CTX_new.3 X509_STORE_CTX_set_verify_cb.3 \ - X509_STORE_set_verify_cb_func.3 X509_VERIFY_PARAM_set_flags.3 \ - X509_new.3 X509_verify_cert.3 - -MAN+= d2i_ASN1_OBJECT.3 d2i_DHparams.3 d2i_DSAPublicKey.3 \ - d2i_PKCS8PrivateKey.3 d2i_RSAPublicKey.3 d2i_X509.3 d2i_X509_ALGOR.3 \ - d2i_X509_CRL.3 d2i_X509_NAME.3 d2i_X509_REQ.3 d2i_X509_SIG.3 - -MAN+= i2d_CMS_bio_stream.3 i2d_PKCS7_bio_stream.3 - -MAN+= bio.3 blowfish.3 bn.3 bn_internal.3 buffer.3 crypto.3 des.3 \ - des_modes.3 dh.3 dsa.3 ecdsa.3 engine.3 err.3 evp.3 hmac.3 lh_stats.3 \ - lhash.3 md5.3 mdc2.3 pem.3 rand.3 rc4.3 ripemd.3 rsa.3 sha.3 threads.3 \ - ui.3 ui_compat.3 x509.3 - -# libssl -MAN+= SSL_CIPHER_get_name.3 SSL_COMP_add_compression_method.3 \ - SSL_CTX_add_extra_chain_cert.3 SSL_CTX_add_session.3 SSL_CTX_ctrl.3 \ - SSL_CTX_flush_sessions.3 SSL_CTX_free.3 SSL_CTX_get_ex_new_index.3 \ - SSL_CTX_get_verify_mode.3 SSL_CTX_load_verify_locations.3 \ - SSL_CTX_new.3 SSL_CTX_sess_number.3 SSL_CTX_sess_set_cache_size.3 \ - SSL_CTX_sess_set_get_cb.3 SSL_CTX_sessions.3 SSL_CTX_set_cert_store.3 \ - SSL_CTX_set_cert_verify_callback.3 SSL_CTX_set_cipher_list.3 \ - SSL_CTX_set_client_CA_list.3 SSL_CTX_set_client_cert_cb.3 \ - SSL_CTX_set_default_passwd_cb.3 SSL_CTX_set_generate_session_id.3 \ - SSL_CTX_set_info_callback.3 SSL_CTX_set_max_cert_list.3 \ - SSL_CTX_set_mode.3 SSL_CTX_set_msg_callback.3 SSL_CTX_set_options.3 \ - SSL_CTX_set_psk_client_callback.3 SSL_CTX_set_quiet_shutdown.3 \ - SSL_CTX_set_session_cache_mode.3 SSL_CTX_set_session_id_context.3 \ - SSL_CTX_set_ssl_version.3 SSL_CTX_set_timeout.3 \ - SSL_CTX_set_tmp_dh_callback.3 SSL_CTX_set_tmp_rsa_callback.3 \ - SSL_CTX_set_verify.3 SSL_CTX_use_certificate.3 \ - SSL_CTX_use_psk_identity_hint.3 SSL_SESSION_free.3 \ - SSL_SESSION_get_ex_new_index.3 SSL_SESSION_get_time.3 SSL_accept.3 \ - SSL_alert_type_string.3 SSL_clear.3 SSL_connect.3 SSL_do_handshake.3 \ - SSL_free.3 SSL_get_SSL_CTX.3 SSL_get_ciphers.3 \ - SSL_get_client_CA_list.3 SSL_get_current_cipher.3 \ - SSL_get_default_timeout.3 SSL_get_error.3 \ - SSL_get_ex_data_X509_STORE_CTX_idx.3 SSL_get_ex_new_index.3 \ - SSL_get_fd.3 SSL_get_peer_cert_chain.3 SSL_get_peer_certificate.3 \ - SSL_get_psk_identity.3 SSL_get_rbio.3 SSL_get_session.3 \ - SSL_get_verify_result.3 SSL_get_version.3 SSL_library_init.3 \ - SSL_load_client_CA_file.3 SSL_new.3 SSL_pending.3 SSL_read.3 \ - SSL_rstate_string.3 SSL_session_reused.3 SSL_set_bio.3 \ - SSL_set_connect_state.3 SSL_set_fd.3 SSL_set_session.3 \ - SSL_set_shutdown.3 SSL_set_verify_result.3 SSL_shutdown.3 \ - SSL_state_string.3 SSL_want.3 SSL_write.3 \ - d2i_SSL_SESSION.3 ssl.3 +MAN= \ + BIO_f_ssl.3 \ + SSL_CIPHER_get_name.3 \ + SSL_COMP_add_compression_method.3 \ + SSL_CTX_add_extra_chain_cert.3 \ + SSL_CTX_add_session.3 \ + SSL_CTX_ctrl.3 \ + SSL_CTX_flush_sessions.3 \ + SSL_CTX_free.3 \ + SSL_CTX_get_ex_new_index.3 \ + SSL_CTX_get_verify_mode.3 \ + SSL_CTX_load_verify_locations.3 \ + SSL_CTX_new.3 \ + SSL_CTX_sess_number.3 \ + SSL_CTX_sess_set_cache_size.3 \ + SSL_CTX_sess_set_get_cb.3 \ + SSL_CTX_sessions.3 \ + SSL_CTX_set_cert_store.3 \ + SSL_CTX_set_cert_verify_callback.3 \ + SSL_CTX_set_cipher_list.3 \ + SSL_CTX_set_client_CA_list.3 \ + SSL_CTX_set_client_cert_cb.3 \ + SSL_CTX_set_default_passwd_cb.3 \ + SSL_CTX_set_generate_session_id.3 \ + SSL_CTX_set_info_callback.3 \ + SSL_CTX_set_max_cert_list.3 \ + SSL_CTX_set_mode.3 \ + SSL_CTX_set_msg_callback.3 \ + SSL_CTX_set_options.3 \ + SSL_CTX_set_psk_client_callback.3 \ + SSL_CTX_set_quiet_shutdown.3 \ + SSL_CTX_set_session_cache_mode.3 \ + SSL_CTX_set_session_id_context.3 \ + SSL_CTX_set_ssl_version.3 \ + SSL_CTX_set_timeout.3 \ + SSL_CTX_set_tmp_dh_callback.3 \ + SSL_CTX_set_tmp_rsa_callback.3 \ + SSL_CTX_set_verify.3 \ + SSL_CTX_use_certificate.3 \ + SSL_CTX_use_psk_identity_hint.3 \ + SSL_SESSION_free.3 \ + SSL_SESSION_get_ex_new_index.3 \ + SSL_SESSION_get_time.3 \ + SSL_accept.3 \ + SSL_alert_type_string.3 \ + SSL_clear.3 \ + SSL_connect.3 \ + SSL_do_handshake.3 \ + SSL_free.3 \ + SSL_get_SSL_CTX.3 \ + SSL_get_ciphers.3 \ + SSL_get_client_CA_list.3 \ + SSL_get_current_cipher.3 \ + SSL_get_default_timeout.3 \ + SSL_get_error.3 \ + SSL_get_ex_data_X509_STORE_CTX_idx.3 \ + SSL_get_ex_new_index.3 \ + SSL_get_fd.3 \ + SSL_get_peer_cert_chain.3 \ + SSL_get_peer_certificate.3 \ + SSL_get_psk_identity.3 \ + SSL_get_rbio.3 \ + SSL_get_session.3 \ + SSL_get_verify_result.3 \ + SSL_get_version.3 \ + SSL_library_init.3 \ + SSL_load_client_CA_file.3 \ + SSL_new.3 \ + SSL_pending.3 \ + SSL_read.3 \ + SSL_rstate_string.3 \ + SSL_session_reused.3 \ + SSL_set_bio.3 \ + SSL_set_connect_state.3 \ + SSL_set_fd.3 \ + SSL_set_session.3 \ + SSL_set_shutdown.3 \ + SSL_set_verify_result.3 \ + SSL_shutdown.3 \ + SSL_state_string.3 \ + SSL_want.3 \ + SSL_write.3 \ + d2i_SSL_SESSION.3 \ + ssl.3 \ # XXX ERR_load_crypto_strings.3 built by libcrypto MLINKS+=\ @@ -282,9 +247,7 @@ maninstall: .endif -# XXX .PATH order is critical because of non-unique filenames -# XXX doc/crypto because of BIO_f_ssl() -.PATH: ${.CURDIR}/../src/doc/crypto ${.CURDIR}/../src/doc/ssl +.PATH: ${.CURDIR}/../src/doc/ssl .SUFFIXES: .pod .1 .3 .7 .for sect in 1 3 7 .pod.${sect}: diff --git a/src/lib/libssl/src/doc/crypto/BF_set_key.pod b/src/lib/libssl/src/doc/crypto/BF_set_key.pod new file mode 100644 index 0000000000..5b2d274c15 --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/BF_set_key.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, +BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption + +=head1 SYNOPSIS + + #include + + void BF_set_key(BF_KEY *key, int len, const unsigned char *data); + + void BF_ecb_encrypt(const unsigned char *in, unsigned char *out, + BF_KEY *key, int enc); + void BF_cbc_encrypt(const unsigned char *in, unsigned char *out, + long length, BF_KEY *schedule, unsigned char *ivec, int enc); + void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out, + long length, BF_KEY *schedule, unsigned char *ivec, int *num, + int enc); + void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out, + long length, BF_KEY *schedule, unsigned char *ivec, int *num); + const char *BF_options(void); + + void BF_encrypt(BF_LONG *data,const BF_KEY *key); + void BF_decrypt(BF_LONG *data,const BF_KEY *key); + +=head1 DESCRIPTION + +This library implements the Blowfish cipher, which was invented and described +by Counterpane (see http://www.counterpane.com/blowfish.html ). + +Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. +It uses a variable size key, but typically, 128 bit (16 byte) keys are +considered good for strong encryption. Blowfish can be used in the same +modes as DES (see L). Blowfish is currently one +of the faster block ciphers. It is quite a bit faster than DES, and much +faster than IDEA or RC2. + +Blowfish consists of a key setup phase and the actual encryption or decryption +phase. + +BF_set_key() sets up the B B using the B bytes long key +at B. + +BF_ecb_encrypt() is the basic Blowfish encryption and decryption function. +It encrypts or decrypts the first 64 bits of B using the key B, +putting the result in B. B decides if encryption (B) +or decryption (B) shall be performed. The vector pointed at by +B and B must be 64 bits in length, no less. If they are larger, +everything after the first 64 bits is ignored. + +The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt() +all operate on variable length data. They all take an initialization vector +B which needs to be passed along into the next call of the same function +for the same message. B may be initialized with anything, but the +recipient needs to know what it was initialized with, or it won't be able +to decrypt. Some programs and protocols simplify this, like SSH, where +B is simply initialized to zero. +BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while +BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable +number of bytes (the amount does not have to be an exact multiple of 8). The +purpose of the latter two is to simulate stream ciphers, and therefore, they +need the parameter B, which is a pointer to an integer where the current +offset in B is stored between calls. This integer must be initialized +to zero when B is initialized. + +BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It +encrypts or decrypts the 64 bits chunks of B using the key B, +putting the result in B. B decides if encryption (BF_ENCRYPT) or +decryption (BF_DECRYPT) shall be performed. B must point at an 8 byte +long initialization vector. + +BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback. +It encrypts or decrypts the bytes in B using the key B, +putting the result in B. B decides if encryption (B) +or decryption (B) shall be performed. B must point at an +8 byte long initialization vector. B must point at an integer which must +be initially zero. + +BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback. +It uses the same parameters as BF_cfb64_encrypt(), which must be initialized +the same way. + +BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish +encryption. They encrypt/decrypt the first 64 bits of the vector pointed by +B, using the key B. These functions should not be used unless you +implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt(). +If you still want to use these functions, you should be aware that they take +each 32-bit chunk in host-byte order, which is little-endian on little-endian +platforms and big-endian on big-endian ones. + +=head1 RETURN VALUES + +None of the functions presented here return any value. + +=head1 NOTE + +Applications should use the higher level functions +L etc. instead of calling the +blowfish functions directly. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The Blowfish functions are available in all versions of SSLeay and OpenSSL. + +=cut + diff --git a/src/lib/libssl/src/doc/crypto/BIO.pod b/src/lib/libssl/src/doc/crypto/BIO.pod new file mode 100644 index 0000000000..f9239226ff --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/BIO.pod @@ -0,0 +1,54 @@ +=pod + +=head1 NAME + +bio - I/O abstraction + +=head1 SYNOPSIS + + #include + +TBA + + +=head1 DESCRIPTION + +A BIO is an I/O abstraction, it hides many of the underlying I/O +details from an application. If an application uses a BIO for its +I/O it can transparently handle SSL connections, unencrypted network +connections and file I/O. + +There are two type of BIO, a source/sink BIO and a filter BIO. + +As its name implies a source/sink BIO is a source and/or sink of data, +examples include a socket BIO and a file BIO. + +A filter BIO takes data from one BIO and passes it through to +another, or the application. The data may be left unmodified (for +example a message digest BIO) or translated (for example an +encryption BIO). The effect of a filter BIO may change according +to the I/O operation it is performing: for example an encryption +BIO will encrypt data if it is being written to and decrypt data +if it is being read from. + +BIOs can be joined together to form a chain (a single BIO is a chain +with one component). A chain normally consist of one source/sink +BIO and one or more filter BIOs. Data read from or written to the +first BIO then traverses the chain to the end (normally a source/sink +BIO). + +=head1 SEE ALSO + +L, +L, L, +L, L, +L, L, +L, L, +L, +L, L, +L, L, +L, L, +L, L, +L, L, +L, +L diff --git a/src/lib/libssl/src/doc/crypto/BIO_f_ssl.pod b/src/lib/libssl/src/doc/crypto/BIO_f_ssl.pod deleted file mode 100644 index bc5861ab34..0000000000 --- a/src/lib/libssl/src/doc/crypto/BIO_f_ssl.pod +++ /dev/null @@ -1,322 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, -BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, -BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, -BIO_ssl_shutdown - SSL BIO - -=head1 SYNOPSIS - - #include - #include - - BIO_METHOD *BIO_f_ssl(void); - - #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) - #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) - #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) - #define BIO_set_ssl_renegotiate_bytes(b,num) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); - #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); - #define BIO_get_num_renegotiates(b) \ - BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); - - BIO *BIO_new_ssl(SSL_CTX *ctx,int client); - BIO *BIO_new_ssl_connect(SSL_CTX *ctx); - BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); - int BIO_ssl_copy_session_id(BIO *to,BIO *from); - void BIO_ssl_shutdown(BIO *bio); - - #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) - -=head1 DESCRIPTION - -BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which -is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to -SSL I/O. - -I/O performed on an SSL BIO communicates using the SSL protocol with -the SSLs read and write BIOs. If an SSL connection is not established -then an attempt is made to establish one on the first I/O call. - -If a BIO is appended to an SSL BIO using BIO_push() it is automatically -used as the SSL BIOs read and write BIOs. - -Calling BIO_reset() on an SSL BIO closes down any current SSL connection -by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in -the chain: this will typically disconnect the underlying transport. -The SSL BIO is then reset to the initial accept or connect state. - -If the close flag is set when an SSL BIO is freed then the internal -SSL structure is also freed using SSL_free(). - -BIO_set_ssl() sets the internal SSL pointer of BIO B to B using -the close flag B. - -BIO_get_ssl() retrieves the SSL pointer of BIO B, it can then be -manipulated using the standard SSL library functions. - -BIO_set_ssl_mode() sets the SSL BIO mode to B. If B -is 1 client mode is set. If B is 0 server mode is set. - -BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count -to B. When set after every B bytes of I/O (read and write) -the SSL session is automatically renegotiated. B must be at -least 512 bytes. - -BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to -B. When the renegotiate timeout elapses the session is -automatically renegotiated. - -BIO_get_num_renegotiates() returns the total number of session -renegotiations due to I/O or timeout. - -BIO_new_ssl() allocates an SSL BIO using SSL_CTX B and using -client mode if B is non zero. - -BIO_new_ssl_connect() creates a new BIO chain consisting of an -SSL BIO (using B) followed by a connect BIO. - -BIO_new_buffer_ssl_connect() creates a new BIO chain consisting -of a buffering BIO, an SSL BIO (using B) and a connect -BIO. - -BIO_ssl_copy_session_id() copies an SSL session id between -BIO chains B and B. It does this by locating the -SSL BIOs in each chain and calling SSL_copy_session_id() on -the internal SSL pointer. - -BIO_ssl_shutdown() closes down an SSL connection on BIO -chain B. It does this by locating the SSL BIO in the -chain and calling SSL_shutdown() on its internal SSL -pointer. - -BIO_do_handshake() attempts to complete an SSL handshake on the -supplied BIO and establish the SSL connection. It returns 1 -if the connection was established successfully. A zero or negative -value is returned if the connection could not be established, the -call BIO_should_retry() should be used for non blocking connect BIOs -to determine if the call should be retried. If an SSL connection has -already been established this call has no effect. - -=head1 NOTES - -SSL BIOs are exceptional in that if the underlying transport -is non blocking they can still request a retry in exceptional -circumstances. Specifically this will happen if a session -renegotiation takes place during a BIO_read() operation, one -case where this happens is when SGC or step up occurs. - -In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be -set to disable this behaviour. That is when this flag is set -an SSL BIO using a blocking transport will never request a -retry. - -Since unknown BIO_ctrl() operations are sent through filter -BIOs the servers name and port can be set using BIO_set_host() -on the BIO returned by BIO_new_ssl_connect() without having -to locate the connect BIO first. - -Applications do not have to call BIO_do_handshake() but may wish -to do so to separate the handshake process from other I/O -processing. - -=head1 RETURN VALUES - -TBA - -=head1 EXAMPLE - -This SSL/TLS client example, attempts to retrieve a page from an -SSL/TLS web server. The I/O routines are identical to those of the -unencrypted example in L. - - BIO *sbio, *out; - int len; - char tmpbuf[1024]; - SSL_CTX *ctx; - SSL *ssl; - - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); - - /* We would seed the PRNG here if the platform didn't - * do it automatically - */ - - ctx = SSL_CTX_new(SSLv23_client_method()); - - /* We'd normally set some stuff like the verify paths and - * mode here because as things stand this will connect to - * any server whose certificate is signed by any CA. - */ - - sbio = BIO_new_ssl_connect(ctx); - - BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ - } - - /* Don't want any retries */ - SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - - /* We might want to do other things with ssl here */ - - BIO_set_conn_hostname(sbio, "localhost:https"); - - out = BIO_new_fp(stdout, BIO_NOCLOSE); - if(BIO_do_connect(sbio) <= 0) { - fprintf(stderr, "Error connecting to server\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error establishing SSL connection\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - - /* Could examine ssl here to get connection info */ - - BIO_puts(sbio, "GET / HTTP/1.0\n\n"); - for(;;) { - len = BIO_read(sbio, tmpbuf, 1024); - if(len <= 0) break; - BIO_write(out, tmpbuf, len); - } - BIO_free_all(sbio); - BIO_free(out); - -Here is a simple server example. It makes use of a buffering -BIO to allow lines to be read from the SSL BIO using BIO_gets. -It creates a pseudo web page containing the actual request from -a client and also echoes the request to standard output. - - BIO *sbio, *bbio, *acpt, *out; - int len; - char tmpbuf[1024]; - SSL_CTX *ctx; - SSL *ssl; - - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); - - /* Might seed PRNG here */ - - ctx = SSL_CTX_new(SSLv23_server_method()); - - if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) - || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) - || !SSL_CTX_check_private_key(ctx)) { - - fprintf(stderr, "Error setting up SSL_CTX\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* Might do other things here like setting verify locations and - * DH and/or RSA temporary key callbacks - */ - - /* New SSL BIO setup as server */ - sbio=BIO_new_ssl(ctx,0); - - BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ - } - - /* Don't want any retries */ - SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - - /* Create the buffering BIO */ - - bbio = BIO_new(BIO_f_buffer()); - - /* Add to chain */ - sbio = BIO_push(bbio, sbio); - - acpt=BIO_new_accept("4433"); - - /* By doing this when a new connection is established - * we automatically have sbio inserted into it. The - * BIO chain is now 'swallowed' by the accept BIO and - * will be freed when the accept BIO is freed. - */ - - BIO_set_accept_bios(acpt,sbio); - - out = BIO_new_fp(stdout, BIO_NOCLOSE); - - /* Setup accept BIO */ - if(BIO_do_accept(acpt) <= 0) { - fprintf(stderr, "Error setting up accept BIO\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* Now wait for incoming connection */ - if(BIO_do_accept(acpt) <= 0) { - fprintf(stderr, "Error in connection\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* We only want one connection so remove and free - * accept BIO - */ - - sbio = BIO_pop(acpt); - - BIO_free_all(acpt); - - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error in SSL handshake\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n"); - BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n"); - BIO_puts(sbio, "--------------------------------------------------\r\n"); - - for(;;) { - len = BIO_gets(sbio, tmpbuf, 1024); - if(len <= 0) break; - BIO_write(sbio, tmpbuf, len); - BIO_write(out, tmpbuf, len); - /* Look for blank line signifying end of headers*/ - if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break; - } - - BIO_puts(sbio, "--------------------------------------------------\r\n"); - BIO_puts(sbio, "\r\n"); - - /* Since there is a buffering BIO present we had better flush it */ - BIO_flush(sbio); - - BIO_free_all(sbio); - -=head1 BUGS - -In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly, -the I/O BIO reference count was incorrectly incremented (instead of -decremented) and dissociated with the SSL BIO even if the SSL BIO was not -explicitly being popped (e.g. a pop higher up the chain). Applications which -included workarounds for this bug (e.g. freeing BIOs more than once) should -be modified to handle this fix or they may free up an already freed BIO. - -=head1 SEE ALSO - -TBA diff --git a/src/lib/libssl/src/doc/crypto/BUF_MEM_new.pod b/src/lib/libssl/src/doc/crypto/BUF_MEM_new.pod new file mode 100644 index 0000000000..781f5b11ee --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/BUF_MEM_new.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple +character arrays structure + +=head1 SYNOPSIS + + #include + + BUF_MEM *BUF_MEM_new(void); + + void BUF_MEM_free(BUF_MEM *a); + + int BUF_MEM_grow(BUF_MEM *str, int len); + + char * BUF_strdup(const char *str); + +=head1 DESCRIPTION + +The buffer library handles simple character arrays. Buffers are used for +various purposes in the library, most notably memory BIOs. + +The library uses the BUF_MEM structure defined in buffer.h: + + typedef struct buf_mem_st + { + int length; /* current number of bytes */ + char *data; + int max; /* size of buffer */ + } BUF_MEM; + +B is the current size of the buffer in bytes, B is the amount of +memory allocated to the buffer. There are three functions which handle these +and one "miscellaneous" function. + +BUF_MEM_new() allocates a new buffer of zero size. + +BUF_MEM_free() frees up an already existing buffer. The data is zeroed +before freeing up in case the buffer contains sensitive data. + +BUF_MEM_grow() changes the size of an already existing buffer to +B. Any data already in the buffer is preserved if it increases in +size. + +BUF_strdup() copies a null terminated string into a block of allocated +memory and returns a pointer to the allocated block. +Unlike the standard C library strdup() this function uses OPENSSL_malloc() and so +should be used in preference to the standard library strdup() because it can +be used for memory leak checking or replacing the malloc() function. + +The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free() +function. + +=head1 RETURN VALUES + +BUF_MEM_new() returns the buffer or NULL on error. + +BUF_MEM_free() has no return value. + +BUF_MEM_grow() returns zero on error or the new size (i.e. B). + +=head1 SEE ALSO + +L + +=head1 HISTORY + +BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all +versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8. + +=cut diff --git a/src/lib/libssl/src/doc/crypto/CRYPTO_set_locking_callback.pod b/src/lib/libssl/src/doc/crypto/CRYPTO_set_locking_callback.pod new file mode 100644 index 0000000000..dc0e9391dc --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/CRYPTO_set_locking_callback.pod @@ -0,0 +1,210 @@ +=pod + +=head1 NAME + +CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback, +CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy, +CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks, +CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, +CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, +CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support + +=head1 SYNOPSIS + + #include + + /* Don't use this structure directly. */ + typedef struct crypto_threadid_st + { + void *ptr; + unsigned long val; + } CRYPTO_THREADID; + /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ + void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val); + void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr); + int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *)); + void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *); + void CRYPTO_THREADID_current(CRYPTO_THREADID *id); + int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a, + const CRYPTO_THREADID *b); + void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest, + const CRYPTO_THREADID *src); + unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id); + + int CRYPTO_num_locks(void); + + /* struct CRYPTO_dynlock_value needs to be defined by the user */ + struct CRYPTO_dynlock_value; + + void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * + (*dyn_create_function)(char *file, int line)); + void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) + (int mode, struct CRYPTO_dynlock_value *l, + const char *file, int line)); + void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) + (struct CRYPTO_dynlock_value *l, const char *file, int line)); + + int CRYPTO_get_new_dynlockid(void); + + void CRYPTO_destroy_dynlockid(int i); + + void CRYPTO_lock(int mode, int n, const char *file, int line); + + #define CRYPTO_w_lock(type) \ + CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) + #define CRYPTO_w_unlock(type) \ + CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) + #define CRYPTO_r_lock(type) \ + CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) + #define CRYPTO_r_unlock(type) \ + CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) + #define CRYPTO_add(addr,amount,type) \ + CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) + +=head1 DESCRIPTION + +OpenSSL can safely be used in multi-threaded applications provided +that at least two callback functions are set, locking_function and +threadid_func. + +locking_function(int mode, int n, const char *file, int line) is +needed to perform locking on shared data structures. +(Note that OpenSSL uses a number of global data structures that +will be implicitly shared whenever multiple threads use OpenSSL.) +Multi-threaded applications will crash at random if it is not set. + +locking_function() must be able to handle up to CRYPTO_num_locks() +different mutex locks. It sets the B-th lock if B & +B, and releases it otherwise. + +B and B are the file number of the function setting the +lock. They can be useful for debugging. + +threadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing +thread's identifier into B. The implementation of this callback should not +fill in B directly, but should use CRYPTO_THREADID_set_numeric() if thread +IDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based. +If the application does not register such a callback using +CRYPTO_THREADID_set_callback(), then a default implementation is used - on +Windows and BeOS this uses the system's default thread identifying APIs, and on +all other platforms it uses the address of B. The latter is satisfactory +for thread-safety if and only if the platform has a thread-local error number +facility. + +Once threadid_func() is registered, or if the built-in default implementation is +to be used; + +=over 4 + +=item * +CRYPTO_THREADID_current() records the currently-executing thread ID into the +given B object. + +=item * +CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie. +the same semantics as memcmp()). + +=item * +CRYPTO_THREADID_cpy() duplicates a thread ID value, + +=item * +CRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This +is usually the exact numeric or pointer-based thread ID used internally, however +this also handles the unusual case where pointers are larger than 'long' +variables and the platform's thread IDs are pointer-based - in this case, mixing +is done to attempt to produce a unique numeric value even though it is not as +wide as the platform's true thread IDs. + +=back + +Additionally, OpenSSL supports dynamic locks, and sometimes, some parts +of OpenSSL need it for better performance. To enable this, the following +is required: + +=over 4 + +=item * +Three additional callback function, dyn_create_function, dyn_lock_function +and dyn_destroy_function. + +=item * +A structure defined with the data that each lock needs to handle. + +=back + +struct CRYPTO_dynlock_value has to be defined to contain whatever structure +is needed to handle locks. + +dyn_create_function(const char *file, int line) is needed to create a +lock. Multi-threaded applications might crash at random if it is not set. + +dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) +is needed to perform locking off dynamic lock numbered n. Multi-threaded +applications might crash at random if it is not set. + +dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is +needed to destroy the lock l. Multi-threaded applications might crash at +random if it is not set. + +CRYPTO_get_new_dynlockid() is used to create locks. It will call +dyn_create_function for the actual creation. + +CRYPTO_destroy_dynlockid() is used to destroy locks. It will call +dyn_destroy_function for the actual destruction. + +CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield +describing what should be done with the lock. n is the number of the +lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined +from the following values. These values are pairwise exclusive, with +undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE +should not be used together): + + CRYPTO_LOCK 0x01 + CRYPTO_UNLOCK 0x02 + CRYPTO_READ 0x04 + CRYPTO_WRITE 0x08 + +=head1 RETURN VALUES + +CRYPTO_num_locks() returns the required number of locks. + +CRYPTO_get_new_dynlockid() returns the index to the newly created lock. + +The other functions return no values. + +=head1 NOTES + +You can find out if OpenSSL was configured with thread support: + + #define OPENSSL_THREAD_DEFINES + #include + #if defined(OPENSSL_THREADS) + // thread support enabled + #else + // no thread support + #endif + +Also, dynamic locks are currently not used internally by OpenSSL, but +may do so in the future. + +=head1 EXAMPLES + +B shows examples of the callback functions on +Solaris, Irix and Win32. + +=head1 HISTORY + +CRYPTO_set_locking_callback() is +available in all versions of SSLeay and OpenSSL. +CRYPTO_num_locks() was added in OpenSSL 0.9.4. +All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. +B and associated functions were introduced in OpenSSL 1.0.0 +to replace (actually, deprecate) the previous CRYPTO_set_id_callback(), +CRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed +thread IDs to always be represented by 'unsigned long'. + +=head1 SEE ALSO + +L + +=cut diff --git a/src/lib/libssl/src/doc/crypto/DES_set_key.pod b/src/lib/libssl/src/doc/crypto/DES_set_key.pod new file mode 100644 index 0000000000..6f0cf1cc5e --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/DES_set_key.pod @@ -0,0 +1,358 @@ +=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. The PRNG must be seeded +prior to using this function (see L). If the PRNG +could not generate a secure key, 0 is returned. + +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 probability that a randomly generated key is weak is +1/2^52, so it is not really worth checking for them. + +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; see L. + +The L library provides higher-level encryption functions. + +=head1 BUGS + +DES_3cbc_encrypt() is flawed and must not be used in applications. + +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 written to be source code compatible with +the MIT Kerberos library. + +=head1 SEE ALSO + +crypt(3), L, L, L + +=head1 HISTORY + +In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid +clashes with older versions of libdes. Compatibility des_ functions +are provided for a short while, as well as crypt(). +Declarations for these are in . There is no DES_ +variant for des_random_seed(). +This will happen to other functions +as well if they are deemed redundant (des_random_seed() just calls +RAND_seed() and is present for backward compatibility only), buggy or +already scheduled for removal. + +des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(), +des_is_weak_key(), des_key_sched(), des_pcbc_encrypt(), +des_quad_cksum(), des_random_key() and des_string_to_key() +are available in the MIT Kerberos library; +des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key() +are available in newer versions of that library. + +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/libssl/src/doc/crypto/ERR.pod b/src/lib/libssl/src/doc/crypto/ERR.pod new file mode 100644 index 0000000000..6f729554d2 --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/ERR.pod @@ -0,0 +1,187 @@ +=pod + +=head1 NAME + +err - error codes + +=head1 SYNOPSIS + + #include + + unsigned long ERR_get_error(void); + unsigned long ERR_peek_error(void); + unsigned long ERR_get_error_line(const char **file, int *line); + unsigned long ERR_peek_error_line(const char **file, int *line); + unsigned long ERR_get_error_line_data(const char **file, int *line, + const char **data, int *flags); + unsigned long ERR_peek_error_line_data(const char **file, int *line, + const char **data, int *flags); + + int ERR_GET_LIB(unsigned long e); + int ERR_GET_FUNC(unsigned long e); + int ERR_GET_REASON(unsigned long e); + + void ERR_clear_error(void); + + char *ERR_error_string(unsigned long e, char *buf); + const char *ERR_lib_error_string(unsigned long e); + const char *ERR_func_error_string(unsigned long e); + const char *ERR_reason_error_string(unsigned long e); + + void ERR_print_errors(BIO *bp); + void ERR_print_errors_fp(FILE *fp); + + void ERR_load_crypto_strings(void); + void ERR_free_strings(void); + + void ERR_remove_state(unsigned long pid); + + void ERR_put_error(int lib, int func, int reason, const char *file, + int line); + void ERR_add_error_data(int num, ...); + + void ERR_load_strings(int lib,ERR_STRING_DATA str[]); + unsigned long ERR_PACK(int lib, int func, int reason); + int ERR_get_next_error_library(void); + +=head1 DESCRIPTION + +When a call to the OpenSSL library fails, this is usually signalled +by the return value, and an error code is stored in an error queue +associated with the current thread. The B library provides +functions to obtain these error codes and textual error messages. + +The L manpage describes how to +access error codes. + +Error codes contain information about where the error occurred, and +what went wrong. L describes how to +extract this information. A method to obtain human-readable error +messages is described in L. + +L can be used to clear the +error queue. + +Note that L should be used to +avoid memory leaks when threads are terminated. + +=head1 ADDING NEW ERROR CODES TO OPENSSL + +See L if you want to record error codes in the +OpenSSL error system from within your application. + +The remainder of this section is of interest only if you want to add +new error codes to OpenSSL or add error codes from external libraries. + +=head2 Reporting errors + +Each sub-library has a specific macro XXXerr() that is used to report +errors. Its first argument is a function code B, the second +argument is a reason code B. Function codes are derived +from the function names; reason codes consist of textual error +descriptions. For example, the function ssl23_read() reports a +"handshake failure" as follows: + + SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); + +Function and reason codes should consist of upper case characters, +numbers and underscores only. The error file generation script translates +function codes into function names by looking in the header files +for an appropriate function name, if none is found it just uses +the capitalized form such as "SSL23_READ" in the above example. + +The trailing section of a reason code (after the "_R_") is translated +into lower case and underscores changed to spaces. + +When you are using new function or reason codes, run B. +The necessary B<#define>s will then automatically be added to the +sub-library's header file. + +Although a library will normally report errors using its own specific +XXXerr macro, another library's macro can be used. This is normally +only done when a library wants to include ASN1 code which must use +the ASN1err() macro. + +=head2 Adding new libraries + +When adding a new sub-library to OpenSSL, assign it a library number +B, define a macro XXXerr() (both in B), add its +name to B (in B), and add +C to the ERR_load_crypto_strings() function +(in B). Finally, add an entry + + L XXX xxx.h xxx_err.c + +to B, and add B to the Makefile. +Running B will then generate a file B, and +add all error codes used in the library to B. + +Additionally the library include file must have a certain form. +Typically it will initially look like this: + + #ifndef HEADER_XXX_H + #define HEADER_XXX_H + + #ifdef __cplusplus + extern "C" { + #endif + + /* Include files */ + + #include + #include + + /* Macros, structures and function prototypes */ + + + /* BEGIN ERROR CODES */ + +The B sequence is used by the error code +generation script as the point to place new error codes, any text +after this point will be overwritten when B is run. +The closing #endif etc will be automatically added by the script. + +The generated C error code file B will load the header +files B, B and B so the +header file must load any additional header files containing any +definitions it uses. + +=head1 USING ERROR CODES IN EXTERNAL LIBRARIES + +It is also possible to use OpenSSL's error code scheme in external +libraries. The library needs to load its own codes and call the OpenSSL +error code insertion script B explicitly to add codes to +the header file and generate the C error code file. This will normally +be done if the external library needs to generate new ASN1 structures +but it can also be used to add more general purpose error code handling. + +TBA more details + +=head1 INTERNALS + +The error queues are stored in a hash table with one B +entry for each pid. ERR_get_state() returns the current thread's +B. An B can hold up to B error +codes. When more error codes are added, the old ones are overwritten, +on the assumption that the most recent errors are most important. + +Error strings are also stored in hash table. The hash tables can +be obtained by calling ERR_get_err_state_table(void) and +ERR_get_string_table(void) respectively. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=cut diff --git a/src/lib/libssl/src/doc/crypto/HMAC.pod b/src/lib/libssl/src/doc/crypto/HMAC.pod new file mode 100644 index 0000000000..d92138d273 --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/HMAC.pod @@ -0,0 +1,106 @@ +=pod + +=head1 NAME + +HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message +authentication code + +=head1 SYNOPSIS + + #include + + unsigned char *HMAC(const EVP_MD *evp_md, const void *key, + int key_len, const unsigned char *d, int n, + unsigned char *md, unsigned int *md_len); + + void HMAC_CTX_init(HMAC_CTX *ctx); + + int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, + const EVP_MD *md); + int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, + const EVP_MD *md, ENGINE *impl); + int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); + int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); + + void HMAC_CTX_cleanup(HMAC_CTX *ctx); + void HMAC_cleanup(HMAC_CTX *ctx); + +=head1 DESCRIPTION + +HMAC is a MAC (message authentication code), i.e. a keyed hash +function used for message authentication, which is based on a hash +function. + +HMAC() computes the message authentication code of the B bytes at +B using the hash function B and the key B which is +B bytes long. + +It places the result in B (which must have space for the output of +the hash function, which is no more than B bytes). +If B is NULL, the digest is placed in a static array. The size of +the output is placed in B, unless it is B. + +B can be EVP_sha1(), EVP_ripemd160() etc. + +HMAC_CTX_init() initialises a B before first use. It must be +called. + +HMAC_CTX_cleanup() erases the key and other data from the B +and releases any associated resources. It must be called when an +B is no longer required. + +HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back +compatibility with 0.9.6b, it is deprecated. + +The following functions may be used if the message is not completely +stored in memory: + +HMAC_Init() initializes a B structure to use the hash +function B and the key B which is B bytes +long. It is deprecated and only included for backward compatibility +with OpenSSL 0.9.6b. + +HMAC_Init_ex() initializes or reuses a B structure to use +the function B and key B. Either can be NULL, in which +case the existing one will be reused. HMAC_CTX_init() must have been +called before the first use of an B in this +function. B. + +HMAC_Update() can be called repeatedly with chunks of the message to +be authenticated (B bytes at B). + +HMAC_Final() places the message authentication code in B, which +must have space for the hash function output. + +=head1 RETURN VALUES + +HMAC() returns a pointer to the message authentication code or NULL if +an error occurred. + +HMAC_Init_ex(), HMAC_Update() and HMAC_Final() return 1 for success or 0 if +an error occurred. + +HMAC_CTX_init() and HMAC_CTX_cleanup() do not return values. + +=head1 CONFORMING TO + +RFC 2104 + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() +are available since SSLeay 0.9.0. + +HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available +since OpenSSL 0.9.7. + +HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in +versions of OpenSSL before 1.0.0. + +=cut diff --git a/src/lib/libssl/src/doc/crypto/MD5.pod b/src/lib/libssl/src/doc/crypto/MD5.pod new file mode 100644 index 0000000000..d11d5c32cb --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/MD5.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + +MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, +MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions + +=head1 SYNOPSIS + + #include + + unsigned char *MD2(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MD2_Init(MD2_CTX *c); + int MD2_Update(MD2_CTX *c, const unsigned char *data, + unsigned long len); + int MD2_Final(unsigned char *md, MD2_CTX *c); + + + #include + + unsigned char *MD4(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MD4_Init(MD4_CTX *c); + int MD4_Update(MD4_CTX *c, const void *data, + unsigned long len); + int MD4_Final(unsigned char *md, MD4_CTX *c); + + + #include + + unsigned char *MD5(const unsigned char *d, unsigned long n, + unsigned char *md); + + int MD5_Init(MD5_CTX *c); + int MD5_Update(MD5_CTX *c, const void *data, + unsigned long len); + int MD5_Final(unsigned char *md, MD5_CTX *c); + +=head1 DESCRIPTION + +MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. + +MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest +of the B bytes at B and place it in B (which must have space +for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 +bytes of output). If B is NULL, the digest is placed in a static +array. + +The following functions may be used if the message is not completely +stored in memory: + +MD2_Init() initializes a B structure. + +MD2_Update() can be called repeatedly with chunks of the message to +be hashed (B bytes at B). + +MD2_Final() places the message digest in B, which must have space +for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B. + +MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and +MD5_Final() are analogous using an B and B structure. + +Applications should use the higher level functions +L +etc. instead of calling the hash functions directly. + +=head1 NOTE + +MD2, MD4, and MD5 are recommended only for compatibility with existing +applications. In new applications, SHA-1 or RIPEMD-160 should be +preferred. + +=head1 RETURN VALUES + +MD2(), MD4(), and MD5() return pointers to the hash value. + +MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), +MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for +success, 0 otherwise. + +=head1 CONFORMING TO + +RFC 1319, RFC 1320, RFC 1321 + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), +MD5_Update() and MD5_Final() are available in all versions of SSLeay +and OpenSSL. + +MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and +above. + +=cut diff --git a/src/lib/libssl/src/doc/crypto/PEM_read_bio_PrivateKey.pod b/src/lib/libssl/src/doc/crypto/PEM_read_bio_PrivateKey.pod new file mode 100644 index 0000000000..54414a3f6f --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/PEM_read_bio_PrivateKey.pod @@ -0,0 +1,476 @@ +=pod + +=head1 NAME + +PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines + +=head1 SYNOPSIS + + #include + + EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + + EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, + char *kstr, int klen, + pem_password_cb *cb, void *u); + + EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + + EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); + int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); + + RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, + pem_password_cb *cb, void *u); + + RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, + pem_password_cb *cb, void *u); + + RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); + + int PEM_write_RSAPublicKey(FILE *fp, RSA *x); + + RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, + pem_password_cb *cb, void *u); + + RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); + + int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); + + DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, + pem_password_cb *cb, void *u); + + DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + + DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, + pem_password_cb *cb, void *u); + + DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); + + int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); + + DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); + + DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_DSAparams(BIO *bp, DSA *x); + + int PEM_write_DSAparams(FILE *fp, DSA *x); + + DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); + + DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_DHparams(BIO *bp, DH *x); + + int PEM_write_DHparams(FILE *fp, DH *x); + + X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); + + X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_X509(BIO *bp, X509 *x); + + int PEM_write_X509(FILE *fp, X509 *x); + + X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); + + X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); + + int PEM_write_X509_AUX(FILE *fp, X509 *x); + + X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, + pem_password_cb *cb, void *u); + + X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); + + int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); + + int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); + + int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); + + X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, + pem_password_cb *cb, void *u); + X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, + pem_password_cb *cb, void *u); + int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); + int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); + + PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); + + PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); + + int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); + + int PEM_write_PKCS7(FILE *fp, PKCS7 *x); + + NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, + NETSCAPE_CERT_SEQUENCE **x, + pem_password_cb *cb, void *u); + + NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp, + NETSCAPE_CERT_SEQUENCE **x, + pem_password_cb *cb, void *u); + + int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x); + + int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x); + +=head1 DESCRIPTION + +The PEM functions read or write structures in PEM format. In +this sense PEM format is simply base64 encoded data surrounded +by header lines. + +For more details about the meaning of arguments see the +B section. + +Each operation has four functions associated with it. For +clarity the term "B functions" will be used to collectively +refer to the PEM_read_bio_foobar(), PEM_read_foobar(), +PEM_write_bio_foobar() and PEM_write_foobar() functions. + +The B functions read or write a private key in +PEM format using an EVP_PKEY structure. The write routines use +"traditional" private key format and can handle both RSA and DSA +private keys. The read functions can additionally transparently +handle PKCS#8 format encrypted and unencrypted keys too. + +PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() +write a private key in an EVP_PKEY structure in PKCS#8 +EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption +algorithms. The B argument specifies the encryption algorithm to +use: unlike all other PEM routines the encryption is applied at the +PKCS#8 level and not in the PEM headers. If B is NULL then no +encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. + +PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() +also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however +it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm +to use is specified in the B parameter and should be the NID of the +corresponding OBJECT IDENTIFIER (see NOTES section). + +The B functions process a public key using an EVP_PKEY +structure. The public key is encoded as a SubjectPublicKeyInfo +structure. + +The B functions process an RSA private key using an +RSA structure. It handles the same formats as the B +functions but an error occurs if the private key is not RSA. + +The B functions process an RSA public key using an +RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey +structure. + +The B functions also process an RSA public key using +an RSA structure. However the public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not RSA. + +The B functions process a DSA private key using a +DSA structure. It handles the same formats as the B +functions but an error occurs if the private key is not DSA. + +The B functions process a DSA public key using +a DSA structure. The public key is encoded using a +SubjectPublicKeyInfo structure and an error occurs if the public +key is not DSA. + +The B functions process DSA parameters using a DSA +structure. The parameters are encoded using a foobar structure. + +The B functions process DH parameters using a DH +structure. The parameters are encoded using a PKCS#3 DHparameter +structure. + +The B functions process an X509 certificate using an X509 +structure. They will also process a trusted X509 certificate but +any trust settings are discarded. + +The B functions process a trusted X509 certificate using +an X509 structure. + +The B and B functions process a PKCS#10 +certificate request using an X509_REQ structure. The B +write functions use B in the header whereas +the B functions use B +(as required by some CAs). The B read functions will +handle either form so there are no B read functions. + +The B functions process an X509 CRL using an X509_CRL +structure. + +The B functions process a PKCS#7 ContentInfo using a PKCS7 +structure. + +The B functions process a Netscape Certificate +Sequence using a NETSCAPE_CERT_SEQUENCE structure. + +=head1 PEM FUNCTION ARGUMENTS + +The PEM functions have many common arguments. + +The B BIO parameter (if present) specifies the BIO to read from +or write to. + +The B FILE parameter (if present) specifies the FILE pointer to +read from or write to. + +The PEM read functions all take an argument B and return +a B pointer. Where B is whatever structure the function +uses. If B is NULL then the parameter is ignored. If B is not +NULL but B<*x> is NULL then the structure returned will be written +to B<*x>. If neither B nor B<*x> is NULL then an attempt is made +to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections). +Irrespective of the value of B a pointer to the structure is always +returned (or NULL if an error occurred). + +The PEM functions which write private keys take an B parameter +which specifies the encryption algorithm to use, encryption is done +at the PEM level. If this parameter is set to NULL then the private +key is written in unencrypted form. + +The B argument is the callback to use when querying for the pass +phrase used for encrypted PEM structures (normally only private keys). + +For the PEM write routines if the B parameter is not NULL then +B bytes at B are used as the passphrase and B is +ignored. + +If the B parameters is set to NULL and the B parameter is not +NULL then the B parameter is interpreted as a null terminated string +to use as the passphrase. If both B and B are NULL then the +default callback routine is used which will typically prompt for the +passphrase on the current terminal with echoing turned off. + +The default passphrase callback is sometimes inappropriate (for example +in a GUI application) so an alternative can be supplied. The callback +routine has the following form: + + int cb(char *buf, int size, int rwflag, void *u); + +B is the buffer to write the passphrase to. B is the maximum +length of the passphrase (i.e. the size of buf). B is a flag +which is set to 0 when reading and 1 when writing. A typical routine +will ask the user to verify the passphrase (for example by prompting +for it twice) if B is 1. The B parameter has the same +value as the B parameter passed to the PEM routine. It allows +arbitrary data to be passed to the callback by the application +(for example a window handle in a GUI application). The callback +B return the number of characters in the passphrase or 0 if +an error occurred. + +=head1 EXAMPLES + +Although the PEM routines take several arguments in almost all applications +most of them are set to 0 or NULL. + +Read a certificate in PEM format from a BIO: + + X509 *x; + x = PEM_read_bio_X509(bp, NULL, 0, NULL); + if (x == NULL) + { + /* Error */ + } + +Alternative method: + + X509 *x = NULL; + if (!PEM_read_bio_X509(bp, &x, 0, NULL)) + { + /* Error */ + } + +Write a certificate to a BIO: + + if (!PEM_write_bio_X509(bp, x)) + { + /* Error */ + } + +Write an unencrypted private key to a FILE pointer: + + if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) + { + /* Error */ + } + +Write a private key (using traditional format) to a BIO using +triple DES encryption, the pass phrase is prompted for: + + if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) + { + /* Error */ + } + +Write a private key (using PKCS#8 format) to a BIO using triple +DES encryption, using the pass phrase "hello": + + if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) + { + /* Error */ + } + +Read a private key from a BIO using the pass phrase "hello": + + key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); + if (key == NULL) + { + /* Error */ + } + +Read a private key from a BIO using a pass phrase callback: + + key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); + if (key == NULL) + { + /* Error */ + } + +Skeleton pass phrase callback: + + int pass_cb(char *buf, int size, int rwflag, void *u); + { + int len; + char *tmp; + /* We'd probably do something else if 'rwflag' is 1 */ + printf("Enter pass phrase for \"%s\"\n", u); + + /* get pass phrase, length 'len' into 'tmp' */ + tmp = "hello"; + len = strlen(tmp); + + if (len <= 0) return 0; + /* if too long, truncate */ + if (len > size) len = size; + memcpy(buf, tmp, len); + return len; + } + +=head1 NOTES + +The old B write routines are retained for compatibility. +New applications should write private keys using the +PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines +because they are more secure (they use an iteration count of 2048 whereas +the traditional routines use a count of 1) unless compatibility with older +versions of OpenSSL is important. + +The B read routines can be used in all applications because +they handle all formats transparently. + +A frequent cause of problems is attempting to use the PEM routines like +this: + + X509 *x; + PEM_read_bio_X509(bp, &x, 0, NULL); + +this is a bug because an attempt will be made to reuse the data at B +which is an uninitialised pointer. + +=head1 PEM ENCRYPTION FORMAT + +This old B routines use a non standard technique for encryption. + +The private key (or other data) takes the following form: + + -----BEGIN RSA PRIVATE KEY----- + Proc-Type: 4,ENCRYPTED + DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 + + ...base64 encoded data... + -----END RSA PRIVATE KEY----- + +The line beginning DEK-Info contains two comma separated pieces of information: +the encryption algorithm name as used by EVP_get_cipherbyname() and an 8 +byte B encoded as a set of hexadecimal digits. + +After this is the base64 encoded encrypted data. + +The encryption key is determined using EVP_bytestokey(), using B and an +iteration count of 1. The IV used is the value of B and *not* the IV +returned by EVP_bytestokey(). + +=head1 BUGS + +The PEM read routines in some versions of OpenSSL will not correctly reuse +an existing structure. Therefore the following: + + PEM_read_bio_X509(bp, &x, 0, NULL); + +where B already contains a valid certificate, may not work, whereas: + + X509_free(x); + x = PEM_read_bio_X509(bp, NULL, 0, NULL); + +is guaranteed to work. + +=head1 RETURN CODES + +The read routines return either a pointer to the structure read or NULL +if an error occurred. + +The write routines return 1 for success or 0 for failure. diff --git a/src/lib/libssl/src/doc/crypto/RAND.pod b/src/lib/libssl/src/doc/crypto/RAND.pod new file mode 100644 index 0000000000..e987414477 --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/RAND.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +rand - pseudo-random number generator + +=head1 SYNOPSIS + + #include + + int RAND_set_rand_engine(ENGINE *engine); + + int RAND_bytes(unsigned char *buf, int num); + int RAND_pseudo_bytes(unsigned char *buf, int num); + + void RAND_seed(const void *buf, int num); + void RAND_add(const void *buf, int num, int entropy); + int RAND_status(void); + + int RAND_load_file(const char *file, long max_bytes); + int RAND_write_file(const char *file); + const char *RAND_file_name(char *file, size_t num); + + int RAND_egd(const char *path); + + void RAND_set_rand_method(const RAND_METHOD *meth); + const RAND_METHOD *RAND_get_rand_method(void); + RAND_METHOD *RAND_SSLeay(void); + + void RAND_cleanup(void); + +=head1 DESCRIPTION + +Since the introduction of the ENGINE API, the recommended way of controlling +default implementations is by using the ENGINE API functions. The default +B, as set by RAND_set_rand_method() and returned by +RAND_get_rand_method(), is only used if no ENGINE has been set as the default +"rand" implementation. Hence, these two functions are no longer the recommened +way to control defaults. + +If an alternative B implementation is being used (either set +directly or as provided by an ENGINE module), then it is entirely responsible +for the generation and management of a cryptographically secure PRNG stream. The +mechanisms described below relate solely to the software PRNG implementation +built in to OpenSSL and used by default. + +These functions implement a cryptographically secure pseudo-random +number generator (PRNG). It is used by other library functions for +example to generate random keys, and applications can use it when they +need randomness. + +A cryptographic PRNG must be seeded with unpredictable data such as +mouse movements or keys pressed at random by the user. This is +described in L. Its state can be saved in a seed file +(see L) to avoid having to go through the +seeding process whenever the application is started. + +L describes how to obtain random data from the +PRNG. + +=head1 INTERNALS + +The RAND_SSLeay() method implements a PRNG based on the systems' +L random number generator. + +=head1 SEE ALSO + +L, L, +L, L, +L, +L, +L + +=cut diff --git a/src/lib/libssl/src/doc/crypto/RC4.pod b/src/lib/libssl/src/doc/crypto/RC4.pod new file mode 100644 index 0000000000..b6d3a4342c --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/RC4.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +RC4_set_key, RC4 - RC4 encryption + +=head1 SYNOPSIS + + #include + + void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); + + void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, + unsigned char *outdata); + +=head1 DESCRIPTION + +This library implements the Alleged RC4 cipher, which is described for +example in I. It is believed to be compatible +with RC4[TM], a proprietary cipher of RSA Security Inc. + +RC4 is a stream cipher with variable key length. Typically, 128 bit +(16 byte) keys are used for strong encryption, but shorter insecure +key sizes have been widely used due to export restrictions. + +RC4 consists of a key setup phase and the actual encryption or +decryption phase. + +RC4_set_key() sets up the B B using the B bytes long +key at B. + +RC4() encrypts or decrypts the B bytes of data at B using +B and places the result at B. Repeated RC4() calls with +the same B yield a continuous key stream. + +Since RC4 is a stream cipher (the input is XORed with a pseudo-random +key stream to produce the output), decryption uses the same function +calls as encryption. + +Applications should use the higher level functions +L +etc. instead of calling the RC4 functions directly. + +=head1 RETURN VALUES + +RC4_set_key() and RC4() do not return values. + +=head1 NOTE + +Certain conditions have to be observed to securely use stream ciphers. +It is not permissible to perform multiple encryptions using the same +key stream. + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/src/lib/libssl/src/doc/crypto/RIPEMD160.pod b/src/lib/libssl/src/doc/crypto/RIPEMD160.pod new file mode 100644 index 0000000000..264bb99ae7 --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/RIPEMD160.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - +RIPEMD-160 hash function + +=head1 SYNOPSIS + + #include + + unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, + unsigned char *md); + + int RIPEMD160_Init(RIPEMD160_CTX *c); + int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, + unsigned long len); + int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); + +=head1 DESCRIPTION + +RIPEMD-160 is a cryptographic hash function with a +160 bit output. + +RIPEMD160() computes the RIPEMD-160 message digest of the B +bytes at B and places it in B (which must have space for +RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +RIPEMD160_Init() initializes a B structure. + +RIPEMD160_Update() can be called repeatedly with chunks of the message to +be hashed (B bytes at B). + +RIPEMD160_Final() places the message digest in B, which must have +space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases +the B. + +Applications should use the higher level functions +L etc. instead of calling the +hash functions directly. + +=head1 RETURN VALUES + +RIPEMD160() returns a pointer to the hash value. + +RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for +success, 0 otherwise. + +=head1 CONFORMING TO + +ISO/IEC 10118-3 (draft) (??) + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and +RIPEMD160_Final() are available since SSLeay 0.9.0. + +=cut diff --git a/src/lib/libssl/src/doc/crypto/SHA1.pod b/src/lib/libssl/src/doc/crypto/SHA1.pod new file mode 100644 index 0000000000..94ab7bc724 --- /dev/null +++ b/src/lib/libssl/src/doc/crypto/SHA1.pod @@ -0,0 +1,70 @@ +=pod + +=head1 NAME + +SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm + +=head1 SYNOPSIS + + #include + + unsigned char *SHA1(const unsigned char *d, unsigned long n, + unsigned char *md); + + int SHA1_Init(SHA_CTX *c); + int SHA1_Update(SHA_CTX *c, const void *data, + unsigned long len); + int SHA1_Final(unsigned char *md, SHA_CTX *c); + +=head1 DESCRIPTION + +SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a +160 bit output. + +SHA1() computes the SHA-1 message digest of the B +bytes at B and places it in B (which must have space for +SHA_DIGEST_LENGTH == 20 bytes of output). If B is NULL, the digest +is placed in a static array. + +The following functions may be used if the message is not completely +stored in memory: + +SHA1_Init() initializes a B structure. + +SHA1_Update() can be called repeatedly with chunks of the message to +be hashed (B bytes at B). + +SHA1_Final() places the message digest in B, which must have space +for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B. + +Applications should use the higher level functions +L +etc. instead of calling the hash functions directly. + +The predecessor of SHA-1, SHA, is also implemented, but it should be +used only when backward compatibility is required. + +=head1 RETURN VALUES + +SHA1() returns a pointer to the hash value. + +SHA1_Init(), SHA1_Update() and SHA1_Final() return 1 for success, 0 otherwise. + +=head1 CONFORMING TO + +SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash +Standard), +SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash +Standard), +ANSI X9.30 + +=head1 SEE ALSO + +L, L, L + +=head1 HISTORY + +SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all +versions of SSLeay and OpenSSL. + +=cut diff --git a/src/lib/libssl/src/doc/crypto/bio.pod b/src/lib/libssl/src/doc/crypto/bio.pod deleted file mode 100644 index f9239226ff..0000000000 --- a/src/lib/libssl/src/doc/crypto/bio.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -bio - I/O abstraction - -=head1 SYNOPSIS - - #include - -TBA - - -=head1 DESCRIPTION - -A BIO is an I/O abstraction, it hides many of the underlying I/O -details from an application. If an application uses a BIO for its -I/O it can transparently handle SSL connections, unencrypted network -connections and file I/O. - -There are two type of BIO, a source/sink BIO and a filter BIO. - -As its name implies a source/sink BIO is a source and/or sink of data, -examples include a socket BIO and a file BIO. - -A filter BIO takes data from one BIO and passes it through to -another, or the application. The data may be left unmodified (for -example a message digest BIO) or translated (for example an -encryption BIO). The effect of a filter BIO may change according -to the I/O operation it is performing: for example an encryption -BIO will encrypt data if it is being written to and decrypt data -if it is being read from. - -BIOs can be joined together to form a chain (a single BIO is a chain -with one component). A chain normally consist of one source/sink -BIO and one or more filter BIOs. Data read from or written to the -first BIO then traverses the chain to the end (normally a source/sink -BIO). - -=head1 SEE ALSO - -L, -L, L, -L, L, -L, L, -L, L, -L, -L, L, -L, L, -L, L, -L, L, -L, L, -L, -L diff --git a/src/lib/libssl/src/doc/crypto/blowfish.pod b/src/lib/libssl/src/doc/crypto/blowfish.pod deleted file mode 100644 index 5b2d274c15..0000000000 --- a/src/lib/libssl/src/doc/crypto/blowfish.pod +++ /dev/null @@ -1,112 +0,0 @@ -=pod - -=head1 NAME - -blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, -BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption - -=head1 SYNOPSIS - - #include - - void BF_set_key(BF_KEY *key, int len, const unsigned char *data); - - void BF_ecb_encrypt(const unsigned char *in, unsigned char *out, - BF_KEY *key, int enc); - void BF_cbc_encrypt(const unsigned char *in, unsigned char *out, - long length, BF_KEY *schedule, unsigned char *ivec, int enc); - void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out, - long length, BF_KEY *schedule, unsigned char *ivec, int *num, - int enc); - void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out, - long length, BF_KEY *schedule, unsigned char *ivec, int *num); - const char *BF_options(void); - - void BF_encrypt(BF_LONG *data,const BF_KEY *key); - void BF_decrypt(BF_LONG *data,const BF_KEY *key); - -=head1 DESCRIPTION - -This library implements the Blowfish cipher, which was invented and described -by Counterpane (see http://www.counterpane.com/blowfish.html ). - -Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. -It uses a variable size key, but typically, 128 bit (16 byte) keys are -considered good for strong encryption. Blowfish can be used in the same -modes as DES (see L). Blowfish is currently one -of the faster block ciphers. It is quite a bit faster than DES, and much -faster than IDEA or RC2. - -Blowfish consists of a key setup phase and the actual encryption or decryption -phase. - -BF_set_key() sets up the B B using the B bytes long key -at B. - -BF_ecb_encrypt() is the basic Blowfish encryption and decryption function. -It encrypts or decrypts the first 64 bits of B using the key B, -putting the result in B. B decides if encryption (B) -or decryption (B) shall be performed. The vector pointed at by -B and B must be 64 bits in length, no less. If they are larger, -everything after the first 64 bits is ignored. - -The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt() -all operate on variable length data. They all take an initialization vector -B which needs to be passed along into the next call of the same function -for the same message. B may be initialized with anything, but the -recipient needs to know what it was initialized with, or it won't be able -to decrypt. Some programs and protocols simplify this, like SSH, where -B is simply initialized to zero. -BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while -BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable -number of bytes (the amount does not have to be an exact multiple of 8). The -purpose of the latter two is to simulate stream ciphers, and therefore, they -need the parameter B, which is a pointer to an integer where the current -offset in B is stored between calls. This integer must be initialized -to zero when B is initialized. - -BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It -encrypts or decrypts the 64 bits chunks of B using the key B, -putting the result in B. B decides if encryption (BF_ENCRYPT) or -decryption (BF_DECRYPT) shall be performed. B must point at an 8 byte -long initialization vector. - -BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback. -It encrypts or decrypts the bytes in B using the key B, -putting the result in B. B decides if encryption (B) -or decryption (B) shall be performed. B must point at an -8 byte long initialization vector. B must point at an integer which must -be initially zero. - -BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback. -It uses the same parameters as BF_cfb64_encrypt(), which must be initialized -the same way. - -BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish -encryption. They encrypt/decrypt the first 64 bits of the vector pointed by -B, using the key B. These functions should not be used unless you -implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt(). -If you still want to use these functions, you should be aware that they take -each 32-bit chunk in host-byte order, which is little-endian on little-endian -platforms and big-endian on big-endian ones. - -=head1 RETURN VALUES - -None of the functions presented here return any value. - -=head1 NOTE - -Applications should use the higher level functions -L etc. instead of calling the -blowfish functions directly. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -The Blowfish functions are available in all versions of SSLeay and OpenSSL. - -=cut - diff --git a/src/lib/libssl/src/doc/crypto/buffer.pod b/src/lib/libssl/src/doc/crypto/buffer.pod deleted file mode 100644 index 781f5b11ee..0000000000 --- a/src/lib/libssl/src/doc/crypto/buffer.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple -character arrays structure - -=head1 SYNOPSIS - - #include - - BUF_MEM *BUF_MEM_new(void); - - void BUF_MEM_free(BUF_MEM *a); - - int BUF_MEM_grow(BUF_MEM *str, int len); - - char * BUF_strdup(const char *str); - -=head1 DESCRIPTION - -The buffer library handles simple character arrays. Buffers are used for -various purposes in the library, most notably memory BIOs. - -The library uses the BUF_MEM structure defined in buffer.h: - - typedef struct buf_mem_st - { - int length; /* current number of bytes */ - char *data; - int max; /* size of buffer */ - } BUF_MEM; - -B is the current size of the buffer in bytes, B is the amount of -memory allocated to the buffer. There are three functions which handle these -and one "miscellaneous" function. - -BUF_MEM_new() allocates a new buffer of zero size. - -BUF_MEM_free() frees up an already existing buffer. The data is zeroed -before freeing up in case the buffer contains sensitive data. - -BUF_MEM_grow() changes the size of an already existing buffer to -B. Any data already in the buffer is preserved if it increases in -size. - -BUF_strdup() copies a null terminated string into a block of allocated -memory and returns a pointer to the allocated block. -Unlike the standard C library strdup() this function uses OPENSSL_malloc() and so -should be used in preference to the standard library strdup() because it can -be used for memory leak checking or replacing the malloc() function. - -The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free() -function. - -=head1 RETURN VALUES - -BUF_MEM_new() returns the buffer or NULL on error. - -BUF_MEM_free() has no return value. - -BUF_MEM_grow() returns zero on error or the new size (i.e. B). - -=head1 SEE ALSO - -L - -=head1 HISTORY - -BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all -versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/des.pod b/src/lib/libssl/src/doc/crypto/des.pod deleted file mode 100644 index 6f0cf1cc5e..0000000000 --- a/src/lib/libssl/src/doc/crypto/des.pod +++ /dev/null @@ -1,358 +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. The PRNG must be seeded -prior to using this function (see L). If the PRNG -could not generate a secure key, 0 is returned. - -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 probability that a randomly generated key is weak is -1/2^52, so it is not really worth checking for them. - -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; see L. - -The L library provides higher-level encryption functions. - -=head1 BUGS - -DES_3cbc_encrypt() is flawed and must not be used in applications. - -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 written to be source code compatible with -the MIT Kerberos library. - -=head1 SEE ALSO - -crypt(3), L, L, L - -=head1 HISTORY - -In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid -clashes with older versions of libdes. Compatibility des_ functions -are provided for a short while, as well as crypt(). -Declarations for these are in . There is no DES_ -variant for des_random_seed(). -This will happen to other functions -as well if they are deemed redundant (des_random_seed() just calls -RAND_seed() and is present for backward compatibility only), buggy or -already scheduled for removal. - -des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(), -des_is_weak_key(), des_key_sched(), des_pcbc_encrypt(), -des_quad_cksum(), des_random_key() and des_string_to_key() -are available in the MIT Kerberos library; -des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key() -are available in newer versions of that library. - -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/libssl/src/doc/crypto/err.pod b/src/lib/libssl/src/doc/crypto/err.pod deleted file mode 100644 index 6f729554d2..0000000000 --- a/src/lib/libssl/src/doc/crypto/err.pod +++ /dev/null @@ -1,187 +0,0 @@ -=pod - -=head1 NAME - -err - error codes - -=head1 SYNOPSIS - - #include - - unsigned long ERR_get_error(void); - unsigned long ERR_peek_error(void); - unsigned long ERR_get_error_line(const char **file, int *line); - unsigned long ERR_peek_error_line(const char **file, int *line); - unsigned long ERR_get_error_line_data(const char **file, int *line, - const char **data, int *flags); - unsigned long ERR_peek_error_line_data(const char **file, int *line, - const char **data, int *flags); - - int ERR_GET_LIB(unsigned long e); - int ERR_GET_FUNC(unsigned long e); - int ERR_GET_REASON(unsigned long e); - - void ERR_clear_error(void); - - char *ERR_error_string(unsigned long e, char *buf); - const char *ERR_lib_error_string(unsigned long e); - const char *ERR_func_error_string(unsigned long e); - const char *ERR_reason_error_string(unsigned long e); - - void ERR_print_errors(BIO *bp); - void ERR_print_errors_fp(FILE *fp); - - void ERR_load_crypto_strings(void); - void ERR_free_strings(void); - - void ERR_remove_state(unsigned long pid); - - void ERR_put_error(int lib, int func, int reason, const char *file, - int line); - void ERR_add_error_data(int num, ...); - - void ERR_load_strings(int lib,ERR_STRING_DATA str[]); - unsigned long ERR_PACK(int lib, int func, int reason); - int ERR_get_next_error_library(void); - -=head1 DESCRIPTION - -When a call to the OpenSSL library fails, this is usually signalled -by the return value, and an error code is stored in an error queue -associated with the current thread. The B library provides -functions to obtain these error codes and textual error messages. - -The L manpage describes how to -access error codes. - -Error codes contain information about where the error occurred, and -what went wrong. L describes how to -extract this information. A method to obtain human-readable error -messages is described in L. - -L can be used to clear the -error queue. - -Note that L should be used to -avoid memory leaks when threads are terminated. - -=head1 ADDING NEW ERROR CODES TO OPENSSL - -See L if you want to record error codes in the -OpenSSL error system from within your application. - -The remainder of this section is of interest only if you want to add -new error codes to OpenSSL or add error codes from external libraries. - -=head2 Reporting errors - -Each sub-library has a specific macro XXXerr() that is used to report -errors. Its first argument is a function code B, the second -argument is a reason code B. Function codes are derived -from the function names; reason codes consist of textual error -descriptions. For example, the function ssl23_read() reports a -"handshake failure" as follows: - - SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); - -Function and reason codes should consist of upper case characters, -numbers and underscores only. The error file generation script translates -function codes into function names by looking in the header files -for an appropriate function name, if none is found it just uses -the capitalized form such as "SSL23_READ" in the above example. - -The trailing section of a reason code (after the "_R_") is translated -into lower case and underscores changed to spaces. - -When you are using new function or reason codes, run B. -The necessary B<#define>s will then automatically be added to the -sub-library's header file. - -Although a library will normally report errors using its own specific -XXXerr macro, another library's macro can be used. This is normally -only done when a library wants to include ASN1 code which must use -the ASN1err() macro. - -=head2 Adding new libraries - -When adding a new sub-library to OpenSSL, assign it a library number -B, define a macro XXXerr() (both in B), add its -name to B (in B), and add -C to the ERR_load_crypto_strings() function -(in B). Finally, add an entry - - L XXX xxx.h xxx_err.c - -to B, and add B to the Makefile. -Running B will then generate a file B, and -add all error codes used in the library to B. - -Additionally the library include file must have a certain form. -Typically it will initially look like this: - - #ifndef HEADER_XXX_H - #define HEADER_XXX_H - - #ifdef __cplusplus - extern "C" { - #endif - - /* Include files */ - - #include - #include - - /* Macros, structures and function prototypes */ - - - /* BEGIN ERROR CODES */ - -The B sequence is used by the error code -generation script as the point to place new error codes, any text -after this point will be overwritten when B is run. -The closing #endif etc will be automatically added by the script. - -The generated C error code file B will load the header -files B, B and B so the -header file must load any additional header files containing any -definitions it uses. - -=head1 USING ERROR CODES IN EXTERNAL LIBRARIES - -It is also possible to use OpenSSL's error code scheme in external -libraries. The library needs to load its own codes and call the OpenSSL -error code insertion script B explicitly to add codes to -the header file and generate the C error code file. This will normally -be done if the external library needs to generate new ASN1 structures -but it can also be used to add more general purpose error code handling. - -TBA more details - -=head1 INTERNALS - -The error queues are stored in a hash table with one B -entry for each pid. ERR_get_state() returns the current thread's -B. An B can hold up to B error -codes. When more error codes are added, the old ones are overwritten, -on the assumption that the most recent errors are most important. - -Error strings are also stored in hash table. The hash tables can -be obtained by calling ERR_get_err_state_table(void) and -ERR_get_string_table(void) respectively. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/crypto/hmac.pod b/src/lib/libssl/src/doc/crypto/hmac.pod deleted file mode 100644 index d92138d273..0000000000 --- a/src/lib/libssl/src/doc/crypto/hmac.pod +++ /dev/null @@ -1,106 +0,0 @@ -=pod - -=head1 NAME - -HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message -authentication code - -=head1 SYNOPSIS - - #include - - unsigned char *HMAC(const EVP_MD *evp_md, const void *key, - int key_len, const unsigned char *d, int n, - unsigned char *md, unsigned int *md_len); - - void HMAC_CTX_init(HMAC_CTX *ctx); - - int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, - const EVP_MD *md); - int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, - const EVP_MD *md, ENGINE *impl); - int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); - int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); - - void HMAC_CTX_cleanup(HMAC_CTX *ctx); - void HMAC_cleanup(HMAC_CTX *ctx); - -=head1 DESCRIPTION - -HMAC is a MAC (message authentication code), i.e. a keyed hash -function used for message authentication, which is based on a hash -function. - -HMAC() computes the message authentication code of the B bytes at -B using the hash function B and the key B which is -B bytes long. - -It places the result in B (which must have space for the output of -the hash function, which is no more than B bytes). -If B is NULL, the digest is placed in a static array. The size of -the output is placed in B, unless it is B. - -B can be EVP_sha1(), EVP_ripemd160() etc. - -HMAC_CTX_init() initialises a B before first use. It must be -called. - -HMAC_CTX_cleanup() erases the key and other data from the B -and releases any associated resources. It must be called when an -B is no longer required. - -HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back -compatibility with 0.9.6b, it is deprecated. - -The following functions may be used if the message is not completely -stored in memory: - -HMAC_Init() initializes a B structure to use the hash -function B and the key B which is B bytes -long. It is deprecated and only included for backward compatibility -with OpenSSL 0.9.6b. - -HMAC_Init_ex() initializes or reuses a B structure to use -the function B and key B. Either can be NULL, in which -case the existing one will be reused. HMAC_CTX_init() must have been -called before the first use of an B in this -function. B. - -HMAC_Update() can be called repeatedly with chunks of the message to -be authenticated (B bytes at B). - -HMAC_Final() places the message authentication code in B, which -must have space for the hash function output. - -=head1 RETURN VALUES - -HMAC() returns a pointer to the message authentication code or NULL if -an error occurred. - -HMAC_Init_ex(), HMAC_Update() and HMAC_Final() return 1 for success or 0 if -an error occurred. - -HMAC_CTX_init() and HMAC_CTX_cleanup() do not return values. - -=head1 CONFORMING TO - -RFC 2104 - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() -are available since SSLeay 0.9.0. - -HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available -since OpenSSL 0.9.7. - -HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in -versions of OpenSSL before 1.0.0. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/md5.pod b/src/lib/libssl/src/doc/crypto/md5.pod deleted file mode 100644 index d11d5c32cb..0000000000 --- a/src/lib/libssl/src/doc/crypto/md5.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, -MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions - -=head1 SYNOPSIS - - #include - - unsigned char *MD2(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MD2_Init(MD2_CTX *c); - int MD2_Update(MD2_CTX *c, const unsigned char *data, - unsigned long len); - int MD2_Final(unsigned char *md, MD2_CTX *c); - - - #include - - unsigned char *MD4(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MD4_Init(MD4_CTX *c); - int MD4_Update(MD4_CTX *c, const void *data, - unsigned long len); - int MD4_Final(unsigned char *md, MD4_CTX *c); - - - #include - - unsigned char *MD5(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MD5_Init(MD5_CTX *c); - int MD5_Update(MD5_CTX *c, const void *data, - unsigned long len); - int MD5_Final(unsigned char *md, MD5_CTX *c); - -=head1 DESCRIPTION - -MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. - -MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest -of the B bytes at B and place it in B (which must have space -for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 -bytes of output). If B is NULL, the digest is placed in a static -array. - -The following functions may be used if the message is not completely -stored in memory: - -MD2_Init() initializes a B structure. - -MD2_Update() can be called repeatedly with chunks of the message to -be hashed (B bytes at B). - -MD2_Final() places the message digest in B, which must have space -for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B. - -MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and -MD5_Final() are analogous using an B and B structure. - -Applications should use the higher level functions -L -etc. instead of calling the hash functions directly. - -=head1 NOTE - -MD2, MD4, and MD5 are recommended only for compatibility with existing -applications. In new applications, SHA-1 or RIPEMD-160 should be -preferred. - -=head1 RETURN VALUES - -MD2(), MD4(), and MD5() return pointers to the hash value. - -MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), -MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for -success, 0 otherwise. - -=head1 CONFORMING TO - -RFC 1319, RFC 1320, RFC 1321 - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), -MD5_Update() and MD5_Final() are available in all versions of SSLeay -and OpenSSL. - -MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and -above. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/pem.pod b/src/lib/libssl/src/doc/crypto/pem.pod deleted file mode 100644 index 54414a3f6f..0000000000 --- a/src/lib/libssl/src/doc/crypto/pem.pod +++ /dev/null @@ -1,476 +0,0 @@ -=pod - -=head1 NAME - -PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines - -=head1 SYNOPSIS - - #include - - EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - - EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - - EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); - int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); - - RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, - pem_password_cb *cb, void *u); - - RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, - pem_password_cb *cb, void *u); - - RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); - - int PEM_write_RSAPublicKey(FILE *fp, RSA *x); - - RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, - pem_password_cb *cb, void *u); - - RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); - - int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); - - DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, - pem_password_cb *cb, void *u); - - DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, - pem_password_cb *cb, void *u); - - DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); - - int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); - - DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); - - DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_DSAparams(BIO *bp, DSA *x); - - int PEM_write_DSAparams(FILE *fp, DSA *x); - - DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); - - DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_DHparams(BIO *bp, DH *x); - - int PEM_write_DHparams(FILE *fp, DH *x); - - X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); - - X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_X509(BIO *bp, X509 *x); - - int PEM_write_X509(FILE *fp, X509 *x); - - X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); - - X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); - - int PEM_write_X509_AUX(FILE *fp, X509 *x); - - X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, - pem_password_cb *cb, void *u); - - X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); - - int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); - - int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); - - int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); - - X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, - pem_password_cb *cb, void *u); - X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, - pem_password_cb *cb, void *u); - int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); - int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); - - PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); - - PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); - - int PEM_write_PKCS7(FILE *fp, PKCS7 *x); - - NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x); - - int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x); - -=head1 DESCRIPTION - -The PEM functions read or write structures in PEM format. In -this sense PEM format is simply base64 encoded data surrounded -by header lines. - -For more details about the meaning of arguments see the -B section. - -Each operation has four functions associated with it. For -clarity the term "B functions" will be used to collectively -refer to the PEM_read_bio_foobar(), PEM_read_foobar(), -PEM_write_bio_foobar() and PEM_write_foobar() functions. - -The B functions read or write a private key in -PEM format using an EVP_PKEY structure. The write routines use -"traditional" private key format and can handle both RSA and DSA -private keys. The read functions can additionally transparently -handle PKCS#8 format encrypted and unencrypted keys too. - -PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() -write a private key in an EVP_PKEY structure in PKCS#8 -EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption -algorithms. The B argument specifies the encryption algorithm to -use: unlike all other PEM routines the encryption is applied at the -PKCS#8 level and not in the PEM headers. If B is NULL then no -encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. - -PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() -also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however -it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm -to use is specified in the B parameter and should be the NID of the -corresponding OBJECT IDENTIFIER (see NOTES section). - -The B functions process a public key using an EVP_PKEY -structure. The public key is encoded as a SubjectPublicKeyInfo -structure. - -The B functions process an RSA private key using an -RSA structure. It handles the same formats as the B -functions but an error occurs if the private key is not RSA. - -The B functions process an RSA public key using an -RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey -structure. - -The B functions also process an RSA public key using -an RSA structure. However the public key is encoded using a -SubjectPublicKeyInfo structure and an error occurs if the public -key is not RSA. - -The B functions process a DSA private key using a -DSA structure. It handles the same formats as the B -functions but an error occurs if the private key is not DSA. - -The B functions process a DSA public key using -a DSA structure. The public key is encoded using a -SubjectPublicKeyInfo structure and an error occurs if the public -key is not DSA. - -The B functions process DSA parameters using a DSA -structure. The parameters are encoded using a foobar structure. - -The B functions process DH parameters using a DH -structure. The parameters are encoded using a PKCS#3 DHparameter -structure. - -The B functions process an X509 certificate using an X509 -structure. They will also process a trusted X509 certificate but -any trust settings are discarded. - -The B functions process a trusted X509 certificate using -an X509 structure. - -The B and B functions process a PKCS#10 -certificate request using an X509_REQ structure. The B -write functions use B in the header whereas -the B functions use B -(as required by some CAs). The B read functions will -handle either form so there are no B read functions. - -The B functions process an X509 CRL using an X509_CRL -structure. - -The B functions process a PKCS#7 ContentInfo using a PKCS7 -structure. - -The B functions process a Netscape Certificate -Sequence using a NETSCAPE_CERT_SEQUENCE structure. - -=head1 PEM FUNCTION ARGUMENTS - -The PEM functions have many common arguments. - -The B BIO parameter (if present) specifies the BIO to read from -or write to. - -The B FILE parameter (if present) specifies the FILE pointer to -read from or write to. - -The PEM read functions all take an argument B and return -a B pointer. Where B is whatever structure the function -uses. If B is NULL then the parameter is ignored. If B is not -NULL but B<*x> is NULL then the structure returned will be written -to B<*x>. If neither B nor B<*x> is NULL then an attempt is made -to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections). -Irrespective of the value of B a pointer to the structure is always -returned (or NULL if an error occurred). - -The PEM functions which write private keys take an B parameter -which specifies the encryption algorithm to use, encryption is done -at the PEM level. If this parameter is set to NULL then the private -key is written in unencrypted form. - -The B argument is the callback to use when querying for the pass -phrase used for encrypted PEM structures (normally only private keys). - -For the PEM write routines if the B parameter is not NULL then -B bytes at B are used as the passphrase and B is -ignored. - -If the B parameters is set to NULL and the B parameter is not -NULL then the B parameter is interpreted as a null terminated string -to use as the passphrase. If both B and B are NULL then the -default callback routine is used which will typically prompt for the -passphrase on the current terminal with echoing turned off. - -The default passphrase callback is sometimes inappropriate (for example -in a GUI application) so an alternative can be supplied. The callback -routine has the following form: - - int cb(char *buf, int size, int rwflag, void *u); - -B is the buffer to write the passphrase to. B is the maximum -length of the passphrase (i.e. the size of buf). B is a flag -which is set to 0 when reading and 1 when writing. A typical routine -will ask the user to verify the passphrase (for example by prompting -for it twice) if B is 1. The B parameter has the same -value as the B parameter passed to the PEM routine. It allows -arbitrary data to be passed to the callback by the application -(for example a window handle in a GUI application). The callback -B return the number of characters in the passphrase or 0 if -an error occurred. - -=head1 EXAMPLES - -Although the PEM routines take several arguments in almost all applications -most of them are set to 0 or NULL. - -Read a certificate in PEM format from a BIO: - - X509 *x; - x = PEM_read_bio_X509(bp, NULL, 0, NULL); - if (x == NULL) - { - /* Error */ - } - -Alternative method: - - X509 *x = NULL; - if (!PEM_read_bio_X509(bp, &x, 0, NULL)) - { - /* Error */ - } - -Write a certificate to a BIO: - - if (!PEM_write_bio_X509(bp, x)) - { - /* Error */ - } - -Write an unencrypted private key to a FILE pointer: - - if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) - { - /* Error */ - } - -Write a private key (using traditional format) to a BIO using -triple DES encryption, the pass phrase is prompted for: - - if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL)) - { - /* Error */ - } - -Write a private key (using PKCS#8 format) to a BIO using triple -DES encryption, using the pass phrase "hello": - - if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello")) - { - /* Error */ - } - -Read a private key from a BIO using the pass phrase "hello": - - key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); - if (key == NULL) - { - /* Error */ - } - -Read a private key from a BIO using a pass phrase callback: - - key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); - if (key == NULL) - { - /* Error */ - } - -Skeleton pass phrase callback: - - int pass_cb(char *buf, int size, int rwflag, void *u); - { - int len; - char *tmp; - /* We'd probably do something else if 'rwflag' is 1 */ - printf("Enter pass phrase for \"%s\"\n", u); - - /* get pass phrase, length 'len' into 'tmp' */ - tmp = "hello"; - len = strlen(tmp); - - if (len <= 0) return 0; - /* if too long, truncate */ - if (len > size) len = size; - memcpy(buf, tmp, len); - return len; - } - -=head1 NOTES - -The old B write routines are retained for compatibility. -New applications should write private keys using the -PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines -because they are more secure (they use an iteration count of 2048 whereas -the traditional routines use a count of 1) unless compatibility with older -versions of OpenSSL is important. - -The B read routines can be used in all applications because -they handle all formats transparently. - -A frequent cause of problems is attempting to use the PEM routines like -this: - - X509 *x; - PEM_read_bio_X509(bp, &x, 0, NULL); - -this is a bug because an attempt will be made to reuse the data at B -which is an uninitialised pointer. - -=head1 PEM ENCRYPTION FORMAT - -This old B routines use a non standard technique for encryption. - -The private key (or other data) takes the following form: - - -----BEGIN RSA PRIVATE KEY----- - Proc-Type: 4,ENCRYPTED - DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 - - ...base64 encoded data... - -----END RSA PRIVATE KEY----- - -The line beginning DEK-Info contains two comma separated pieces of information: -the encryption algorithm name as used by EVP_get_cipherbyname() and an 8 -byte B encoded as a set of hexadecimal digits. - -After this is the base64 encoded encrypted data. - -The encryption key is determined using EVP_bytestokey(), using B and an -iteration count of 1. The IV used is the value of B and *not* the IV -returned by EVP_bytestokey(). - -=head1 BUGS - -The PEM read routines in some versions of OpenSSL will not correctly reuse -an existing structure. Therefore the following: - - PEM_read_bio_X509(bp, &x, 0, NULL); - -where B already contains a valid certificate, may not work, whereas: - - X509_free(x); - x = PEM_read_bio_X509(bp, NULL, 0, NULL); - -is guaranteed to work. - -=head1 RETURN CODES - -The read routines return either a pointer to the structure read or NULL -if an error occurred. - -The write routines return 1 for success or 0 for failure. diff --git a/src/lib/libssl/src/doc/crypto/rand.pod b/src/lib/libssl/src/doc/crypto/rand.pod deleted file mode 100644 index e987414477..0000000000 --- a/src/lib/libssl/src/doc/crypto/rand.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -rand - pseudo-random number generator - -=head1 SYNOPSIS - - #include - - int RAND_set_rand_engine(ENGINE *engine); - - int RAND_bytes(unsigned char *buf, int num); - int RAND_pseudo_bytes(unsigned char *buf, int num); - - void RAND_seed(const void *buf, int num); - void RAND_add(const void *buf, int num, int entropy); - int RAND_status(void); - - int RAND_load_file(const char *file, long max_bytes); - int RAND_write_file(const char *file); - const char *RAND_file_name(char *file, size_t num); - - int RAND_egd(const char *path); - - void RAND_set_rand_method(const RAND_METHOD *meth); - const RAND_METHOD *RAND_get_rand_method(void); - RAND_METHOD *RAND_SSLeay(void); - - void RAND_cleanup(void); - -=head1 DESCRIPTION - -Since the introduction of the ENGINE API, the recommended way of controlling -default implementations is by using the ENGINE API functions. The default -B, as set by RAND_set_rand_method() and returned by -RAND_get_rand_method(), is only used if no ENGINE has been set as the default -"rand" implementation. Hence, these two functions are no longer the recommened -way to control defaults. - -If an alternative B implementation is being used (either set -directly or as provided by an ENGINE module), then it is entirely responsible -for the generation and management of a cryptographically secure PRNG stream. The -mechanisms described below relate solely to the software PRNG implementation -built in to OpenSSL and used by default. - -These functions implement a cryptographically secure pseudo-random -number generator (PRNG). It is used by other library functions for -example to generate random keys, and applications can use it when they -need randomness. - -A cryptographic PRNG must be seeded with unpredictable data such as -mouse movements or keys pressed at random by the user. This is -described in L. Its state can be saved in a seed file -(see L) to avoid having to go through the -seeding process whenever the application is started. - -L describes how to obtain random data from the -PRNG. - -=head1 INTERNALS - -The RAND_SSLeay() method implements a PRNG based on the systems' -L random number generator. - -=head1 SEE ALSO - -L, L, -L, L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/crypto/rc4.pod b/src/lib/libssl/src/doc/crypto/rc4.pod deleted file mode 100644 index b6d3a4342c..0000000000 --- a/src/lib/libssl/src/doc/crypto/rc4.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -RC4_set_key, RC4 - RC4 encryption - -=head1 SYNOPSIS - - #include - - void RC4_set_key(RC4_KEY *key, int len, const unsigned char *data); - - void RC4(RC4_KEY *key, unsigned long len, const unsigned char *indata, - unsigned char *outdata); - -=head1 DESCRIPTION - -This library implements the Alleged RC4 cipher, which is described for -example in I. It is believed to be compatible -with RC4[TM], a proprietary cipher of RSA Security Inc. - -RC4 is a stream cipher with variable key length. Typically, 128 bit -(16 byte) keys are used for strong encryption, but shorter insecure -key sizes have been widely used due to export restrictions. - -RC4 consists of a key setup phase and the actual encryption or -decryption phase. - -RC4_set_key() sets up the B B using the B bytes long -key at B. - -RC4() encrypts or decrypts the B bytes of data at B using -B and places the result at B. Repeated RC4() calls with -the same B yield a continuous key stream. - -Since RC4 is a stream cipher (the input is XORed with a pseudo-random -key stream to produce the output), decryption uses the same function -calls as encryption. - -Applications should use the higher level functions -L -etc. instead of calling the RC4 functions directly. - -=head1 RETURN VALUES - -RC4_set_key() and RC4() do not return values. - -=head1 NOTE - -Certain conditions have to be observed to securely use stream ciphers. -It is not permissible to perform multiple encryptions using the same -key stream. - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/ripemd.pod b/src/lib/libssl/src/doc/crypto/ripemd.pod deleted file mode 100644 index 264bb99ae7..0000000000 --- a/src/lib/libssl/src/doc/crypto/ripemd.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -RIPEMD160, RIPEMD160_Init, RIPEMD160_Update, RIPEMD160_Final - -RIPEMD-160 hash function - -=head1 SYNOPSIS - - #include - - unsigned char *RIPEMD160(const unsigned char *d, unsigned long n, - unsigned char *md); - - int RIPEMD160_Init(RIPEMD160_CTX *c); - int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, - unsigned long len); - int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c); - -=head1 DESCRIPTION - -RIPEMD-160 is a cryptographic hash function with a -160 bit output. - -RIPEMD160() computes the RIPEMD-160 message digest of the B -bytes at B and places it in B (which must have space for -RIPEMD160_DIGEST_LENGTH == 20 bytes of output). If B is NULL, the digest -is placed in a static array. - -The following functions may be used if the message is not completely -stored in memory: - -RIPEMD160_Init() initializes a B structure. - -RIPEMD160_Update() can be called repeatedly with chunks of the message to -be hashed (B bytes at B). - -RIPEMD160_Final() places the message digest in B, which must have -space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases -the B. - -Applications should use the higher level functions -L etc. instead of calling the -hash functions directly. - -=head1 RETURN VALUES - -RIPEMD160() returns a pointer to the hash value. - -RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for -success, 0 otherwise. - -=head1 CONFORMING TO - -ISO/IEC 10118-3 (draft) (??) - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and -RIPEMD160_Final() are available since SSLeay 0.9.0. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/sha.pod b/src/lib/libssl/src/doc/crypto/sha.pod deleted file mode 100644 index 94ab7bc724..0000000000 --- a/src/lib/libssl/src/doc/crypto/sha.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -SHA1, SHA1_Init, SHA1_Update, SHA1_Final - Secure Hash Algorithm - -=head1 SYNOPSIS - - #include - - unsigned char *SHA1(const unsigned char *d, unsigned long n, - unsigned char *md); - - int SHA1_Init(SHA_CTX *c); - int SHA1_Update(SHA_CTX *c, const void *data, - unsigned long len); - int SHA1_Final(unsigned char *md, SHA_CTX *c); - -=head1 DESCRIPTION - -SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a -160 bit output. - -SHA1() computes the SHA-1 message digest of the B -bytes at B and places it in B (which must have space for -SHA_DIGEST_LENGTH == 20 bytes of output). If B is NULL, the digest -is placed in a static array. - -The following functions may be used if the message is not completely -stored in memory: - -SHA1_Init() initializes a B structure. - -SHA1_Update() can be called repeatedly with chunks of the message to -be hashed (B bytes at B). - -SHA1_Final() places the message digest in B, which must have space -for SHA_DIGEST_LENGTH == 20 bytes of output, and erases the B. - -Applications should use the higher level functions -L -etc. instead of calling the hash functions directly. - -The predecessor of SHA-1, SHA, is also implemented, but it should be -used only when backward compatibility is required. - -=head1 RETURN VALUES - -SHA1() returns a pointer to the hash value. - -SHA1_Init(), SHA1_Update() and SHA1_Final() return 1 for success, 0 otherwise. - -=head1 CONFORMING TO - -SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure Hash -Standard), -SHA-1: US Federal Information Processing Standard FIPS PUB 180-1 (Secure Hash -Standard), -ANSI X9.30 - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all -versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libssl/src/doc/crypto/threads.pod b/src/lib/libssl/src/doc/crypto/threads.pod deleted file mode 100644 index dc0e9391dc..0000000000 --- a/src/lib/libssl/src/doc/crypto/threads.pod +++ /dev/null @@ -1,210 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback, -CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy, -CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks, -CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, -CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, -CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support - -=head1 SYNOPSIS - - #include - - /* Don't use this structure directly. */ - typedef struct crypto_threadid_st - { - void *ptr; - unsigned long val; - } CRYPTO_THREADID; - /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ - void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val); - void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr); - int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *)); - void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *); - void CRYPTO_THREADID_current(CRYPTO_THREADID *id); - int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a, - const CRYPTO_THREADID *b); - void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest, - const CRYPTO_THREADID *src); - unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id); - - int CRYPTO_num_locks(void); - - /* struct CRYPTO_dynlock_value needs to be defined by the user */ - struct CRYPTO_dynlock_value; - - void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * - (*dyn_create_function)(char *file, int line)); - void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) - (int mode, struct CRYPTO_dynlock_value *l, - const char *file, int line)); - void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) - (struct CRYPTO_dynlock_value *l, const char *file, int line)); - - int CRYPTO_get_new_dynlockid(void); - - void CRYPTO_destroy_dynlockid(int i); - - void CRYPTO_lock(int mode, int n, const char *file, int line); - - #define CRYPTO_w_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_w_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_r_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_r_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_add(addr,amount,type) \ - CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) - -=head1 DESCRIPTION - -OpenSSL can safely be used in multi-threaded applications provided -that at least two callback functions are set, locking_function and -threadid_func. - -locking_function(int mode, int n, const char *file, int line) is -needed to perform locking on shared data structures. -(Note that OpenSSL uses a number of global data structures that -will be implicitly shared whenever multiple threads use OpenSSL.) -Multi-threaded applications will crash at random if it is not set. - -locking_function() must be able to handle up to CRYPTO_num_locks() -different mutex locks. It sets the B-th lock if B & -B, and releases it otherwise. - -B and B are the file number of the function setting the -lock. They can be useful for debugging. - -threadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing -thread's identifier into B. The implementation of this callback should not -fill in B directly, but should use CRYPTO_THREADID_set_numeric() if thread -IDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based. -If the application does not register such a callback using -CRYPTO_THREADID_set_callback(), then a default implementation is used - on -Windows and BeOS this uses the system's default thread identifying APIs, and on -all other platforms it uses the address of B. The latter is satisfactory -for thread-safety if and only if the platform has a thread-local error number -facility. - -Once threadid_func() is registered, or if the built-in default implementation is -to be used; - -=over 4 - -=item * -CRYPTO_THREADID_current() records the currently-executing thread ID into the -given B object. - -=item * -CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie. -the same semantics as memcmp()). - -=item * -CRYPTO_THREADID_cpy() duplicates a thread ID value, - -=item * -CRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This -is usually the exact numeric or pointer-based thread ID used internally, however -this also handles the unusual case where pointers are larger than 'long' -variables and the platform's thread IDs are pointer-based - in this case, mixing -is done to attempt to produce a unique numeric value even though it is not as -wide as the platform's true thread IDs. - -=back - -Additionally, OpenSSL supports dynamic locks, and sometimes, some parts -of OpenSSL need it for better performance. To enable this, the following -is required: - -=over 4 - -=item * -Three additional callback function, dyn_create_function, dyn_lock_function -and dyn_destroy_function. - -=item * -A structure defined with the data that each lock needs to handle. - -=back - -struct CRYPTO_dynlock_value has to be defined to contain whatever structure -is needed to handle locks. - -dyn_create_function(const char *file, int line) is needed to create a -lock. Multi-threaded applications might crash at random if it is not set. - -dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) -is needed to perform locking off dynamic lock numbered n. Multi-threaded -applications might crash at random if it is not set. - -dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is -needed to destroy the lock l. Multi-threaded applications might crash at -random if it is not set. - -CRYPTO_get_new_dynlockid() is used to create locks. It will call -dyn_create_function for the actual creation. - -CRYPTO_destroy_dynlockid() is used to destroy locks. It will call -dyn_destroy_function for the actual destruction. - -CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield -describing what should be done with the lock. n is the number of the -lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined -from the following values. These values are pairwise exclusive, with -undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE -should not be used together): - - CRYPTO_LOCK 0x01 - CRYPTO_UNLOCK 0x02 - CRYPTO_READ 0x04 - CRYPTO_WRITE 0x08 - -=head1 RETURN VALUES - -CRYPTO_num_locks() returns the required number of locks. - -CRYPTO_get_new_dynlockid() returns the index to the newly created lock. - -The other functions return no values. - -=head1 NOTES - -You can find out if OpenSSL was configured with thread support: - - #define OPENSSL_THREAD_DEFINES - #include - #if defined(OPENSSL_THREADS) - // thread support enabled - #else - // no thread support - #endif - -Also, dynamic locks are currently not used internally by OpenSSL, but -may do so in the future. - -=head1 EXAMPLES - -B shows examples of the callback functions on -Solaris, Irix and Win32. - -=head1 HISTORY - -CRYPTO_set_locking_callback() is -available in all versions of SSLeay and OpenSSL. -CRYPTO_num_locks() was added in OpenSSL 0.9.4. -All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. -B and associated functions were introduced in OpenSSL 1.0.0 -to replace (actually, deprecate) the previous CRYPTO_set_id_callback(), -CRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed -thread IDs to always be represented by 'unsigned long'. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/BIO_f_ssl.pod b/src/lib/libssl/src/doc/ssl/BIO_f_ssl.pod new file mode 100644 index 0000000000..bc5861ab34 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/BIO_f_ssl.pod @@ -0,0 +1,322 @@ +=pod + +=head1 NAME + +BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, +BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, +BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, +BIO_ssl_shutdown - SSL BIO + +=head1 SYNOPSIS + + #include + #include + + BIO_METHOD *BIO_f_ssl(void); + + #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) + #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) + #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) + #define BIO_set_ssl_renegotiate_bytes(b,num) \ + BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); + #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ + BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); + #define BIO_get_num_renegotiates(b) \ + BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); + + BIO *BIO_new_ssl(SSL_CTX *ctx,int client); + BIO *BIO_new_ssl_connect(SSL_CTX *ctx); + BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); + int BIO_ssl_copy_session_id(BIO *to,BIO *from); + void BIO_ssl_shutdown(BIO *bio); + + #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) + +=head1 DESCRIPTION + +BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which +is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to +SSL I/O. + +I/O performed on an SSL BIO communicates using the SSL protocol with +the SSLs read and write BIOs. If an SSL connection is not established +then an attempt is made to establish one on the first I/O call. + +If a BIO is appended to an SSL BIO using BIO_push() it is automatically +used as the SSL BIOs read and write BIOs. + +Calling BIO_reset() on an SSL BIO closes down any current SSL connection +by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in +the chain: this will typically disconnect the underlying transport. +The SSL BIO is then reset to the initial accept or connect state. + +If the close flag is set when an SSL BIO is freed then the internal +SSL structure is also freed using SSL_free(). + +BIO_set_ssl() sets the internal SSL pointer of BIO B to B using +the close flag B. + +BIO_get_ssl() retrieves the SSL pointer of BIO B, it can then be +manipulated using the standard SSL library functions. + +BIO_set_ssl_mode() sets the SSL BIO mode to B. If B +is 1 client mode is set. If B is 0 server mode is set. + +BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count +to B. When set after every B bytes of I/O (read and write) +the SSL session is automatically renegotiated. B must be at +least 512 bytes. + +BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to +B. When the renegotiate timeout elapses the session is +automatically renegotiated. + +BIO_get_num_renegotiates() returns the total number of session +renegotiations due to I/O or timeout. + +BIO_new_ssl() allocates an SSL BIO using SSL_CTX B and using +client mode if B is non zero. + +BIO_new_ssl_connect() creates a new BIO chain consisting of an +SSL BIO (using B) followed by a connect BIO. + +BIO_new_buffer_ssl_connect() creates a new BIO chain consisting +of a buffering BIO, an SSL BIO (using B) and a connect +BIO. + +BIO_ssl_copy_session_id() copies an SSL session id between +BIO chains B and B. It does this by locating the +SSL BIOs in each chain and calling SSL_copy_session_id() on +the internal SSL pointer. + +BIO_ssl_shutdown() closes down an SSL connection on BIO +chain B. It does this by locating the SSL BIO in the +chain and calling SSL_shutdown() on its internal SSL +pointer. + +BIO_do_handshake() attempts to complete an SSL handshake on the +supplied BIO and establish the SSL connection. It returns 1 +if the connection was established successfully. A zero or negative +value is returned if the connection could not be established, the +call BIO_should_retry() should be used for non blocking connect BIOs +to determine if the call should be retried. If an SSL connection has +already been established this call has no effect. + +=head1 NOTES + +SSL BIOs are exceptional in that if the underlying transport +is non blocking they can still request a retry in exceptional +circumstances. Specifically this will happen if a session +renegotiation takes place during a BIO_read() operation, one +case where this happens is when SGC or step up occurs. + +In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be +set to disable this behaviour. That is when this flag is set +an SSL BIO using a blocking transport will never request a +retry. + +Since unknown BIO_ctrl() operations are sent through filter +BIOs the servers name and port can be set using BIO_set_host() +on the BIO returned by BIO_new_ssl_connect() without having +to locate the connect BIO first. + +Applications do not have to call BIO_do_handshake() but may wish +to do so to separate the handshake process from other I/O +processing. + +=head1 RETURN VALUES + +TBA + +=head1 EXAMPLE + +This SSL/TLS client example, attempts to retrieve a page from an +SSL/TLS web server. The I/O routines are identical to those of the +unencrypted example in L. + + BIO *sbio, *out; + int len; + char tmpbuf[1024]; + SSL_CTX *ctx; + SSL *ssl; + + ERR_load_crypto_strings(); + ERR_load_SSL_strings(); + OpenSSL_add_all_algorithms(); + + /* We would seed the PRNG here if the platform didn't + * do it automatically + */ + + ctx = SSL_CTX_new(SSLv23_client_method()); + + /* We'd normally set some stuff like the verify paths and + * mode here because as things stand this will connect to + * any server whose certificate is signed by any CA. + */ + + sbio = BIO_new_ssl_connect(ctx); + + BIO_get_ssl(sbio, &ssl); + + if(!ssl) { + fprintf(stderr, "Can't locate SSL pointer\n"); + /* whatever ... */ + } + + /* Don't want any retries */ + SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + + /* We might want to do other things with ssl here */ + + BIO_set_conn_hostname(sbio, "localhost:https"); + + out = BIO_new_fp(stdout, BIO_NOCLOSE); + if(BIO_do_connect(sbio) <= 0) { + fprintf(stderr, "Error connecting to server\n"); + ERR_print_errors_fp(stderr); + /* whatever ... */ + } + + if(BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error establishing SSL connection\n"); + ERR_print_errors_fp(stderr); + /* whatever ... */ + } + + /* Could examine ssl here to get connection info */ + + BIO_puts(sbio, "GET / HTTP/1.0\n\n"); + for(;;) { + len = BIO_read(sbio, tmpbuf, 1024); + if(len <= 0) break; + BIO_write(out, tmpbuf, len); + } + BIO_free_all(sbio); + BIO_free(out); + +Here is a simple server example. It makes use of a buffering +BIO to allow lines to be read from the SSL BIO using BIO_gets. +It creates a pseudo web page containing the actual request from +a client and also echoes the request to standard output. + + BIO *sbio, *bbio, *acpt, *out; + int len; + char tmpbuf[1024]; + SSL_CTX *ctx; + SSL *ssl; + + ERR_load_crypto_strings(); + ERR_load_SSL_strings(); + OpenSSL_add_all_algorithms(); + + /* Might seed PRNG here */ + + ctx = SSL_CTX_new(SSLv23_server_method()); + + if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) + || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) + || !SSL_CTX_check_private_key(ctx)) { + + fprintf(stderr, "Error setting up SSL_CTX\n"); + ERR_print_errors_fp(stderr); + return 0; + } + + /* Might do other things here like setting verify locations and + * DH and/or RSA temporary key callbacks + */ + + /* New SSL BIO setup as server */ + sbio=BIO_new_ssl(ctx,0); + + BIO_get_ssl(sbio, &ssl); + + if(!ssl) { + fprintf(stderr, "Can't locate SSL pointer\n"); + /* whatever ... */ + } + + /* Don't want any retries */ + SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + + /* Create the buffering BIO */ + + bbio = BIO_new(BIO_f_buffer()); + + /* Add to chain */ + sbio = BIO_push(bbio, sbio); + + acpt=BIO_new_accept("4433"); + + /* By doing this when a new connection is established + * we automatically have sbio inserted into it. The + * BIO chain is now 'swallowed' by the accept BIO and + * will be freed when the accept BIO is freed. + */ + + BIO_set_accept_bios(acpt,sbio); + + out = BIO_new_fp(stdout, BIO_NOCLOSE); + + /* Setup accept BIO */ + if(BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error setting up accept BIO\n"); + ERR_print_errors_fp(stderr); + return 0; + } + + /* Now wait for incoming connection */ + if(BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error in connection\n"); + ERR_print_errors_fp(stderr); + return 0; + } + + /* We only want one connection so remove and free + * accept BIO + */ + + sbio = BIO_pop(acpt); + + BIO_free_all(acpt); + + if(BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error in SSL handshake\n"); + ERR_print_errors_fp(stderr); + return 0; + } + + BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n"); + BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n"); + BIO_puts(sbio, "--------------------------------------------------\r\n"); + + for(;;) { + len = BIO_gets(sbio, tmpbuf, 1024); + if(len <= 0) break; + BIO_write(sbio, tmpbuf, len); + BIO_write(out, tmpbuf, len); + /* Look for blank line signifying end of headers*/ + if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break; + } + + BIO_puts(sbio, "--------------------------------------------------\r\n"); + BIO_puts(sbio, "\r\n"); + + /* Since there is a buffering BIO present we had better flush it */ + BIO_flush(sbio); + + BIO_free_all(sbio); + +=head1 BUGS + +In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly, +the I/O BIO reference count was incorrectly incremented (instead of +decremented) and dissociated with the SSL BIO even if the SSL BIO was not +explicitly being popped (e.g. a pop higher up the chain). Applications which +included workarounds for this bug (e.g. freeing BIOs more than once) should +be modified to handle this fix or they may free up an already freed BIO. + +=head1 SEE ALSO + +TBA -- cgit v1.2.3-55-g6feb