mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-12-15 06:01:37 +08:00
Code Issues Packages Projects Releases Wiki Activity
5a6d6fe666
openssl/doc/man3/RAND_load_file.pod

88 lines
2.3 KiB
Plaintext
Raw Normal View History

Document RAND library.
2000-01-22 01:50:27 +08:00
=pod
=head1 NAME
RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file
=head1 SYNOPSIS
#include <openssl/rand.h>
int RAND_load_file(const char *filename, long max_bytes);
int RAND_write_file(const char *filename);
Cleanup RAND_load_file,RAND_write_file Document an internal assumption that these are only for use with files, and return an error if not. That made the code much simpler. Leave it as writing 1024 bytes, even though we don't need more than 256 from a security perspective. But the amount isn't specified, now, so we can change it later if we want. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3864)
2017-07-06 04:08:19 +08:00
const char *RAND_file_name(char *buf, size_t num);
Document RAND library.
2000-01-22 01:50:27 +08:00
=head1 DESCRIPTION
Cleanup RAND_load_file,RAND_write_file Document an internal assumption that these are only for use with files, and return an error if not. That made the code much simpler. Leave it as writing 1024 bytes, even though we don't need more than 256 from a security perspective. But the amount isn't specified, now, so we can change it later if we want. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3864)
2017-07-06 04:08:19 +08:00
RAND_load_file() reads a number of bytes from file B<filename> and
Align documentation with recommendations of Linux Documentation Project This change applies the recommendation of the Linux Documentation Project to the documentation files of OpenSSL. Additionally, util/find-doc-nits was updated accordingly. The change follows a suggestion of mspncp on https://github.com/openssl/openssl/pull/12370 and incoporates the requested changes on the pull request Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/12460)
2020-07-17 18:31:26 +08:00
adds them to the PRNG. If B<max_bytes> is nonnegative,
Cleanup RAND_load_file,RAND_write_file Document an internal assumption that these are only for use with files, and return an error if not. That made the code much simpler. Leave it as writing 1024 bytes, even though we don't need more than 256 from a security perspective. But the amount isn't specified, now, so we can change it later if we want. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3864)
2017-07-06 04:08:19 +08:00
up to B<max_bytes> are read;
if B<max_bytes> is -1, the complete file is read.
Add --with-rand-seed Add a new config param to specify how the CSPRNG should be seeded. Illegal values or nonsensical combinations (e.g., anything other than "os" on VMS or HP VOS etc) result in build failures. Add RDSEED support. Add RDTSC but leave it disabled for now pending more investigation. Refactor and reorganization all seeding files (rand_unix/win/vms) so that they are simpler. Only require 128 bits of seeding material. Many document improvements, including why to not use RAND_add() and the limitations around using load_file/write_file. Document RAND_poll(). Cleanup Windows RAND_poll and return correct status More completely initialize the default DRBG. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/3965)
2017-07-18 21:39:21 +08:00
Do not load the same file multiple times unless its contents have
been updated by RAND_write_file() between reads.
Also, note that B<filename> should be adequately protected so that an
attacker cannot replace or examine the contents.
rand/randfile.c: permit non-regular files in RAND_load_file. Apparently applications rely on RAND_load_file's ability to work with non-regular files, customarily with /dev/urandom, so that the ban was not exactly appropriate. Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Bernd Edlinger <bernd.edlinger@hotmail.de> Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Tim Hudson <tjh@openssl.org> (Merged from https://github.com/openssl/openssl/pull/5737)
2018-03-23 22:12:20 +08:00
If B<filename> is not a regular file, then user is considered to be
responsible for any side effects, e.g. non-anticipated blocking or
capture of controlling terminal.
Cleanup RAND_load_file,RAND_write_file Document an internal assumption that these are only for use with files, and return an error if not. That made the code much simpler. Leave it as writing 1024 bytes, even though we don't need more than 256 from a security perspective. But the amount isn't specified, now, so we can change it later if we want. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3864)
2017-07-06 04:08:19 +08:00
Add --with-rand-seed Add a new config param to specify how the CSPRNG should be seeded. Illegal values or nonsensical combinations (e.g., anything other than "os" on VMS or HP VOS etc) result in build failures. Add RDSEED support. Add RDTSC but leave it disabled for now pending more investigation. Refactor and reorganization all seeding files (rand_unix/win/vms) so that they are simpler. Only require 128 bits of seeding material. Many document improvements, including why to not use RAND_add() and the limitations around using load_file/write_file. Document RAND_poll(). Cleanup Windows RAND_poll and return correct status More completely initialize the default DRBG. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/3965)
2017-07-18 21:39:21 +08:00
RAND_write_file() writes a number of random bytes (currently 128) to
Cleanup RAND_load_file,RAND_write_file Document an internal assumption that these are only for use with files, and return an error if not. That made the code much simpler. Leave it as writing 1024 bytes, even though we don't need more than 256 from a security perspective. But the amount isn't specified, now, so we can change it later if we want. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3864)
2017-07-06 04:08:19 +08:00
file B<filename> which can be used to initialize the PRNG by calling
RAND_load_file() in a later session.
Document RAND library.
2000-01-22 01:50:27 +08:00
RAND_file_name() generates a default path for the random seed
file. B<buf> points to a buffer of size B<num> in which to store the
Change default directory for storing the .rnd file on Windows Previously we would try %RANDFILE%, then %HOME% and finally "C:". Unfortunately this often ends up being "C:" which the user may not have write permission for. Now we try %RANDFILE% first, and then the same set of environment vars as GetTempFile() uses, i.e. %TMP%, then %TEMP%, %USERPROFILE% and %SYSTEMROOT%. If all else fails we fall back to %HOME% and only then "C:". Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-06-15 23:14:30 +08:00
filename.
Change the RAND_file_name documentation accordingly Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Andy Polyakov <appro@openssl.org>
2016-06-20 14:11:50 +08:00
On all systems, if the environment variable B<RANDFILE> is set, its
Fix errors found by new find-doc-nits Also patch find-doc-nits to ignore a Microsoft trademark and not flag it as a spelling error. Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/10023)
2019-09-28 01:17:09 +08:00
value will be used as the seed filename.
Cleanup RAND_load_file,RAND_write_file Document an internal assumption that these are only for use with files, and return an error if not. That made the code much simpler. Leave it as writing 1024 bytes, even though we don't need more than 256 from a security perspective. But the amount isn't specified, now, so we can change it later if we want. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3864)
2017-07-06 04:08:19 +08:00
Otherwise, the file is called C<.rnd>, found in platform dependent locations:
Change default directory for storing the .rnd file on Windows Previously we would try %RANDFILE%, then %HOME% and finally "C:". Unfortunately this often ends up being "C:" which the user may not have write permission for. Now we try %RANDFILE% first, and then the same set of environment vars as GetTempFile() uses, i.e. %TMP%, then %TEMP%, %USERPROFILE% and %SYSTEMROOT%. If all else fails we fall back to %HOME% and only then "C:". Reviewed-by: Rich Salz <rsalz@openssl.org>
2016-06-15 23:14:30 +08:00
Change the RAND_file_name documentation accordingly Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Andy Polyakov <appro@openssl.org>
2016-06-20 14:11:50 +08:00
=over 4
=item On Windows (in order of preference)
Cleanup RAND_load_file,RAND_write_file Document an internal assumption that these are only for use with files, and return an error if not. That made the code much simpler. Leave it as writing 1024 bytes, even though we don't need more than 256 from a security perspective. But the amount isn't specified, now, so we can change it later if we want. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3864)
2017-07-06 04:08:19 +08:00
%HOME%, %USERPROFILE%, %SYSTEMROOT%, C:\
Change the RAND_file_name documentation accordingly Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Andy Polyakov <appro@openssl.org>
2016-06-20 14:11:50 +08:00
=item On VMS
Cleanup RAND_load_file,RAND_write_file Document an internal assumption that these are only for use with files, and return an error if not. That made the code much simpler. Leave it as writing 1024 bytes, even though we don't need more than 256 from a security perspective. But the amount isn't specified, now, so we can change it later if we want. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3864)
2017-07-06 04:08:19 +08:00
SYS$LOGIN:
Change the RAND_file_name documentation accordingly Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Andy Polyakov <appro@openssl.org>
2016-06-20 14:11:50 +08:00
=item On all other systems
Cleanup RAND_load_file,RAND_write_file Document an internal assumption that these are only for use with files, and return an error if not. That made the code much simpler. Leave it as writing 1024 bytes, even though we don't need more than 256 from a security perspective. But the amount isn't specified, now, so we can change it later if we want. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3864)
2017-07-06 04:08:19 +08:00
$HOME
Change the RAND_file_name documentation accordingly Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Andy Polyakov <appro@openssl.org>
2016-06-20 14:11:50 +08:00
=back
If C<$HOME> (on non-Windows and non-VMS system) is not set either, or
Fix errors found by new find-doc-nits Also patch find-doc-nits to ignore a Microsoft trademark and not flag it as a spelling error. Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/10023)
2019-09-28 01:17:09 +08:00
B<num> is too small for the pathname, an error occurs.
Document RAND library.
2000-01-22 01:50:27 +08:00
=head1 RETURN VALUES
Update RAND_load_file return value. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/4537)
2017-10-17 00:10:45 +08:00
RAND_load_file() returns the number of bytes read or -1 on error.
Document RAND library.
2000-01-22 01:50:27 +08:00
Add --with-rand-seed Add a new config param to specify how the CSPRNG should be seeded. Illegal values or nonsensical combinations (e.g., anything other than "os" on VMS or HP VOS etc) result in build failures. Add RDSEED support. Add RDTSC but leave it disabled for now pending more investigation. Refactor and reorganization all seeding files (rand_unix/win/vms) so that they are simpler. Only require 128 bits of seeding material. Many document improvements, including why to not use RAND_add() and the limitations around using load_file/write_file. Document RAND_poll(). Cleanup Windows RAND_poll and return correct status More completely initialize the default DRBG. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/3965)
2017-07-18 21:39:21 +08:00
RAND_write_file() returns the number of bytes written, or -1 if the
bytes written were generated without appropriate seeding.
Document RAND library.
2000-01-22 01:50:27 +08:00
RAND_file_name() returns a pointer to B<buf> on success, and NULL on
error.
=head1 SEE ALSO
Add documentation for the RAND_DRBG API The RAND_DRBG API was added in PR #5462 and modified by PR #5547. This commit adds the corresponding documention. Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/5461)
2018-02-28 02:02:24 +08:00
L<RAND_add(3)>,
L<RAND_bytes(3)>,
L<RAND(7)>
Document RAND library.
2000-01-22 01:50:27 +08:00
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
=head1 COPYRIGHT
Update copyright year Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/12595)
2020-08-06 20:22:30 +08:00
Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
Following the license change, modify the boilerplates in doc/man3/ [skip ci] Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7829)
2018-12-06 21:04:44 +08:00
Licensed under the Apache License 2.0 (the "License"). You may not use
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
Reference in New Issue Copy Permalink