Skip to content

Commit 8958b66

Browse files
remicolletremicollet
authored
add Xpass extension (#4320)
* add Xpass extension * add .gitleaks for security scanner * improve Xpass constants' description * xpass: improve ex using hash_equals
1 parent ef5a008 commit 8958b66

File tree

10 files changed

+731
-0
lines changed

10 files changed

+731
-0
lines changed

‎.gitleaks.toml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[allowlist]
2+
description = "Global Allowlist"
3+
4+
# Ignore based on any subset of the file path
5+
paths = [
6+
# Ignore Xpass function with examples
7+
'''reference\/xpass\/functions\/.*\.xml''',
8+
]

‎appendices/extensions.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,7 @@
181181
<listitem><simpara><xref linkend="book.xmlreader"/></simpara></listitem>
182182
<listitem><simpara><xref linkend="book.xmlrpc"/></simpara></listitem>
183183
<listitem><simpara><xref linkend="book.xmlwriter"/></simpara></listitem>
184+
<listitem><simpara><xref linkend="book.xpass"/></simpara></listitem>
184185
<listitem><simpara><xref linkend="book.xsl"/></simpara></listitem>
185186
<listitem><simpara><xref linkend="book.yac"/></simpara></listitem>
186187
<listitem><simpara><xref linkend="book.yaconf"/></simpara></listitem>
@@ -396,6 +397,7 @@
396397
<listitem><para><xref linkend="book.xlswriter"/></para></listitem>
397398
<listitem><para><xref linkend="book.xmldiff"/></para></listitem>
398399
<listitem><para><xref linkend="book.xmlrpc"/></para></listitem>
400+
<listitem><para><xref linkend="book.xpass"/></para></listitem>
399401
<listitem><para><xref linkend="book.yac"/></para></listitem>
400402
<listitem><para><xref linkend="book.yaconf"/></para></listitem>
401403
<listitem><para><xref linkend="book.yaf"/></para></listitem>

‎reference/xpass/book.xml

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<book xml:id="book.xpass" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<?phpdoc extension-membership="pecl" ?>
6+
<title>Xpass</title>
7+
<titleabbrev>Xpass</titleabbrev>
8+
9+
<preface xml:id="intro.xpass">
10+
&reftitle.intro;
11+
<para>
12+
This extension provides password hashing algorithms used by Linux
13+
distributions, using extended crypt library.
14+
</para>
15+
<para>
16+
It also provides additional functions from libxcrypt missing in core PHP.
17+
</para>
18+
</preface>
19+
20+
&reference.xpass.setup;
21+
&reference.xpass.constants;
22+
&reference.xpass.reference;
23+
24+
</book>
25+
26+
<!-- Keep this comment at the end of the file
27+
Local variables:
28+
mode: sgml
29+
sgml-omittag:t
30+
sgml-shorttag:t
31+
sgml-minimize-attributes:nil
32+
sgml-always-quote-attributes:t
33+
sgml-indent-step:1
34+
sgml-indent-data:t
35+
indent-tabs-mode:nil
36+
sgml-parent-document:nil
37+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
38+
sgml-exposed-tags:nil
39+
sgml-local-catalogs:nil
40+
sgml-local-ecat-files:nil
41+
End:
42+
vim600: syn=xml fen fdm=syntax fdl=2 si
43+
vim: et tw=78 syn=sgml
44+
vi: ts=1 sw=1
45+
-->

‎reference/xpass/constants.xml

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<appendix xml:id="xpass.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
&reftitle.constants;
6+
&extension.constants;
7+
8+
<para>
9+
Xpass extension provides various set of constants.
10+
Hash methods (CRYPT_PREFIX_) for <function>crypt_gensalt</function> prefix parameter.
11+
Error codes (CRYPT_SALT_) returned by <function>crypt_checksalt</function>.
12+
Password algorithms (PASSWORD_) for <function>password_hash</function> algo parameter.
13+
</para>
14+
15+
<variablelist xml:id="xpass.constants.algo">
16+
<title>Hashing methods</title>
17+
<varlistentry xml:id="constant.crypt-prefix-std-des">
18+
<term>
19+
<constant>CRYPT_PREFIX_STD_DES</constant>
20+
(<type>string</type>)
21+
</term>
22+
<listitem>
23+
<simpara>
24+
The original hashing method from Unix V7, based on the DES block cipher.
25+
Because DES is cheap on modern hardware, because there are only 4096 possible
26+
salts and 2**56 distinct passphrases, which it truncates to 8 characters,
27+
it is feasible to discover any passphrase hashed with this method.
28+
It should only be used if you absolutely have to generate hashes that will
29+
work on an old operating system that supports nothing else.
30+
</simpara>
31+
</listitem>
32+
</varlistentry>
33+
<varlistentry xml:id="constant.crypt-prefix-ext-des">
34+
<term>
35+
<constant>CRYPT_PREFIX_EXT_DES</constant>
36+
(<type>string</type>)
37+
</term>
38+
<listitem>
39+
<simpara>
40+
An extension of traditional DES, which eliminates the length limit, increases
41+
the salt size, and makes the time cost tunable. It originates with BSDI BSD/OS
42+
and is also available on at least NetBSD, OpenBSD, and FreeBSD due to the
43+
use of David Burren's FreeSec library. It is much better than traditional DES
44+
and bigcrypt, but still should not be used for new hashes.
45+
</simpara>
46+
</listitem>
47+
</varlistentry>
48+
<varlistentry xml:id="constant.crypt-prefix-md5">
49+
<term>
50+
<constant>CRYPT_PREFIX_MD5</constant>
51+
(<type>string</type>)
52+
</term>
53+
<listitem>
54+
<simpara>
55+
A hash based on the MD5 algorithm, originally developed by Poul-Henning Kamp for FreeBSD.
56+
Supported on most free Unixes and newer versions of Solaris. Not as weak as the DES-based
57+
hashes below, but MD5 is so cheap on modern hardware that it should not be used for new
58+
hashes. Processing cost is not adjustable.
59+
</simpara>
60+
</listitem>
61+
</varlistentry>
62+
<varlistentry xml:id="constant.crypt-prefix-blowfish">
63+
<term>
64+
<constant>CRYPT_PREFIX_BLOWFISH</constant>
65+
(<type>string</type>)
66+
</term>
67+
<listitem>
68+
<simpara>
69+
A hash based on the Blowfish block cipher, modified to have an extra-expensive key schedule.
70+
Originally developed by Niels Provos and David Mazieres for OpenBSD and also supported on recent
71+
versions of FreeBSD and NetBSD, on Solaris 10 and newer, and on several GNU/*/Linux distributions.
72+
</simpara>
73+
</listitem>
74+
</varlistentry>
75+
<varlistentry xml:id="constant.crypt-prefix-sha256">
76+
<term>
77+
<constant>CRYPT_PREFIX_SHA256</constant>
78+
(<type>string</type>)
79+
</term>
80+
<listitem>
81+
<simpara>
82+
A hash based on SHA-2 with 256-bit output, originally developed by Ulrich Drepper for GNU libc.
83+
Supported on Linux but not common elsewhere. Acceptable for new hashes.
84+
The default processing cost parameter is 5000, which is too low for modern hardware.
85+
</simpara>
86+
</listitem>
87+
</varlistentry>
88+
<varlistentry xml:id="constant.crypt-prefix-sha512">
89+
<term>
90+
<constant>CRYPT_PREFIX_SHA512</constant>
91+
(<type>string</type>)
92+
</term>
93+
<listitem>
94+
<simpara>
95+
A hash based on SHA-2 with 512-bit output, originally developed by Ulrich Drepper for GNU libc.
96+
Supported on Linux but not common elsewhere. Acceptable for new hashes.
97+
The default processing cost parameter is 5000, which is too low for modern hardware.
98+
</simpara>
99+
</listitem>
100+
</varlistentry>
101+
<varlistentry xml:id="constant.crypt-prefix-scrypt">
102+
<term>
103+
<constant>CRYPT_PREFIX_SCRYPT</constant>
104+
(<type>string</type>)
105+
</term>
106+
<listitem>
107+
<simpara>
108+
Scrypt is a password-based key derivation function created by Colin Percival, originally
109+
for the Tarsnap online backup service. The algorithm was specifically designed to make it
110+
costly to perform large-scale custom hardware attacks by requiring large amounts of memory.
111+
In 2016, the scrypt algorithm was published by IETF as RFC 7914.
112+
</simpara>
113+
</listitem>
114+
</varlistentry>
115+
<varlistentry xml:id="constant.crypt-prefix-gost-yescrypt">
116+
<term>
117+
<constant>CRYPT_PREFIX_GOST_YESCRYPT</constant>
118+
(<type>string</type>)
119+
</term>
120+
<listitem>
121+
<simpara>
122+
Gost-yescrypt uses the output from yescrypt as an input message to HMAC with the
123+
GOST R 34.11-2012 (Streebog) hash function with a 256-bit digest.
124+
Thus, yescrypt's cryptographic properties are superseded by those of the GOST hash function.
125+
This hashing method is useful in applications that need modern passphrase hashing, but have
126+
to rely on GOST algorithms. The GOST R 34.11-2012 (Streebog) hash function
127+
has been published by the IETF as RFC 6986. Acceptable for new hashes where required.
128+
</simpara>
129+
</listitem>
130+
</varlistentry>
131+
<varlistentry xml:id="constant.crypt-prefix-yescrypt">
132+
<term>
133+
<constant>CRYPT_PREFIX_YESCRYPT</constant>
134+
(<type>string</type>)
135+
</term>
136+
<listitem>
137+
<simpara>
138+
Yescrypt is a scalable passphrase hashing scheme designed by Solar Designer, which is based
139+
on Colin Percival's scrypt. While yescrypt's strength against password guessing attacks comes
140+
from its algorithm design, its cryptographic security is guaranteed by its use of SHA-256
141+
on the outer layer. The SHA-256 hash function has been published by NIST in FIPS PUB 180-2
142+
(and its subsequent revisions such as FIPS PUB 180-4) and by the IETF as RFC 4634
143+
(and subsequently RFC 6234). Recommended for new hashes.
144+
</simpara>
145+
</listitem>
146+
</varlistentry>
147+
</variablelist>
148+
149+
<variablelist xml:id="xpass.constants.error">
150+
<title>Error codes</title>
151+
<varlistentry xml:id="constant.crypt-salt-ok">
152+
<term>
153+
<constant>CRYPT_SALT_OK</constant>
154+
(<type>int</type>)
155+
</term>
156+
<listitem>
157+
<simpara>
158+
No error.
159+
</simpara>
160+
</listitem>
161+
</varlistentry>
162+
<varlistentry xml:id="constant.crypt-salt-invalid">
163+
<term>
164+
<constant>CRYPT_SALT_INVALID</constant>
165+
(<type>int</type>)
166+
</term>
167+
<listitem>
168+
<simpara>
169+
Unkown hashing method or invalid parameters.
170+
</simpara>
171+
</listitem>
172+
</varlistentry>
173+
<varlistentry xml:id="constant.crypt-salt-method-disabled">
174+
<term>
175+
<constant>CRYPT_SALT_METHOD_DISABLED</constant>
176+
(<type>int</type>)
177+
</term>
178+
<listitem>
179+
<simpara>
180+
Hashing method is no longer allowed to be used.
181+
</simpara>
182+
</listitem>
183+
</varlistentry>
184+
<varlistentry xml:id="constant.crypt-salt-method-legacy">
185+
<term>
186+
<constant>CRYPT_SALT_METHOD_LEGACY</constant>
187+
(<type>int</type>)
188+
</term>
189+
<listitem>
190+
<simpara>
191+
Hashing method is no longer considered strong enough.
192+
</simpara>
193+
</listitem>
194+
</varlistentry>
195+
<varlistentry xml:id="constant.crypt-salt-too-cheap">
196+
<term>
197+
<constant>CRYPT_SALT_TOO_CHEAP</constant>
198+
(<type>int</type>)
199+
</term>
200+
<listitem>
201+
<simpara>
202+
Cost parameters are considered too cheap.
203+
</simpara>
204+
</listitem>
205+
</varlistentry>
206+
</variablelist>
207+
208+
<variablelist xml:id="xpass.constants.password">
209+
<title>Password algorithms</title>
210+
<varlistentry xml:id="constant.password-sha512">
211+
<term>
212+
<constant>PASSWORD_SHA512</constant>
213+
(<type>string</type>)
214+
</term>
215+
<listitem>
216+
<para>
217+
<constant>PASSWORD_SHA512</constant> is used to create new password
218+
hashes using the <constant>CRYPT_SHA512</constant> algorithm.
219+
</para>
220+
</listitem>
221+
</varlistentry>
222+
<varlistentry xml:id="constant.password-yescrypt">
223+
<term>
224+
<constant>PASSWORD_YESCRYPT</constant>
225+
(<type>string</type>)
226+
</term>
227+
<listitem>
228+
<para>
229+
<constant>PASSWORD_YESCRYPT</constant> is used to create new password
230+
hashes using the <constant>CRYPT_YESCRYPT</constant> algorithm.
231+
</para>
232+
</listitem>
233+
</varlistentry>
234+
</variablelist>
235+
</appendix>
236+
237+
<!-- Keep this comment at the end of the file
238+
Local variables:
239+
mode: sgml
240+
sgml-omittag:t
241+
sgml-shorttag:t
242+
sgml-minimize-attributes:nil
243+
sgml-always-quote-attributes:t
244+
sgml-indent-step:1
245+
sgml-indent-data:t
246+
indent-tabs-mode:nil
247+
sgml-parent-document:nil
248+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
249+
sgml-exposed-tags:nil
250+
sgml-local-catalogs:nil
251+
sgml-local-ecat-files:nil
252+
End:
253+
vim600: syn=xml fen fdm=syntax fdl=2 si
254+
vim: et tw=78 syn=sgml
255+
vi: ts=1 sw=1
256+
-->

0 commit comments

Comments
 (0)