jpayne@68: .\" Written by Zack Weinberg <zackw at panix.com> in 2018.
jpayne@68: .\"
jpayne@68: .\" To the extent possible under law, the authors have waived
jpayne@68: .\" all copyright and related or neighboring rights to this work.
jpayne@68: .\" See https://creativecommons.org/publicdomain/zero/1.0/ for further
jpayne@68: .\" details.
jpayne@68: .\"
jpayne@68: .Dd November 8, 2018
jpayne@68: .Dt CRYPT_CHECKSALT 3
jpayne@68: .Os "libxcrypt"
jpayne@68: .Sh NAME
jpayne@68: .Nm crypt_checksalt
jpayne@68: .Nd validate a crypt setting string
jpayne@68: .Sh LIBRARY
jpayne@68: .Lb libcrypt
jpayne@68: .Sh SYNOPSIS
jpayne@68: .In crypt.h
jpayne@68: .Ft int
jpayne@68: .Fo crypt_checksalt
jpayne@68: .Fa "const char *setting"
jpayne@68: .Fc
jpayne@68: .Sh DESCRIPTION
jpayne@68: .Nm
jpayne@68: checks the
jpayne@68: .Ar setting
jpayne@68: string against the system configuration
jpayne@68: and reports whether the hashing method and parameters it specifies
jpayne@68: are acceptable.
jpayne@68: It is intended to be used by programs
jpayne@68: such as
jpayne@68: .Xr login 1
jpayne@68: to determine whether the user's passphrase should be re-hashed
jpayne@68: using the currently preferred hashing method.
jpayne@68: .Sh RETURN VALUES
jpayne@68: The return value is 0 if there is nothing wrong with this setting.
jpayne@68: Otherwise, it is one of the following constants:
jpayne@68: .Bl -tag -width 4n
jpayne@68: .It Dv CRYPT_SALT_OK
jpayne@68: .Ar setting
jpayne@68: is a fully correct setting string.
jpayne@68: This constant is guaranteed to equal 0.
jpayne@68: .It Dv CRYPT_SALT_INVALID
jpayne@68: .Ar setting
jpayne@68: is not a valid setting string; either it specifies a hashing method
jpayne@68: that is not known to this version of libxcrypt,
jpayne@68: or it specifies invalid parameters for the method.
jpayne@68: .It Dv CRYPT_SALT_METHOD_DISABLED (Not implemented, yet)
jpayne@68: .Ar setting
jpayne@68: specifies a hashing method that is no longer allowed to be used at all;
jpayne@68: .Nm crypt
jpayne@68: will fail if passed this
jpayne@68: .Ar setting .
jpayne@68: Manual intervention will be required to reactivate the user's account.
jpayne@68: .It Dv CRYPT_SALT_METHOD_LEGACY
jpayne@68: .Ar setting
jpayne@68: specifies a hashing method that is no longer considered strong enough
jpayne@68: for use with new passphrases.
jpayne@68: .Nm crypt
jpayne@68: will still authenticate a passphrase against this setting,
jpayne@68: but if authentication succeeds,
jpayne@68: the passphrase should be re-hashed using the currently preferred method.
jpayne@68: .It Dv CRYPT_SALT_TOO_CHEAP (Not implemented, yet)
jpayne@68: .Ar setting
jpayne@68: specifies cost parameters that are considered too cheap for use with
jpayne@68: new passphrases.
jpayne@68: .Nm crypt
jpayne@68: will still authenticate a passphrase against this setting,
jpayne@68: but if authentication succeeds,
jpayne@68: the passphrase should be re-hashed using the currently preferred method.
jpayne@68: .El
jpayne@68: .Sh FEATURE TEST MACROS
jpayne@68: .In crypt.h
jpayne@68: will define the macro
jpayne@68: .Dv CRYPT_CHECKSALT_AVAILABLE
jpayne@68: if
jpayne@68: .Nm
jpayne@68: is available in the current version of libxcrypt.
jpayne@68: .Sh BUGS
jpayne@68: Since full configurability is not yet implemented, the current
jpayne@68: implementation will only ever return
jpayne@68: .Nm CRYPT_SALT_OK (0)
jpayne@68: or
jpayne@68: .Nm CRYPT_SALT_INVALID
jpayne@68: when invoked.
jpayne@68: .Sh PORTABILITY NOTES
jpayne@68: The function
jpayne@68: .Nm
jpayne@68: is not part of any standard.
jpayne@68: It was added to libxcrypt in version 4.3.0.
jpayne@68: .Sh ATTRIBUTES
jpayne@68: For an explanation of the terms used in this section, see
jpayne@68: .Xr attributes 7 .
jpayne@68: .TS
jpayne@68: allbox;
jpayne@68: lb lb lb
jpayne@68: l l l.
jpayne@68: Interface	Attribute	Value
jpayne@68: T{
jpayne@68: .Nm
jpayne@68: T}	Thread safety	MT-Safe
jpayne@68: .TE
jpayne@68: .sp
jpayne@68: .Sh SEE ALSO
jpayne@68: .Xr crypt 3 ,
jpayne@68: .Xr crypt_gensalt 3 ,
jpayne@68: .Xr crypt 5