path: root/doc/crypto
diff options
authorJung-uk Kim <jkim@FreeBSD.org>2016-09-22 13:04:03 +0000
committerJung-uk Kim <jkim@FreeBSD.org>2016-09-22 13:04:03 +0000
commite1b483878d9824c63d376895da633b0b96fbbaed (patch)
tree0846e185ed4cc1159a684e408e772c86ae0fc1a7 /doc/crypto
parent57f1256b1a087adbdf8e5c080dd9ed7975de939a (diff)
Import OpenSSL 1.0.2i.vendor/openssl/1.0.2i
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')
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
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
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
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.
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;
new_nid = OBJ_create("", "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);
-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
- unsigned int *OPENSSL_ia32cap_loc(void);
+ unsigned long *OPENSSL_ia32cap_loc(void);
#define OPENSSL_ia32cap ((OPENSSL_ia32cap_loc())[0])
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 @@
+=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);
+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.
+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
+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
+=head1 SEE ALSO
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