Struct Salt 

pub struct Salt(/* private fields */);

Random salt used to decorrelate other information.

A Salt is a cryptographic primitive consisting of random data that is used to modify the output of a cryptographic function. Salts are primarily used in password hashing to defend against dictionary attacks, rainbow table attacks, and pre-computation attacks. They are also used in other cryptographic contexts to ensure uniqueness and prevent correlation between different parts of a cryptosystem.

Unlike a Nonce which has a fixed size, a Salt in this implementation can have a variable length (minimum 8 bytes). Different salt creation methods are provided to generate salts of appropriate sizes for different use cases.

Minimum Size Requirement

For security reasons, salts must be at least 8 bytes long. Attempting to create a salt with fewer than 8 bytes will result in an error.

CBOR Serialization

Salt implements the CBORTaggedCodable trait, which means it can be serialized to and deserialized from CBOR with a specific tag. The tag used is TAG_SALT defined in the tags module.

UR Serialization

When serialized as a Uniform Resource (UR), a Salt is represented as a binary blob with the type “salt”.

Common Uses

• Password hashing and key derivation functions
• Preventing correlation in cryptographic protocols
• Randomizing data before encryption to prevent pattern recognition
• Adding entropy to improve security in various cryptographic functions

Examples

Creating a salt with a specific length:

use bc_components::Salt;

// Generate a salt with 16 bytes
let salt = Salt::new_with_len(16).unwrap();
assert_eq!(salt.len(), 16);

Creating a salt with a length proportional to data size:

use bc_components::Salt;

// Generate a salt proportional to 100 bytes of data
let salt = Salt::new_for_size(100);

// Salts for larger data will be larger (but still efficient)
let big_salt = Salt::new_for_size(1000);
assert!(big_salt.len() > salt.len());

Creating a salt with a length in a specific range:

use bc_components::Salt;

// Generate a salt with length between 16 and 32 bytes
let salt = Salt::new_in_range(16..=32).unwrap();
assert!(salt.len() >= 16 && salt.len() <= 32);

Implementations

impl Salt

pub fn len(&self) -> usize

Return the length of the salt.

pub fn is_empty(&self) -> bool

Return true if the salt is empty (this is not recommended).

pub fn from_data(data: impl AsRef<[u8]>) -> Self

Create a new salt from data.

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

Return the data of the salt.

pub fn new_with_len(count: usize) -> Result<Self>

Create a specific number of bytes of salt.

If the number of bytes is less than 8, this will return None.

pub fn new_with_len_using( count: usize, rng: &mut impl RandomNumberGenerator, ) -> Result<Self>

Create a specific number of bytes of salt.

If the number of bytes is less than 8, this will return None.

pub fn new_in_range(range: RangeInclusive<usize>) -> Result<Self>

Create a number of bytes of salt chosen randomly from the given range.

If the minimum number of bytes is less than 8, this will return None.

pub fn new_in_range_using( range: &RangeInclusive<usize>, rng: &mut impl RandomNumberGenerator, ) -> Result<Self>

Create a number of bytes of salt chosen randomly from the given range.

If the minimum number of bytes is less than 8, this will return None.

pub fn new_for_size(size: usize) -> Self

Create a number of bytes of salt generally proportionate to the size of the object being salted.

pub fn new_for_size_using( size: usize, rng: &mut impl RandomNumberGenerator, ) -> Self

Create a number of bytes of salt generally proportionate to the size of the object being salted.

pub fn from_hex(hex: impl AsRef<str>) -> Self

Create a new salt from the given hexadecimal string.

pub fn hex(&self) -> String

The data as a hexadecimal string.

Trait Implementations

impl AsRef<[u8]> for Salt

Allows using a Salt as a reference to a byte slice.

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

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

impl AsRef<Salt> for Salt

Provides a self-reference, enabling API consistency with other types.

fn as_ref(&self) -> &Salt

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

impl CBORTagged for Salt

Identifies the CBOR tags used for Salt serialization.

fn cbor_tags() -> Vec<Tag>

Returns the CBOR tags associated with this type.

impl CBORTaggedDecodable for Salt

Defines how a Salt is decoded from CBOR.

fn from_untagged_cbor(untagged_cbor: CBOR) -> Result<Self>

Creates an instance of this type by decoding it from untagged CBOR.

fn from_tagged_cbor(cbor: CBOR) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from tagged CBOR.

fn from_tagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded tagged CBOR.

fn from_untagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded untagged CBOR.

impl CBORTaggedEncodable for Salt

Defines how a Salt is encoded as CBOR (as a byte string).

fn untagged_cbor(&self) -> CBOR

Returns the untagged CBOR encoding of this instance.

fn tagged_cbor(&self) -> CBOR

Returns the tagged CBOR encoding of this instance.

fn tagged_cbor_data(&self) -> Vec<u8>

Returns the tagged value in CBOR binary representation.

impl Clone for Salt

fn clone(&self) -> Salt

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Salt

Provides a debug representation showing the salt’s length.

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

Formats the value using the given formatter.

impl<'a> From<&'a Salt> for &'a [u8]

Allows accessing the underlying data as a byte slice reference.

fn from(value: &'a Salt) -> Self

Converts to this type from the input type.

impl From<&Salt> for Salt

Enables cloning a Salt from a reference using From trait.

fn from(salt: &Salt) -> Self

Converts to this type from the input type.

impl From<&Salt> for Vec<u8>

Converts a Salt reference into a Vec<u8> containing the salt bytes.

fn from(salt: &Salt) -> Self

Converts to this type from the input type.

impl From<Salt> for CBOR

Enables conversion of a Salt into a tagged CBOR value.

fn from(value: Salt) -> Self

Converts to this type from the input type.

impl From<Salt> for Vec<u8>

Converts a Salt into a Vec<u8> containing the salt bytes.

fn from(salt: Salt) -> Self

Converts to this type from the input type.

impl PartialEq for Salt

fn eq(&self, other: &Salt) -> 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 TryFrom<CBOR> for Salt

Enables conversion from CBOR to Salt, with proper error handling.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(cbor: CBOR) -> Result<Self>

Performs the conversion.

impl Eq for Salt

impl StructuralPartialEq for Salt