Merge pull request #721 from datatrails/steve/scitt-doc-updates

SCITT API Cleanup

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,29 +44,37 @@ 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
   ```
 
 ## Environment Configuration
 
 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\)_<br>
 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 <<EOF
-{
-    "author": "fred",
-    "title": "my biography",
-    "reviews": "mixed"
-}
-EOF
-```
-
-1. Create a Feed ID, used to correlate a collection of statements
+1. Create a simple json payload
 
-    ```shell
-    FEED="my-product-id"
+    ```bash
+    cat > payload.json <<EOF
+    {
+        "author": "fred",
+        "title": "my biography",
+        "reviews": "mixed"
+    }
+    EOF
     ```
 
-1. Create a Signed Statement for the SPDX SBOM
+1. Create a COSE Signed Statement for the `payload.json` file
 
-    ```shell
+    ```bash
     python scitt/create_signed_statement.py \
       --signing-key-file $SIGNING_KEY \
       --issuer $ISSUER \
       --feed $FEED \
-      --content-type application/spdx+json \
+      --content-type "application/json" \
       --payload-file payload.json \
       --output-file $SIGNED_STATEMENT_FILE
 
 1. Register the Statement
+  {{< note >}}
+  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":"<COSE_SIGNED_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 \<TODO: here>
+{{< note >}}
+Coming soon: Filter on specific content types, such as what SBOMs have been registered, or which issuers have made statements.
+{{< /note >}}
 
 ## Summary