Struct orion::pwhash::PasswordHash

pub struct PasswordHash { /* fields omitted */ }

A type to represent the PasswordHash that Argon2i returns when used for password hashing.

Errors:

An error will be returned if:

• The encoded password hash contains whitespace.
• The encoded password hash has a parallelism count other than 1.
• The encoded password contains any other fields than: The algorithm name, version, m, t, p and the salt and password hash.
• The encoded password hash contains invalid Base64 encoding.
• Any decimal parameter value, such as m, contains leading zeroes and is longer than a single character.
• iterations is less than 3.
• memory is less than 8.
• password is not 32 bytes.
• salt is not 16 bytes.
• The encoded password hash contains numerical values that cannot be represented as a u32.
• The encoded password hash length is less than MIN_ENCODED_LEN or greater than MAX_ENCODED_LEN.
• The parameters in the encoded password hash are not correctly ordered. The ordering must be: $argon2i$v=19$m=<value>,t=<value>,p=<value>$<salt>$<hash>

Panics:

A panic will occur if:

• Overflowing calculations happen on usize when decoding the password and salt from Base64.

Security:

• Avoid using unprotected_as_bytes() whenever possible, as it breaks all protections that the type implements.
• Never use unprotected_as_bytes() or unprotected_as_encoded() to compare password hashes, as that will not run in constant-time. Compare PasswordHashes directly using == instead.
• The base64 encoding and decoding operations that PasswordHash performs, do NOT run in constant-time.
• The trait PartialEq<&'_ [u8]> is implemented for this type so that users are not tempted to call unprotected_as_bytes to compare this sensitive value to a byte slice. The trait is implemented in such a way that the comparison happens in constant time. Thus, users should prefer SecretType == &[u8] over SecretType.unprotected_as_bytes() == &[u8]. Examples are shown below. The examples apply to any type that implements PartialEq<&'_ [u8]>.

use orion::hazardous::mac::hmac::Tag;

// Initialize an arbitrary, 64-byte tag.
let tag = Tag::from_slice(&[1; 64])?;

// Secure, constant-time comparison with a byte slice
assert!(tag == &[1; 64][..]);

// Secure, constant-time comparison with another Tag
assert!(tag == Tag::from_slice(&[1; 64])?);

Methods

impl PasswordHash

pub const MIN_ENCODED_LEN: usize

Given a 16-byte salt (22 characters encoded) and 32-byte password hash (43 characters encoded), and parameters (m, t) in decimal representation of 1..10 in length, 92 is the minimum length for an encoded password hash.

pub const MAX_ENCODED_LEN: usize

Given a 16-byte salt (22 characters encoded) and 32-byte password hash (43 characters encoded), and parameters (m, t) in decimal representation of 1..10 in length, 110 is the maximum length for an encoded password hash.

#[must_use = "SECURITY WARNING: Ignoring a Result can have real security implications."] pub fn from_slice(
    password_hash: &[u8],
    salt: &[u8],
    iterations: u32,
    memory: u32
) -> Result<Self, UnknownCryptoError>

Construct from given byte slice and parameters.

#[must_use = "SECURITY WARNING: Ignoring a Result can have real security implications."] pub fn from_encoded(password_hash: &str) -> Result<Self, UnknownCryptoError>

Construct from encoded password hash.

pub fn unprotected_as_encoded(&self) -> &str

Return encoded password hash. Warning: Should not be used to verify password hashes. This breaks protections that the type implements.

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

Return the password hash as byte slice. Warning: Should not be used unless strictly needed. This breaks protections that the type implements.

pub fn len(&self) -> usize

Return the length of the password hash.

Trait Implementations

impl Debug for PasswordHash

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

Formats the value using the given formatter.

impl Eq for PasswordHash

impl<'_> PartialEq<&'_ [u8]> for PasswordHash

fn eq(&self, other: &&[u8]) -> bool

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PartialEq<PasswordHash> for PasswordHash

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

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.