add Xpass extension (#4320)

* add Xpass extension

* add .gitleaks for security scanner

* improve Xpass constants' description

* xpass: improve ex using hash_equals

.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''',
+  ]

appendices/extensions.xml

@@ -181,6 +181,7 @@
    <listitem><simpara><xref linkend="book.xmlreader"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.xmlrpc"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.xmlwriter"/></simpara></listitem>
+   <listitem><simpara><xref linkend="book.xpass"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.xsl"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.yac"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.yaconf"/></simpara></listitem>
@@ -396,6 +397,7 @@
     <listitem><para><xref linkend="book.xlswriter"/></para></listitem>
     <listitem><para><xref linkend="book.xmldiff"/></para></listitem>
     <listitem><para><xref linkend="book.xmlrpc"/></para></listitem>
+    <listitem><para><xref linkend="book.xpass"/></para></listitem>
     <listitem><para><xref linkend="book.yac"/></para></listitem>
     <listitem><para><xref linkend="book.yaconf"/></para></listitem>
     <listitem><para><xref linkend="book.yaf"/></para></listitem>

reference/xpass/book.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<book xml:id="book.xpass" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <?phpdoc extension-membership="pecl" ?>
+ <title>Xpass</title>
+ <titleabbrev>Xpass</titleabbrev>
+
+ <preface xml:id="intro.xpass">
+  &reftitle.intro;
+  <para>
+   This extension provides password hashing algorithms used by Linux
+   distributions, using extended crypt library.
+  </para>
+  <para>
+   It also provides additional functions from libxcrypt missing in core PHP.
+  </para>
+ </preface>
+
+ &reference.xpass.setup;
+ &reference.xpass.constants;
+ &reference.xpass.reference;
+
+</book>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

reference/xpass/constants.xml

@@ -0,0 +1,256 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<appendix xml:id="xpass.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ &reftitle.constants;
+ &extension.constants;
+
+  <para>
+   Xpass extension provides various set of constants.
+   Hash methods (CRYPT_PREFIX_) for <function>crypt_gensalt</function> prefix parameter.
+   Error codes (CRYPT_SALT_) returned by <function>crypt_checksalt</function>.
+   Password algorithms (PASSWORD_) for <function>password_hash</function> algo parameter.
+  </para>
+
+ <variablelist xml:id="xpass.constants.algo">
+  <title>Hashing methods</title>
+   <varlistentry xml:id="constant.crypt-prefix-std-des">
+    <term>
+     <constant>CRYPT_PREFIX_STD_DES</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <simpara>
+       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.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-prefix-ext-des">
+    <term>
+     <constant>CRYPT_PREFIX_EXT_DES</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <simpara>
+      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.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-prefix-md5">
+    <term>
+     <constant>CRYPT_PREFIX_MD5</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <simpara>
+      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.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-prefix-blowfish">
+    <term>
+     <constant>CRYPT_PREFIX_BLOWFISH</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <simpara>
+      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.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-prefix-sha256">
+    <term>
+     <constant>CRYPT_PREFIX_SHA256</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <simpara>
+      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.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-prefix-sha512">
+    <term>
+     <constant>CRYPT_PREFIX_SHA512</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <simpara>
+      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.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-prefix-scrypt">
+    <term>
+     <constant>CRYPT_PREFIX_SCRYPT</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <simpara>
+       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.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-prefix-gost-yescrypt">
+    <term>
+     <constant>CRYPT_PREFIX_GOST_YESCRYPT</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <simpara>
+      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.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-prefix-yescrypt">
+    <term>
+     <constant>CRYPT_PREFIX_YESCRYPT</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <simpara>
+      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.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+ <variablelist xml:id="xpass.constants.error">
+  <title>Error codes</title>
+   <varlistentry xml:id="constant.crypt-salt-ok">
+    <term>
+     <constant>CRYPT_SALT_OK</constant>
+     (<type>int</type>)
+    </term>
+    <listitem>
+     <simpara>
+     No error.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-salt-invalid">
+    <term>
+     <constant>CRYPT_SALT_INVALID</constant>
+     (<type>int</type>)
+    </term>
+    <listitem>
+     <simpara>
+     Unkown hashing method or invalid parameters.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-salt-method-disabled">
+    <term>
+     <constant>CRYPT_SALT_METHOD_DISABLED</constant>
+     (<type>int</type>)
+    </term>
+    <listitem>
+     <simpara>
+     Hashing method is no longer allowed to be used.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-salt-method-legacy">
+    <term>
+     <constant>CRYPT_SALT_METHOD_LEGACY</constant>
+     (<type>int</type>)
+    </term>
+    <listitem>
+     <simpara>
+     Hashing method is no longer considered strong enough.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.crypt-salt-too-cheap">
+    <term>
+     <constant>CRYPT_SALT_TOO_CHEAP</constant>
+     (<type>int</type>)
+    </term>
+    <listitem>
+     <simpara>
+     Cost parameters are considered too cheap.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+ <variablelist xml:id="xpass.constants.password">
+  <title>Password algorithms</title>
+   <varlistentry xml:id="constant.password-sha512">
+    <term>
+     <constant>PASSWORD_SHA512</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <para>
+      <constant>PASSWORD_SHA512</constant> is used to create new password
+      hashes using the <constant>CRYPT_SHA512</constant> algorithm.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.password-yescrypt">
+    <term>
+     <constant>PASSWORD_YESCRYPT</constant>
+     (<type>string</type>)
+    </term>
+    <listitem>
+     <para>
+      <constant>PASSWORD_YESCRYPT</constant> is used to create new password
+      hashes using the <constant>CRYPT_YESCRYPT</constant> algorithm.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+</appendix>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->