sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Derive a key from a password, using Argon2

说明

sodium_crypto_pwhash ( int $length , string $password , string $salt , int $opslimit , int $memlimit , int $algo = SODIUM_CRYPTO_PWHASH_ALG_DEFAULT ) : string

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 sodium_crypto_pwhash_str() or password_hash() functions instead.

A common reason to use this particular function is to derive the seeds for cryptographic keys from a password and salt, and then use these seeds to generate the actual keys needed for some purpose (e.g. sodium_crypto_sign_detached()).

参数

length: int; The length of the password hash to generate, in bytes.
password: string; The password to generate a hash for.
salt: A salt to add to the password before hashing. The salt should be unpredictable, ideally generated from a good random number source such as random_bytes(), and have a length of at least SODIUM_CRYPTO_PWHASH_SALTBYTES bytes.
opslimit: 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: SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE and SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE.
memlimit: 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: SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE, SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE, and SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE. Typically these should be paired with the matching opslimit values.
algo: int A number indicating the hash algorithm to use. By default SODIUM_CRYPTO_PWHASH_ALG_DEFAULT (the currently recommended algorithm, which can change from one version of libsodium to another), or explicitly using SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13, representing the Argon2id algorithm version 1.3.

返回值

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 sodium_crypto_pwhash_str() to avoid needing to do all that.

范例

Example #1 sodium_crypto_pwhash() example


<?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
    )
);
?>

以上例程的输出类似于：

a18f346ba57992eb7e4ae6abf3fd30ee

User Contributed Notes

craig at craigfrancis dot co dot uk 08-Mar-2020 06:08


When encrypting, you would ideally use a randomly generated key, as that's considerably harder to guess.



For example, sodium_crypto_aead_chacha20poly1305_ietf_keygen()



But if you need to use a password to encrypt/decrypt, you can use sodium_crypto_pwhash():



<?php



function secrets_encrypt($password, $secret) {



  $config = [

      'size'      => SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES,

      'salt'      => random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES),

      'limit_ops' => SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE,

      'limit_mem' => SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE,

      'alg'       => SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13,

      'nonce'     => random_bytes(SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES),

    ];



  // $config['limit_ops'] = SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE;

  // $config['limit_mem'] = SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE;



  $key = sodium_crypto_pwhash(

      $config['size'],

      $password,

      $config['salt'],

      $config['limit_ops'],

      $config['limit_mem'],

      $config['alg'],

    );



  $encrypted = sodium_crypto_aead_chacha20poly1305_ietf_encrypt(

      $secret,

      $config['nonce'], // Associated Data

      $config['nonce'],

      $key

    );



  return [

      'config' => array_map('base64_encode', $config),

      'encrypted' => base64_encode($encrypted),

    ];



}



$password = 'YoxPR4QLeZ';

$secret   = 'This-is-my-secret';



$data = secrets_encrypt($password, $secret);



?>



To decrypt with that password, using the same limits:



<?php



function secrets_decrypt($password, $data) {



  $config = array_map('base64_decode', $data['config']);

  $encrypted = base64_decode($data['encrypted']);



  $key = sodium_crypto_pwhash(

      $config['size'],

      $password,

      $config['salt'],

      $config['limit_ops'],

      $config['limit_mem'],

      $config['alg'],

    );



  return sodium_crypto_aead_chacha20poly1305_ietf_decrypt(

      $encrypted,

      $config['nonce'], // Associated Data

      $config['nonce'],

      $key

    );



}



$secret = secrets_decrypt($password, $data);



?>