Commit b26befb541f8bc7d4f4e0beead50248b16949932 - openssl

Fix & update documentation about RAND_priv_bytes() Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Ben Kaduk <kaduk@mit.edu> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/6514) Nicola Tuveri authored 5 years ago Dr. Matthias St. Pierre committed 5 years ago

3 changed file(s) with 75 addition(s) and 23 deletion(s). Raw diff Collapse all Expand all

+37

-8

doc/man3/BN_rand.pod less more

1	1
2	2	=head1 NAME
3	3
4		BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-random number
	4	BN_rand, BN_priv_rand, BN_pseudo_rand,
	5	BN_rand_range, BN_priv_rand_range, BN_pseudo_rand_range
	6	- generate pseudo-random number
5	7
6	8	=head1 SYNOPSIS
7	9

9	11
10	12	int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
11	13
	14	int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom);
	15
12	16	int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
13	17
14	18	int BN_rand_range(BIGNUM rnd, BIGNUM range);
	19
	20	int BN_priv_rand_range(BIGNUM rnd, BIGNUM range);
15	21
16	22	int BN_pseudo_rand_range(BIGNUM rnd, BIGNUM range);
17	23

36	42	BN_rand_range() generates a cryptographically strong pseudo-random
37	43	number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>.
38	44
39		The PRNG must be seeded prior to calling BN_rand() or BN_rand_range().
	45	BN_priv_rand() and BN_priv_rand_range() have the same semantics as
	46	BN_rand() and BN_rand_range() respectively. They are intended to be
	47	used for generating values that should remain private, and mirror the
	48	same difference between L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>.
	49
	50	=head1 NOTES
	51
	52	Always check the error return value of these functions and do not take
	53	randomness for granted: an error occurs if the CSPRNG has not been
	54	seeded with enough randomness to ensure an unpredictable byte sequence.
40	55
41	56	=head1 RETURN VALUES
42	57

45	60
46	61	=head1 HISTORY
47	62
48		Starting with OpenSSL release 1.1.0,
49		BN_pseudo_rand() has been identical to BN_rand()
50		and
51		BN_pseudo_rand_range() has been identical to BN_rand_range().
	63	=over 2
	64
	65	=item *
	66
	67	Starting with OpenSSL release 1.1.0, BN_pseudo_rand() has been identical
	68	to BN_rand() and BN_pseudo_rand_range() has been identical to
	69	BN_rand_range().
52	70	The "pseudo" functions should not be used and may be deprecated in
53	71	a future release.
54	72
	73	=item *
	74
	75	BN_priv_rand() and BN_priv_rand_range() were added in OpenSSL 1.1.1.
	76
	77	=back
	78
55	79	=head1 SEE ALSO
56	80
57		L<ERR_get_error(3)>, L<RAND_add(3)>, L<RAND_bytes(3)>
	81	L<ERR_get_error(3)>,
	82	L<RAND_add(3)>,
	83	L<RAND_bytes(3)>,
	84	L<RAND_priv_bytes(3)>,
	85	L<RAND(7)>,
	86	L<RAND_DRBG(7)>
58	87
59	88	=head1 COPYRIGHT
60	89
61		Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
	90	Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
62	91
63	92	Licensed under the OpenSSL license (the "License"). You may not use
64	93	this file except in compliance with the License. You can obtain a copy

+26

-6

doc/man3/RAND_bytes.pod less more

19	19	=head1 DESCRIPTION
20	20
21	21	RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes
22		into B<buf>. An error occurs if the CSPRNG has not been seeded with
23		enough randomness to ensure an unpredictable byte sequence.
	22	into B<buf>.
24	23
25	24	RAND_priv_bytes() has the same semantics as RAND_bytes(). It is intended to
26		be used for generating long-term private keys. If using the default
27		RAND_METHOD, this function uses a separate instance of the PRNG so that
28		a compromise of the global generator will not affect such key generation.
	25	be used for generating values that should remain private. If using the
	26	default RAND_METHOD, this function uses a separate "private" PRNG
	27	instance so that a compromise of the "public" PRNG instance will not
	28	affect the secrecy of these private values, as described in L<RAND(7)>
	29	and L<RAND_DRBG(7)>.
	30
	31	=head1 NOTES
	32
	33	Always check the error return value of RAND_bytes() and
	34	RAND_priv_bytes() and do not take randomness for granted: an error occurs
	35	if the CSPRNG has not been seeded with enough randomness to ensure an
	36	unpredictable byte sequence.
29	37
30	38	=head1 RETURN VALUES
31	39

36	44
37	45	=head1 HISTORY
38	46
	47	=over 2
	48
	49	=item *
	50
39	51	RAND_pseudo_bytes() was deprecated in OpenSSL 1.1.0; use RAND_bytes() instead.
	52
	53	=item *
	54
	55	RAND_priv_bytes() was added in OpenSSL 1.1.1.
	56
	57	=back
40	58
41	59	=head1 SEE ALSO
42	60
43	61	L<RAND_add(3)>,
44	62	L<RAND_bytes(3)>,
	63	L<RAND_priv_bytes(3)>,
45	64	L<ERR_get_error(3)>,
46		L<RAND(7)>
	65	L<RAND(7)>,
	66	L<RAND_DRBG(7)>
47	67
48	68	=head1 COPYRIGHT
49	69

+12

-9

doc/man7/RAND.pod less more

23	23	It seeds and reseeds itself automatically using trusted random sources
24	24	provided by the operating system.
25	25
26		As a normal application developer, you don't have to worry about any details,
	26	As a normal application developer, you do not have to worry about any details,
27	27	just use L<RAND_bytes(3)> to obtain random data.
28	28	Having said that, there is one important rule to obey: Always check the error
29		return value of L<RAND_bytes(3)> and don't take randomness for granted.
	29	return value of L<RAND_bytes(3)> and do not take randomness for granted.
30	30
31		For long-term secrets, you can use L<RAND_priv_bytes(3)> instead.
	31	For values that should remain secret, you can use L<RAND_priv_bytes(3)>
	32	instead.
32	33	This method does not provide 'better' randomness, it uses the same type of CSPRNG.
33		The intention behind using a dedicated CSPRNG exclusively for long-term secrets is
34		that none of its output should be visible to an attacker (e.g used as salt value),
35		in order to reveal as little information as possible about its internal state.
	34	The intention behind using a dedicated CSPRNG exclusively for private
	35	values is that none of its output should be visible to an attacker (e.g.,
	36	used as salt value), in order to reveal as little information as
	37	possible about its internal state, and that a compromise of the "public"
	38	CSPRNG instance will not affect the secrecy of these private values.
36	39
37	40	In the rare case where the default implementation does not satisfy your special
38	41	requirements, there are two options:

60	63	L<RAND_add(3)>,
61	64	L<RAND_bytes(3)>,
62	65	L<RAND_priv_bytes(3)>,
63		L<RAND_get_rand_method(3)>
64		L<RAND_set_rand_method(3)>
	66	L<RAND_get_rand_method(3)>,
	67	L<RAND_set_rand_method(3)>,
65	68	L<RAND_OpenSSL(3)>,
66		L<RAND_DRBG(7)>,
	69	L<RAND_DRBG(7)>
67	70
68	71	=head1 COPYRIGHT
69	72