1
0
mirror of https://github.com/php/doc-en.git synced 2026-03-23 23:32:18 +01:00

add Xpass extension (#4320)

* add Xpass extension

* add .gitleaks for security scanner

* improve Xpass constants' description

* xpass: improve ex using hash_equals
This commit is contained in:
Remi Collet
2024-12-18 15:48:35 +01:00
committed by GitHub
parent ef5a00895d
commit 8958b668b2
10 changed files with 731 additions and 0 deletions

8
.gitleaks.toml Normal file
View File

@@ -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''',
]

View File

@@ -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>

45
reference/xpass/book.xml Normal file
View File

@@ -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
-->

View File

@@ -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
-->

View File

@@ -0,0 +1,109 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.crypt-checksalt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>crypt_checksalt</refname>
<refpurpose>Validate a crypt setting string</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>string</type><type>null</type></type><methodname>crypt_preferred_method</methodname>
<methodparam><type>string</type><parameter>salt</parameter></methodparam>
</methodsynopsis>
<para>
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.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>salt</parameter></term>
<listitem>
<para>
Salt string to check.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an <type>int</type>, one of CRYPT_SALT_* constant,
see the <link linkend="xpass.constants">Xpass constants</link> page.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>crypt_checksalt</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// Generate a salt for a legacy method
$salt = crypt_gensalt(CRYPT_PREFIX_STD_DES);
// Check the salt
$test = crypt_checksalt($salt);
var_dump($test === CRYPT_SALT_METHOD_LEGACY);
// Generate a salt for default method
$salt = crypt_gensalt();
// Check the salt
$test = crypt_checksalt($salt);
var_dump($test === CRYPT_SALT_OK);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(true)
bool(true)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>crypt_gensalt</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- 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
-->

View File

@@ -0,0 +1,118 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.crypt-gensalt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>crypt_gensalt</refname>
<refpurpose>Compile a string for use as the salt argument to crypt</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>string</type><type>null</type></type><methodname>crypt_preferred_method</methodname>
<methodparam choice="opt"><type>string</type><parameter>prefix</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type>int</type><parameter>count</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<para>
Compile a string for use as the salt argument to <function>crypt</function>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>prefix</parameter></term>
<listitem>
<para>
Hashing method.
One of CRYPT_PREFIX_* constant, see the <link linkend="xpass.constants">Xpass constants</link> page.
If &null;, the best available hashing method will be selected.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>count</parameter></term>
<listitem>
<para>
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 <literal>0</literal>, a low default cost will be selected.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a string with the setting, or &null; if error.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>crypt_gensalt</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// Generate the salt
$salt = crypt_gensalt(CRYPT_PREFIX_BLOWFISH);
// Hash the password
$hash = crypt("secret", $salt);
// Check the hash
$test = hash_equals(crypt("secret", $hash), $hash);
var_dump($salt, $hash, $test);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(29) "$2y$05$GcPykP.Am8C1.dGamdpwW."
string(60) "$2y$05$GcPykP.Am8C1.dGamdpwW.1RR.7uicWvJPZfJfCEizZHqVWwuaJLm"
bool(true)
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>crypt_preferred_method</function></member>
<member><function>crypt</function></member>
<member><function>hash_equals</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- 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
-->

View File

@@ -0,0 +1,85 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.crypt-preferred-method" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>crypt_preferred_method</refname>
<refpurpose>Get the prefix of the preferred hash method</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>string</type><type>null</type></type><methodname>crypt_preferred_method</methodname>
<void/>
</methodsynopsis>
<para>
Get the prefix of the preferred hash method.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a string with the prefix, or &null; if error.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>crypt_preferred_method</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
var_dump(crypt_preferred_method());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
string(3) "$y$"
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>crypt_gensalt</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- 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
-->

View File

@@ -0,0 +1,30 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<reference xml:id="ref.xpass" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Xpass &Functions;</title>
&reference.xpass.entities.functions;
</reference>
<!-- 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
-->

45
reference/xpass/setup.xml Normal file
View File

@@ -0,0 +1,45 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="xpass.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<section xml:id="xpass.requirements">
&reftitle.required;
<para>
This extension requires
<link xlink:href="https://github.com/besser82/libxcrypt">libxcrypt</link>
version 4.4 or higher.
</para>
</section>
<section xml:id="xpass.installation">
<title>Installation via PECL</title>
<para>
&pecl.info;
<link xlink:href="&url.pecl.package;xpass">&url.pecl.package;xpass</link>.
</para>
</section>
</chapter>
<!-- 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
-->

View File

@@ -0,0 +1,33 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!--
Do NOT translate this file
-->
<versions>
<!-- Functions -->
<function name='crypt_gensalt' from='PECL xpass &gt;= 1.1.0'/>
<function name='crypt_preferred_method' from='PECL xpass &gt;= 1.1.0'/>
<function name='crypt_checksalt' from='PECL xpass &gt;= 1.1.0'/>
</versions>
<!-- 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
-->