diff options
author | Jung-uk Kim <jkim@FreeBSD.org> | 2016-09-22 13:04:03 +0000 |
---|---|---|
committer | Jung-uk Kim <jkim@FreeBSD.org> | 2016-09-22 13:04:03 +0000 |
commit | e1b483878d9824c63d376895da633b0b96fbbaed (patch) | |
tree | 0846e185ed4cc1159a684e408e772c86ae0fc1a7 /doc/crypto | |
parent | 57f1256b1a087adbdf8e5c080dd9ed7975de939a (diff) | |
download | src-e1b483878d9824c63d376895da633b0b96fbbaed.tar.gz src-e1b483878d9824c63d376895da633b0b96fbbaed.zip |
Import OpenSSL 1.0.2i.vendor/openssl/1.0.2i
Notes
Notes:
svn path=/vendor-crypto/openssl/dist/; revision=306189
svn path=/vendor-crypto/openssl/1.0.2i/; revision=306190; tag=vendor/openssl/1.0.2i
Diffstat (limited to 'doc/crypto')
-rw-r--r-- | doc/crypto/BIO_s_bio.pod | 3 | ||||
-rw-r--r-- | doc/crypto/BN_bn2bin.pod | 4 | ||||
-rw-r--r-- | doc/crypto/BN_rand.pod | 6 | ||||
-rw-r--r-- | doc/crypto/EVP_EncryptInit.pod | 9 | ||||
-rw-r--r-- | doc/crypto/EVP_PKEY_cmp.pod | 4 | ||||
-rw-r--r-- | doc/crypto/OBJ_nid2obj.pod | 21 | ||||
-rw-r--r-- | doc/crypto/OPENSSL_config.pod | 9 | ||||
-rw-r--r-- | doc/crypto/OPENSSL_ia32cap.pod | 2 | ||||
-rw-r--r-- | doc/crypto/X509_verify_cert.pod | 13 | ||||
-rw-r--r-- | doc/crypto/d2i_PrivateKey.pod | 59 | ||||
-rw-r--r-- | doc/crypto/d2i_X509.pod | 14 | ||||
-rw-r--r-- | doc/crypto/hmac.pod | 18 | ||||
-rw-r--r-- | doc/crypto/rand.pod | 2 | ||||
-rw-r--r-- | doc/crypto/ui.pod | 12 |
14 files changed, 141 insertions, 35 deletions
diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod index 8d0a55a025c7..9fe88b26b0af 100644 --- a/doc/crypto/BIO_s_bio.pod +++ b/doc/crypto/BIO_s_bio.pod @@ -120,6 +120,9 @@ the application then waits for data to be available on the underlying transport before flushing the write buffer it will never succeed because the request was never sent! +BIO_eof() is true if no data is in the peer BIO and the peer BIO has been +shutdown. + =head1 RETURN VALUES BIO_new_bio_pair() returns 1 on success, with the new BIOs available in diff --git a/doc/crypto/BN_bn2bin.pod b/doc/crypto/BN_bn2bin.pod index a4b17ca60a89..3bed47f8f1d5 100644 --- a/doc/crypto/BN_bn2bin.pod +++ b/doc/crypto/BN_bn2bin.pod @@ -42,7 +42,9 @@ BN_hex2bn() converts the string B<str> containing a hexadecimal number to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's length in hexadecimal digits. If the string starts with '-', the -number is negative. BN_dec2bn() is the same using the decimal system. +number is negative. +A "negative zero" is converted to zero. +BN_dec2bn() is the same using the decimal system. BN_print() and BN_print_fp() write the hexadecimal encoding of B<a>, with a leading '-' for negative numbers, to the B<BIO> or B<FILE> diff --git a/doc/crypto/BN_rand.pod b/doc/crypto/BN_rand.pod index e8cbf658b47d..a1513a952654 100644 --- a/doc/crypto/BN_rand.pod +++ b/doc/crypto/BN_rand.pod @@ -19,7 +19,11 @@ BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-r =head1 DESCRIPTION BN_rand() generates a cryptographically strong pseudo-random number of -B<bits> in length and stores it in B<rnd>. If B<top> is -1, the +B<bits> in length and stores it in B<rnd>. +If B<bits> is less than zero, or too small to +accomodate the requirements specified by the B<top> and B<bottom> +parameters, an error is returned. +If B<top> is -1, the most significant bit of the random number can be zero. If B<top> is 0, it is set to 1, and if B<top> is 1, the two most significant bits of the number will be set to 1, so that the product of two such random diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod index c69e6a6d700e..d9513338d8aa 100644 --- a/doc/crypto/EVP_EncryptInit.pod +++ b/doc/crypto/EVP_EncryptInit.pod @@ -165,10 +165,11 @@ similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and EVP_CipherInit_ex() except the B<ctx> parameter does not need to be initialized and they always use the default cipher implementation. -EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a -similar way to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and -EVP_CipherFinal_ex() except B<ctx> is automatically cleaned up -after the call. +EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are +identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and +EVP_CipherFinal_ex(). In previous releases they also cleaned up +the B<ctx>, but this is no longer done and EVP_CIPHER_CTX_clean() +must be called to free any context resources. EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() return an EVP_CIPHER structure when passed a cipher name, a NID or an diff --git a/doc/crypto/EVP_PKEY_cmp.pod b/doc/crypto/EVP_PKEY_cmp.pod index 0ff027c0d5f9..f8e7ff1039ee 100644 --- a/doc/crypto/EVP_PKEY_cmp.pod +++ b/doc/crypto/EVP_PKEY_cmp.pod @@ -21,7 +21,9 @@ parameters of B<pkey> are missing and 0 if they are present or the algorithm doesn't use parameters. The function EVP_PKEY_copy_parameters() copies the parameters from key -B<from> to key B<to>. +B<from> to key B<to>. An error is returned if the parameters are missing in +B<from> or present in both B<from> and B<to> and mismatch. If the parameters +in B<from> and B<to> are both present and match this function has no effect. The function EVP_PKEY_cmp_parameters() compares the parameters of keys B<a> and B<b>. diff --git a/doc/crypto/OBJ_nid2obj.pod b/doc/crypto/OBJ_nid2obj.pod index 1e45dd40f6bb..b8d289673dee 100644 --- a/doc/crypto/OBJ_nid2obj.pod +++ b/doc/crypto/OBJ_nid2obj.pod @@ -33,6 +33,12 @@ functions The ASN1 object utility functions process ASN1_OBJECT structures which are a representation of the ASN1 OBJECT IDENTIFIER (OID) type. +For convenience, OIDs are usually represented in source code as numeric +identifiers, or B<NID>s. OpenSSL has an internal table of OIDs that +are generated when the library is built, and their corresponding NIDs +are available as defined constants. For the functions below, application +code should treat all returned values -- OIDs, NIDs, or names -- as +constants. OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to an ASN1_OBJECT structure, its long name and its short name respectively, @@ -96,6 +102,16 @@ Objects do not need to be in the internal tables to be processed, the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical form of an OID. +Some objects are used to represent algorithms which do not have a +corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently +exists for a particular algorithm). As a result they B<cannot> be encoded or +decoded as part of ASN.1 structures. Applications can determine if there +is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero. + +These functions cannot return B<const> because an B<ASN1_OBJECT> can +represent both an internal, constant, OID and a dynamically-created one. +The latter cannot be constant because it needs to be freed after use. + =head1 EXAMPLES Create an object for B<commonName>: @@ -106,12 +122,13 @@ Create an object for B<commonName>: Check if an object is B<commonName> if (OBJ_obj2nid(obj) == NID_commonName) - /* Do something */ + /* Do something */ Create a new NID and initialize an object from it: int new_nid; ASN1_OBJECT *obj; + new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); obj = OBJ_nid2obj(new_nid); @@ -133,6 +150,8 @@ than enough to handle any OID encountered in practice. OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an error occurred. +It returns a pointer to an internal table and does not +allocate memory; ASN1_OBJECT_free() will have no effect. OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> on error. diff --git a/doc/crypto/OPENSSL_config.pod b/doc/crypto/OPENSSL_config.pod index 2d25b2669512..4e713653d09c 100644 --- a/doc/crypto/OPENSSL_config.pod +++ b/doc/crypto/OPENSSL_config.pod @@ -8,15 +8,14 @@ OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions #include <openssl/conf.h> - void OPENSSL_config(const char *config_name); + void OPENSSL_config(const char *appname); void OPENSSL_no_config(void); =head1 DESCRIPTION -OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf> -configuration file name using B<config_name>. If B<config_name> is NULL then -the file specified in the environment variable B<OPENSSL_CONF> will be used, -and if that is not set then a system default location is used. +OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf> and +reads from the application section B<appname>. If B<appname> is NULL then +the default section, B<openssl_conf>, will be used. Errors are silently ignored. Multiple calls have no effect. diff --git a/doc/crypto/OPENSSL_ia32cap.pod b/doc/crypto/OPENSSL_ia32cap.pod index 90156d21901b..5bcb82e3cfed 100644 --- a/doc/crypto/OPENSSL_ia32cap.pod +++ b/doc/crypto/OPENSSL_ia32cap.pod @@ -6,7 +6,7 @@ OPENSSL_ia32cap, OPENSSL_ia32cap_loc - the IA-32 processor capabilities vector =head1 SYNOPSIS - unsigned int *OPENSSL_ia32cap_loc(void); + unsigned long *OPENSSL_ia32cap_loc(void); #define OPENSSL_ia32cap ((OPENSSL_ia32cap_loc())[0]) =head1 DESCRIPTION diff --git a/doc/crypto/X509_verify_cert.pod b/doc/crypto/X509_verify_cert.pod index a22e44118cfc..4689e3afea4e 100644 --- a/doc/crypto/X509_verify_cert.pod +++ b/doc/crypto/X509_verify_cert.pod @@ -31,12 +31,13 @@ Applications rarely call this function directly but it is used by OpenSSL internally for certificate validation, in both the S/MIME and SSL/TLS code. -The negative return value from X509_verify_cert() can only occur if no -certificate is set in B<ctx> (due to a programming error); if X509_verify_cert() -twice without reinitialising B<ctx> in between; or if a retry -operation is requested during internal lookups (which never happens with -standard lookup methods). It is however recommended that application check -for <= 0 return value on error. +A negative return value from X509_verify_cert() can occur if it is invoked +incorrectly, such as with no certificate set in B<ctx>, or when it is called +twice in succession without reinitialising B<ctx> for the second call. +A negative return value can also happen due to internal resource problems or if +a retry operation is requested during internal lookups (which never happens +with standard lookup methods). +Applications must check for <= 0 return value on error. =head1 BUGS diff --git a/doc/crypto/d2i_PrivateKey.pod b/doc/crypto/d2i_PrivateKey.pod new file mode 100644 index 000000000000..e06ab6c5dee8 --- /dev/null +++ b/doc/crypto/d2i_PrivateKey.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +d2i_Private_key, d2i_AutoPrivateKey, i2d_PrivateKey - decode and encode +functions for reading and saving EVP_PKEY structures. + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **a, const unsigned char **pp, + long length); + EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp, + long length); + int i2d_PrivateKey(EVP_PKEY *a, unsigned char **pp); + +=head1 DESCRIPTION + +d2i_PrivateKey() decodes a private key using algorithm B<type>. It attempts to +use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The +B<type> parameter should be a public key algorithm constant such as +B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match B<type>. + +d2i_AutoPrivateKey() is similar to d2i_PrivateKey() except it attempts to +automatically detect the private key format. + +i2d_PrivateKey() encodes B<key>. It uses a key specific format or, if none is +defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format. + +These functions are similar to the d2i_X509() functions, and you should refer to +that page for a detailed description (see L<d2i_X509(3)>). + +=head1 NOTES + +All these functions use DER format and unencrypted keys. Applications wishing +to encrypt or decrypt private keys should use other functions such as +d2i_PKC8PrivateKey() instead. + +If the B<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey() +(i.e. an existing structure is being reused) and the key format is PKCS#8 +then B<*a> will be freed and replaced on a successful call. + +=head1 RETURN VALUES + +d2i_PrivateKey() and d2i_AutoPrivateKey() return a valid B<EVP_KEY> structure +or B<NULL> if an error occurs. The error code can be obtained by calling +L<ERR_get_error(3)>. + +i2d_PrivateKey() returns the number of bytes successfully encoded or a +negative value if an error occurs. The error code can be obtained by calling +L<ERR_get_error(3)>. + +=head1 SEE ALSO + +L<crypto(3)>, +L<d2i_PKCS8PrivateKey(3)> + +=cut diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod index 5b7c16fd0316..2743bc73e70e 100644 --- a/doc/crypto/d2i_X509.pod +++ b/doc/crypto/d2i_X509.pod @@ -9,8 +9,10 @@ i2d_X509_fp - X509 encode and decode functions #include <openssl/x509.h> - X509 *d2i_X509(X509 **px, const unsigned char **in, int len); + X509 *d2i_X509(X509 **px, const unsigned char **in, long len); + X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); int i2d_X509(X509 *x, unsigned char **out); + int i2d_X509_AUX(X509 *x, unsigned char **out); X509 *d2i_X509_bio(BIO *bp, X509 **x); X509 *d2i_X509_fp(FILE *fp, X509 **x); @@ -37,6 +39,11 @@ below, and the discussion in the RETURN VALUES section). If the call is successful B<*in> is incremented to the byte following the parsed data. +d2i_X509_AUX() is similar to d2i_X509() but the input is expected to consist of +an X509 certificate followed by auxiliary trust information. +This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects. +This function should not be called on untrusted input. + i2d_X509() encodes the structure pointed to by B<x> into DER format. If B<out> is not B<NULL> is writes the DER encoded data to the buffer at B<*out>, and increments it to point after the data just written. @@ -48,6 +55,11 @@ allocated for a buffer and the encoded data written to it. In this case B<*out> is not incremented and it points to the start of the data just written. +i2d_X509_AUX() is similar to i2d_X509(), but the encoded output contains both +the certificate and any auxiliary trust information. +This is used by the PEM routines to write "TRUSTED CERTIFICATE" objects. +Note, this is a non-standard OpenSSL-specific data format. + d2i_X509_bio() is similar to d2i_X509() except it attempts to parse data from BIO B<bp>. diff --git a/doc/crypto/hmac.pod b/doc/crypto/hmac.pod index 58a57f47bb4f..2c8f20a20188 100644 --- a/doc/crypto/hmac.pod +++ b/doc/crypto/hmac.pod @@ -60,13 +60,17 @@ function B<evp_md> and the key B<key> which is B<key_len> bytes long. It is deprecated and only included for backward compatibility with OpenSSL 0.9.6b. -HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use -the function B<evp_md> and key B<key>. 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<HMAC_CTX> in this -function. B<N.B. HMAC_Init() had this undocumented behaviour in -previous versions of OpenSSL - failure to switch to HMAC_Init_ex() in -programs that expect it will cause them to stop working>. +HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash +function B<evp_md> and key B<key>. If both are NULL (or B<evp_md> is the same +as the previous digest used by B<ctx> and B<key> is NULL) the existing key is +reused. B<ctx> must have been created with HMAC_CTX_new() before the first use +of an B<HMAC_CTX> in this function. B<N.B. HMAC_Init() had this undocumented +behaviour in previous versions of OpenSSL - failure to switch to HMAC_Init_ex() +in programs that expect it will cause them to stop working>. + +B<NB: if HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the +same as the previous digest used by B<ctx> then an error is returned +because reuse of an existing key with a different digest is not supported.> HMAC_Update() can be called repeatedly with chunks of the message to be authenticated (B<len> bytes at B<data>). diff --git a/doc/crypto/rand.pod b/doc/crypto/rand.pod index d102df2eee80..b754854bcf05 100644 --- a/doc/crypto/rand.pod +++ b/doc/crypto/rand.pod @@ -14,7 +14,7 @@ rand - pseudo-random number generator 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); + void RAND_add(const void *buf, int num, double entropy); int RAND_status(void); int RAND_load_file(const char *file, long max_bytes); diff --git a/doc/crypto/ui.pod b/doc/crypto/ui.pod index 04f8e9c360a8..2e94d8c0f689 100644 --- a/doc/crypto/ui.pod +++ b/doc/crypto/ui.pod @@ -109,12 +109,12 @@ that's connected to it, like duplicated input strings, results and others. UI_add_input_string() and UI_add_verify_string() add a prompt to the UI, as well as flags and a result buffer and the desired minimum and maximum -sizes of the result. The given information is used to prompt for -information, for example a password, and to verify a password (i.e. having -the user enter it twice and check that the same string was entered twice). -UI_add_verify_string() takes and extra argument that should be a pointer -to the result buffer of the input string that it's supposed to verify, or -verification will fail. +sizes of the result, not counting the final NUL character. The given +information is used to prompt for information, for example a password, +and to verify a password (i.e. having the user enter it twice and check +that the same string was entered twice). UI_add_verify_string() takes +and extra argument that should be a pointer to the result buffer of the +input string that it's supposed to verify, or verification will fail. UI_add_input_boolean() adds a prompt to the UI that's supposed to be answered in a boolean way, with a single character for yes and a different character |