|
jpayne@68
|
1 .\" Written by Zack Weinberg <zackw at panix.com> in 2018.
|
|
jpayne@68
|
2 .\"
|
|
jpayne@68
|
3 .\" To the extent possible under law, the authors have waived
|
|
jpayne@68
|
4 .\" all copyright and related or neighboring rights to this work.
|
|
jpayne@68
|
5 .\" See https://creativecommons.org/publicdomain/zero/1.0/ for further
|
|
jpayne@68
|
6 .\" details.
|
|
jpayne@68
|
7 .\"
|
|
jpayne@68
|
8 .Dd November 8, 2018
|
|
jpayne@68
|
9 .Dt CRYPT_CHECKSALT 3
|
|
jpayne@68
|
10 .Os "libxcrypt"
|
|
jpayne@68
|
11 .Sh NAME
|
|
jpayne@68
|
12 .Nm crypt_checksalt
|
|
jpayne@68
|
13 .Nd validate a crypt setting string
|
|
jpayne@68
|
14 .Sh LIBRARY
|
|
jpayne@68
|
15 .Lb libcrypt
|
|
jpayne@68
|
16 .Sh SYNOPSIS
|
|
jpayne@68
|
17 .In crypt.h
|
|
jpayne@68
|
18 .Ft int
|
|
jpayne@68
|
19 .Fo crypt_checksalt
|
|
jpayne@68
|
20 .Fa "const char *setting"
|
|
jpayne@68
|
21 .Fc
|
|
jpayne@68
|
22 .Sh DESCRIPTION
|
|
jpayne@68
|
23 .Nm
|
|
jpayne@68
|
24 checks the
|
|
jpayne@68
|
25 .Ar setting
|
|
jpayne@68
|
26 string against the system configuration
|
|
jpayne@68
|
27 and reports whether the hashing method and parameters it specifies
|
|
jpayne@68
|
28 are acceptable.
|
|
jpayne@68
|
29 It is intended to be used by programs
|
|
jpayne@68
|
30 such as
|
|
jpayne@68
|
31 .Xr login 1
|
|
jpayne@68
|
32 to determine whether the user's passphrase should be re-hashed
|
|
jpayne@68
|
33 using the currently preferred hashing method.
|
|
jpayne@68
|
34 .Sh RETURN VALUES
|
|
jpayne@68
|
35 The return value is 0 if there is nothing wrong with this setting.
|
|
jpayne@68
|
36 Otherwise, it is one of the following constants:
|
|
jpayne@68
|
37 .Bl -tag -width 4n
|
|
jpayne@68
|
38 .It Dv CRYPT_SALT_OK
|
|
jpayne@68
|
39 .Ar setting
|
|
jpayne@68
|
40 is a fully correct setting string.
|
|
jpayne@68
|
41 This constant is guaranteed to equal 0.
|
|
jpayne@68
|
42 .It Dv CRYPT_SALT_INVALID
|
|
jpayne@68
|
43 .Ar setting
|
|
jpayne@68
|
44 is not a valid setting string; either it specifies a hashing method
|
|
jpayne@68
|
45 that is not known to this version of libxcrypt,
|
|
jpayne@68
|
46 or it specifies invalid parameters for the method.
|
|
jpayne@68
|
47 .It Dv CRYPT_SALT_METHOD_DISABLED (Not implemented, yet)
|
|
jpayne@68
|
48 .Ar setting
|
|
jpayne@68
|
49 specifies a hashing method that is no longer allowed to be used at all;
|
|
jpayne@68
|
50 .Nm crypt
|
|
jpayne@68
|
51 will fail if passed this
|
|
jpayne@68
|
52 .Ar setting .
|
|
jpayne@68
|
53 Manual intervention will be required to reactivate the user's account.
|
|
jpayne@68
|
54 .It Dv CRYPT_SALT_METHOD_LEGACY
|
|
jpayne@68
|
55 .Ar setting
|
|
jpayne@68
|
56 specifies a hashing method that is no longer considered strong enough
|
|
jpayne@68
|
57 for use with new passphrases.
|
|
jpayne@68
|
58 .Nm crypt
|
|
jpayne@68
|
59 will still authenticate a passphrase against this setting,
|
|
jpayne@68
|
60 but if authentication succeeds,
|
|
jpayne@68
|
61 the passphrase should be re-hashed using the currently preferred method.
|
|
jpayne@68
|
62 .It Dv CRYPT_SALT_TOO_CHEAP (Not implemented, yet)
|
|
jpayne@68
|
63 .Ar setting
|
|
jpayne@68
|
64 specifies cost parameters that are considered too cheap for use with
|
|
jpayne@68
|
65 new passphrases.
|
|
jpayne@68
|
66 .Nm crypt
|
|
jpayne@68
|
67 will still authenticate a passphrase against this setting,
|
|
jpayne@68
|
68 but if authentication succeeds,
|
|
jpayne@68
|
69 the passphrase should be re-hashed using the currently preferred method.
|
|
jpayne@68
|
70 .El
|
|
jpayne@68
|
71 .Sh FEATURE TEST MACROS
|
|
jpayne@68
|
72 .In crypt.h
|
|
jpayne@68
|
73 will define the macro
|
|
jpayne@68
|
74 .Dv CRYPT_CHECKSALT_AVAILABLE
|
|
jpayne@68
|
75 if
|
|
jpayne@68
|
76 .Nm
|
|
jpayne@68
|
77 is available in the current version of libxcrypt.
|
|
jpayne@68
|
78 .Sh BUGS
|
|
jpayne@68
|
79 Since full configurability is not yet implemented, the current
|
|
jpayne@68
|
80 implementation will only ever return
|
|
jpayne@68
|
81 .Nm CRYPT_SALT_OK (0)
|
|
jpayne@68
|
82 or
|
|
jpayne@68
|
83 .Nm CRYPT_SALT_INVALID
|
|
jpayne@68
|
84 when invoked.
|
|
jpayne@68
|
85 .Sh PORTABILITY NOTES
|
|
jpayne@68
|
86 The function
|
|
jpayne@68
|
87 .Nm
|
|
jpayne@68
|
88 is not part of any standard.
|
|
jpayne@68
|
89 It was added to libxcrypt in version 4.3.0.
|
|
jpayne@68
|
90 .Sh ATTRIBUTES
|
|
jpayne@68
|
91 For an explanation of the terms used in this section, see
|
|
jpayne@68
|
92 .Xr attributes 7 .
|
|
jpayne@68
|
93 .TS
|
|
jpayne@68
|
94 allbox;
|
|
jpayne@68
|
95 lb lb lb
|
|
jpayne@68
|
96 l l l.
|
|
jpayne@68
|
97 Interface Attribute Value
|
|
jpayne@68
|
98 T{
|
|
jpayne@68
|
99 .Nm
|
|
jpayne@68
|
100 T} Thread safety MT-Safe
|
|
jpayne@68
|
101 .TE
|
|
jpayne@68
|
102 .sp
|
|
jpayne@68
|
103 .Sh SEE ALSO
|
|
jpayne@68
|
104 .Xr crypt 3 ,
|
|
jpayne@68
|
105 .Xr crypt_gensalt 3 ,
|
|
jpayne@68
|
106 .Xr crypt 5
|
