From 151476a00a5c8d74d56e0ecd15fb7c9bc718602e Mon Sep 17 00:00:00 2001 From: Remi Collet Date: Mon, 16 Dec 2024 11:52:56 +0100 Subject: [PATCH] add Xpass extension --- appendices/extensions.xml | 2 + reference/xpass/book.xml | 45 ++++ reference/xpass/constants.xml | 218 ++++++++++++++++++ reference/xpass/functions/crypt-checksalt.xml | 109 +++++++++ reference/xpass/functions/crypt-gensalt.xml | 117 ++++++++++ .../functions/crypt-preferred-method.xml | 85 +++++++ reference/xpass/reference.xml | 30 +++ reference/xpass/setup.xml | 45 ++++ reference/xpass/versions.xml | 33 +++ 9 files changed, 684 insertions(+) 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/appendices/extensions.xml b/appendices/extensions.xml index a054b00ca3f1..3434c95e8c14 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 000000000000..f44bc96adee8 --- /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 000000000000..15187ea7f738 --- /dev/null +++ b/reference/xpass/constants.xml @@ -0,0 +1,218 @@ + + + + + &reftitle.constants; + &extension.constants; + + + Hashing methods + + + CRYPT_PREFIX_STD_DES + (string) + + + + Prefix for standard DES algorithm. + + + + + + CRYPT_PREFIX_EXT_DES + (string) + + + + Prefix for extended DES algorithm. + + + + + + CRYPT_PREFIX_MD5 + (string) + + + + Prefix for MD5 algorithm. + + + + + + CRYPT_PREFIX_BLOWFISH + (string) + + + + Prefix for Blowfish algorithm. + + + + + + CRYPT_PREFIX_SHA256 + (string) + + + + Prefix for SHA-256 algorithm. + + + + + + CRYPT_PREFIX_SHA512 + (string) + + + + Prefix for SHA-512 algorithm. + + + + + + CRYPT_PREFIX_SCRYPT + (string) + + + + Prefix for scrypt algorithm. + + + + + + CRYPT_PREFIX_GOST_YESCRYPT + (string) + + + + Prefix for GOST yescrypt algorithm. + + + + + + CRYPT_PREFIX_YESCRYPT + (string) + + + + Prefix for yescrypt algorithm. + + + + + + + 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 hashing methods + + + 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 000000000000..4817823f2f75 --- /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 000000000000..728cddbb3dda --- /dev/null +++ b/reference/xpass/functions/crypt-gensalt.xml @@ -0,0 +1,117 @@ + + + + + + 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 + + + + + + + diff --git a/reference/xpass/functions/crypt-preferred-method.xml b/reference/xpass/functions/crypt-preferred-method.xml new file mode 100644 index 000000000000..6ef5e13b2f0c --- /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 000000000000..1782b820cab7 --- /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 000000000000..783fcf6d0c42 --- /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 000000000000..9cffbcca91ea --- /dev/null +++ b/reference/xpass/versions.xml @@ -0,0 +1,33 @@ + + + + + + + + + + + +