Skip to content

Cratis Fundamentals SHA-256 hashing

GenerateValue.Sha256(string value) in Cratis Fundamentals computes a deterministic fingerprint of text or a stored verifier for a server-generated bearer token with at least 128 bits of entropy. It returns the same digest for the same exact text. Hashing adds no randomness or entropy and does not encrypt or anonymize the input.

The result is the SHA-256 digest specified by FIPS 180-4, rendered as exactly 64 lowercase hexadecimal characters. C# strings use UTF-16. The helper checks that the text is well-formed, then encodes it as UTF-8 without inserting a byte-order mark (BOM), normalizing Unicode or folding case. A literal leading U+FEFF is preserved and hashed.

Empty text is valid. null throws ArgumentNullException; an unpaired UTF-16 surrogate, an incomplete character encoding, throws InvalidSha256Input without including the input in its message.

using Cratis.Concepts;
var digest = GenerateValue.Sha256("abc");
// ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

For a token generated as base64url text, hash that text rather than the bytes obtained by decoding it. Use the same representation when the token is presented later. If your domain treats different text forms as equivalent, canonicalize them before hashing: e\u0301 and \u00e9 otherwise have different digests, as do jane@example.com and Jane@example.com.

A digest depends on an existing value, so give the concept a From(value) factory instead of an IGeneratable contract or New() method:

using Cratis.Concepts;
public record ContentFingerprint(string Value) : ConceptAs<string>(Value)
{
public static ContentFingerprint From(string value) => new(GenerateValue.Sha256(value));
}

ContentFingerprint.From lets you compare content by its digest, but a fingerprint does not prove who produced the content. Anyone who knows the input can recompute it. When you need to authenticate content with a secret key, use a keyed construction such as a hash-based message authentication code (HMAC) instead of this unkeyed hash.

For server-generated tokens with at least 128 bits of entropy, return the raw token once and persist only its digest:

using Cratis.Concepts;
public record TokenDigest(string Value) : ConceptAs<string>(Value)
{
public static TokenDigest From(string token) => new(GenerateValue.Sha256(token));
}

At issuance, generate var token = GenerateValue.Bytes(32); and persist TokenDigest.From(token). Return token once to the caller. Never log it, include it in events, or keep it as recoverable plaintext. On presentation, derive a digest from the supplied token text and compare it with the stored digest.

For a direct comparison, decode the hexadecimal digests into equal-length byte arrays and use CryptographicOperations.FixedTimeEquals. Normal string equality is not a constant-time comparison:

using System.Security.Cryptography;
// storedDigest and presentedDigest are TokenDigest values containing validated 64-character hex digests.
var matches = CryptographicOperations.FixedTimeEquals(
Convert.FromHexString(storedDigest.Value),
Convert.FromHexString(presentedDigest.Value));

Lookup by digest index is not constant-time. That pattern is acceptable only for server-generated tokens with at least 128 bits of entropy, where an attacker cannot feasibly enumerate the token space. It is not a way to verify guessable secrets. Expire and rotate tokens; the digest is not an authorization decision. See Secrets and tokens for generation, audit markings and storage rules.

SHA-256 is fast and unsalted, which makes passwords, PINs and short codes vulnerable to guessing. Use a password hashing function with a salt and a slow algorithm for those inputs. Hashing does not make a weak token harder to guess.

A digest cannot replace a secret whose original value is needed later. For example, a TOTP secret is used to compute time-based one-time passwords. Keep it and other recoverable key material in protected storage.

A digest of personal data is still personal data. Common email addresses, phone numbers and other guessable values can be enumerated, and equal digests link repeated values. This helper is not an anonymization tool.

The implementation clears its temporary UTF-8 buffer in a finally block with CryptographicOperations.ZeroMemory before returning any rented buffer to the pool. Input and output strings cannot be erased; keep them out of logs and permanent event payloads.

Assert the complete expected digest for fixed text; no seed or clock is needed. Include empty text and the Unicode forms your application accepts. If you canonicalize input, test that rule too so equivalent inputs reach the helper as the same text. Testing explains how to separate exact-value assertions like these from tests of random generation.