]>
Commit | Line | Data |
---|---|---|
60b52453 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/rand.h> | |
10 | ||
60b52453 UM |
11 | int RAND_load_file(const char *filename, long max_bytes); |
12 | ||
13 | int RAND_write_file(const char *filename); | |
14 | ||
9ee344f5 RS |
15 | const char *RAND_file_name(char *buf, size_t num); |
16 | ||
60b52453 UM |
17 | =head1 DESCRIPTION |
18 | ||
9ee344f5 RS |
19 | RAND_load_file() reads a number of bytes from file B<filename> and |
20 | adds them to the PRNG. If B<max_bytes> is non-negative, | |
21 | up to B<max_bytes> are read; | |
22 | if B<max_bytes> is -1, the complete file is read. | |
8389ec4b RS |
23 | Do not load the same file multiple times unless its contents have |
24 | been updated by RAND_write_file() between reads. | |
25 | Also, note that B<filename> should be adequately protected so that an | |
26 | attacker cannot replace or examine the contents. | |
242fcd69 AP |
27 | If B<filename> is not a regular file, then user is considered to be |
28 | responsible for any side effects, e.g. non-anticipated blocking or | |
29 | capture of controlling terminal. | |
9ee344f5 | 30 | |
8389ec4b | 31 | RAND_write_file() writes a number of random bytes (currently 128) to |
9ee344f5 RS |
32 | file B<filename> which can be used to initialize the PRNG by calling |
33 | RAND_load_file() in a later session. | |
34 | ||
60b52453 UM |
35 | RAND_file_name() generates a default path for the random seed |
36 | file. B<buf> points to a buffer of size B<num> in which to store the | |
13c03c8d MC |
37 | filename. |
38 | ||
2be7014c RL |
39 | On all systems, if the environment variable B<RANDFILE> is set, its |
40 | value will be used as the seed file name. | |
9ee344f5 | 41 | Otherwise, the file is called C<.rnd>, found in platform dependent locations: |
13c03c8d | 42 | |
2be7014c RL |
43 | =over 4 |
44 | ||
45 | =item On Windows (in order of preference) | |
46 | ||
9ee344f5 | 47 | %HOME%, %USERPROFILE%, %SYSTEMROOT%, C:\ |
2be7014c RL |
48 | |
49 | =item On VMS | |
50 | ||
9ee344f5 | 51 | SYS$LOGIN: |
2be7014c RL |
52 | |
53 | =item On all other systems | |
54 | ||
9ee344f5 | 55 | $HOME |
2be7014c RL |
56 | |
57 | =back | |
58 | ||
59 | If C<$HOME> (on non-Windows and non-VMS system) is not set either, or | |
60 | B<num> is too small for the path name, an error occurs. | |
60b52453 | 61 | |
60b52453 UM |
62 | =head1 RETURN VALUES |
63 | ||
fe7a4d7c | 64 | RAND_load_file() returns the number of bytes read or -1 on error. |
60b52453 | 65 | |
8389ec4b RS |
66 | RAND_write_file() returns the number of bytes written, or -1 if the |
67 | bytes written were generated without appropriate seeding. | |
60b52453 UM |
68 | |
69 | RAND_file_name() returns a pointer to B<buf> on success, and NULL on | |
70 | error. | |
71 | ||
72 | =head1 SEE ALSO | |
73 | ||
a73d990e DMSP |
74 | L<RAND_add(3)>, |
75 | L<RAND_bytes(3)>, | |
76 | L<RAND(7)> | |
60b52453 | 77 | |
e2f92610 RS |
78 | =head1 COPYRIGHT |
79 | ||
a73d990e | 80 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 81 | |
4746f25a | 82 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
83 | this file except in compliance with the License. You can obtain a copy |
84 | in the file LICENSE in the source distribution or at | |
85 | L<https://www.openssl.org/source/license.html>. | |
86 | ||
87 | =cut |