HashValue Struct
Definition
- Namespace
- Bodu.Security.Cryptography
- Assembly
- Bodu.Security.Cryptography.dll
- Package
- Bodu.Security.Cryptography 1.2.0
- Source
- HashValue.cs
Represents the immutable output of a hash operation, with strict hexadecimal parsing, common text formattings, and explicit fixed-time comparison.
public readonly struct HashValue : IEquatable<HashValue>- Implements
- Inherited Members
- Extension Methods
Examples
// Wrap a freshly computed digest, then format it for logging or storage.
HashValue digest = HashValue.FromBytes(SHA256.HashData(payload));
string hex = digest.ToHexString(); // lowercase, e.g. "e3b0c442..."
// Compare the digest against an expected value in fixed time before trusting the payload.
HashValue expected = HashValue.ParseHex("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
if (!digest.FixedTimeEquals(expected))
throw new CryptographicException("Digest mismatch.");Remarks
HashValue carries the digest bytes by defensive copy: the value is unaffected by later mutation of the source buffer, and no member exposes the internal storage as a mutable array.
The default instance (default(HashValue)) is the empty value: Length is 0,
IsEmpty is true, and it compares equal to
FromBytes(ReadOnlySpan<byte>) over an empty span.
Equals(HashValue) compares content in constant time via FixedTimeEquals(ReadOnlySpan<byte>, ReadOnlySpan<byte>), so even the ordinary equality operators are safe when the comparison is security-relevant - for example validating a received digest against a locally computed one. FixedTimeEquals(HashValue) remains available and behaves identically, making the intent explicit at the call site.
Properties
IsEmpty
Gets a value indicating whether the hash value is empty.
public bool IsEmpty { get; }Property Value
Length
Gets the number of bytes in the hash value.
public int Length { get; }Property Value
- int
The digest length in bytes, or
0for the empty value.
Methods
AsSpan()
Returns a read-only view over the digest bytes.
public ReadOnlySpan<byte> AsSpan()Returns
- ReadOnlySpan<byte>
A read-only span over the value; empty for the empty value.
Equals(HashValue)
Determines whether this hash value equals another.
public bool Equals(HashValue other)Parameters
otherHashValueThe hash value to compare against.
Returns
Remarks
The byte comparison is constant-time in content - it runs through FixedTimeEquals(ReadOnlySpan<byte>, ReadOnlySpan<byte>), so its duration depends only on the operand length, not on where the bytes first differ. A length mismatch returns false immediately (the length is not secret). FixedTimeEquals(HashValue) remains available and behaves identically.
Equals(object?)
Determines whether this hash value equals the specified object.
public override bool Equals(object? obj)Parameters
objobjectThe object to compare against.
Returns
FixedTimeEquals(HashValue)
Compares this hash value to another in fixed time.
public bool FixedTimeEquals(HashValue other)Parameters
otherHashValueThe hash value to compare against.
Returns
Remarks
Built on FixedTimeEquals(ReadOnlySpan<byte>, ReadOnlySpan<byte>): the comparison time depends only on the length of the operands, not on their content. A length mismatch returns false immediately, so the lengths themselves are not concealed.
FromBytes(ReadOnlySpan<byte>)
Creates a HashValue from the provided bytes.
public static HashValue FromBytes(ReadOnlySpan<byte> value)Parameters
valueReadOnlySpan<byte>The digest bytes to copy. An empty span yields the empty value.
Returns
GetHashCode()
Returns a hash code computed over the digest bytes.
public override int GetHashCode()Returns
- int
A hash code consistent with Equals(HashValue).
ParseHex(string)
Parses a strict hexadecimal string into a HashValue.
public static HashValue ParseHex(string text)Parameters
textstringThe hexadecimal text. Both uppercase and lowercase digits are accepted.
Returns
Remarks
Parsing is strict: whitespace, separators, and 0x prefixes are rejected. An empty string parses to the
empty value.
Exceptions
- ArgumentNullException
textis null.- FormatException
texthas odd length or contains a character that is not an ASCII hexadecimal digit.
ToArray()
Copies the digest bytes into a new array.
public byte[] ToArray()Returns
- byte[]
A new array containing the digest bytes; an empty array for the empty value.
ToBase64String()
Formats the hash value as a Base64 string.
public string ToBase64String()Returns
ToHexString()
Formats the hash value as a lowercase hexadecimal string.
public string ToHexString()Returns
ToString()
Returns the lowercase hexadecimal representation of the hash value.
public override string ToString()Returns
- string
The same text as ToHexString().
Remarks
Hash values are not secrets, so the digest content is intentionally included in the string representation.
TryParseHex(string?, out HashValue)
Attempts to parse a strict hexadecimal string into a HashValue.
public static bool TryParseHex(string? text, out HashValue result)Parameters
textstringThe hexadecimal text, or null.
resultHashValueWhen this method returns true, the parsed value; otherwise the empty value.
Returns
Operators
operator ==(HashValue, HashValue)
Determines whether two hash values are equal.
public static bool operator ==(HashValue left, HashValue right)Parameters
Returns
operator !=(HashValue, HashValue)
Determines whether two hash values are not equal.
public static bool operator !=(HashValue left, HashValue right)Parameters
Returns
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |