Commit f987a4dd authored by Dr. Matthias St. Pierre's avatar Dr. Matthias St. Pierre
Browse files

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: default avatarPaul Dale <paul.dale@oracle.com>
Reviewed-by: default avatarTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/9257)

(cherry picked from commit 262c00882a2fd7cf16672bf467a86f75b4098a7c)
parent 4fb5fdb7

doc/man3/BN_generate_prime.pod

+8 −4
Original line number Diff line number Diff line
@@ -51,7 +51,9 @@ Deprecated: 
=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

doc/man3/DES_random_key.pod

+5 −3
Original line number Diff line number Diff line
@@ -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

doc/man3/DSA_generate_key.pod

+3 −1
Original line number Diff line number Diff line
@@ -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

doc/man3/DSA_sign.pod

+5 −2
Original line number Diff line number Diff line
@@ -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

doc/man3/EVP_DigestSignInit.pod

+5 −3
Original line number Diff line number Diff line
@@ -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