Skip to content

Commit bf0243f

Browse files
redpigredpig
committed
documentation: adding more diagrams and documentation
This change adds some more documentation. None of it is meant to be authoritative, but to help broaden understanding of the design decisions and possible ways to experiment with the system Much more documentation is needed.
1 parent 4ab5658 commit bf0243f

11 files changed

+1079
-0
lines changed

‎README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,8 @@ Additionally, see
5656
[xaptum/ecdaa](https://github.com/xaptum/ecdaa/blob/master/doc/BUILDING.md) for
5757
any system requirements for building AMCL or ECDAA, such as libtss2.
5858

59+
Diagram generation depends on [PlantUML](https://plantuml.com/).
60+
5961

6062
### Building
6163

‎docs/design/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
This directory contains documentation related to the design of briolette.
2+
3+
All markdown files may be read with any markdown reader.
4+
5+
Explainers start from markdown but were generated with [marp-cli](https://github.com/marp-team/marp-cli) and [bespoke](https://github.com/bespokejs/bespoke).

‎docs/design/architecture/credentials/credentials.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Credentials in Briolette
2+
3+
There are a number of credentials present throughout briolette, each with its
4+
own capabilities.
5+
6+
7+
## Service certificates
8+
9+
All operator services are expected to operate on top of a normal TLS deployment
10+
where the client can rely on server authenticity based on the certificates and keys
11+
held by the server.
12+
13+
None of briolette's trust depends on TLS functioning, it does provide heightened
14+
assurance against denial of service or service disruption attacks.
15+
16+
## State signing key
17+
18+
The state signing key is the most critical cryptographic key in the system.
19+
After a system-defined period of time has elapsed, a 'epoch', briolette
20+
system-wide state is updated. This update includes the current epoch number (a
21+
monotonically increasing 64-bit integer, usually based on wall-clock time), any
22+
ticket group numbers that have been temporarily blocked from the system
23+
(revoked), and the other public keys for the remainder of the system that a
24+
client, or wallet, device must know: token transfer public key, ticket server
25+
public key, issuing mint public keys, etc.
26+
27+
The level of trust given to the state signing key enables a compromise between
28+
in-the-field key rotation with minimal gossip overhead. A secondary signature
29+
over the extended state (epoch) data may be appropriate to introduce if the
30+
risk introduced is too high.
31+
32+
### Installation
33+
34+
The initial state signing key is installed on the wallet device by the wallet
35+
vendor or through an out-of-band installation process. Knowledge of the state
36+
server (clerk) and the state signing key is all that is required for a
37+
certified wallet to participate in different briolette systems.
38+
39+
See discussion of the 'Network Access Credential' for more.
40+
41+
### Usage
42+
43+
The state signing key does not need to be online and may be air gapped. The
44+
data it signs is fixed and well-formed, so the process for using the signing
45+
key, or keys, may be accompanied by additional software validation both on and
46+
off the signing infrastructure. The signer operates over the next epoch, a
47+
bitfield of revoked groups, and the extended epoch data cryptographic hash.
48+
The extended epoch data contains the all other signing keys, as well as the
49+
alternative state signing keys.
50+
51+
Epoch updates are not expected in real-time and as such, the generation of
52+
the new epoch data and signing process may be subject to high levels of
53+
assurance.
54+
55+
## Network Access Credential (NAC) Issuer Key
56+
57+
Wallet vendors will have at least one NAC issuer key. This key is used to grant
58+
network access credentials to wallets. The associated group public key must be
59+
known and accepted by briolette system operators for the credential to be used.
60+
61+
The issuer may require the wallet to have a proprietary key or perform some
62+
other service to be accepted for credential issuance.
63+
64+
## Network Access Credential (NAC)
65+
66+
The NAC is used by a wallet to connect to briolette operator services and is
67+
required for acquiring a token transfer credential.
68+
69+
Signatures over requests with epoch-bound basenames may be used to create
70+
linkable signatures over time periods. This will allow operator services to
71+
limit requests from any given wallet during a time period without being able
72+
to uniquely identify that wallet in the future.
73+
74+
## Token Transfer Credential (TTC) Issuer Key
75+
76+
This key is usually held by the system operator and is used to grant token
77+
transfer credentials to wallets. Wallets will need to request a TTC upon
78+
setup for a given operator and its request must be authenticated by the
79+
wallet's NAC with a known NAC group public key.
80+
81+
## Token Transfer Credential (TTC)
82+
83+
The TTC is used by the wallet to send and receive tokens. The wallet holds the
84+
private key and the credential acts as a "public" key. The credential itself
85+
is never used directly. Instead it may be randomized prior to use.
86+
87+
Prior to transacting, a wallet must pre-randomize its credential several times.
88+
It will take these randomized credentials and present them to the ticket clerk
89+
service (signed with the wallet's NAC). The ticket clerk will return signed
90+
tickets which may be used as the destination to receive tokens at.
91+
92+
When transferring received tokens, the wallet must use the same randomized
93+
credential from the signed ticket the token was transferred to when signing the
94+
transaction.
95+
96+
## Token Signing Key
97+
98+
The token signing key is the minting key. It fixates the token descriptor data
99+
with its signature and assigns the first recipient of a token.
100+
101+
## Transfer Ticket Signing Key
102+
103+
This key is held by the ticket clerk service and is used to sign transfer tickets
104+
which are built from randomized TTCs and specific policy attributes, such as
105+
expiration times.
106+
107+

‎docs/design/architecture/credentials/trust_hierarchy_class.png

155 KB
Loading

‎docs/design/architecture/credentials/trust_hierarchy_class.svg

Lines changed: 165 additions & 0 deletions
Loading

‎docs/design/architecture/credentials/trust_hierarchy_class.uml

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
@startuml
2+
skinparam shadowing false
3+
4+
title Trust and Configuration Hierarchy
5+
6+
skinparam class {
7+
BackgroundColor #lightblue
8+
ArrowColor #darkblue
9+
BorderColor black
10+
}
11+
12+
13+
hide members
14+
skinparam groupInheritance 2
15+
16+
17+
18+
entity "Wallet Vendor" #lightgrey
19+
note left: There will be many Wallet Vendors
20+
21+
class "Network Access Credential Issuer Key" <<🔑>> {
22+
issues network access credentials with valid provisioning credentials
23+
}
24+
show "Network Access Credential Issuer Key" members
25+
26+
class "Wallet Provisioning Credential Issuer Key" <<🔑>> {
27+
issues wallet provisioning credentials in a secured context
28+
}
29+
show "Wallet Provisioning Credential Issuer Key" members
30+
31+
class Wallet #lightgreen {
32+
+ Wallet Provisioning Credential <<🔑>>
33+
+ Network Access Credential <<🔑>>
34+
+ Token Transfer Credential <<🔑>>
35+
+ Configuration Data
36+
}
37+
show Wallet members
38+
39+
40+
41+
42+
entity "Briolette Operator" #lightgrey
43+
note left: Wallets may work across many operators
44+
45+
annotation "Common Server State" #beige {
46+
+ Network Access Credential Group Public Keys
47+
+ Epoch Data Signing Public Key
48+
+ Epoch Data
49+
+ Service Policies
50+
}
51+
show "Common Server State" members
52+
53+
class "Client State (Epoch) Signing Key" <<🔑>> {
54+
}
55+
56+
annotation "Epoch Data" #beige {
57+
+ Current System Epoch (time)
58+
+ System-wide trusted public keys
59+
+ Revocation data
60+
}
61+
show "Epoch Data" members
62+
63+
class "Token Signing Key (Mint)" <<🔑>>
64+
65+
class "Transfer Ticket Signing Key" <<🔑>> {
66+
signs tickets
67+
}
68+
show "Transfer Ticket Signing Key" members
69+
70+
class "Token Transfer Credential Issuer Key" <<🔑>> {
71+
issues token transfer credentials with valid Network Access Credentials
72+
}
73+
show "Token Transfer Credential Issuer Key" members
74+
75+
annotation "Token" #beige {
76+
+ Value
77+
+ Transfer Ticket
78+
+ Transfer Signature
79+
+ ...
80+
}
81+
show Token members
82+
83+
class "Briolette Online Services" #lightgreen
84+
85+
"Briolette Operator" --|> "Common Server State"
86+
"Common Server State" --|> "Network Access Credential Issuer Key"
87+
"Common Server State" --|> "Briolette Online Services" : configures
88+
"Briolette Operator" --|> "Client State (Epoch) Signing Key"
89+
"Epoch Data" --|> "Client State (Epoch) Signing Key"
90+
"Epoch Data" --|> "Token Signing Key (Mint)"
91+
"Epoch Data" --|> "Transfer Ticket Signing Key"
92+
"Transfer Ticket Signing Key" --|> "Token::Transfer Ticket"
93+
"Epoch Data" --|> "Token Transfer Credential Issuer Key"
94+
"Token Signing Key (Mint)" --|> "Token::Value" : signs
95+
"Token Transfer Credential Issuer Key" --|> "Wallet::Token Transfer Credential"
96+
"Client State (Epoch) Signing Key" --|> "Epoch Data"
97+
"Epoch Data" --|> "Wallet::Configuration Data"
98+
99+
100+
"Wallet Vendor" --|> "Wallet Provisioning Credential Issuer Key"
101+
"Wallet Provisioning Credential Issuer Key" --|> "Wallet::Wallet Provisioning Credential"
102+
"Wallet Vendor" --|> "Network Access Credential Issuer Key"
103+
"Wallet Vendor" --|> "Wallet::Configuration Data"
104+
"Wallet::Configuration Data" -[dotted]-|> "Token Signing Key (Mint)" : may trust out-of-system mints
105+
"Network Access Credential Issuer Key" --|> "Wallet::Network Access Credential"
106+
"Wallet::Network Access Credential" --|> "Briolette Online Services" : authenticates
107+
"Wallet::Token Transfer Credential" --|> "Token::Transfer Signature" : creates
108+
109+
hide <<🔑>> circle
110+
hide class circle
111+
hide annotation circle
112+
113+
114+
legend
115+
<size:18>Key</size>
116+
|<#lightgrey> Entities |
117+
|<#lightblue> Cryptographic Key (🔑) |
118+
|<#beige> Data |
119+
|<#lightgreen> Software System(s) |
120+
endlegend
121+
@enduml

‎docs/design/explainers/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
All HTML files were generated with
2+
```
3+
marp --template bespoke source.md
4+
```
5+
6+
All SVG and PNG files were generated using
7+
```
8+
plantuml -t<filetype> source.uml out.<filetype>
9+
```
10+
11+

‎docs/design/explainers/introduction.html

Lines changed: 268 additions & 0 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)