scitt -- Supply Chain Integrity, Transparency, and Trust (IETF SCITT)#

Native OCaml implementation of draft-ietf-scitt-architecture. Provides Signed Statements, Receipts with Merkle inclusion proofs, and Transparent Statements. Uses COSE for signing and supports pluggable Verifiable Data Structure (VDS) backends.

This repository provides three opam packages:

• scitt -- core SCITT library with built-in RFC 9162 SHA-256 binary Merkle tree
• scitt-atp -- AT Proto MST backend for SCITT (keyed lookup via Merkle Search Tree)
• atp-lexicon-scitt -- AT Protocol lexicon types and Jsont codecs for SCITT records

Installation#

Install the core package with opam:

$ opam install scitt

Optional packages provide the AT Proto backend and lexicon types:

$ opam install scitt-atp          # for AT Proto MST backend
$ opam install atp-lexicon-scitt  # for AT Proto lexicon types

If opam cannot find the packages, they may not yet be released in the public opam-repository. Add the overlay repository, then install the packages you need:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install scitt

Quick Start#

let run ~clock ~ts_private_key ~ts_public_key ~issuer_key ~issuer_public_key
    ~sbom_json =
  (* Create a transparency service with RFC 9162 VDS. *)
  let vds = Scitt.Vds_rfc9162.in_memory () in
  let ts =
    Scitt.Transparency_service.v ~service_id:"my-ts" ~vds
      ~algorithm:Cose.Algorithm.ES256
      ~sign:(Scitt.Signer.of_key ts_private_key)
      clock
  in
  (* Register a signed statement. *)
  let statement =
    Scitt.Statement.v ~issuer:"did:web:example.com" ~subject:"sha256:abcdef..."
      ~content_type:"application/spdx+json" ~payload:sbom_json
  in
  let signed =
    match Scitt.Signed_statement.sign ~key:issuer_key statement with
    | Ok s -> s
    | Error e -> Fmt.failwith "sign: %a" Scitt.pp_error e
  in
  let receipt =
    match
      Scitt.Transparency_service.register ts ~issuer_key:issuer_public_key
        signed
    with
    | Ok r -> r
    | Error e -> Fmt.failwith "register: %a" Scitt.pp_error e
  in
  (* Create and verify a transparent statement. *)
  let transparent = Scitt.Transparent_statement.v signed [ receipt ] in
  match
    Scitt.Transparent_statement.verify
      ~ts_keys:(fun ~service_id:_ -> Some ts_public_key)
      ~issuer_key:issuer_public_key transparent
  with
  | Ok (stmt, _level, _summary) ->
      Fmt.pr "Verified: %s@." (Scitt.Statement.issuer stmt)
  | Error e -> Fmt.epr "Failed: %a@." Scitt.pp_error e

API Overview#

• Scitt.Statement -- create statements with issuer, subject, content type, and payload
• Scitt.Signed_statement -- COSE Sign1 envelopes for statements
• Scitt.Receipt -- Merkle inclusion proofs signed by a Transparency Service
• Scitt.Transparent_statement -- bundle a signed statement with receipts; verify offline
• Scitt.Transparency_service -- register statements and issue receipts
• Scitt.Vds_rfc9162 -- built-in RFC 9162 VDS (in-memory or SQLite-backed)
• Scitt.Signer -- pluggable signing (in-process key or HSM/KMS)

References#

• draft-ietf-scitt-architecture -- SCITT Architecture
• RFC 9162 -- Certificate Transparency v2
• RFC 9052 -- COSE Structures

License#

MIT