silk.crypto.pbkdf2.

When to use#

Use Pbkdf2.derive when a format or protocol names PBKDF2, such as crypto.pbkdf2 in Node.js, PKCS #5, or a stored password hash. For new password storage, prefer a memory-hard function such as silk.crypto.scrypt.

Details#

The hash is a type argument, such as Pbkdf2.derive<Sha256> or Pbkdf2.derive<Sha1>. The output can have any length up to (2^32 - 1) times the digest length. Each iteration costs two compressions of the hash, because the keyed HMAC prefix is computed once. Nothing allocates.

Errors#

Pbkdf2.derive returns a Pbkdf2Error and leaves output unchanged when the iteration count is zero or the output is too long.

Gotchas#

The time grows with iterations, so a count that an attacker controls can take a long time. The function does not erase its copies of the password.

Examples#

Derive a key with PBKDF2-HMAC-SHA-256#

import silk.crypto.pbkdf2 { Pbkdf2, Pbkdf2Error }
import silk.crypto.sha2 { Sha256 }
import silk.core.result { Result }

pub fn main() -> i32 {
  let mut key: [u8; 32] = [0; 32]
  let derived = Pbkdf2.derive<Sha256>(b"password", b"salt", 1, &mut key)
  if let Result.Failure { error: _ } = move derived {
    return 1
  }
  // RFC 7914 section 11: PBKDF2-HMAC-SHA-256 of these inputs starts with 120fb6cf.
  if key[0] != 0x12 || key[1] != 0x0f || key[2] != 0xb6 || key[3] != 0xcf {
    return 1
  }
  return 0
}

Import as Pbkdf2 with import silk.crypto.pbkdf2 { Pbkdf2 }.

Public declarations: 2.

Pbkdf2Error#

pub union Pbkdf2Error

The reason that Pbkdf2.derive rejected a call. The output does not change.

ZeroIterations#

ZeroIterations

The iteration count is zero.

OutputTooLong#

OutputTooLong

The output is longer than (2^32 - 1) times the digest length of the hash.

Implementation Debug for Pbkdf2Error#

impl Debug for Pbkdf2Error

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Writes the name of the variant, such as ZeroIterations.

Pbkdf2#

pub struct Pbkdf2

Functions that derive keys from passwords with PBKDF2 (RFC 8018).

When to use#

Use Pbkdf2.derive when a format or protocol names PBKDF2. For new password storage, prefer silk.crypto.scrypt.

Implementation Pbkdf2#

impl Pbkdf2

Associated function derive#

pub fn derive<H: Digest>(
    password: &[u8],
    salt: &[u8],
    iterations: u32,
    output: &mut [u8],
  ) -> Result<(), Pbkdf2Error,>

Fills output with the PBKDF2-HMAC key of password and salt over the hash H, with iterations rounds.

Any password and salt length is valid, also 0. The output can have any length, also 0. The first bytes do not depend on how long output is, so a shorter output is a prefix of a longer one. Nothing allocates.

Errors#

On an error, output does not change.

• ZeroIterations if iterations is 0.

• OutputTooLong if output is longer than (2^32 - 1) times the digest length of H.

Gotchas#

The time grows with iterations. The function does not erase its copies of the password.

Category: Cryptography.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.