Skip to content

Commit 7b9d57f

Browse files
GirgiasGirgias
committed
Some markup fixes for the new XPass documentation
1 parent 0987e91 commit 7b9d57f

File tree

8 files changed

+123
-138
lines changed

8 files changed

+123
-138
lines changed

‎reference/xpass/book.xml

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,26 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
4-
<book xml:id="book.xpass" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3+
<book xml:id="book.xpass" xmlns="http://docbook.org/ns/docbook">
54
<?phpdoc extension-membership="pecl" ?>
65
<title>Xpass</title>
76
<titleabbrev>Xpass</titleabbrev>
87

98
<preface xml:id="intro.xpass">
109
&reftitle.intro;
11-
<para>
10+
<simpara>
1211
This extension provides password hashing algorithms used by Linux
1312
distributions, using extended crypt library.
14-
</para>
15-
<para>
13+
</simpara>
14+
<simpara>
1615
It also provides additional functions from libxcrypt missing in core PHP.
17-
</para>
16+
</simpara>
1817
</preface>
1918

2019
&reference.xpass.setup;
2120
&reference.xpass.constants;
2221
&reference.xpass.reference;
2322

2423
</book>
25-
2624
<!-- Keep this comment at the end of the file
2725
Local variables:
2826
mode: sgml

‎reference/xpass/constants.xml

Lines changed: 50 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,15 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
4-
<appendix xml:id="xpass.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3+
<appendix xml:id="xpass.constants" xmlns="http://docbook.org/ns/docbook">
54
&reftitle.constants;
65
&extension.constants;
76

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>
7+
<simpara>
8+
Xpass extension provides various set of constants.
9+
Hash methods (CRYPT_PREFIX_) for <function>crypt_gensalt</function> prefix parameter.
10+
Error codes (CRYPT_SALT_) returned by <function>crypt_checksalt</function>.
11+
Password algorithms (PASSWORD_) for <function>password_hash</function> algo parameter.
12+
</simpara>
1413

