crypt_gensalt(3)

1CRYPT_GENSALT(3)               Library Functions              CRYPT_GENSALT(3)
2
3
4

NAME

6       crypt_gensalt, crypt_gensalt_rn, crypt_gensalt_ra - encode settings for
7       passphrase hashing
8

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

70       EINVAL prefix is invalid or not supported by this implementation; count
71              is invalid for the requested prefix; the input nrbytes is
72              insufficient for the smallest valid salt with the requested
73              prefix.
74
75       ERANGE crypt_gensalt_rn only: output_size is too small to hold the
76              compiled setting string.
77
78       ENOMEM Failed to allocate internal scratch memory.
79              crypt_gensalt_ra only: failed to allocate memory for the
80              compiled setting string.
81

FEATURE TEST MACROS

83       The following macros are defined by crypt.h:
84
85       CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX
86              A null pointer can be specified as prefix argument.
87
88       CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY
89              A null pointer can be specified as rbytes argument.
90

PORTABILITY NOTES

92       The functions crypt_gensalt, crypt_gensalt_rn, and crypt_gensalt_ra are
93       not part of any standard.  They originate with the Openwall project.  A
94       function with the name crypt_gensalt also exists on Solaris 10 and new‐
95       er, but its prototype and semantics differ.
96
97       The  default prefix and auto entropy features are available since libx‐
98       crypt version 4.0.0.  Portable software can use feature test macros  to
99       find  out whether null pointers could be specified as prefix and rbytes
100       arguments.
101
102       The set of supported hashing methods varies considerably from system to
103       system.
104

ATTRIBUTES

106       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
107       tributes(7).
108
109       ┌──────────────────┬───────────────┬──────────────────────────────┐
110       │Interface         │ Attribute     │ Value                        │
111       ├──────────────────┼───────────────┼──────────────────────────────┤
112       │crypt_gensalt     │ Thread safety │ MT-Unsafe race:crypt_gensalt │
113       ├──────────────────┼───────────────┼──────────────────────────────┤
114       │crypt_gensalt_rn, │ Thread safety │ MT-Safe                      │
115       │crypt_gensalt_ra  │               │                              │
116       └──────────────────┴───────────────┴──────────────────────────────┘
117