Skip to content
This repository has been archived by the owner on Nov 22, 2024. It is now read-only.

Commit

Permalink
Archived notification and links (#49)
Browse files Browse the repository at this point in the history 
Signed-off-by: steve lasker <[email protected]>
  • Loading branch information
@SteveLasker
SteveLasker authored Nov 22, 2024
1 parent cfebeee commit 6e67760
Showing 1 changed file with 5 additions and 215 deletions.
220 changes: 5 additions & 215 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,220 +1,10 @@
# SCITT API Interoperability Client

This repository contains the source code for the SCITT API interoperability client and sample emulator.
> ## ⚠️This Repository Has Been Archived and Is No Longer Maintained. ⚠️
It is meant to allow experimenting with [SCITT](https://datatracker.ietf.org/wg/scitt/about/) APIs and formats and proving interoperability of implementations.
For current info, please see:

Note the SCITT standards are not yet fully published and are subject to change.
This repository aims to keep up with changes to the WG output as faithfully as possible but in the event of inconsistencies between this and the IETF WG documents, the IETF documents are primary.
- [IETF SCITT Working Group](https://datatracker.ietf.org/wg/scitt/about/)
- [SCITT Implementations](https://scitt.io/implementations.html)

## Prerequisites

The emulator assumes a Linux environment with Python 3.10 or higher.
On Ubuntu, run the following to install Python:

```sh
sudo apt install python3.10-venv
```

## Clone the Emulator

1. Clone the scitt-api-emulator repository and change into the scitt-api-emulator folder:

```sh
git clone https://github.com/scitt-community/scitt-api-emulator.git
```

1. Move into the emulator director to utilize the local commands

```sh
cd scitt-api-emulator
```

### Optional Dependencies

If you want to use conda, first install it:

- [Install Conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html)

You can get things setup with the following:

```sh
conda env create -f environment.yml
conda activate scitt
```

## Start the Proxy Server

The proxy server supports 2 options currently:

- 'CCF' uses the emulator server to create and verify receipts using the CCF tree algorithm
- 'RKVST' uses the RKVST production SaaS server to create and verify receipts using native Merkle trees

**Note:** _the emulator is for experimentation only and not recommended for production use._

### Start a Fake Emulated SCITT Service

1. Start the service, under the `/workspace` directory, using CCF

```sh
./scitt-emulator.sh server --workspace workspace/ --tree-alg CCF
```

1. The server is running at http://localhost:8000/ and uses the `workspace/` folder to store the service parameters and service state
**Note:** _The default port is `8000` but can be changed with the `--port` argument._
1. Start another shell to run the test scripts, leaving the above shell for diagnostic output
1. Skip to [Create Signed Claims](#create-signed-claims)

### Start an RKVST SCITT Proxy Service

1. Start the service, under the `/workspace` directory, using RKVST
The default port is `8000` but can be changed with the `--port` argument.

```sh
./scitt-emulator.sh server --workspace workspace/ --tree-alg RKVST
```

### Executing Commands

The service has the following REST API:

- `POST /entries` submit a COSE_Sign1 claim as HTTP body, with a JSON response containing `"entry_id"`
- `GET /entries/<entry_id>` - retrieve the COSE_Sign1 claim for the corresponding entry id
- `GET /entries/<entry_id>/receipt` to retrieve the SCITT receipt.

**Note:** The `submit-claim` and `retrieve-claim` commands use the default service URL `http://127.0.0.1:8000` which can be changed with the `--url` argument.
They can be used with the built-in server or an external service implementation.

### Create Signed Claims

1. Create a signed `json` claim with the payload: `{"sun": "yellow"}`, saving the formatted output to `claim.cose`

```sh
./scitt-emulator.sh client create-claim \
--content-type application/json \
--subject 'solar' \
--payload '{"sun": "yellow"}' \
--out claim.cose
```

_**Note:** The emulator generates an ad-hoc key pair to sign the claim if
``--issuer`` and ``--public-key-pem`` are not given. See [Registration Policies](docs/registration_policies.md) docs for more deatiled examples_

2. View the signed claim by uploading `claim.cose` to one of the [CBOR or COSE Debugging Tools](#cose-and-cbor-debugging)

### Submit Claims and Retrieve Receipts

1. Submit the Signed Claim

```sh
./scitt-emulator.sh client submit-claim \
--claim claim.cose \
--out claim.receipt.cbor
```

1. View the response, noting the `Entry ID` value

```output
Claim Registered:
json: {'entryId': '1'}
Entry ID: 1
Receipt: ./claim.receipt.cbor
```

1. Create an environment variable (`ENTRY_ID`) for the value of `entryId` above:

```sh
ENTRY_ID=<entryId>
```

### Retrieve Statements and Receipts

1. Retrieve the Statement, based on the ENTRY_ID set from the `submit-claim` command above

```sh
./scitt-emulator.sh client retrieve-claim \
--entry-id $ENTRY_ID \
--out claim.cose
```

`retrieve-claim` sends the following request:
`GET /entries/<entry_id>` to retrieve the claim.

1. Retrieve the Receipt, based on the ENTRY_ID set from the `submit-claim` command above

```sh
./scitt-emulator.sh client retrieve-receipt \
--entry-id $ENTRY_ID \
--out receipt.cbor
```

`retrieve-receipt` sends the following request:
`GET /entries/<entry_id>/receipt` to retrieve the receipt.

### Validate Receipts

```sh
./scitt-emulator.sh client verify-receipt \
--claim claim.cose \
--receipt claim.receipt.cbor \
--service-parameters workspace/service_parameters.json
```

The `verify-receipt` command verifies a SCITT receipt given a SCITT claim and a service parameters file.
This command can be used to verify receipts generated by other implementations.

The `workspace/service_parameters.json` file gets created when starting a service using `./scitt-emulator.sh server`.
The format of this file is not standardized and is currently:

```json
{
"serviceId": "emulator",
"treeAlgorithm": "CCF",
"signatureAlgorithm": "ES256",
"insertPolicy": "*",
"serviceCertificate": "-----BEGIN CERTIFICATE-----..."
}
```

`"signatureAlgorithm"` and `"serviceCertificate"` are additional parameters specific to the [`CCF` tree algorithm](https://ietf-scitt.github.io/draft-birkholz-scitt-receipts/draft-birkholz-scitt-receipts.html#name-additional-parameters).

To view the file:

```sh
cat workspace/service_parameters.json | jq
```

### COSE and CBOR Debugging

The following websites can be used to inspect COSE and CBOR files:

- [gluecose.github.io/cose-viewer](https://gluecose.github.io/cose-viewer/)
- [cbor.me](https://cbor.me/)

## Code Structure

`scitt_emulator/scitt.py` contains the core SCITT algorithms that are agnostic of a specific tree algorithm.

`scitt_emulator/ccf.py` is the implementation of the [CCF tree algorithm](https://ietf-scitt.github.io/draft-birkholz-scitt-receipts/draft-birkholz-scitt-receipts.html#name-ccf-tree-algorithm).
For each claim, a receipt is generated using a fake but valid Merkle tree that is independent of other submitted claims.
A real CCF service would maintain a single Merkle tree covering all submitted claims and auxiliary entries.

`scitt_emulator/rkvst.py` is a simple REST proxy that takes SCITT standard API calls and routes them through to the [RKVST production SaaS service](https://app.rkvst.io).
Each claim is stored in a Merkle tree underpinning a Quorum blockchain and receipts contain valid, verifiable inclusion proofs for the claim in that Merkle proof.
[More docs on receipts here](https://docs.rkvst.com/platform/overview/scitt-receipts/).

`scitt_emulator/server.py` is a simple Flask server that acts as a SCITT transparency service.

`scitt_emulator/client.py` is a CLI that supports creating claims, submitting claims to and retrieving receipts from the server, and verifying receipts.

In order to add a new tree algorithm, a file like `scitt_emulator/ccf.py` must be created and the containing class be added in `scitt_emulator/tree_algs.py`.

## Run Tests

```bash
./run-tests.sh
```

## Contributing

This project welcomes contributions and suggestions. Please see the [Contribution guidelines](CONTRIBUTING.md).
[Pre-archived content](https://github.com/scitt-community/scitt-api-emulator/blob/pre-archive/README.md)

0 comments on commit 6e67760

Please sign in to comment.