Skip to content

Commit

Permalink
add Xpass extension
Browse files Browse the repository at this point in the history
  • Loading branch information
@remicollet
remicollet committed Dec 16, 2024
1 parent 3b06ef4 commit 151476a
Show file tree
Hide file tree
Showing 9 changed files with 684 additions and 0 deletions.
2 changes: 2 additions & 0 deletions appendices/extensions.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
45 changes: 45 additions & 0 deletions reference/xpass/book.xml
View file
Original file line number Diff line number Diff line change
@@ -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
-->
218 changes: 218 additions & 0 deletions reference/xpass/constants.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,218 @@
<?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;

<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>
Prefix for standard DES algorithm.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.crypt-prefix-ext-des">
<term>
<constant>CRYPT_PREFIX_EXT_DES</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Prefix for extended DES algorithm.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.crypt-prefix-md5">
<term>
<constant>CRYPT_PREFIX_MD5</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Prefix for MD5 algorithm.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.crypt-prefix-blowfish">
<term>
<constant>CRYPT_PREFIX_BLOWFISH</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Prefix for Blowfish algorithm.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.crypt-prefix-sha256">
<term>
<constant>CRYPT_PREFIX_SHA256</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Prefix for SHA-256 algorithm.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.crypt-prefix-sha512">
<term>
<constant>CRYPT_PREFIX_SHA512</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Prefix for SHA-512 algorithm.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.crypt-prefix-scrypt">
<term>
<constant>CRYPT_PREFIX_SCRYPT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Prefix for scrypt algorithm.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.crypt-prefix-gost-yescrypt">
<term>
<constant>CRYPT_PREFIX_GOST_YESCRYPT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Prefix for GOST yescrypt algorithm.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.crypt-prefix-yescrypt">
<term>
<constant>CRYPT_PREFIX_YESCRYPT</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Prefix for yescrypt algorithm.
</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 hashing methods</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
-->
109 changes: 109 additions & 0 deletions reference/xpass/functions/crypt-checksalt.xml
View file
Original file line number Diff line number Diff line change
@@ -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
-->
Loading

0 comments on commit 151476a

Please sign in to comment.