Documentation
¶
Overview ¶
Package tscrypto implements the Truestamp-specific cryptographic primitives used by proofs: SHA-256 with one-byte domain-separation prefixes (see docs/CRYPTOGRAPHY.md in truestamp-v2 for the prefix registry) and Ed25519 signature verification.
Index ¶
- Constants
- func BuildCompactProofPayload(version byte, typeCode uint16, keyIDHex string, timestampMs uint64, ...) ([]byte, error)
- func BytesToHex(b []byte) string
- func ComputeBlockHash(id, prevHashHex, merkleRootHex, metadataHashHex, signingKeyIDHex string) (string, error)
- func ComputeCommitmentDataHash(jcsBytes []byte) string
- func ComputeCommitmentHash(id, commitmentDataHashHex, ownerID, signingKeyIDHex string) (string, error)
- func ComputeEntropyHash(jcsBytes []byte) string
- func ComputeEntropyMetadataHash(jcsBytes []byte) string
- func ComputeItemHash(id, claimsHashHex, metadataHashHex, signingKeyIDHex string) (string, error)
- func ComputeKeyID(pubkey []byte) string
- func ComputeObservationHash(id, entropyHashHex, metadataHashHex, signingKeyIDHex string) (string, error)
- func ComputeProofHash(version byte, keyIDHex, subjectHashHex string, ...) (string, []byte, error)
- func DecodeCompactMerkleProof(base64urlProof string) ([]string, error)
- func DecodePublicKey(b64 string) (ed25519.PublicKey, error)
- func DomainHash(prefix byte, data []byte) []byte
- func ExtractULIDTimestamp(id string) (time.Time, error)
- func ExtractUUIDv7Timestamp(id string) (time.Time, error)
- func FormatBlockTime(blockID string) string
- func FormatItemTime(itemID string) string
- func HexEqual(a, b string) bool
- func HexToBytes(h string) ([]byte, error)
- func LenPrefix(data []byte) []byte
- func ValidateClaimsHash(hash, hashType string) error
- func VerifyEd25519(hashBytes []byte, signatureB64 string, pubkey ed25519.PublicKey) (bool, error)
- func VerifyMerkleProof(itemHashHex string, proof []string, expectedRootHex string) (bool, error)
Constants ¶
const ( PrefixMerkleLeaf = 0x00 PrefixMerkleInternal = 0x01 PrefixItemClaims = 0x11 PrefixItemMetadata = 0x12 PrefixItemHash = 0x13 PrefixEntropy = 0x21 PrefixEntropyMetadata = 0x22 PrefixObservationHash = 0x23 PrefixBlockMetadata = 0x33 PrefixBlockHash = 0x32 PrefixCommitmentData = 0x34 PrefixCommitmentHash = 0x35 PrefixKeyID = 0x51 PrefixProofHash = 0x61 )
Domain separation prefix bytes per docs/CRYPTOGRAPHY.md.
Variables ¶
This section is empty.
Functions ¶
func BuildCompactProofPayload ¶
func BuildCompactProofPayload(version byte, typeCode uint16, keyIDHex string, timestampMs uint64, subjectHashHex, blockHashHex string, epochRootHexes []string) ([]byte, error)
BuildCompactProofPayload builds the compact proof signature payload and computes SHA256(0x61 || payload). The returned 32-byte hash is what the Ed25519 signature covers.
Byte layout (big-endian throughout):
offset size field 0 1 v (version, uint8) 1 2 t (type code, uint16 BE) 3 4 kid (raw 4 bytes from b.kid hex-decoded) 7 8 ts_ms (timestamp in ms since Unix epoch, uint64 BE) 15 32 subject_hash 47 32 block_hash 79 2 N (epoch root count, uint16 BE) 81 32*N epoch_roots (concatenated, in cx order)
For block-like subjects (t ∈ {10, 11} — plain block and beacon), subject_hash == block_hash — the same 32 bytes appear in both slots. The `t` byte in the payload domain-separates block (t=10) and beacon (t=11) signatures for the same underlying block.
func BytesToHex ¶
BytesToHex encodes bytes to lowercase hex string.
func ComputeBlockHash ¶
func ComputeBlockHash(id, prevHashHex, merkleRootHex, metadataHashHex, signingKeyIDHex string) (string, error)
ComputeBlockHash computes the length-prefixed block hash with domain prefix 0x32. Field order: id, previous_block_hash, merkle_root, metadata_hash, signing_key_id
func ComputeCommitmentDataHash ¶
ComputeCommitmentDataHash computes SHA256(0x34 || JCS(commitment_data)).
func ComputeCommitmentHash ¶
func ComputeCommitmentHash(id, commitmentDataHashHex, ownerID, signingKeyIDHex string) (string, error)
ComputeCommitmentHash computes the length-prefixed commitment hash with domain prefix 0x35. Field order: id, commitment_data_hash, owner_id, signing_key_id
func ComputeEntropyHash ¶
ComputeEntropyHash computes SHA256(0x21 || JCS(entropy_data)).
func ComputeEntropyMetadataHash ¶
ComputeEntropyMetadataHash computes SHA256(0x22 || JCS(metadata)).
func ComputeItemHash ¶
ComputeItemHash computes the length-prefixed item hash with domain prefix 0x13. Field order: id, claims_hash, metadata_hash, signing_key_id
func ComputeKeyID ¶
ComputeKeyID derives key_id from public key: truncate4(SHA256(0x51 || pubkey)).
func ComputeObservationHash ¶
func ComputeObservationHash(id, entropyHashHex, metadataHashHex, signingKeyIDHex string) (string, error)
ComputeObservationHash computes the length-prefixed observation hash with domain prefix 0x23. Field order: id, entropy_hash, metadata_hash, signing_key_id This mirrors ComputeItemHash but uses prefix 0x23 for entropy observations.
func ComputeProofHash ¶
func ComputeProofHash(version byte, keyIDHex, subjectHashHex string, blockHashes, commitmentHashes []string) (string, []byte, error)
ComputeProofHash builds the binary proof_hash payload and computes SHA256(0x61 || payload). Returns both the hex hash and raw hash bytes (raw needed for Ed25519 verification).
func DecodeCompactMerkleProof ¶
DecodeCompactMerkleProof decodes a compact base64url-encoded Merkle proof into the standard ["l:hex", "r:hex", ...] format.
Binary format:
- Byte 0: depth (number of proof steps, 0-64)
- Next ceil(depth/8) bytes: direction bitfield (little-endian) bit=0 means left sibling ("l:"), bit=1 means right sibling ("r:")
- Remaining: depth * 32 bytes of raw sibling hashes
func DecodePublicKey ¶
DecodePublicKey decodes a base64-encoded Ed25519 public key.
func DomainHash ¶
DomainHash computes SHA256(prefix_byte || data).
func ExtractULIDTimestamp ¶
ExtractULIDTimestamp extracts the millisecond timestamp from a ULID string.
func ExtractUUIDv7Timestamp ¶
ExtractUUIDv7Timestamp extracts the millisecond timestamp from a UUIDv7 string.
func FormatBlockTime ¶
FormatBlockTime extracts and formats the timestamp from a UUIDv7 block ID. Returns "unknown" if extraction fails.
func FormatItemTime ¶
FormatItemTime extracts and formats the timestamp from a ULID item ID. Returns "unknown" if extraction fails.
func HexToBytes ¶
HexToBytes decodes a hex string to bytes. Returns empty slice for empty input.
func ValidateClaimsHash ¶
ValidateClaimsHash checks that a hex hash string has the correct length for the given hash type.
func VerifyEd25519 ¶
VerifyEd25519 verifies an Ed25519 signature over a hash.
Types ¶
This section is empty.
Source Files