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

Commit 2502eda

Browse files
letmaikletmaik
committed
initial commit
Signed-off-by: Maik Riechert <maik.riechert@microsoft.com>
0 parents  commit 2502eda

19 files changed

+1330
-0
lines changed

‎.github/workflows/ci.yml

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: CI
2+
on:
3+
push:
4+
branches:
5+
- main
6+
paths-ignore:
7+
- '**.md'
8+
pull_request:
9+
paths-ignore:
10+
- '**.md'
11+
workflow_dispatch:
12+
13+
jobs:
14+
ci:
15+
name: CI
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v3
19+
20+
- run: ./run-tests.sh
21+

‎.gitignore

+148
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
pip-wheel-metadata/
24+
share/python-wheels/
25+
*.egg-info/
26+
.installed.cfg
27+
*.egg
28+
MANIFEST
29+
30+
# PyInstaller
31+
# Usually these files are written by a python script from a template
32+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
33+
*.manifest
34+
*.spec
35+
36+
# Installer logs
37+
pip-log.txt
38+
pip-delete-this-directory.txt
39+
40+
# Unit test / coverage reports
41+
htmlcov/
42+
.tox/
43+
.nox/
44+
.coverage
45+
.coverage.*
46+
.cache
47+
nosetests.xml
48+
coverage.xml
49+
*.cover
50+
*.py,cover
51+
.hypothesis/
52+
53+
54+
# Translations
55+
*.mo
56+
*.pot
57+
58+
# Django stuff:
59+
*.log
60+
local_settings.py
61+
db.sqlite3
62+
db.sqlite3-journal
63+
64+
# Flask stuff:
65+
instance/
66+
.webassets-cache
67+
68+
# Scrapy stuff:
69+
.scrapy
70+
71+
# Sphinx documentation
72+
docs/_build/
73+
74+
# PyBuilder
75+
target/
76+
77+
# Jupyter Notebook
78+
.ipynb_checkpoints
79+
80+
# IPython
81+
profile_default/
82+
ipython_config.py
83+
84+
# pyenv
85+
.python-version
86+
87+
# pipenv
88+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
89+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
90+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
91+
# install all needed dependencies.
92+
#Pipfile.lock
93+
Pipfile
94+
95+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow
96+
__pypackages__/
97+
98+
# Celery stuff
99+
celerybeat-schedule
100+
celerybeat.pid
101+
102+
# SageMath parsed files
103+
*.sage.py
104+
105+
# Environments
106+
.env
107+
.venv
108+
env/
109+
venv/
110+
ENV/
111+
env.bak/
112+
venv.bak/
113+
114+
# Spyder project settings
115+
.spyderproject
116+
.spyproject
117+
118+
# Rope project settings
119+
.ropeproject
120+
121+
# mkdocs documentation
122+
/site
123+
124+
# mypy
125+
.mypy_cache/
126+
.dmypy.json
127+
dmypy.json
128+
129+
# Pyre type checker
130+
.pyre/
131+
132+
# history cache
133+
.history/
134+
135+
136+
#redis cache file
137+
.dump.rdb
138+
dump.rdb
139+
.rdb
140+
141+
#vscode configure
142+
vscode/
143+
.vscode/
144+
vscode
145+
146+
workspace/
147+
*.cbor
148+
*.cose

‎CODE_OF_CONDUCT.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Microsoft Open Source Code of Conduct
2+
3+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
4+
5+
Resources:
6+
7+
- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
8+
- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
9+
- Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns

‎CONTRIBUTING.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Contributing
2+
3+
This project welcomes contributions and suggestions. Most contributions require you to
4+
agree to a Contributor License Agreement (CLA) declaring that you have the right to,
5+
and actually do, grant us the rights to use your contribution. For details, visit
6+
https://cla.microsoft.com.
7+
8+
When you submit a pull request, a CLA-bot will automatically determine whether you need
9+
to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
10+
instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
11+
12+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
13+
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
14+
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

