| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
SDJWT.Internal.Digest
Description
Hash computation and verification for SD-JWT disclosures (low-level).
This module provides functions for computing digests of disclosures and verifying that digests match disclosures. All three hash algorithms required by RFC 9901 are supported: SHA-256, SHA-384, and SHA-512.
Usage
This module contains low-level hash and digest utilities that are typically used internally by other SD-JWT modules. Most users should use the higher-level APIs in:
Issuer- For issuers (handles digest computation internally)Holder- For holders (handles digest computation internally)Verifier- For verifiers (handles digest verification internally)
These utilities may be useful for:
- Advanced use cases requiring custom digest computation
- Library developers building on top of SD-JWT
- Testing and debugging
Synopsis
- computeDigest :: HashAlgorithm -> EncodedDisclosure -> Digest
- computeDigestText :: HashAlgorithm -> EncodedDisclosure -> Text
- verifyDigest :: HashAlgorithm -> Digest -> EncodedDisclosure -> Bool
- parseHashAlgorithm :: Text -> Maybe HashAlgorithm
- defaultHashAlgorithm :: HashAlgorithm
- hashAlgorithmToText :: HashAlgorithm -> Text
- extractDigestsFromValue :: Value -> Either SDJWTError [Digest]
- extractDigestStringsFromSDArray :: Object -> [Text]
Documentation
computeDigest :: HashAlgorithm -> EncodedDisclosure -> Digest Source #
Compute digest of a disclosure.
The digest is computed over the US-ASCII bytes of the base64url-encoded disclosure string (per RFC 9901). The bytes of the hash output are then base64url encoded to produce the final digest.
This follows the convention in JWS (RFC 7515) and JWE (RFC 7516).
Note: RFC 9901 requires US-ASCII encoding. Since base64url strings contain only ASCII characters (A-Z, a-z, 0-9, -, _), UTF-8 encoding produces identical bytes to US-ASCII for these strings.
computeDigestText :: HashAlgorithm -> EncodedDisclosure -> Text Source #
Compute digest text (string) from a disclosure.
Convenience function that computes the digest and extracts the text.
Equivalent to unDigest . computeDigest.
verifyDigest :: HashAlgorithm -> Digest -> EncodedDisclosure -> Bool Source #
Verify that a digest matches a disclosure.
Computes the digest of the disclosure using the specified hash algorithm
and compares it to the expected digest using constant-time comparison.
Returns True if they match.
SECURITY: Uses constant-time comparison to prevent timing attacks. This is critical for cryptographic verification operations.
parseHashAlgorithm :: Text -> Maybe HashAlgorithm Source #
Parse hash algorithm from text identifier.
Parses hash algorithm names from the _sd_alg claim.
Returns Nothing if the algorithm is not recognized.
defaultHashAlgorithm :: HashAlgorithm Source #
Default hash algorithm (SHA-256 per RFC 9901).
When the _sd_alg claim is not present in an SD-JWT, SHA-256 is used as the default hash algorithm.
hashAlgorithmToText :: HashAlgorithm -> Text Source #
Convert hash algorithm to text identifier.
Returns the hash algorithm name as specified in RFC 9901: "sha-256", "sha-384", or "sha-512".
extractDigestsFromValue :: Value -> Either SDJWTError [Digest] Source #
Recursively extract digests from JSON value (_sd arrays and array ellipsis objects).
This function extracts all digests from a JSON value by:
- Looking for _sd arrays in objects and extracting string digests
- Looking for {"...": "digest"} objects in arrays
- Recursively processing nested structures
Used for extracting digests from SD-JWT payloads and disclosure values.
Per RFC 9901 Section 4.2.4.1, _sd arrays MUST contain only strings (digests). Returns an error if non-string values are found in _sd arrays.
extractDigestStringsFromSDArray :: Object -> [Text] Source #
Extract digest strings from an _sd array in a JSON object.
This helper function extracts string digests from the _sd array field of a JSON object. Returns an empty list if _sd is not present or not an array. This is a convenience function for cases where you only need the digest strings, not the full Digest type.