Interface TraceCryptoProvider


public interface TraceCryptoProvider
The crypto operations of TRACE ingestion: canonicalization, key parsing, signature verification with content digest, and receipt hashing. Select an implementation with TraceCryptoImpl.

Scopes. The Ed25519 signature covers the JCS (RFC 8785) form of the record without its top-level signature member. The content_digest covers the JCS form of the complete record, signature included.

Receipt hash. "sha256:" + hex(SHA-256(JCS(m))) where m has exactly these members: receipt_profile (TraceHashes.RECEIPT_PROFILE), evidence_domain_id, receipt_sequence (JSON integer), received_at (RFC 3339 UTC string with three fraction digits, see TraceTime), producer_id, record_id, content_digest and prev_receipt_hash.

Thread safety. Implementations are @ApplicationScoped singletons. Every method is safe for concurrent use.

Failures are reported as TraceCryptoException; messages carry no key material, signature bytes or record content.

Author:
Yuriy Movchan
  • Method Details

    • type

      Returns:
      the type this provider implements
    • requireAvailable

      void requireAvailable()
      Throws:
      TraceCryptoException - with reason crypto_unavailable when the provider cannot perform Ed25519 verification
    • isAvailable

      boolean isAvailable()
      Returns:
      true when requireAvailable() would not throw
    • describe

      String describe()
      Returns:
      one line for the startup log; never contains secrets
    • canonicalize

      String canonicalize(com.fasterxml.jackson.databind.JsonNode node)
      Returns:
      the RFC 8785 canonical text of node
      Throws:
      TraceCryptoException - with reason canonicalization_failed
    • parseKey

      Builds a verification key from a public Ed25519 JWK (kty, crv, x).
      Throws:
      TraceCryptoException - with a jwk_* reason, invalid_key or crypto_unavailable
    • verifyAndDigest

      String verifyAndDigest(TraceSignedRecord record, byte[] signature, TraceVerificationKey key)
      Verifies signature (Ed25519) over the JCS form of the record without its top-level signature member and computes the content digest.
      Returns:
      content_digest: "sha256:" + hex(SHA-256(JCS(complete record)))
      Throws:
      TraceCryptoException - with reason signature_mismatch, canonicalization_failed or crypto_unavailable
    • receiptHash

      String receiptHash(String domainId, long receiptSequence, long receivedAtMs, String producerId, String recordId, String contentDigest, String prevReceiptHash)
      Returns:
      the receipt hash for one receipt-chain position (see the class description for the member set)
      Throws:
      TraceCryptoException - with reason invalid_receipt_input when an input cannot be a receipt position