Struct password_hash::Salt

source ·
pub struct Salt<'a>(/* private fields */);
Expand description

Salt string.

In password hashing, a “salt” is an additional value used to personalize/tweak the output of a password hashing function for a given input password.

Salts help defend against attacks based on precomputed tables of hashed passwords, i.e. “rainbow tables”.

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

  • Maximum lengths for salt, output and parameter values are meant to help consumer implementations, in particular written in C and using stack-allocated buffers. These buffers must account for the worst case, i.e. the maximum defined length. Therefore, keep these lengths low.
  • The role of salts is to achieve uniqueness. A random salt is fine for that as long as its length is sufficient; a 16-byte salt would work well (by definition, UUID are very good salts, and they encode over exactly 16 bytes). 16 bytes encode as 22 characters in B64. Functions should disallow salt values that are too small for security (4 bytes should be viewed as an absolute minimum).

The recommended default length for a salt string is 16-bytes (128-bits).

See Salt::RECOMMENDED_LENGTH for more information.

§Constraints

Salt strings are constrained to the following set of characters per the PHC spec:

The salt consists in a sequence of characters in: [a-zA-Z0-9/+.-] (lowercase letters, uppercase letters, digits, /, +, . and -).

Additionally the following length restrictions are enforced based on the guidelines from the spec:

  • Minimum length: 4-bytes
  • Maximum length: 64-bytes

A maximum length is enforced based on the above recommendation for supporting stack-allocated buffers (which this library uses), and the specific determination of 64-bytes is taken as a best practice from the Argon2 Encoding specification in the same document:

The length in bytes of the salt is between 8 and 64 bytes, thus yielding a length in characters between 11 and 64 characters (and that length is never equal to 1 modulo 4). The default byte length of the salt is 16 bytes (22 characters in B64 encoding). An encoded UUID, or a sequence of 16 bytes produced with a cryptographically strong PRNG, are appropriate salt values.

The Argon2 specification states that the salt can be much longer, up to 2^32-1 bytes, but this makes little sense for password hashing. Specifying a relatively small maximum length allows for parsing with a stack allocated buffer.)

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

Implementations§

source§

impl<'a> Salt<'a>

source

pub const MIN_LENGTH: usize = 4usize

Minimum length of a Salt string: 4-bytes.

source

pub const MAX_LENGTH: usize = 64usize

Maximum length of a Salt string: 64-bytes.

See type-level documentation about Salt for more information.

source

pub const RECOMMENDED_LENGTH: usize = 16usize

Recommended length of a salt: 16-bytes.

This recommendation comes from the PHC string format specification:

The role of salts is to achieve uniqueness. A random salt is fine for that as long as its length is sufficient; a 16-byte salt would work well (by definition, UUID are very good salts, and they encode over exactly 16 bytes). 16 bytes encode as 22 characters in B64.

source

pub fn from_b64(input: &'a str) -> Result<Self>

Create a Salt from the given B64-encoded input string, validating Salt::MIN_LENGTH and Salt::MAX_LENGTH restrictions.

source

pub fn decode_b64<'b>(&self, buf: &'b mut [u8]) -> Result<&'b [u8]>

Attempt to decode a B64-encoded Salt into bytes, writing the decoded output into the provided buffer, and returning a slice of the portion of the buffer containing the decoded result on success.

source

pub fn as_str(&self) -> &'a str

Borrow this value as a str.

source

pub fn len(&self) -> usize

Get the length of this value in ASCII characters.

source

pub fn new(input: &'a str) -> Result<Self>

👎Deprecated since 0.5.0: use from_b64 instead

Create a Salt from the given B64-encoded input string, validating Salt::MIN_LENGTH and Salt::MAX_LENGTH restrictions.

source

pub fn b64_decode<'b>(&self, buf: &'b mut [u8]) -> Result<&'b [u8]>

👎Deprecated since 0.5.0: use decode_b64 instead

Attempt to decode a B64-encoded Salt into bytes, writing the decoded output into the provided buffer, and returning a slice of the portion of the buffer containing the decoded result on success.

Trait Implementations§

source§

impl<'a> AsRef<str> for Salt<'a>

source§

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl<'a> Clone for Salt<'a>

source§

fn clone(&self) -> Salt<'a>

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl<'a> Debug for Salt<'a>

source§

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

Formats the value using the given formatter. Read more
source§

impl<'a> Display for Salt<'a>

source§

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

Formats the value using the given formatter. Read more
source§

impl<'a> From<&'a SaltString> for Salt<'a>

source§

fn from(salt_string: &'a SaltString) -> Salt<'a>

Converts to this type from the input type.
source§

impl<'a> PartialEq for Salt<'a>

source§

fn eq(&self, other: &Salt<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

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

impl<'a> TryFrom<&'a str> for Salt<'a>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(input: &'a str) -> Result<Self>

Performs the conversion.
source§

impl<'a> Copy for Salt<'a>

source§

impl<'a> Eq for Salt<'a>

source§

impl<'a> StructuralPartialEq for Salt<'a>

Auto Trait Implementations§

§

impl<'a> Freeze for Salt<'a>

§

impl<'a> RefUnwindSafe for Salt<'a>

§

impl<'a> Send for Salt<'a>

§

impl<'a> Sync for Salt<'a>

§

impl<'a> Unpin for Salt<'a>

§

impl<'a> UnwindSafe for Salt<'a>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.