xcrypt 0.1.0

data/ext/libxcrypt/doc/crypt_gensalt.3

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

data/ext/libxcrypt/doc/crypt_gensalt_ra.3

@@ -0,0 +1 @@
+.so man3/crypt_gensalt.3

data/ext/libxcrypt/doc/crypt_gensalt_rn.3

@@ -0,0 +1 @@
+.so man3/crypt_gensalt.3

data/ext/libxcrypt/doc/crypt_preferred_method.3

@@ -0,0 +1,68 @@
+.\" Written by Björn Esser <besser82 at fedoraproject.org> in 2018.
+.\"
+.\" To the extent possible under law, the authors have waived
+.\" all copyright and related or neighboring rights to this work.
+.\" See https://creativecommons.org/publicdomain/zero/1.0/ for further
+.\" details.
+.\"
+.Dd November 16, 2018
+.Dt CRYPT_PREFERRED_METHOD 3
+.Os libxcrypt
+.Sh NAME
+.Nm crypt_preferred_method
+.Nd get the prefix of the preferred hash method
+.Sh LIBRARY
+.Lb libcrypt
+.Sh SYNOPSIS
+.In crypt.h
+.Ft const char*
+.Fo crypt_preferred_method
+.Fa void
+.Fc
+.Sh DESCRIPTION
+.Nm
+is a convenience function to get the prefix of the preferred hash
+method.  If a preferred method is available,
+it is the same as the one also used by the
+.Nm crypt_gensalt functions ,
+if their given
+.Ar prefix
+parameter is NULL.
+.Sh RETURN VALUES
+The string returned equals the prefix of the preferred hash method.
+If no preferred hash method is available it is NULL.
+It
+.Em is
+safe to pass the string returned by
+.Nm crypt_preferred_method
+directly to
+.Nm crypt_gensalt
+without prior string-sanitizing nor NULL-pointer checks.
+.Sh FEATURE TEST MACROS
+.In crypt.h
+will define the macro
+.Dv CRYPT_PREFERRED_METHOD_AVAILABLE
+if
+.Nm
+is available in the current version of libxcrypt.
+.Sh PORTABILITY NOTES
+The function
+.Nm
+is not part of any standard.
+It was added to libxcrypt in version 4.4.0.
+.Sh ATTRIBUTES
+For an explanation of the terms used in this section,
+see
+.Xr attributes 7 .
+.TS
+allbox;
+lb lb lb
+lw(22n) l l.
+Interface	Attribute	Value
+T{
+.Nm
+T}	Thread safety	MT-Safe
+.TE
+.sp
+.Sh SEE ALSO
+.Xr crypt_gensalt 3

data/ext/libxcrypt/doc/crypt_r.3

@@ -0,0 +1 @@
+.so man3/crypt.3

data/ext/libxcrypt/doc/crypt_ra.3

@@ -0,0 +1 @@
+.so man3/crypt.3

data/ext/libxcrypt/doc/crypt_rn.3

@@ -0,0 +1 @@
+.so man3/crypt.3