crypt_gensalt(3)

1CRYPT_GENSALT(3)         BSD Library Functions Manual         CRYPT_GENSALT(3)
2

NAME

4     crypt_gensalt, crypt_gensalt_rn, crypt_gensalt_ra — encode settings for
5     passphrase hashing
6

LIBRARY

8     Crypt Library (libcrypt, -lcrypt)
9

SYNOPSIS

11     #include <crypt.h>
12
13     char *
14     crypt_gensalt(const char *prefix, unsigned long count,
15         const char *rbytes, int nrbytes);
16
17     char *
18     crypt_gensalt_rn(const char * prefix, unsigned long count,
19         const char *rbytes, int nrbytes, char * output, int output_size);
20
21     char *
22     crypt_gensalt_ra(const char *prefix, unsigned long count,
23         const char *rbytes, int nrbytes);
24

DESCRIPTION

26     The crypt_gensalt, crypt_gensalt_rn, and crypt_gensalt_ra functions com‐
27     pile a string for use as the setting argument to crypt, crypt_r,
28     crypt_rn, and crypt_ra.  prefix selects the hashing method to use.  count
29     controls the CPU time cost of the hash; the valid range for count and the
30     exact meaning of “CPU time cost” depends on the hashing method, but
31     larger numbers correspond to more costly hashes.  rbytes should point to
32     nrbytes cryptographically random bytes for use as “salt.”
33
34     If prefix is a null pointer, the best available hashing method will be
35     selected.  (CAUTION: if prefix is an empty string, the “traditional” DES-
36     based hashing method will be selected; this method is unacceptably weak
37     by modern standards.)  If count is 0, a low default cost will be
38     selected.  If rbytes is a null pointer, an appropriate number of random
39     bytes will be obtained from the operating system, and nrbytes is ignored.
40
41     See crypt(5) for other strings that can be used as prefix, and valid val‐
42     ues of count for each.
43

RETURN VALUES

45     crypt_gensalt, crypt_gensalt_rn, and crypt_gensalt_ra return a pointer to
46     an encoded setting string.  This string will be entirely printable ASCII,
47     and will not contain whitespace or the characters ‘:’, ‘;’, ‘*’, ‘!’, or
48     ‘\’.  See crypt(5) for more detail on the format of this string.  Upon
49     error, they return a null pointer and set errno to an appropriate error
50     code.
51
52     crypt_gensalt places its result in a static storage area, which will be
53     overwritten by subsequent calls to crypt_gensalt.  It is not safe to call
54     crypt_gensalt from multiple threads simultaneously.  However, it is safe
55     to pass the string returned by crypt_gensalt directly to crypt without
56     copying it; each function has its own static storage area.
57
58     crypt_gensalt_rn places its result in the supplied output buffer, which
59     has output_size bytes of storage available.  output_size should be
60     greater than or equal to CRYPT_GENSALT_OUTPUT_SIZE.
61
62     crypt_gensalt_ra allocates memory for its result using malloc(3).  It
63     should be freed with free(3) after use.
64
65     Upon error, in addition to returning a null pointer, crypt_gensalt and
66     crypt_gensalt_rn will write an invalid setting string to their output
67     buffer, if there is enough space; this string will begin with a ‘*’ and
68     will not be equal to prefix.
69

ERRORS

71     EINVAL             prefix is invalid or not supported by this implementa‐
72                        tion; count is invalid for the requested prefix; the
73                        input nrbytes is insufficient for the smallest valid
74                        salt with the requested prefix.
75
76     ERANGE             crypt_gensalt_rn only: output_size is too small to
77                        hold the compiled setting string.
78
79     ENOMEM             Failed to allocate internal scratch memory.
80                        crypt_gensalt_ra only: failed to allocate memory for
81                        the compiled setting string.
82
83     ENOSYS, EACCES, EIO, etc.
84                        Obtaining random bytes from the operating system
85                        failed.  This can only happen when rbytes is a null
86                        pointer.
87

FEATURE TEST MACROS

89     The following macros are defined by <crypt.h>:
90
91     CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX
92             A null pointer can be specified as the prefix argument.
93
94     CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY
95             A null pointer can be specified as the rbytes argument.
96

PORTABILITY NOTES

98     The functions crypt_gensalt, crypt_gensalt_rn, and crypt_gensalt_ra are
99     not part of any standard.  They originate with the Openwall project.  A
100     function with the name crypt_gensalt also exists on Solaris 10 and newer,
101     but its prototype and semantics differ.
102
103     The default prefix and auto entropy features are available since libx‐
104     crypt version 4.0.0.  Portable software can use feature test macros to
105     find out whether null pointers can be used for the prefix and rbytes
106     arguments.
107
108     The set of supported hashing methods varies considerably from system to
109     system.
110

ATTRIBUTES

112     For an explanation of the terms used in this section, see attributes(7).
113     ┌──────────────────┬───────────────┬──────────────────────────────┐
114     │Interface         │ Attribute     │ Value                        │
115     ├──────────────────┼───────────────┼──────────────────────────────┤
116     │crypt_gensalt     │ Thread safety │ MT-Unsafe race:crypt_gensalt │
117     ├──────────────────┼───────────────┼──────────────────────────────┤
118     │crypt_gensalt_rn, │ Thread safety │ MT-Safe                      │
119     │crypt_gensalt_ra  │               │                              │
120     └──────────────────┴───────────────┴──────────────────────────────┘
121