Struct PasswordHash

pub struct PasswordHash { /* private fields */ }

Available on crate feature dep_orion only.

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 PasswordHash::MIN_ENCODED_LEN or greater than PasswordHash::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 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::sha512::Tag;

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

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

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

Implementations

impl PasswordHash

pub const MIN_ENCODED_LEN: usize = 92usize

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 = 110usize

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.

pub fn from_slice( password_hash: &[u8], salt: &[u8], iterations: u32, memory: u32, ) -> Result<PasswordHash, UnknownCryptoError>

Construct from given byte slice and parameters.

pub fn from_encoded( password_hash: &str, ) -> Result<PasswordHash, 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.

pub fn is_empty(&self) -> bool

Return true if the password hash is empty, false otherwise.

NOTE: This method should always return false, since there shouldn’t be a way to create an empty password hash.

Trait Implementations

impl Debug for PasswordHash

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for PasswordHash

PasswordHash deserializes from a String.

fn deserialize<D>( deserializer: D, ) -> Result<PasswordHash, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq<&[u8]> for PasswordHash

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for PasswordHash

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for PasswordHash

PasswordHash serializes as would a String. Note that the serialized type likely does not have the same protections that Orion provides, such as constant-time operations. A good rule of thumb is to only serialize these types for storage. Don’t operate on the serialized types.

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for PasswordHash