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