[openssl] master update
matthias.st.pierre at ncp-e.com
matthias.st.pierre at ncp-e.com
Thu Jun 27 12:48:24 UTC 2019
The branch master has been updated
via 262c00882a2fd7cf16672bf467a86f75b4098a7c (commit)
from 0588be2e01c244c41b0215689f411a6223063fd7 (commit)
- Log -----------------------------------------------------------------
commit 262c00882a2fd7cf16672bf467a86f75b4098a7c
Author: Dr. Matthias St. Pierre <Matthias.St.Pierre at ncp-e.com>
Date: Thu Jun 27 10:12:08 2019 +0200
man: clarify the 'random number generator must be seeded' requirement
The manual pages require for some API functions that the 'random number
generator must be seeded' before calling the function. Initially, this
was meant literally, i.e. the OpenSSL CSPRNG had to be seeded manually
before calling these functions.
Since version 1.1.1, the CSPRNG is seeded automatically on first use,
so it's not the responsibility of the programmer anymore. Still, he
needs to be aware that the seeding might fail.
Reviewed-by: Paul Dale <paul.dale at oracle.com>
Reviewed-by: Tomas Mraz <tmraz at fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/9257)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/BN_generate_prime.pod | 12 ++++++++----
doc/man3/DES_random_key.pod | 8 +++++---
doc/man3/DSA_generate_key.pod | 4 +++-
doc/man3/DSA_sign.pod | 7 +++++--
doc/man3/EVP_DigestSignInit.pod | 8 +++++---
doc/man3/EVP_DigestVerifyInit.pod | 8 +++++---
doc/man3/EVP_SealInit.pod | 7 +++++--
doc/man3/EVP_SignInit.pod | 7 ++++---
doc/man3/RSA_blinding_on.pod | 3 +--
doc/man3/RSA_generate_key.pod | 9 ++++++---
doc/man3/RSA_padding_add_PKCS1_type_1.pod | 5 ++++-
doc/man3/RSA_sign_ASN1_OCTET_STRING.pod | 8 ++++++--
doc/man7/RAND.pod | 6 ++++++
13 files changed, 63 insertions(+), 29 deletions(-)
diff --git a/doc/man3/BN_generate_prime.pod b/doc/man3/BN_generate_prime.pod
index 253fde3..eb5d89a 100644
--- a/doc/man3/BN_generate_prime.pod
+++ b/doc/man3/BN_generate_prime.pod
@@ -51,7 +51,9 @@ L<openssl_user_macros(7)>:
=head1 DESCRIPTION
BN_generate_prime_ex() generates a pseudo-random prime number of
-at least bit length B<bits>.
+at least bit length B<bits>. The returned number is probably prime
+with a negligible error.
+
If B<ret> is not B<NULL>, it will be used to store the number.
If B<cb> is not B<NULL>, it is used as follows:
@@ -89,8 +91,9 @@ generator.
If B<safe> is true, it will be a safe prime (i.e. a prime p so
that (p-1)/2 is also prime).
-The PRNG must be seeded prior to calling BN_generate_prime_ex().
-The prime number generation has a negligible error probability.
+The random generator must be seeded prior to calling BN_generate_prime_ex().
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is
prime. The following tests are performed until one of them shows that
@@ -193,7 +196,8 @@ Instead applications should create a BN_GENCB structure using BN_GENCB_new:
=head1 SEE ALSO
L<DH_generate_parameters(3)>, L<DSA_generate_parameters(3)>,
-L<RSA_generate_key(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>
+L<RSA_generate_key(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
+L<RAND(7)>
=head1 HISTORY
diff --git a/doc/man3/DES_random_key.pod b/doc/man3/DES_random_key.pod
index 4f0f25a..a148000 100644
--- a/doc/man3/DES_random_key.pod
+++ b/doc/man3/DES_random_key.pod
@@ -104,9 +104,11 @@ 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<RAND_bytes(3)>). If the PRNG
-could not generate a secure key, 0 is returned.
+DES_random_key() generates a random key. The random generator must be
+seeded when calling this function.
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
+If the function fails, 0 is returned.
Before a DES key can be used, it must be converted into the
architecture dependent I<DES_key_schedule> via the
diff --git a/doc/man3/DSA_generate_key.pod b/doc/man3/DSA_generate_key.pod
index 6dc2f79..079c2fe 100644
--- a/doc/man3/DSA_generate_key.pod
+++ b/doc/man3/DSA_generate_key.pod
@@ -15,7 +15,9 @@ DSA_generate_key - generate DSA key pair
DSA_generate_key() expects B<a> to contain DSA parameters. It generates
a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>.
-The PRNG must be seeded prior to calling DSA_generate_key().
+The random generator must be seeded prior to calling DSA_generate_key().
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
=head1 RETURN VALUES
diff --git a/doc/man3/DSA_sign.pod b/doc/man3/DSA_sign.pod
index 07fa3ca..bf99ecc 100644
--- a/doc/man3/DSA_sign.pod
+++ b/doc/man3/DSA_sign.pod
@@ -36,8 +36,10 @@ B<dsa> is the signer's public key.
The B<type> parameter is ignored.
-The PRNG must be seeded before DSA_sign() (or DSA_sign_setup())
+The random generator must be seeded when DSA_sign() (or DSA_sign_setup())
is called.
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
=head1 RETURN VALUES
@@ -54,7 +56,8 @@ Standard, DSS), ANSI X9.30
=head1 SEE ALSO
L<DSA_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>,
-L<DSA_do_sign(3)>
+L<DSA_do_sign(3)>,
+L<RAND(7)>
=head1 COPYRIGHT
diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod
index b584d70..4c497fa 100644
--- a/doc/man3/EVP_DigestSignInit.pod
+++ b/doc/man3/EVP_DigestSignInit.pod
@@ -125,8 +125,9 @@ and public key algorithms. This meant that "clone" digests such as EVP_dss1()
needed to be used to sign using SHA1 and DSA. This is no longer necessary and
the use of clone digest is now discouraged.
-For some key types and parameters the random number generator must be seeded
-or the operation will fail.
+For some key types and parameters the random number generator must be seeded.
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
context. This means that calls to EVP_DigestSignUpdate() and
@@ -147,7 +148,8 @@ L<EVP_DigestVerifyInit(3)>,
L<EVP_DigestInit(3)>,
L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>,
-L<SHA1(3)>, L<dgst(1)>
+L<SHA1(3)>, L<dgst(1)>,
+L<RAND(7)>
=head1 HISTORY
diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod
index abb2930..9e2a045 100644
--- a/doc/man3/EVP_DigestVerifyInit.pod
+++ b/doc/man3/EVP_DigestVerifyInit.pod
@@ -76,8 +76,9 @@ and public key algorithms. This meant that "clone" digests such as EVP_dss1()
needed to be used to sign using SHA1 and DSA. This is no longer necessary and
the use of clone digest is now discouraged.
-For some key types and parameters the random number generator must be seeded
-or the operation will fail.
+For some key types and parameters the random number generator must be seeded.
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest
context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can
@@ -93,7 +94,8 @@ L<EVP_DigestSignInit(3)>,
L<EVP_DigestInit(3)>,
L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>,
-L<SHA1(3)>, L<dgst(1)>
+L<SHA1(3)>, L<dgst(1)>,
+L<RAND(7)>
=head1 HISTORY
diff --git a/doc/man3/EVP_SealInit.pod b/doc/man3/EVP_SealInit.pod
index f630e1b..73d9bb7 100644
--- a/doc/man3/EVP_SealInit.pod
+++ b/doc/man3/EVP_SealInit.pod
@@ -55,7 +55,9 @@ failure.
=head1 NOTES
Because a random secret key is generated the random number generator
-must be seeded before calling EVP_SealInit().
+must be seeded when EVP_SealInit() is called.
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
The public key must be RSA because it is the only OpenSSL public key
algorithm that supports key transport.
@@ -75,7 +77,8 @@ with B<type> set to NULL.
L<evp(7)>, L<RAND_bytes(3)>,
L<EVP_EncryptInit(3)>,
-L<EVP_OpenInit(3)>
+L<EVP_OpenInit(3)>,
+L<RAND(7)>
=head1 COPYRIGHT
diff --git a/doc/man3/EVP_SignInit.pod b/doc/man3/EVP_SignInit.pod
index 02786d0..8dbc644 100644
--- a/doc/man3/EVP_SignInit.pod
+++ b/doc/man3/EVP_SignInit.pod
@@ -66,9 +66,10 @@ The B<EVP> interface to digital signatures should almost always be used in
preference to the low level interfaces. This is because the code then becomes
transparent to the algorithm used and much more flexible.
-When signing with DSA private keys the random number generator must be seeded
-or the operation will fail. The random number generator does not need to be
-seeded for RSA signatures.
+When signing with DSA private keys the random number generator must be seeded.
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
+This requirement does not hold for RSA signatures.
The call to EVP_SignFinal() internally finalizes a copy of the digest context.
This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called
diff --git a/doc/man3/RSA_blinding_on.pod b/doc/man3/RSA_blinding_on.pod
index 3bdf734..db06b2f 100644
--- a/doc/man3/RSA_blinding_on.pod
+++ b/doc/man3/RSA_blinding_on.pod
@@ -20,8 +20,7 @@ must be used to protect the RSA operation from that attack.
RSA_blinding_on() turns blinding on for key B<rsa> and generates a
random blinding factor. B<ctx> is B<NULL> or a pre-allocated and
-initialized B<BN_CTX>. The random number generator must be seeded
-prior to calling RSA_blinding_on().
+initialized B<BN_CTX>.
RSA_blinding_off() turns blinding off and frees the memory used for
the blinding factor.
diff --git a/doc/man3/RSA_generate_key.pod b/doc/man3/RSA_generate_key.pod
index b463392..9d8b422 100644
--- a/doc/man3/RSA_generate_key.pod
+++ b/doc/man3/RSA_generate_key.pod
@@ -27,8 +27,10 @@ be seeded prior to calling RSA_generate_key_ex().
RSA_generate_multi_prime_key() generates a multi-prime RSA key pair and stores
it in the B<RSA> structure provided in B<rsa>. The number of primes is given by
-the B<primes> parameter. The pseudo-random number generator must be seeded prior
-to calling RSA_generate_multi_prime_key().
+the B<primes> parameter. The random number generator must be seeded when
+calling RSA_generate_multi_prime_key().
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
The modulus size will be of length B<bits>, the number of primes to form the
modulus will be B<primes>, and the public exponent will be B<e>. Key sizes
@@ -88,7 +90,8 @@ B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
=head1 SEE ALSO
-L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<BN_generate_prime(3)>
+L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<BN_generate_prime(3)>,
+L<RAND(7)>
=head1 HISTORY
diff --git a/doc/man3/RSA_padding_add_PKCS1_type_1.pod b/doc/man3/RSA_padding_add_PKCS1_type_1.pod
index 685063b..40eb8f9 100644
--- a/doc/man3/RSA_padding_add_PKCS1_type_1.pod
+++ b/doc/man3/RSA_padding_add_PKCS1_type_1.pod
@@ -100,6 +100,8 @@ simply copy the data
The random number generator must be seeded prior to calling
RSA_padding_add_xxx().
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
a valid encoding for a B<rsa_len> byte RSA key in the respective
@@ -143,7 +145,8 @@ including PKCS1_OAEP.
L<RSA_public_encrypt(3)>,
L<RSA_private_decrypt(3)>,
-L<RSA_sign(3)>, L<RSA_verify(3)>
+L<RSA_sign(3)>, L<RSA_verify(3)>,
+L<RAND(7)>
=head1 COPYRIGHT
diff --git a/doc/man3/RSA_sign_ASN1_OCTET_STRING.pod b/doc/man3/RSA_sign_ASN1_OCTET_STRING.pod
index fad65e0..27e7cdf 100644
--- a/doc/man3/RSA_sign_ASN1_OCTET_STRING.pod
+++ b/doc/man3/RSA_sign_ASN1_OCTET_STRING.pod
@@ -26,7 +26,10 @@ memory.
B<dummy> is ignored.
-The random number generator must be seeded prior to calling RSA_sign_ASN1_OCTET_STRING().
+The random number generator must be seeded when calling
+RSA_sign_ASN1_OCTET_STRING().
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
RSA_verify_ASN1_OCTET_STRING() verifies that the signature B<sigbuf>
of size B<siglen> is the DER representation of a given octet string
@@ -49,7 +52,8 @@ These functions serve no recognizable purpose.
L<ERR_get_error(3)>,
L<RAND_bytes(3)>, L<RSA_sign(3)>,
-L<RSA_verify(3)>
+L<RSA_verify(3)>,
+L<RAND(7)>
=head1 COPYRIGHT
diff --git a/doc/man7/RAND.pod b/doc/man7/RAND.pod
index 3d47666..e253e90 100644
--- a/doc/man7/RAND.pod
+++ b/doc/man7/RAND.pod
@@ -28,6 +28,12 @@ As a normal application developer, you do not have to worry about any details,
just use L<RAND_bytes(3)> to obtain random data.
Having said that, there is one important rule to obey: Always check the error
return value of L<RAND_bytes(3)> and do not take randomness for granted.
+Although (re-)seeding is automatic, it can fail because no trusted random source
+is available or the trusted source(s) temporarily fail to provide sufficient
+random seed material.
+In this case the CSPRNG enters an error state and ceases to provide output,
+until it is able to recover from the error by reseeding itself.
+For more details on reseeding and error recovery, see L<RAND_DRBG(7)>.
For values that should remain secret, you can use L<RAND_priv_bytes(3)>
instead.
More information about the openssl-commits
mailing list