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 text contract
Section titled “The text contract”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");// ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015adFor 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 fingerprint concept
Section titled “A fingerprint concept”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.
A bearer token verifier
Section titled “A bearer token verifier”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.
Security boundaries
Section titled “Security boundaries”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.
Test it exactly
Section titled “Test it exactly”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.