---
title: Cratis Fundamentals SHA-256 hashing
editUrl: https://github.com/Cratis/Fundamentals/edit/main/Documentation/csharp/generating-values/sha-256.md
description: GenerateValue.Sha256 creates a deterministic text fingerprint or a verifier for high-entropy tokens, but is not a password hash or anonymization tool.
lastUpdated: 2026-11-05T00:00:00.000Z
---


`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

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.

```csharp
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 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:

```csharp
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

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

```csharp
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:

```csharp
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](/fundamentals/csharp/generating-values/secrets-and-tokens/) for generation, audit markings and storage rules.

## 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

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](/fundamentals/csharp/generating-values/testing/) explains how to separate exact-value assertions like
these from tests of random generation.
