Skip to content

Commit e071e5b

Browse files
brunorijsmanbrunorijsman
committed
Progress developer guide
1 parent 542e781 commit e071e5b

2 files changed

Lines changed: 68 additions & 28 deletions

File tree

‎.vscode/settings.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
"Adleman",
55
"APIPSRD",
66
"aread",
7+
"ASGI",
78
"bitarray",
89
"camila",
910
"Ciena",
@@ -29,6 +30,7 @@
2930
"getpid",
3031
"HMAC",
3132
"htmlcov",
33+
"HTTPX",
3234
"ISAKMP",
3335
"Kozlik",
3436
"Mersenne",
@@ -53,6 +55,7 @@
5355
"Shamir",
5456
"Shor's",
5557
"urandom",
58+
"Uvicorn",
5659
"venv"
5760
],
5861
"editor.wordWrapColumn": 100,

‎docs/developer-guide.md‎

Lines changed: 65 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,23 @@ Or, for more details see the
1919

2020
## Technology stack
2121

22-
Our technology stack is:
22+
The code technology stack includes:
2323
* [Python 3.13](https://www.python.org/) as the programming language.
24-
* [FastAPI](https://www.python.org/) for HTTP APIs.
24+
The nodes (clients and hubs) are asynchronous;
25+
the manager is synchronous.
26+
* [FastAPI](https://www.python.org/) for server-side HTTP APIs.
27+
* [HTTPX](https://www.python-httpx.org/) for client-side HTTP APIs.
28+
* [Uvicorn](https://uvicorn.dev/)as the ASGI (synchronous Server Gateway Interface) web server.
2529
* [Git](https://git-scm.com/) and [Github](https://github.com/brunorijsman/dske-python) for version control.
30+
31+
The development toolchain includes:
2632
* [Github actions](https://github.com/features/actions) for continuous integration.
2733
* [Pylint](https://pypi.org/project/pylint/) for linting.
2834
* [Black](https://black.readthedocs.io/) for code formatting.
2935
* [Coverage](https://coverage.readthedocs.io/) for code coverage.
3036
* [Pip](https://pypi.org/project/pip/) for dependency management.
3137
* [Venv](https://docs.python.org/3/library/venv.html) for virtual environments.
38+
* [Markdown](https://en.wikipedia.org/wiki/Markdown) for documentation.
3239

3340
## DSKE protocol
3441

@@ -42,8 +49,10 @@ See [the DSKE protocol page](/docs/dske-protocol.md) for more details.
4249
## Proof of concept
4350

4451
The code is intended to be a proof-of-concept to study the DSKE protocol; it is not
45-
suitable for production deployments for numerous reasons (e.g. we have made no effort to prevent
46-
side-channel attacks).
52+
suitable for production deployments for numerous reasons (e.g.
53+
state is not persisted and the protocol needs to start from scratch every time a daemon restarts,
54+
we have made no effort to prevent side-channel attacks,
55+
etc.)
4756

4857
## Check-and-test script
4958

@@ -90,41 +99,69 @@ for the network node as reported when the topology is started.
9099

91100
Here we provide a summary of the API endpoints and their purpose.
92101

93-
### Hub API endpoints
94-
95-
The hubs provides the following API endpoints:
96-
97-
| Method | URL | Purpose | Authenticated |
98-
|-|-|-|-|
99-
| PUT | `/hub/HUB_NAME/dske/oob/v1/registration` | Register a client with a hub. | No |
100-
| GET | `/hub/HUB_NAME/dske/oob/v1/psrd` | Allows a client to get a block of Pre-Shared Random Data (PSRD) from the hub. | No |
101-
| POST | `/hub/HUB_NAME/dske/api/v1/key-share` | Allows an initiator client to add a key share to the hub, so that it can later be retrieved by the responder client. | Yes |
102-
| GET | `/hub/HUB_NAME/dske/api/v1/key-share` | Allows a responder client to add a key share to the hub, that was previously added by the initiator client. | Yes |
103-
| GET | `/hub/HUB_NAME/mgmt/v1/status` | Get the status of the hub. | No |
104-
| POST | `/hub/HUB_NAME/mgmt/v1/stop` | Stop the hub. | No |
105-
106-
See the [authentication section](#authentication) below for more details on authentication.
107-
108-
HUB_NAME is the name of the hub.
109-
If each hub runs in a separate process (and hence has a separate port number) as is currently the
110-
case, this is not really needed.
111-
We include it anyway to allow for the possibility of running all hubs (and clients) in a single
112-
process with a single port.
102+
### API naming conventions
113103

114104
The API endpoints belong to one of the following groups:
115105

116106
| Endpoint path | Purpose |
117107
|-|-|
118108
| `.../dske/...` | DSKE protocol. |
119-
| `.../dske/oob/...` | The out-of-band (OOB) portion of the DSKE protocol. |
120-
| `.../dske/api/...` | The in-band portion of the DSKE protocol. . |
109+
| `.../dske/oob/...` | The out-of-band (OOB) portion of the DSKE protocol. |
110+
| `.../dske/api/...` | The in-band portion of the DSKE protocol. |
121111
| `../mgmt/...` | Used for management. Since this code is not intended for production deployment, these endpoints are also not authenticated. |
122112

113+
All API endpoints include the node type and the node name at the start of the URL path.
114+
For example:
115+
116+
| Node type | URL prefix |
117+
|-|-|
118+
| PUT | `/hub/HUB_NAME/...` |
119+
| GET | `/client/CLIENT_NAME/...` |
120+
121+
Currently, this is not really necessary for anything, since each node runs in its own process
122+
on a different HTTP port.
123+
But we anticipate that we (or someone else) may run this code as a cloud-based service at some
124+
point in the future (similar to what we did with
125+
[QuKayDee](https://qukaydee.com) for QKD).
126+
In that case, the cloud-based service would expose only a single HTTP port, and some proxy
127+
(e.g [Nginx](https://nginx.org/)) would use URL-based routing to dispatch each request to the
128+
correct node process.
129+
123130
All API endpoints are versioned (currently `v1`).
124131

132+
Putting all of this together, an example of a complete URL for one of the API endpoints is:
133+
`/hub/HUB_NAME/dske/api/v1/key-share`
134+
135+
### Hub API endpoints
136+
137+
The hubs provides the following API endpoints:
138+
139+
| Method | URL | Purpose | Authenticated |
140+
|-|-|-|-|
141+
| PUT | `/hub/HUB_NAME /dske/oob/v1 /registration` | Register a client with a hub. | No |
142+
| GET | `/hub/HUB_NAME /dske/oob/v1 /psrd` | A client gets a block of Pre-Shared Random Data (PSRD) from the hub. | No |
143+
| POST | `/hub/HUB_NAME /dske/api/v1 /key-share` | An initiator client adds a key share to the hub. The share can later be retrieved by the responder client. | Yes |
144+
| GET | `/hub/HUB_NAME /dske/api/v1 /key-share` | A responder client retrieves a key share from the hub. The share was previously added by the initiator client. | Yes |
145+
| GET | `/hub/HUB_NAME /mgmt/v1 /status` | Get the management status of the hub. | No |
146+
| POST | `/hub/HUB_NAME /mgmt/v1 /stop` | Stop the hub. | No |
147+
148+
### Clients API endpoints
149+
150+
The clients provides the following API endpoints:
151+
152+
| Method | URL | Purpose | Authenticated |
153+
|-|-|-|-|
154+
| GET | `/client/CLIENT_NAME /etsi/api/v1 /keys/SLAVE_SAE_ID/enc_keys` | An initiator encryptor gets a key from a client. | No |
155+
| GET | `/client/CLIENT_NAME /etsi/api/v1 /keys/MASTER_SAE_ID/dec_keys ?key_ID=KEY_ID` | A responder encryptor gets a key with key ID from a client. | No |
156+
| GET | `/client/CLIENT_NAME /etsi/api/v1 /keys/SLAVE_SAE_ID/status` | An encryptor gets the QKD link status from client. | No |
157+
| GET | `/hub/HUB_NAME /mgmt/v1/status` | Get the management status of the client. | No |
158+
| POST | `/hub/HUB_NAME /mgmt/v1/stop` | Stop the club. | No |
159+
125160
## Authentication
126161

127-
Only the in-band DSKE protocol API endpoints (`.../dske/api/...`) are authenticated.
162+
Only the in-band DSKE protocol API endpoints (`.../dske/api/...`) are authenticated
163+
using the authentication mechanism described in the
164+
[protocol guide](/docs/protocol-guide.md)
128165

129166
The out-of-band DSKE protocol API endpoints (`.../dske/oob/...`) are not authenticated.
130167
They only exist to simulate actions that would be some secure out-of-band physical distribution
@@ -138,7 +175,7 @@ we only implement a simplified subset of the
138175
[ETSI QKD 014](https://www.etsi.org/deliver/etsi_gs/QKD/001_099/014/01.01.01_60/gs_qkd014v010101p.pdf)
139176
key delivery interface.
140177

141-
TODO
178+
TODO Continue from here
142179

143180
## Pre-Shared Random Data (PSRD) management
144181

0 commit comments

Comments
 (0)