‎LICENSE.txt

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Copyright (c) Microsoft Corporation.
2+
3+
MIT License
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# SCITT API emulator
2+
3+
This repository contains the source code for the SCITT API emulator. It is meant to allow experimenting with [SCITT](https://datatracker.ietf.org/wg/scitt/about/) APIs and formats. It is not meant to be used in production code.
4+
5+
## Prerequisites
6+
7+
The emulator assumes a Linux environment with Python 3.8 or higher.
8+
On Ubuntu, run the following to install Python:
9+
10+
```sh
11+
sudo apt install python3.8 python3.8-venv
12+
```
13+
14+
## Clone the emulator
15+
16+
Clone the scitt-api-emulator repository and change into the scitt-api-emulator folder:
17+
18+
```sh
19+
git clone https://github.com/microsoft/scitt-api-emulator
20+
cd scitt-api-emulator
21+
```
22+
23+
## Use the emulator
24+
25+
### Start a fake SCITT service
26+
27+
```sh
28+
./scitt-emulator.sh server --workspace workspace/ --tree-alg CCF
29+
```
30+
31+
`--tree-alg` is currently `CCF` only.
32+
33+
The default port is 8000 but can be changed with the `--port` argument.
34+
35+
Now the server is running at http://localhost:8000/ and uses `workspace/` to store the service parameters and service state.
36+
37+
The service has the following REST API:
38+
39+
- `POST /entries` - submit a COSE_Sign1 claim to the emulator and return an entry id
40+
- `GET /entries/<entry_id>` - retrieve the COSE_Sign1 claim for the corresponding entry id
41+
- `GET /entries/<entry_id>/receipt` - retrieve the SCITT receipt for corresponding entry id
42+
43+
The following steps should be done from a different terminal, leaving the service running in the background.
44+
45+
### Create claims
46+
47+
```sh
48+
./scitt-emulator.sh client create-claim --issuer did:web:example.com --content-type application/json --payload '{"sun": "yellow"}' --out claim.cose
49+
```
50+
51+
Note: The emulator does not verify claim signatures and generates an ad-hoc key pair to sign the claim.
52+
53+
### Submit claims and retrieve receipts
54+
55+
```sh
56+
./scitt-emulator.sh client submit-claim --claim claim.cose --out claim.receipt.cbor
57+
```
58+
59+
The `submit-claim` command uses the default service URL `http://127.0.0.1:8000` which can be changed with the `--url` argument. It can be used with the built-in server or an external service implementation.
60+
61+
This command sends the following two requests:
62+
63+
1. `POST /entries` with the claim file as HTTP body. The response is JSON containing `"entry_id"`.
64+
2. `GET /entries/<entry_id>/receipt` to retrieve the SCITT receipt.
65+
66+
### Retrieve claims
67+
68+
```sh
69+
./scitt-emulator.sh client retrieve-claim --entry-id 123 --out claim.cose
70+
```
71+
72+
The `retrieve-claim` command uses the default service URL `http://127.0.0.1:8000` which can be changed with the `--url` argument. It can be used with the built-in server or an external service implementation.
73+
74+
This command sends the following request:
75+
76+
- `GET /entries/<entry_id>` to retrieve the claim.
77+
78+
### Retrieve receipts
79+
80+
```sh
81+
./scitt-emulator.sh client retrieve-receipt --entry-id 123 --out receipt.cbor
82+
```
83+
84+
The `retrieve-receipt` command uses the default service URL `http://127.0.0.1:8000` which can be changed with the `--url` argument. It can be used with the built-in server or an external service implementation.
85+
86+
This command sends the following request:
87+
88+
- `GET /entries/<entry_id>/receipt` to retrieve the receipt.
89+
90+
### Validate receipts
91+
92+
```sh
93+
./scitt-emulator.sh client verify-receipt --claim claim.cose --receipt claim.receipt.cbor --service-parameters workspace/service_parameters.json
94+
```
95+
96+
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.
97+
98+
The `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:
99+
100+
```json
101+
{
102+
"serviceId": "emulator",
103+
"treeAlgorithm": "CCF",
104+
"signatureAlgorithm": "ES256",
105+
"serviceCertificate": "-----BEGIN CERTIFICATE-----..."
106+
}
107+
```
108+
109+
`"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).
110+
111+
### COSE and CBOR debugging
112+
113+
The following websites can be used to inspect COSE and CBOR files:
114+
115+
- https://gluecose.github.io/cose-viewer/
116+
- https://cbor.me/
117+
118+
## Code structure
119+
120+
`scitt_emulator/scitt.py` contains the core SCITT algorithms that are agnostic of a specific tree algorithm.
121+
122+
`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 auxiliarly entries.
123+
124+
`scitt_emulator/server.py` is a simple Flask server that acts as a SCITT transparency service.
125+
126+
`scitt_emulator/client.py` is a CLI that supports creating claims, submitting claims to and retrieving receipts from the server, and verifying receipts.
127+
128+
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`.
129+
130+
## Run tests
131+
132+
```
133+
./run-tests.sh
134+
```
135+
136+
## Contributing
137+
138+
This project welcomes contributions and suggestions. Please see the [Contribution guidelines](CONTRIBUTING.md).

0 commit comments

Comments
 (0)