TRACE Prototype#

The TRACE Prototype has been developed as an end-to-end implementation to facilitate requirements discussions. It consists of the following:

server.trace-poc.xyz#

This is a running instance of the trace-prototype server for use with the command line interface and to demonstrate GitHub actions integration. It is a Docker-based implementation that uses repo2docker to build a container image used to execute runs.

The website provides includes the following:

  • TRACE Server ID: Unique identifier for this server (URI)

  • TRACE Server Fingerprint: GPG public key for this server

Submitting a Run#

To submit a run to server.trace-poc.xyz, you must first intall the trace-prototype client:

$ pip install git+https://github.com/transparency-certified/trace-prototype

Clone the sample-trace-workflow repository:

$ git clone https://github.com/transparency-certified/sample-trace-workflow
$ cd sample-trace-workflow

Submit the run:

$ trace-poc submit --entrypoint "run.sh" --container-user rstudio \
  --target-repo-dir "/home/rstudio" --trace-server https://server.trace-poc.xyz .

This will create a new entry on the server at https://server.trace-poc.xyz/.

Inspecting the TRO#

For each TRO generated by the server, it creates:

  • TRS Signature (.sig): Digest of the contents of the TRO declaration signed using the TRS private key

  • TRO Declaration (.jsonld): JSON-LD document containing the unique ID and public key of the TRS that produced the TRO, claims about the capabilities of the TRS, and a individual artifacts that are part of the TRO composition.

  • TRO Composition (.zip): Comprises all of the digital artifacts (potentially unpersisted) that the TRO declaration describes.

  • Trusted Timestamp (.tsr): A signed timestamp of the TRO declaration and TRS signature provided by a timestamp authority.

For more information, see the Conceptual Model section.

To verify the TRS signature, first extract the public key from the TRO declaration and import it using GPG:

uuid=<541e03e5-ca1f-4fc3-9ed7-3b93be56e02b>
$ cat ${uuid}.jsonld | jq -r '."@graph"[0]."trov:wasAssembledBy"."trov:publicKey"' &> trs.asc

$ gpg --import trs.asc
gpg: key 0x5651D2C6E0F242A7: public key "TRACE POC (TRACE System Proof of Concept) <trace-poc@gmail.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1

$ gpg --edit-key 5651D2C6E0F242A7
...
gpg> trust
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)

  1 = I don't know or won't say
  2 = I do NOT trust
  3 = I trust marginally
  4 = I trust fully
  5 = I trust ultimately
  m = back to the main menu

Your decision? 5

$ gpg --verify ${uuid}.sig ${uuid}.jsonld
gpg: Signature made Tue May  9 11:20:18 2023 EDT
gpg:                using RSA key 8771159FF4E3647B997CC5445651D2C6E0F242A7
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: Good signature from "TRACE POC (TRACE System Proof of Concept) 
     <trace-poc@gmail.com>" [ultimate]

To view the trusted timestamp information:

openssl ts -reply -in ${uuid}.tsr -text

To verify the trusted timestamp:

$ wget https://freetsa.org/files/tsa.crt
$ wget https://freetsa.org/files/cacert.pem

$ echo -n "{\"tro_declaration\": \"$(sha512sum ${uuid}.jsonld | \
  cut -f1 -d ' ')\", \"trs_signature\": \"$(sha512sum ${uuid}.sig | \
  cut -f1 -d ' ')\"}" > $uuid.ts

$ openssl ts -verify -data $uuid.ts -in $uuid.tsr -CAfile cacert.pem -untrusted tsa.crt
Verification: OK

GitHub Action#

The sample-trace-workflow repository includes a GitHub Action workflow that demonstrates using the TRACE prototype to create a TRO on push.