1514
<variablelist xml:id="xpass.constants.algo">
1615
<title>Hashing methods</title>
@@ -21,12 +20,13 @@
2120
</term>
2221
<listitem>
2322
<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.
23+
The original hashing method from Unix V7, based on the DES block cipher.
24+
Because DES is cheap on modern hardware,
25+
because there are only <literal>4096</literal> possible salts and 2**56 distinct passphrases,
26+
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.
3030
</simpara>
3131
</listitem>
3232
</varlistentry>
@@ -37,11 +37,12 @@
3737
</term>
3838
<listitem>
3939
<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.
40+
An extension of traditional DES, which eliminates the length limit,
41+
increases the salt size, and makes the time cost tunable.
42+
It originates with BSDI BSD/OS and is also available on at least NetBSD,
43+
OpenBSD, and FreeBSD due to the use of David Burren's FreeSec library.
44+
It is much better than traditional DES and bigcrypt,
45+
but still should not be used for new hashes.
4546
</simpara>
4647
</listitem>
4748
</varlistentry>
@@ -52,10 +53,11 @@
5253
</term>
5354
<listitem>
5455
<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.
56+
A hash based on the MD5 algorithm, originally developed by Poul-Henning Kamp for FreeBSD.
57+
Supported on most free Unixes and newer versions of Solaris.
58+
Not as weak as the DES-based hashes below,
59+
but MD5 is so cheap on modern hardware that it should not be used for new hashes.
60+
Processing cost is not adjustable.
5961
</simpara>
6062
</listitem>
6163
</varlistentry>
@@ -80,8 +82,10 @@
8082
<listitem>
8183
<simpara>
8284
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+
Supported on Linux but not common elsewhere.
86+
Acceptable for new hashes.
87+
The default processing cost parameter is <literal>5000</literal>,
88+
which is too low for modern hardware.
8589
</simpara>
8690
</listitem>
8791
</varlistentry>
@@ -93,8 +97,10 @@
9397
<listitem>
9498
<simpara>
9599
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.
100+
Supported on Linux but not common elsewhere.
101+
Acceptable for new hashes.
102+
The default processing cost parameter is <literal>5000</literal>,
103+
which is too low for modern hardware.
98104
</simpara>
99105
</listitem>
100106
</varlistentry>
@@ -105,10 +111,11 @@
105111
</term>
106112
<listitem>
107113
<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.
114+
Scrypt is a password-based key derivation function created by Colin Percival,
115+
originally for the Tarsnap online backup service.
116+
The algorithm was specifically designed to make it costly to perform
117+
large-scale custom hardware attacks by requiring large amounts of memory.
118+
In 2016, the scrypt algorithm was published by IETF as RFC 7914.
112119
</simpara>
113120
</listitem>
114121
</varlistentry>
@@ -122,9 +129,10 @@
122129
Gost-yescrypt uses the output from yescrypt as an input message to HMAC with the
123130
GOST R 34.11-2012 (Streebog) hash function with a 256-bit digest.
124131
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.
132+
This hashing method is useful in applications that need modern passphrase hashing,
133+
but have to rely on GOST algorithms.
134+
The GOST R 34.11-2012 (Streebog) hash function has been published by the IETF as RFC 6986.
135+
Acceptable for new hashes where required.
128136
</simpara>
129137
</listitem>
130138
</varlistentry>
@@ -135,12 +143,14 @@
135143
</term>
136144
<listitem>
137145
<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
146+
Yescrypt is a scalable passphrase hashing scheme designed by Solar Designer,
147+
which is based on Colin Percival's scrypt.
148+
While yescrypt's strength against password guessing attacks comes from its algorithm design,
149+
its cryptographic security is guaranteed by its use of SHA-256 on the outer layer.
150+
The SHA-256 hash function has been published by NIST in FIPS PUB 180-2
142151
(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.
152+
(and subsequently RFC 6234).
153+
Recommended for new hashes.
144154
</simpara>
145155
</listitem>
146156
</varlistentry>
@@ -166,7 +176,7 @@
166176
</term>
167177
<listitem>
168178
<simpara>
169-
Unkown hashing method or invalid parameters.
179+
Unknown hashing method or invalid parameters.
170180
</simpara>
171181
</listitem>
172182
</varlistentry>
@@ -233,7 +243,6 @@
233243
</varlistentry>
234244
</variablelist>
235245
</appendix>
236-
237246
<!-- Keep this comment at the end of the file
238247
Local variables:
239248
mode: sgml

‎reference/xpass/functions/crypt-checksalt.xml

Lines changed: 20 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
43
<refentry xml:id="function.crypt-checksalt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
54
<refnamediv>
65
<refname>crypt_checksalt</refname>
@@ -13,12 +12,12 @@
1312
<type class="union"><type>string</type><type>null</type></type><methodname>crypt_checksalt</methodname>
1413
<methodparam><type>string</type><parameter>salt</parameter></methodparam>
1514
</methodsynopsis>
16-
<para>
15+
<simpara>
1716
Checks the salt string against the system configuration and reports whether
1817
the hashing method and parameters it specifies are acceptable.
1918
It is intended to be used to determine whether the user's passphrase should
2019
be re-hashed using the currently preferred hashing method.
21-
</para>
20+
</simpara>
2221
</refsect1>
2322

2423
<refsect1 role="parameters">
@@ -27,28 +26,28 @@
2726
<varlistentry>
2827
<term><parameter>salt</parameter></term>
2928
<listitem>
30-
<para>
29+
<simpara>
3130
Salt string to check.
32-
</para>
31+
</simpara>
3332
</listitem>
3433
</varlistentry>
3534
</variablelist>
3635
</refsect1>
3736

3837
<refsect1 role="returnvalues">
3938
&reftitle.returnvalues;
40-
<para>
41-
Returns an <type>int</type>, one of CRYPT_SALT_* constant,
42-
see the <link linkend="xpass.constants">Xpass constants</link> page.
43-
</para>
39+
<simpara>
40+
Returns one of the
41+
<constant>CRYPT_SALT_<replaceable>*</replaceable></constant>
42+
as an <type>int</type>.
43+
</simpara>
4444
</refsect1>
4545

4646
<refsect1 role="examples">
4747
&reftitle.examples;
48-
<para>
49-
<example>
50-
<title>A <function>crypt_checksalt</function> example</title>
51-
<programlisting role="php">
48+
<example>
49+
<title>A <function>crypt_checksalt</function> example</title>
50+
<programlisting role="php">
5251
<![CDATA[
5352
<?php
5453
// Generate a salt for a legacy method
@@ -64,29 +63,25 @@ $test = crypt_checksalt($salt);
6463
var_dump($test === CRYPT_SALT_OK);
6564
?>
6665
]]>
67-
</programlisting>
68-
&example.outputs;
69-
<screen>
66+
</programlisting>
67+
&example.outputs;
68+
<screen>
7069
<![CDATA[
7170
bool(true)
7271
bool(true)
7372
]]>
74-
</screen>
75-
</example>
76-
</para>
73+
</screen>
74+
</example>
7775
</refsect1>
7876

7977
<refsect1 role="seealso">
8078
&reftitle.seealso;
81-
<para>
82-
<simplelist>
83-
<member><function>crypt_gensalt</function></member>
84-
</simplelist>
85-
</para>
79+
<simplelist>
80+
<member><function>crypt_gensalt</function></member>
81+
</simplelist>
8682
</refsect1>
8783

8884
</refentry>
89-
9085
<!-- Keep this comment at the end of the file
9186
Local variables:
9287
mode: sgml

0 commit comments

Comments
 (0)