php-doc-en/reference/sodium/functions/sodium-crypto-pwhash.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.sodium-crypto-pwhash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>sodium_crypto_pwhash</refname>
  <refpurpose>Derive a key from a password</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>sodium_crypto_pwhash</methodname>
   <methodparam><type>int</type><parameter>length</parameter></methodparam>
   <methodparam><type>string</type><parameter>password</parameter></methodparam>
   <methodparam><type>string</type><parameter>salt</parameter></methodparam>
   <methodparam><type>int</type><parameter>opslimit</parameter></methodparam>
   <methodparam><type>int</type><parameter>memlimit</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>algo</parameter><initializer><constant>SODIUM_CRYPTO_PWHASH_ALG_DEFAULT</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   This function provides low-level access to libsodium's crypto_pwhash key derivation function. Unless you have specific reason to use this function, you should use <function>sodium_crypto_pwhash_str</function> or <function>password_hash</function> functions instead.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>length</parameter></term>
    <listitem>
     <para>
      <type>int</type>; The length of the password hash to generate, in bytes.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>password</parameter></term>
    <listitem>
     <para>
      <type>string</type>; The password to generate a hash for.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>salt</parameter></term>
    <listitem>
     <para>
      <type>string</type> A salt to add to the password before hashing. The salt should be unpredictable, ideally generated from a good random mumber source such as <function>random_bytes</function>, and have a length of at least <constant>SODIUM_CRYPTO_PWHASH_SALTBYTES</constant> bytes.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>opslimit</parameter></term>
    <listitem>
     <para>
      Represents a maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. There are some constants available to set the operations limit to appropriate values depending on intended use, in order of strength: <constant>SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE</constant>, <constant>SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE</constant> and <constant>SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE</constant>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>memlimit</parameter></term>
    <listitem>
     <para>
      The maximum amount of RAM that the function will use, in bytes. There are constants to help you choose an appropriate value, in order of size: <constant>SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE</constant>, <constant>SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE</constant>, and <constant>SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE</constant>. Typically these should be paired with the matching <parameter>opslimit</parameter> values.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>algo</parameter></term>
    <listitem>
     <para>
      <type>int</type> A number indicating the hash algorithm to use. By default <constant>SODIUM_CRYPTO_PWHASH_ALG_DEFAULT</constant> (the currently recommended algorithm, which can change from one version of libsodium to another), or explicitly using <constant>SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13</constant>, representing the Argon2id algorithm version 1.3.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the derived key. The return value is a binary string of the hash, not an ASCII-encoded representation, and does not contain additional information about the parameters used to create the hash, so you will need to keep that information if you are ever going to verify the password in future. Use <function>sodium_crypto_pwhash_str</function> to avoid needing to do all that.
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>password_hash</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
//Need to keep the salt if we're ever going to be able to check this password
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
//Using bin2hex to keep output readable
echo bin2hex(
    sodium_crypto_pwhash(
        16, // == 128 bits
        'password',
        $salt,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
    )
);
?>]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
a18f346ba57992eb7e4ae6abf3fd30ee
]]>
    </screen>
   </example>
  </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
-->