Struct password_hash::Output

pub struct Output { /* fields omitted */ }

Output from password hashing functions, i.e. the “hash” or “digest” as raw bytes.

The Output type implements the RECOMMENDED best practices described in the PHC string format specification, namely:

The hash output, for a verification, must be long enough to make preimage attacks at least as hard as password guessing. To promote wide acceptance, a default output size of 256 bits (32 bytes, encoded as 43 characters) is recommended. Function implementations SHOULD NOT allow outputs of less than 80 bits to be used for password verification.

Recommended length

Per the description above, the recommended default length for an Output of a password hashing function is 32-bytes (256-bits).

Constraints

The above guidelines are interpreted into the following constraints:

• Minimum length: 10-bytes (80-bits)
• Maximum length: 64-bytes (512-bits)

The specific recommendation of a 64-byte maximum length is taken as a best practice from the hash output guidelines for Argon2 Encoding given in the same document:

The hash output…length shall be between 12 and 64 bytes (16 and 86 characters, respectively). The default output length is 32 bytes (43 characters).

Based on this guidance, this type enforces an upper bound of 64-bytes as a reasonable maximum, and recommends using 32-bytes.

Constant-time comparisons

The PartialEq and Eq trait impls for Output provide a non-short-circuiting equality comparison.

There are few cases where this may actually helpful from a practical perspective, namely cases where salts are predictable by an attacker. Due to the limited degree in which such comparisons may be helpful, this crate does not loop in additional dependencies for constant-time comparisons (e.g. subtle).

The extent to which constant-time comparisons of password hashes provides meaningful protections in practical contexts is a topic of considerable debate. This library has elected to use a non-short-circuiting comparison as a safer (“belt-and-suspenders”) default, and also to head off any potential debates around the issue. Our main suggestion to avoid such attacks is to use a unique, randomly generated salt per password which is unpredictable by the attacker. The [SaltString::generate] function randomly generates high-entropy salt values.

Implementations

impl Output

pub const MIN_LENGTH: usize

Minimum length of a Output string: 10-bytes.

pub const MAX_LENGTH: usize

Maximum length of Output string: 64-bytes.

See type-level documentation about Output for more information.

pub const B64_MAX_LENGTH: usize

Maximum length of Output when encoded as B64 string: 86-bytes (i.e. 86 ASCII characters)

pub fn new(input: &[u8]) -> Result<Self>

Create a Output from the given byte slice, validating it according to [Output::min_len] and [Output::max_len] length restrictions.

pub fn new_with_encoding(input: &[u8], encoding: Encoding) -> Result<Self>

Create a Output from the given byte slice and Encoding, validating it according to [Output::min_len] and [Output::max_len] length restrictions.

pub fn init_with<F>(output_size: usize, f: F) -> Result<Self> where
    F: FnOnce(&mut [u8]) -> Result<()>, 

Initialize an Output using the provided method, which is given a mutable byte slice into which it should write the output.

The output_size (in bytes) must be known in advance, as well as at least [Output::min_len] bytes and at most [Output::max_len] bytes.

pub fn as_bytes(&self) -> &[u8]

Borrow the output value as a byte slice.

pub fn encoding(&self) -> Encoding

Get the Encoding that this Output is serialized with.

pub fn len(&self) -> usize

Get the length of the output value as a byte slice.

pub fn b64_decode(input: &str) -> Result<Self>

Parse B64-encoded Output, i.e. using the PHC string specification’s restricted interpretation of Base64.

pub fn b64_encode<'a>(&self, out: &'a mut [u8]) -> Result<&'a str>

Write B64-encoded Output to the provided buffer, returning a sub-slice containing the encoded data.

Returns an error if the buffer is too short to contain the output.

pub fn decode(input: &str, encoding: Encoding) -> Result<Self>

Decode the given input string using the specified Encoding.

pub fn encode<'a>(
    &self,
    out: &'a mut [u8],
    encoding: Encoding
) -> Result<&'a str>

Encode this Output using the specified Encoding.

pub fn b64_len(&self) -> usize

Get the length of this Output when encoded as B64.

Trait Implementations

impl AsRef<[u8]> for Output

fn as_ref(&self) -> &[u8]

Performs the conversion.

impl Clone for Output

fn clone(&self) -> Output

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Output

impl Debug for Output

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Output

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Output

impl FromStr for Output

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self>

Parses a string s to return a value of this type.

impl PartialEq<Output> for Output

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl StructuralEq for Output

impl TryFrom<&'_ [u8]> for Output

type Error = Error

The type returned in the event of a conversion error.

fn try_from(input: &[u8]) -> Result<Output>

Performs the conversion.