Struct SecretHash 

pub struct SecretHash { /* private fields */ }

A STORED VERIFIER for a client secret: enough to check a presented secret, never enough to present one.

This is what ClientAuth::ConfidentialSecretHash holds, and it is the shape a host should persist. RFC 6749 section 2.3.1 says the client secret is a password; a password at rest belongs in a one-way form, so that a dump of the client table is not a set of working credentials.

Two kinds of scheme:

• SecretHash::SHA256_HEX, built by SecretHash::sha256 and verified by this crate with no host code and no new dependency (sha2 is already here for RFC 7636 PKCE). Plain SHA-256 is the RIGHT primitive for this particular job and the wrong one for a user password: a client secret is high-entropy and host-generated, so there is no dictionary to run against it, and the offline-guessing threat that makes a slow KDF necessary for human-chosen passwords does not exist here. The comparison is constant time regardless, for the reason given on ClientAuth::verify_with.
• Anything else, built by SecretHash::custom and verified by a host-supplied SecretVerifier. A host whose policy names argon2id, scrypt or bcrypt, or whose verification happens in an HSM, keeps that dependency in its own tree where it belongs. A custom scheme with NO verifier installed never authenticates: failing closed is the only safe reading of “the server cannot check this credential”.

Implementations

impl SecretHash

pub const SHA256_HEX: &'static str = "sha256-hex"

The scheme identifier for the built-in hash: lower-case hex of the SHA-256 digest of the secret’s UTF-8 bytes. Named on the wire-visible model of a $scheme$ prefix so a host can migrate registrations one at a time and tell which is which.

pub fn sha256(secret: &str) -> Self

Hash secret with the built-in scheme. The result is what the host stores; the secret itself is handed to the client once and never persisted here.

pub fn custom(scheme: impl Into<String>, encoded: impl Into<String>) -> Self

A stored verifier in a scheme this crate does not implement, to be checked by the host’s SecretVerifier. encoded is opaque here: a PHC string, a KMS key handle, whatever the host’s verifier understands.

pub fn scheme(&self) -> &str

The scheme identifier.

pub fn encoded(&self) -> &str

The stored verifier text, in whatever encoding the scheme defines.

pub fn verify( &self, presented: &str, verifier: Option<&dyn SecretVerifier>, ) -> bool

Whether presented is the secret behind this stored verifier, consulting verifier for a scheme this crate does not implement.

The same ORDER OF PREFERENCE, and the same fail-closed rule, as ClientAuth::verify_with, which delegates here: the crate’s own scheme is decided by the crate, an unrecognised one is decided by the host, and an unrecognised one with no host verifier installed never verifies.

Public because a SecretHash is no longer only a client secret. RFC 7592 section 2 makes the registration access token a bearer credential the server has to check on every management request, and it is stored the same one-way way for the same reason (see crate::registration), so it needs the same comparison rather than a second copy of it.

Trait Implementations

impl Clone for SecretHash

fn clone(&self) -> SecretHash

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SecretHash

Hand-written for the same reason as ClientAuth’s: a stored verifier is not a credential a client can present, but it IS the input to an offline attack, so it must not turn up in a host’s logs through {:?}. The SCHEME stays visible, because that is the field an operator needs when auditing which registrations still use a weak or retired one.

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SecretHash

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for SecretHash

impl PartialEq for SecretHash

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for SecretHash

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SecretHash