crypt_checksalt(3)

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

NAME

4     crypt_checksalt — validate a crypt setting string
5

LIBRARY

7     Crypt Library (libcrypt, -lcrypt)
8

SYNOPSIS

10     #include <crypt.h>
11
12     int
13     crypt_checksalt(const char *setting);
14

DESCRIPTION

16     crypt_checksalt checks the setting string against the system configura‐
17     tion and reports whether the hashing method and parameters it specifies
18     are acceptable.  It is intended to be used by programs such as login(1)
19     to determine whether the user's passphrase should be re-hashed using the
20     currently preferred hashing method.
21

RETURN VALUES

23     The return value is 0 if there is nothing wrong with this setting.  Oth‐
24     erwise, it is one of the following constants:
25
26     CRYPT_SALT_OK
27           setting is a fully correct setting string.  This constant is guar‐
28           anteed to equal 0.
29
30     CRYPT_SALT_INVALID
31           setting is not a valid setting string; either it specifies a hash‐
32           ing method that is not known to this version of libxcrypt, or it
33           specifies invalid parameters for the method.
34
35     CRYPT_SALT_METHOD_DISABLED (Not implemented, yet)
36           setting specifies a hashing method that is no longer allowed to be
37           used at all; crypt will fail if passed this setting.  Manual inter‐
38           vention will be required to reactivate the user's account.
39
40     CRYPT_SALT_METHOD_LEGACY
41           setting specifies a hashing method that is no longer considered
42           strong enough for use with new passphrases.  crypt will still au‐
43           thenticate a passphrase against this setting, but if authentication
44           succeeds, the passphrase should be re-hashed using the currently
45           preferred method.
46
47     CRYPT_SALT_TOO_CHEAP (Not implemented, yet)
48           setting specifies cost parameters that are considered too cheap for
49           use with new passphrases.  crypt will still authenticate a
50           passphrase against this setting, but if authentication succeeds,
51           the passphrase should be re-hashed using the currently preferred
52           method.
53

FEATURE TEST MACROS

55     <crypt.h> will define the macro CRYPT_CHECKSALT_AVAILABLE if
56     crypt_checksalt is available in the current version of libxcrypt.
57

BUGS

59     Since full configurability is not yet implemented, the current implemen‐
60     tation will only ever return CRYPT_SALT_OK (0) or CRYPT_SALT_INVALID when
61     invoked.
62

PORTABILITY NOTES

64     The function crypt_checksalt is not part of any standard.  It was added
65     to libxcrypt in version 4.3.0.
66

ATTRIBUTES

68     For an explanation of the terms used in this section, see attributes(7).
69     ┌────────────────┬───────────────┬─────────┐
70     │Interface       │ Attribute     │ Value   │
71     ├────────────────┼───────────────┼─────────┤
72     │crypt_checksalt │ Thread safety │ MT-Safe │
73     └────────────────┴───────────────┴─────────┘
74