diff --git a/content/developers/developer-patterns/scitt-api/index.md b/content/developers/developer-patterns/scitt-api/index.md index 90b4e940c..7a218d91c 100644 --- a/content/developers/developer-patterns/scitt-api/index.md +++ b/content/developers/developer-patterns/scitt-api/index.md @@ -1,7 +1,7 @@ --- title: "Quickstart: SCITT Statements (Preview)" description: "Getting Started with SCITT: creating a collection of statements (Preview)" -lead: "Push a collection of Statements using SCITT APIs" +lead: "How to push a collection of Statements using SCITT APIs" date: 2021-06-09T13:49:35+01:00 lastmod: 2021-06-09T13:49:35+01:00 draft: false @@ -28,7 +28,7 @@ This includes previously registered statements, and newly registered statements This quickstart will: 1. create, or use an existing a key to sign a collection of statements about an artifact -1. create and register an statement for the artifact +1. create and register a statement for the artifact 1. create and register an attestation for the artifact 1. query a collection of statements about the artifact @@ -44,9 +44,8 @@ The Quickstart uses existing samples and scripts to focus on the SCITT APIs. Clone the [DataTrails SCITT Examples](https://github.com/datatrails/datatrails-scitt-samples) repository to copy those files to your environment. - ```shell - git clone https://github.com/datatrails/datatrails-scitt-samples.git - + ```bash + git clone https://github.com/datatrails/datatrails-scitt-samples.git && \ cd datatrails-scitt-samples ``` @@ -54,19 +53,28 @@ Clone the [DataTrails SCITT Examples](https://github.com/datatrails/datatrails-s 1. Create a Python Virtual Environment for the sample scripts and install the dependencies - ```shell + ```bash python -m venv venv && \ source venv/bin/activate && \ + pip install --upgrade pip && \ pip install -r requirements.txt ``` 1. To ease copying and pasting commands, update any variables to fit your environment - ```shell - ISSUER=sample.sysnation.dev - SIGNING_KEY=my-signing-key.pem - SIGNED_STATEMENT_FILE=signed-statement.txt - ``` + ```bash + # your identity + ISSUER="sample.synsation.io" + + # signing key to sign the SCITT Statements + SIGNING_KEY="my-signing-key.pem" + + # File representing the signed statement to be registered + SIGNED_STATEMENT_FILE="signed-statement.txt" + + # Feed ID, used to correlate a collection of statements about an artifact + FEED="my-product-id" + ``` 1. Create a [bearer_token](/developers/developer-patterns/getting-access-tokens-using-app-registrations) stored as a file, in a secure local directory with 0600 permissions. @@ -76,55 +84,54 @@ Clone the [DataTrails SCITT Examples](https://github.com/datatrails/datatrails-s If you already have a COSE Key, skip ahead to [Generating a Payload](#generating-a-payload) {{< /note >}} -There are multiple methods to create a signed statement, for methods other than using a basic signing key, see: _(TODO: link to supporting docs) -_(TODO: link to supported DataTrails Signing Keys\)_
For the Quickstart, create a testing [COSE Key](https://cose-wg.github.io/cose-spec/#key-structure) which DataTrails will cryptographically validate upon registration - ```shell + ```bash openssl ecparam -name prime256v1 -genkey -out $SIGNING_KEY ``` ## Generating a Payload -In the samples we assume the statement is a json document, e.g: - -```shell -cat > payload.json < payload.json <}} + Note: The current DataTrails payload must be encased in a json object: - ```shell - SIGNED_STATEMENT=`cat $SIGNED_STATEMENT_FILE` - OPERATION_ID=$(curl -X POST -H @$HOME/.datatrails/bearer-token.txt -d \ - '{"statement":"'$SIGNED_STATEMENT'"}' \ - https://app.datatrails.ai/archivist/v1/publicscitt/entries | jq -r .operationID) + `{"statement":""}` + + This will be updated to match the SCITT API ([SCRAPI](https://github.com/ietf-scitt/draft-birkholz-scitt-scrapi/)) in a future release. + {{< /note >}} + + ```bash + OPERATION_ID=$(curl -X POST -H @$HOME/.datatrails/bearer-token.txt \ + -d '{"statement":"'$(cat $SIGNED_STATEMENT_FILE)'"}' \ + https://app.datatrails.ai/archivist/v1/publicscitt/entries \ + | jq -r .operationID) ``` -1. Monitor for the Statement to be anchored +1. Monitor for the Statement to be anchored. Once `"status": "succeeded"`, proceed to the next step ```shell curl -H @$HOME/.datatrails/bearer-token.txt \ @@ -142,9 +149,11 @@ EOF 1. Retrieve a SCITT Receipt - ```shell + ```bash + curl -H @$HOME/.datatrails/bearer-token.txt \ - https://app.datatrails.ai/archivist/v1/publicscitt/entries/$ENTRY_ID/receipt | jq + https://app.datatrails.ai/archivist/v1/publicscitt/entries/$ENTRY_ID/receipt \ + -o receipt.cbor ``` ## Retrieve Statements for the Artifact @@ -154,12 +163,14 @@ By querying the series of statements, consumers can verify who did what and when 1. Query DataTrails for the collection of statements - ```shell + ```bash curl -H @$HOME/.datatrails/bearer-token.txt \ https://app.datatrails.ai/archivist/v2/publicassets/-/events?event_attributes.feed_id=$FEED | jq ``` -To filter on specific content types, such as what SBOMs have been registered, or which issuers have made statements, see \ +{{< note >}} +Coming soon: Filter on specific content types, such as what SBOMs have been registered, or which issuers have made statements. +{{< /note >}} ## Summary