From 8958b668b2bda69d2438d13d960444d0cfb111f0 Mon Sep 17 00:00:00 2001 From: Remi Collet Date: Wed, 18 Dec 2024 15:48:35 +0100 Subject: [PATCH] add Xpass extension (#4320) * add Xpass extension * add .gitleaks for security scanner * improve Xpass constants' description * xpass: improve ex using hash_equals --- .gitleaks.toml | 8 + appendices/extensions.xml | 2 + reference/xpass/book.xml | 45 +++ reference/xpass/constants.xml | 256 ++++++++++++++++++ reference/xpass/functions/crypt-checksalt.xml | 109 ++++++++ reference/xpass/functions/crypt-gensalt.xml | 118 ++++++++ .../functions/crypt-preferred-method.xml | 85 ++++++ reference/xpass/reference.xml | 30 ++ reference/xpass/setup.xml | 45 +++ reference/xpass/versions.xml | 33 +++ 10 files changed, 731 insertions(+) create mode 100644 .gitleaks.toml create mode 100644 reference/xpass/book.xml create mode 100644 reference/xpass/constants.xml create mode 100644 reference/xpass/functions/crypt-checksalt.xml create mode 100644 reference/xpass/functions/crypt-gensalt.xml create mode 100644 reference/xpass/functions/crypt-preferred-method.xml create mode 100644 reference/xpass/reference.xml create mode 100644 reference/xpass/setup.xml create mode 100644 reference/xpass/versions.xml diff --git a/.gitleaks.toml b/.gitleaks.toml new file mode 100644 index 0000000000..377562fc6b --- /dev/null +++ b/.gitleaks.toml @@ -0,0 +1,8 @@ +[allowlist] + description = "Global Allowlist" + + # Ignore based on any subset of the file path + paths = [ + # Ignore Xpass function with examples + '''reference\/xpass\/functions\/.*\.xml''', + ] diff --git a/appendices/extensions.xml b/appendices/extensions.xml index a054b00ca3..3434c95e8c 100644 --- a/appendices/extensions.xml +++ b/appendices/extensions.xml @@ -181,6 +181,7 @@ + @@ -396,6 +397,7 @@ + diff --git a/reference/xpass/book.xml b/reference/xpass/book.xml new file mode 100644 index 0000000000..f44bc96ade --- /dev/null +++ b/reference/xpass/book.xml @@ -0,0 +1,45 @@ + + + + + + Xpass + Xpass + + + &reftitle.intro; + + This extension provides password hashing algorithms used by Linux + distributions, using extended crypt library. + + + It also provides additional functions from libxcrypt missing in core PHP. + + + + &reference.xpass.setup; + &reference.xpass.constants; + &reference.xpass.reference; + + + + diff --git a/reference/xpass/constants.xml b/reference/xpass/constants.xml new file mode 100644 index 0000000000..b47c11a48c --- /dev/null +++ b/reference/xpass/constants.xml @@ -0,0 +1,256 @@ + + + + + &reftitle.constants; + &extension.constants; + + + Xpass extension provides various set of constants. + Hash methods (CRYPT_PREFIX_) for crypt_gensalt prefix parameter. + Error codes (CRYPT_SALT_) returned by crypt_checksalt. + Password algorithms (PASSWORD_) for password_hash algo parameter. + + + + Hashing methods + + + CRYPT_PREFIX_STD_DES + (string) + + + + The original hashing method from Unix V7, based on the DES block cipher. + Because DES is cheap on modern hardware, because there are only 4096 possible + salts and 2**56 distinct passphrases, which it truncates to 8 characters, + it is feasible to discover any passphrase hashed with this method. + It should only be used if you absolutely have to generate hashes that will + work on an old operating system that supports nothing else. + + + + + + CRYPT_PREFIX_EXT_DES + (string) + + + + An extension of traditional DES, which eliminates the length limit, increases + the salt size, and makes the time cost tunable. It originates with BSDI BSD/OS + and is also available on at least NetBSD, OpenBSD, and FreeBSD due to the + use of David Burren's FreeSec library. It is much better than traditional DES + and bigcrypt, but still should not be used for new hashes. + + + + + + CRYPT_PREFIX_MD5 + (string) + + + + A hash based on the MD5 algorithm, originally developed by Poul-Henning Kamp for FreeBSD. + Supported on most free Unixes and newer versions of Solaris. Not as weak as the DES-based + hashes below, but MD5 is so cheap on modern hardware that it should not be used for new + hashes. Processing cost is not adjustable. + + + + + + CRYPT_PREFIX_BLOWFISH + (string) + + + + A hash based on the Blowfish block cipher, modified to have an extra-expensive key schedule. + Originally developed by Niels Provos and David Mazieres for OpenBSD and also supported on recent + versions of FreeBSD and NetBSD, on Solaris 10 and newer, and on several GNU/*/Linux distributions. + + + + + + CRYPT_PREFIX_SHA256 + (string) + + + + A hash based on SHA-2 with 256-bit output, originally developed by Ulrich Drepper for GNU libc. + Supported on Linux but not common elsewhere. Acceptable for new hashes. + The default processing cost parameter is 5000, which is too low for modern hardware. + + + + + + CRYPT_PREFIX_SHA512 + (string) + + + + A hash based on SHA-2 with 512-bit output, originally developed by Ulrich Drepper for GNU libc. + Supported on Linux but not common elsewhere. Acceptable for new hashes. + The default processing cost parameter is 5000, which is too low for modern hardware. + + + + + + CRYPT_PREFIX_SCRYPT + (string) + + + + Scrypt is a password-based key derivation function created by Colin Percival, originally + for the Tarsnap online backup service. The algorithm was specifically designed to make it + costly to perform large-scale custom hardware attacks by requiring large amounts of memory. + In 2016, the scrypt algorithm was published by IETF as RFC 7914. + + + + + + CRYPT_PREFIX_GOST_YESCRYPT + (string) + + + + Gost-yescrypt uses the output from yescrypt as an input message to HMAC with the + GOST R 34.11-2012 (Streebog) hash function with a 256-bit digest. + Thus, yescrypt's cryptographic properties are superseded by those of the GOST hash function. + This hashing method is useful in applications that need modern passphrase hashing, but have + to rely on GOST algorithms. The GOST R 34.11-2012 (Streebog) hash function + has been published by the IETF as RFC 6986. Acceptable for new hashes where required. + + + + + + CRYPT_PREFIX_YESCRYPT + (string) + + + + Yescrypt is a scalable passphrase hashing scheme designed by Solar Designer, which is based + on Colin Percival's scrypt. While yescrypt's strength against password guessing attacks comes + from its algorithm design, its cryptographic security is guaranteed by its use of SHA-256 + on the outer layer. The SHA-256 hash function has been published by NIST in FIPS PUB 180-2 + (and its subsequent revisions such as FIPS PUB 180-4) and by the IETF as RFC 4634 + (and subsequently RFC 6234). Recommended for new hashes. + + + + + + + Error codes + + + CRYPT_SALT_OK + (int) + + + + No error. + + + + + + CRYPT_SALT_INVALID + (int) + + + + Unkown hashing method or invalid parameters. + + + + + + CRYPT_SALT_METHOD_DISABLED + (int) + + + + Hashing method is no longer allowed to be used. + + + + + + CRYPT_SALT_METHOD_LEGACY + (int) + + + + Hashing method is no longer considered strong enough. + + + + + + CRYPT_SALT_TOO_CHEAP + (int) + + + + Cost parameters are considered too cheap. + + + + + + + Password algorithms + + + PASSWORD_SHA512 + (string) + + + + PASSWORD_SHA512 is used to create new password + hashes using the CRYPT_SHA512 algorithm. + + + + + + PASSWORD_YESCRYPT + (string) + + + + PASSWORD_YESCRYPT is used to create new password + hashes using the CRYPT_YESCRYPT algorithm. + + + + + + + diff --git a/reference/xpass/functions/crypt-checksalt.xml b/reference/xpass/functions/crypt-checksalt.xml new file mode 100644 index 0000000000..4817823f2f --- /dev/null +++ b/reference/xpass/functions/crypt-checksalt.xml @@ -0,0 +1,109 @@ + + + + + + crypt_checksalt + Validate a crypt setting string + + + + &reftitle.description; + + stringnullcrypt_preferred_method + stringsalt + + + Checks the salt string against the system configuration and reports whether + the hashing method and parameters it specifies are acceptable. + It is intended to be used to determine whether the user's passphrase should + be re-hashed using the currently preferred hashing method. + + + + + &reftitle.parameters; + + + salt + + + Salt string to check. + + + + + + + + &reftitle.returnvalues; + + Returns an int, one of CRYPT_SALT_* constant, + see the Xpass constants page. + + + + + &reftitle.examples; + + + A <function>crypt_checksalt</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + crypt_gensalt + + + + + + + diff --git a/reference/xpass/functions/crypt-gensalt.xml b/reference/xpass/functions/crypt-gensalt.xml new file mode 100644 index 0000000000..e783c3318a --- /dev/null +++ b/reference/xpass/functions/crypt-gensalt.xml @@ -0,0 +1,118 @@ + + + + + + crypt_gensalt + Compile a string for use as the salt argument to crypt + + + + &reftitle.description; + + stringnullcrypt_preferred_method + stringprefix&null; + intcount0 + + + Compile a string for use as the salt argument to crypt. + + + + + &reftitle.parameters; + + + prefix + + + Hashing method. + One of CRYPT_PREFIX_* constant, see the Xpass constants page. + If &null;, the best available hashing method will be selected. + + + + + count + + + Controls the processing cost of the hash; the valid range and exact meaning of count + depend on the hashing method, but larger numbers correspond to more costly hashes in + terms of CPU time and possibly memory usage. + If count is 0, a low default cost will be selected. + + + + + + + + &reftitle.returnvalues; + + Returns a string with the setting, or &null; if error. + + + + + &reftitle.examples; + + + A <function>crypt_gensalt</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + crypt_preferred_method + crypt + hash_equals + + + + + + + diff --git a/reference/xpass/functions/crypt-preferred-method.xml b/reference/xpass/functions/crypt-preferred-method.xml new file mode 100644 index 0000000000..6ef5e13b2f --- /dev/null +++ b/reference/xpass/functions/crypt-preferred-method.xml @@ -0,0 +1,85 @@ + + + + + + crypt_preferred_method + Get the prefix of the preferred hash method + + + + &reftitle.description; + + stringnullcrypt_preferred_method + + + + Get the prefix of the preferred hash method. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns a string with the prefix, or &null; if error. + + + + + &reftitle.examples; + + + A <function>crypt_preferred_method</function> example + + +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + crypt_gensalt + + + + + + + diff --git a/reference/xpass/reference.xml b/reference/xpass/reference.xml new file mode 100644 index 0000000000..1782b820ca --- /dev/null +++ b/reference/xpass/reference.xml @@ -0,0 +1,30 @@ + + + + + Xpass &Functions; + + &reference.xpass.entities.functions; + + + + diff --git a/reference/xpass/setup.xml b/reference/xpass/setup.xml new file mode 100644 index 0000000000..783fcf6d0c --- /dev/null +++ b/reference/xpass/setup.xml @@ -0,0 +1,45 @@ + + + + + &reftitle.setup; + +
+ &reftitle.required; + + This extension requires + libxcrypt + version 4.4 or higher. + +
+ +
+ Installation via PECL + + &pecl.info; + &url.pecl.package;xpass. + +
+ + + + diff --git a/reference/xpass/versions.xml b/reference/xpass/versions.xml new file mode 100644 index 0000000000..9cffbcca91 --- /dev/null +++ b/reference/xpass/versions.xml @@ -0,0 +1,33 @@ + + + + + + + + + + + +