Struct password_hash::Salt [−][src]
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).
Recommended length
The recommended default length for a salt string is 16-bytes (128-bits).
See below for rationale.
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
impl<'a> Salt<'a>
[src]
pub const fn min_len() -> usize
[src]
Minimum length of a Salt
string: 2-bytes.
NOTE: this is below the recommended
pub const fn max_len() -> usize
[src]
Maximum length of a Salt
string: 64-bytes.
See type-level documentation about Salt
for more information.
pub const fn recommended_len() -> usize
[src]
Recommended length of a salt: 16-bytes.
pub fn new(input: &'a str) -> Result<Self, ParseError>
[src]
Create a Salt
from the given str
, validating it according to
Salt::min_len
and Salt::max_len
length restrictions.
pub fn b64_decode<'b>(&self, buf: &'b mut [u8]) -> Result<&'b [u8], B64Error>
[src]
Attempt to decode a [b64
][crate::b64
]-encoded Salt
, writing the
decoded result into the provided buffer, and returning a slice of the
buffer containing the decoded result on success.
pub fn as_str(&self) -> &'a str
[src]
Borrow this value as a str
.
pub fn as_bytes(&self) -> &'a [u8]
[src]
Borrow this value as bytes.
pub fn len(&self) -> usize
[src]
Get the length of this value in ASCII characters.
Trait Implementations
impl<'a> AsRef<str> for Salt<'a>
[src]
impl<'a> Clone for Salt<'a>
[src]
fn clone(&self) -> Salt<'a>
[src]
pub fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl<'a> Copy for Salt<'a>
[src]
impl<'a> Debug for Salt<'a>
[src]
impl<'a> Display for Salt<'a>
[src]
impl<'a> Eq for Salt<'a>
[src]
impl<'a> From<&'a SaltString> for Salt<'a>
[src]
fn from(salt_string: &'a SaltString) -> Salt<'a>
[src]
impl<'a> PartialEq<Salt<'a>> for Salt<'a>
[src]
impl<'a> StructuralEq for Salt<'a>
[src]
impl<'a> StructuralPartialEq for Salt<'a>
[src]
impl<'a> TryFrom<&'a str> for Salt<'a>
[src]
type Error = ParseError
The type returned in the event of a conversion error.
fn try_from(input: &'a str) -> Result<Self, ParseError>
[src]
Auto Trait Implementations
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,