Skip to content

SAIF.NetCore.SystemHash operations and processes

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under operations/.

Operation catalog

Operation Intent Trigger Inputs Outputs Rules
Compute a salted system hash Issue a time-stamped, randomized identity credential for a named system. Caller needs a credential for a SystemType/name pair; used directly, and internally by Get. type (SystemType), systemName (string) Salted hash string (~120 chars), regenerated and randomized per call BR-SH-01, BR-SH-02, BR-SH-03, BR-SH-04
Compute an unsalted system hash on demand Produce the canonical identity hash a validator can compare against a de-salted credential. Validating service needs the identity hash for comparison (external; no in-repo caller). type, systemName Deterministic 44-char Base64 SHA-256 string BR-SH-01, BR-SH-02, BR-SH-05
Get the current application's system hash Resolve the calling application's own identity and issue a credential for it. Application/library needs its own credential (e.g., for a secure-setting request). type Salted hash for "{assemblyName}-{(int)type}" BR-SH-06, BR-SH-07
Resolve the identity assembly Determine which assembly's simple name identifies the current system. Called internally by Get, or directly by a caller that wants to inspect the resolved assembly. none (uses constructor-injected _assembly if present) Assembly BR-SH-06
Compute the identity hash Produce the deterministic SHA-256/Base64 digest shared by both the salted and unsalted operations. Called internally by ComputeHash and ComputeHashNow. type, systemName 44-char Base64 SHA-256 string BR-SH-01, BR-SH-02
De-salt and validate credential lifetime Recover the identity hash from a previously issued credential and reject it if expired or not yet valid. Validating service receives a salted credential (external; exercised only by this library's unit tests in-repo). systemHashValue, expireSeconds, nowBufferSeconds Unsalted 44-char hash, or SystemHashExpiredException BR-SH-03, BR-SH-08, BR-SH-09, BR-SH-10

Process flow diagram

The following diagram visualizes the primary issue-and-validate round trip for a system-hash credential. The simplified acceptance window shown below holds when nowBufferSeconds is any value other than int.MinValue and when createDate.AddSeconds(expireSeconds) stays within the representable DateTime range. If that date shift falls outside the DateTime range, DateTime.AddSeconds throws ArgumentOutOfRangeException, and the exception propagates uncaught rather than becoming SystemHashExpiredException. The nowBufferSeconds * -1 negation never throws: the project does not enable overflow checking and the method uses no checked block, so integer arithmetic is unchecked. At int.MinValue the negation wraps silently back to int.MinValue. Both bound checks then shift now back by about 68 years. The method does not special-case this value in code, but because both arms of the window check then collapse onto the same shifted value, the diagram shows it as its own comparison, shiftedNow = now.AddSeconds(int.MinValue); shiftedNow >= createDate && shiftedNow < expires, rather than the simplified symmetric window used for every other nowBufferSeconds. A current credential still fails that shifted window and is rejected with SystemHashExpiredException, but a credential with a createDate roughly 68+ years in the past, combined with a sufficiently large expireSeconds, can satisfy the shifted window and be accepted instead. See De-salt and validate credential lifetime for the literal evaluation order.

flowchart TD
    Start([Caller needs a credential]) --> ResolveAssembly[Resolve identity assembly]
    ResolveAssembly --> ComputeIdentity["Compute identity hash: SHA-256/Base64 of systemName-ordinal"]
    ComputeIdentity --> Salt[Salt with SaltShaker DateTime.Now]
    Salt --> Issue(["Return salted credential ~120 chars"])
    Issue --> Present[Caller presents credential to external validator]
    Present --> Desalt["De-salt: SaltShaker.BlandHash recovers createDate"]
    Desalt --> Malformed{Well-formed HashUtil format?}
    Malformed -->|No| BclError(["BCL exception: ArgumentOutOfRangeException /<br>FormatException / NullReferenceException"])
    Malformed -->|Yes| Domain{"createDate + expireSeconds<br>within DateTime range?"}
    Domain -->|No| ArithError(["Uncaught ArgumentOutOfRangeException<br>from DateTime.AddSeconds"])
    Domain -->|Yes| MinVal{"nowBufferSeconds<br>== int.MinValue?"}
    MinVal -->|Yes, wraps to int.MinValue| MinValWindow{"shiftedNow = now.AddSeconds(int.MinValue);<br>shiftedNow >= createDate && shiftedNow < expires?"}
    MinVal -->|No| Window{"createDate within<br>(now − abs(buffer) − expireSeconds, now + abs(buffer)]?"}
    Window -->|No| Expired([Throw SystemHashExpiredException])
    Window -->|Yes| ReturnHash[Return unsalted hash]
    MinValWindow -->|Yes| ReturnHash
    MinValWindow -->|No| Expired
    ReturnHash --> Compare{Validator compares against authorized/ComputeHashNow hash}
    Compare -->|Match| Authorized([Credential accepted])
    Compare -->|No match| Rejected([Credential rejected])

Failure and edge-case behavior

  • A malformed or tampered credential causes SaltShaker.BlandHash to raise ArgumentOutOfRangeException, FormatException, or NullReferenceException — not SystemHashExpiredException — because RemoveSystemHashSaltAndValidateLifetime does not wrap the de-salt call in a try/catch (BR-SH-09).
  • A SystemType ordinal change in SAIF.NetCore.ServiceContracts silently changes the identity hash for every affected system type without any error at either the issuing or validating side (BR-SH-02).
  • Calling Get() or new SystemHashService() without an injected assembly most likely resolves the identity to the SAIF.NetCore.SystemHash assembly itself rather than the consuming application, since GetAssembly()'s caller is Get itself — unless the JIT inlines the call.*
  • RemoveSystemHashSaltAndValidateLifetime never establishes identity on its own; a validator that does not independently compare the returned hash against an authorized value accepts any fresh, well-formed credential (BR-SH-10).
  • There are no in-repo production callers of ComputeHashNow or RemoveSystemHashSaltAndValidateLifetime; both are intended for the external Environment API / CryptoAPI validating service.*

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • src/SAIF.NetCore.SystemHash/SAIF.NetCore.SystemHash/SAIF.NetCore.SystemHash/SystemHashService.cs
  • src/SAIF.NetCore.SystemHash/SAIF.NetCore.SystemHash/SAIF.NetCore.SystemHash.Tests/SystemHashTests.cs