Struct AuthKey 

pub struct AuthKey { /* private fields */ }

A 256-bit authentication key.

Sensitive material. Derives ZeroizeOnDrop which provides secure memory cleanup with compiler-resistant zeroization. The Copy derive was removed (br-asupersync-4pegj0) so a key cannot be silently bit-copied past the destructor; callers that need a logical duplicate must call .clone() explicitly, which preserves the zeroize-on-drop contract for both copies.

Implementations

impl AuthKey

pub fn from_seed(seed: u64) -> Self

Creates a new key from a 64-bit seed.

This uses domain-separated SHA-256 to deterministically expand the seed into 32 bytes without depending on DetRng’s zero-seed normalization.

Security

This constructor has at most 64 bits of input entropy. SHA-256 and the fallback HKDF path distribute those bits but cannot create additional entropy, so this API is suitable for deterministic tests, fixtures, and reproducible simulations—not production authentication keys. Production callers should supply 32 bytes from a CSPRNG or secret-management system through Self::from_bytes.

pub fn from_rng(rng: &mut DetRng) -> Self

Creates a new key from the deterministic replay RNG.

Security

DetRng is intentionally reproducible and is not a CSPRNG. This constructor is for deterministic tests and simulations, not production key generation. The output-shape validation below catches pathological buffers but cannot make a predictable RNG secret.

pub fn from_bytes(bytes: [u8; 32]) -> Result<Self, AuthKeyError>

Creates a new key from raw bytes WITH ENTROPY VALIDATION.

br-asupersync-q3terg: rejects pathologically-low-entropy inputs (all-zero, all-0xFF, single-distinct-byte patterns, low-Hamming- weight extremes). HMAC-SHA256 security depends on the key having sufficient entropy; a key with zero entropy produces deterministic and predictable HMAC outputs — an attacker who learns of such a weak key (via leaked default, misconfig, or because the prior from_bytes(bytes) accepted any 32-byte buffer) can forge authentication tags for any symbol.

Validation rules (any failure rejects with AuthKeyError):

• bytes must contain at least MIN_DISTINCT_BYTES (16) distinct byte values out of 32. Strengthened from previous dangerously-low threshold of 8.
• The Hamming weight (count of 1-bits across all 256 bits) must lie in [MIN_HAMMING_WEIGHT, MAX_HAMMING_WEIGHT] (64, 192). Represents 25%-75% bit density, preventing entropy-starved keys. Previous thresholds (8, 248) were cryptographically dangerous.
• No byte value may appear more than MAX_BYTE_FREQUENCY (4) times. Prevents concentration attacks and predictable patterns like repeating sequences.

For known-strong byte sources (e.g. HMAC outputs in the macaroon caveat chain — by construction uniformly random), use Self::from_hmac_derived for HMAC-derived sources. That constructor is pub(crate) to prevent external code from accidentally importing the bypass path.

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

Returns the raw bytes of the key.

pub fn derive_subkey(&self, purpose: &[u8]) -> Self

Derives a subkey for a specific purpose using HMAC-SHA256.

Construction: derived = HMAC-SHA256(self, purpose).

pub fn derive_with_salt(&self, salt: &[u8], context: &[u8]) -> Self

Derives a key using strengthened HMAC-SHA256 with salt and context.

This performs a two-step derivation that’s cryptographically stronger than simple HMAC derivation:

1. Extract: PRK = HMAC-SHA256(salt, self)
2. Expand: derived_key = HMAC-SHA256(PRK, context)

This provides domain separation and salt-based security enhancement.

pub fn from_hkdf(ikm: &[u8], salt: Option<&[u8]>, info: &[u8]) -> Self

Creates a key using HKDF (HMAC-based Key Derivation Function).

Performs the HKDF Extract-and-Expand process with the given input key material, optional salt, and context information to derive a domain-separated key.

HKDF extracts and distributes existing entropy; it does not create entropy. The input key material must already contain sufficient secret entropy for the caller’s threat model. A salt may be public and improves domain separation, but does not turn a password, short integer, or predictable seed into a production authentication secret.

Parameters

• ikm - Input Key Material (the source entropy)
• salt - Optional salt value for the extract phase
• info - Context information for the expand phase

Security

The resulting bytes have a pseudorandom output shape, so this constructor intentionally bypasses Self::from_bytes’s heuristic pattern checks. That is not a claim about the entropy of ikm.

Trait Implementations

impl Clone for AuthKey

fn clone(&self) -> AuthKey

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AuthKey

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

Formats the value using the given formatter.

impl Drop for AuthKey

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Eq for AuthKey

impl Hash for AuthKey

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for AuthKey

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

Equality operator ==.

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

Inequality operator !=.