jpayne@68: .\" Written and revised by Solar Designer <solar at openwall.com> in 2000-2011.
jpayne@68: .\" Revised by Zack Weinberg <zackw at panix.com> in 2017.
jpayne@68: .\" Converted to mdoc format by Zack Weinberg in 2018.
jpayne@68: .\"
jpayne@68: .\" No copyright is claimed, and this man page is hereby placed in the public
jpayne@68: .\" domain.  In case this attempt to disclaim copyright and place the man page
jpayne@68: .\" in the public domain is deemed null and void, then the man page is
jpayne@68: .\" Copyright 2000-2011 Solar Designer, 2017 Zack Weinberg, and it is
jpayne@68: .\" hereby released to the general public under the following terms:
jpayne@68: .\"
jpayne@68: .\" Redistribution and use in source and binary forms, with or without
jpayne@68: .\" modification, are permitted.
jpayne@68: .\"
jpayne@68: .\" There's ABSOLUTELY NO WARRANTY, express or implied.
jpayne@68: .\"
jpayne@68: .Dd October 11, 2017
jpayne@68: .Dt CRYPT_GENSALT 3
jpayne@68: .Os "Openwall Project"
jpayne@68: .Sh NAME
jpayne@68: .Nm crypt_gensalt , crypt_gensalt_rn , crypt_gensalt_ra
jpayne@68: .Nd encode settings for passphrase hashing
jpayne@68: .Sh LIBRARY
jpayne@68: .Lb libcrypt
jpayne@68: .Sh SYNOPSIS
jpayne@68: .In crypt.h
jpayne@68: .Ft "char *"
jpayne@68: .Fo crypt_gensalt
jpayne@68: .Fa "const char *prefix"
jpayne@68: .Fa "unsigned long count"
jpayne@68: .Fa "const char *rbytes"
jpayne@68: .Fa "int nrbytes"
jpayne@68: .Fc
jpayne@68: .Ft "char *"
jpayne@68: .Fo crypt_gensalt_rn
jpayne@68: .Fa "const char * prefix"
jpayne@68: .Fa "unsigned long count"
jpayne@68: .Fa "const char *rbytes"
jpayne@68: .Fa "int nrbytes"
jpayne@68: .Fa "char * output"
jpayne@68: .Fa "int output_size"
jpayne@68: .Fc
jpayne@68: .Ft "char *"
jpayne@68: .Fo crypt_gensalt_ra
jpayne@68: .Fa "const char *prefix"
jpayne@68: .Fa "unsigned long count"
jpayne@68: .Fa "const char *rbytes"
jpayne@68: .Fa "int nrbytes"
jpayne@68: .Fc
jpayne@68: .Sh DESCRIPTION
jpayne@68: The
jpayne@68: .Nm crypt_gensalt ,
jpayne@68: .Nm crypt_gensalt_rn ,
jpayne@68: and
jpayne@68: .Nm crypt_gensalt_ra
jpayne@68: functions compile a string for use as the
jpayne@68: .Fa setting
jpayne@68: argument to
jpayne@68: .Nm crypt ,
jpayne@68: .Nm crypt_r ,
jpayne@68: .Nm crypt_rn ,
jpayne@68: and
jpayne@68: .Nm crypt_ra .
jpayne@68: .Fa prefix
jpayne@68: selects the hashing method to use.
jpayne@68: .Fa count
jpayne@68: controls the CPU time cost of the hash;
jpayne@68: the valid range for
jpayne@68: .Fa count
jpayne@68: and the exact meaning of
jpayne@68: .Dq CPU time cost
jpayne@68: depends on the hashing method,
jpayne@68: but larger numbers correspond to more costly hashes.
jpayne@68: .Fa rbytes
jpayne@68: should point to
jpayne@68: .Fa nrbytes
jpayne@68: cryptographically random bytes for use as
jpayne@68: .Dq salt.
jpayne@68: .Pp
jpayne@68: If
jpayne@68: .Fa prefix
jpayne@68: is a null pointer, the best available hashing method will be selected.
jpayne@68: .Po Sy CAUTION :
jpayne@68: if
jpayne@68: .Fa prefix
jpayne@68: is an empty string,
jpayne@68: the
jpayne@68: .Dq traditional
jpayne@68: DES-based hashing method will be selected;
jpayne@68: this method is unacceptably weak by modern standards.
jpayne@68: .Pc
jpayne@68: If
jpayne@68: .Fa count
jpayne@68: is 0, a low default cost will be selected.
jpayne@68: If
jpayne@68: .Fa rbytes
jpayne@68: is a null pointer, an appropriate number of random bytes will be
jpayne@68: obtained from the operating system, and
jpayne@68: .Fa nrbytes
jpayne@68: is ignored.
jpayne@68: .Pp
jpayne@68: See
jpayne@68: .Xr crypt 5
jpayne@68: for other strings that can be used as
jpayne@68: .Fa prefix ,
jpayne@68: and valid values of
jpayne@68: .Fa count
jpayne@68: for each.
jpayne@68: .Sh RETURN VALUES
jpayne@68: .Nm crypt_gensalt ,
jpayne@68: .Nm crypt_gensalt_rn ,
jpayne@68: and
jpayne@68: .Nm crypt_gensalt_ra
jpayne@68: return a pointer to an encoded setting string.
jpayne@68: This string will be entirely printable ASCII,
jpayne@68: and will not contain whitespace or the characters
jpayne@68: .Sq Li \&: ,
jpayne@68: .Sq Li \&; ,
jpayne@68: .Sq Li \&* ,
jpayne@68: .Sq Li \&! ,
jpayne@68: or
jpayne@68: .Sq Li \&\e .
jpayne@68: See
jpayne@68: .Xr crypt 5
jpayne@68: for more detail on the format of this string.
jpayne@68: Upon error, they return a null pointer and set
jpayne@68: .Va errno
jpayne@68: to an appropriate error code.
jpayne@68: .Pp
jpayne@68: .Nm crypt_gensalt
jpayne@68: places its result in a static storage area,
jpayne@68: which will be overwritten by subsequent calls to
jpayne@68: .Nm crypt_gensalt .
jpayne@68: It is not safe to call
jpayne@68: .Nm crypt_gensalt
jpayne@68: from multiple threads simultaneously.
jpayne@68: However, it
jpayne@68: .Em is
jpayne@68: safe to pass the string returned by
jpayne@68: .Nm crypt_gensalt
jpayne@68: directly to
jpayne@68: .Nm crypt
jpayne@68: without copying it;
jpayne@68: each function has its own static storage area.
jpayne@68: .Pp
jpayne@68: .Nm crypt_gensalt_rn
jpayne@68: places its result in the supplied
jpayne@68: .Fa output
jpayne@68: buffer, which has
jpayne@68: .Fa output_size
jpayne@68: bytes of storage available.
jpayne@68: .Fa output_size
jpayne@68: should be greater than or equal to
jpayne@68: .Dv CRYPT_GENSALT_OUTPUT_SIZE .
jpayne@68: .Pp
jpayne@68: .Nm crypt_gensalt_ra
jpayne@68: allocates memory for its result using
jpayne@68: .Xr malloc 3 .
jpayne@68: It should be freed with
jpayne@68: .Xr free 3
jpayne@68: after use.
jpayne@68: .Pp
jpayne@68: Upon error, in addition to returning a null pointer,
jpayne@68: .Nm crypt_gensalt
jpayne@68: and
jpayne@68: .Nm crypt_gensalt_rn
jpayne@68: will write an invalid setting string
jpayne@68: to their output buffer, if there is enough space;
jpayne@68: this string will begin with a
jpayne@68: .Sq Li \&*
jpayne@68: and will not be equal to
jpayne@68: .Fa prefix .
jpayne@68: .Sh ERRORS
jpayne@68: .Bl -tag -width Er
jpayne@68: .It Er EINVAL
jpayne@68: .Fa prefix
jpayne@68: is invalid or not supported by this implementation;
jpayne@68: .Fa count
jpayne@68: is invalid for the requested
jpayne@68: .Fa prefix ;
jpayne@68: the input
jpayne@68: .Fa nrbytes
jpayne@68: is insufficient for the smallest valid salt with the requested
jpayne@68: .Fa prefix .
jpayne@68: .It Er ERANGE
jpayne@68: .Nm crypt_gensalt_rn
jpayne@68: only:
jpayne@68: .Fa output_size
jpayne@68: is too small to hold the compiled
jpayne@68: .Fa setting
jpayne@68: string.
jpayne@68: .It Er ENOMEM
jpayne@68: Failed to allocate internal scratch memory.
jpayne@68: .br
jpayne@68: .Nm crypt_gensalt_ra
jpayne@68: only:
jpayne@68: failed to allocate memory for the compiled
jpayne@68: .Fa setting
jpayne@68: string.
jpayne@68: .It Er ENOSYS , EACCES , EIO , No etc.\&
jpayne@68: Obtaining random bytes from the operating system failed.
jpayne@68: This can only happen when
jpayne@68: .Fa rbytes
jpayne@68: is a null pointer.
jpayne@68: .El
jpayne@68: .Sh FEATURE TEST MACROS
jpayne@68: The following macros are defined by
jpayne@68: .In crypt.h :
jpayne@68: .Bl -tag -width 6n
jpayne@68: .It Dv CRYPT_GENSALT_IMPLEMENTS_DEFAULT_PREFIX
jpayne@68: A null pointer can be specified as the
jpayne@68: .Fa prefix
jpayne@68: argument.
jpayne@68: .It Dv CRYPT_GENSALT_IMPLEMENTS_AUTO_ENTROPY
jpayne@68: A null pointer can be specified as the
jpayne@68: .Fa rbytes
jpayne@68: argument.
jpayne@68: .El
jpayne@68: .Sh PORTABILITY NOTES
jpayne@68: The functions
jpayne@68: .Nm crypt_gensalt ,
jpayne@68: .Nm crypt_gensalt_rn ,
jpayne@68: and
jpayne@68: .Nm crypt_gensalt_ra
jpayne@68: are not part of any standard.
jpayne@68: They originate with the Openwall project.
jpayne@68: A function with the name
jpayne@68: .Nm crypt_gensalt
jpayne@68: also exists on Solaris 10 and newer, but its prototype and semantics differ.
jpayne@68: .Pp
jpayne@68: The default prefix and auto entropy features are available since libxcrypt
jpayne@68: version 4.0.0.  Portable software can use feature test macros to find out
jpayne@68: whether null pointers can be used for the
jpayne@68: .Fa prefix
jpayne@68: and
jpayne@68: .Fa rbytes
jpayne@68: arguments.
jpayne@68: .Pp
jpayne@68: The set of supported hashing methods varies considerably from system
jpayne@68: to system.
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 crypt_gensalt
jpayne@68: T}	Thread safety	MT-Unsafe race:crypt_gensalt
jpayne@68: T{
jpayne@68: .Nm crypt_gensalt_rn ,
jpayne@68: .Nm crypt_gensalt_ra
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 getpass 3 ,
jpayne@68: .Xr getpwent 3 ,
jpayne@68: .Xr shadow 3 ,
jpayne@68: .Xr login 1 ,
jpayne@68: .Xr passwd 1 ,
jpayne@68: .Xr crypt 5 ,
jpayne@68: .Xr passwd 5 ,
jpayne@68: .Xr shadow 5 ,
jpayne@68: .Xr pam 8