Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Minor corrections for the RAND_DRBG API documentation #5804

Closed
wants to merge 1 commit into from
Closed

Minor corrections for the RAND_DRBG API documentation #5804

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/man3/RAND_DRBG_set_callbacks.pod
View file
Open in desktop
Expand Up @@ -79,7 +79,7 @@ See NOTES section for more details.

The B<cleanup_entropy>() callback is called from the B<drbg> to to clear and
free the buffer allocated previously by get_entropy().
The values B<out> and B<outlen> are the random buffer's address and length,
The values B<out> and B<outlen> are the random buffer's address and length,
as returned by the get_entropy() callback.

The B<get_nonce>() and B<cleanup_nonce>() callbacks are used to obtain a nonce
Expand Down
4 changes: 2 additions & 2 deletions doc/man7/RAND.pod
View file
Open in desktop
Expand Up @@ -32,8 +32,8 @@ return value of L<RAND_bytes(3)> and don't take randomness for granted.
For long-term secrets, you can use L<RAND_priv_bytes(3)> instead.
This method does not provide 'better' randomness, it uses the same type of CSPRNG.
The intention behind using a dedicated CSPRNG exclusively for long-term secrets is
that none of its output should be visible to an attacker (e.g used as salt value),
in order to reveal as little information as possible about its internal state.
that none of its output should be visible to an attacker (e.g used as salt value),
in order to reveal as little information as possible about its internal state.

In the rare case where the default implementation does not satisfy your special
requirements, there are two options:
Expand Down
17 changes: 9 additions & 8 deletions doc/man7/RAND_DRBG.pod
View file
Open in desktop
Expand Up @@ -37,8 +37,7 @@ Typical examples for such special use cases are the following:

=item *

You want to use your own private DRBG instances, similar to how it
is currently done in the ssl library.
You want to use your own private DRBG instances.
Multiple DRBG instances which are accessed only by a single thread provide
additional security (because their internal states are independent) and
better scalability in multithreaded applications (because they don't need
Expand Down Expand Up @@ -80,8 +79,8 @@ the thread-local <public> and <private> DRBG instance, respectively.
=head2 The <master> DRBG instance

The <master> DRBG is not used directly by the application, only for reseeding
the two other two DRBG instances. It reseeds itself by obtaining randomness
either from os entropy sources or by consuming randomness which was added
the two other two DRBG instances. It reseeds itself by obtaining randomness
either from os entropy sources or by consuming randomness which was added
previously by L<RAND_add(3)>.

=head2 The <public> DRBG instance
Expand Down Expand Up @@ -144,10 +143,12 @@ together and are being used.
+------------------+ +------------------------------------+



The method L<RAND_DRBG_bytes(3)> is a convenience method wrapping the
L<RAND_DRBG_generate(3)> function, which serves the actual request for
random data.
Copy link
Contributor Author

@mspncp mspncp Mar 29, 2018 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At some time in the past, this line served as explanation for the caption <ssl->drbg> ==> RAND_DRBG_bytes(ssl->drbg, ...) in the image above. Now since that caption disappeared together with the per-ssl DRBG, this single line was orphaned and appeared to be a bit misplaced.

The usual way to obtain random bytes is to call RAND_bytes(...) or
RAND_priv_bytes(...). These calls are roughly equivalent to calling
RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...),
respectively. The method L<RAND_DRBG_bytes(3)> is a convenience method
wrapping the L<RAND_DRBG_generate(3)> function, which serves the actual
request for random data.

=head1 RESEEDING

Expand Down