Skip to content

Commit a5258c7

Browse files
sameosameo
authored
Merge pull request #1 from jialez0/main
Document: Add KBS attestation protocol design doc
2 parents 2d388a6 + 8799557 commit a5258c7

File tree

1 file changed

+295
-0
lines changed

1 file changed

+295
-0
lines changed

‎docs/kbs_attestation_protocol.md‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
# KBS attestation Protocol
2+
3+
The Key Broker Service attestation protocol defines communication between a Key Broker Client in a confidential guest
4+
and a trusted Key Broker Service. The protocol uses the simple, universal, and extensible
5+
"Request-Challenge-Attestation-Response" (RCAR) method to facilitate guest attestation and secret injection.
6+
7+
# Introduction
8+
9+
The purpose of the attestation between KBS and KBC is actually to confirm whether
10+
**the platform where the KBC is located is in the expected security state**, that is, it runs in
11+
a real and harmless HW-TEE, and the software stack is measured and verifiable.
12+
13+
In this document, HW-TEE attestation process is the semantics of the application
14+
layer, which is defined as a simple, universal and extensible
15+
"Request-Challenge-Attestation-Response" (RACR) protocol. The temporary asymmetric key generated
16+
by HW-TEE is used to encrypt the response output payload, and the token mechanism is used to avoid the
17+
performance problems caused by multiple attestation: it's fairly typical to request for several resources,
18+
and then send from the same KBC multiple Requests. Having to do the whole attestation dance would
19+
be time consuming and have a latency impact on the guest.
20+
21+
In order to ensure the ease of use and security completeness of KBS, we will use HTTPS
22+
as the default transmission method to carry the application layer semantics designed in this
23+
document. This is because HTTPS provides KBC with a means to authenticate KBS identity, which
24+
effectively avoids malicious attackers from hijacking KBS address to impersonate KBS and deceive KBC.
25+
In order to achieve this, the public key of KBS needs to be transmitted to KBC through an effective way,
26+
and the specific way of public key distribution is not within the scope of this document.
27+
In addition, it should be noted that the confidentiality protection provided by HTTPS alone is not enough
28+
to meet the security requirements of KBS protocol, therefore, as mentioned above, the key generated
29+
by HW-TEE needs to be used to encrypt and protect the confidential data.
30+
31+
# RCAR semantics
32+
33+
The semantics of attestation defined by KBS is a simple and extensible four-step model,
34+
which uses JSON structure to organize information. As follows:
35+
36+
1. **Request**: The KBC sends to KBS, calls the service API provided by KBS to request resources.
37+
2. **Challenge**: After receiving the request, KBS returns a challenge to KBC and asks KBC to
38+
send evidence to prove that its environment (HW-TEE) is safe and reliable.
39+
3. **Attestation**: KBC sends the evidence and the HW-TEE generated, ephemeral public key to the KBS.
40+
4. **Response**: The `Reponse` payload includes the resource data requested when sending the initial `Request` to
41+
the specific KBS resource endpoint. The resource data is is protected by the ephemeral public key
42+
passed via the previously sent Attestation payload. Within the valid time of the token, KBC can directly
43+
request resources or services of KBS by virtue of the token without step 2 and step 3.
44+
45+
## Request
46+
47+
The payload format of the request is as follows:
48+
49+
(Note that the `/*...*/` comments are not valid in JSON, and must not be used in real message.)
50+
51+
```json
52+
{
53+
"request": {
54+
/* Attestation rotocol version number used by KBC */
55+
"version": "0.1.0",
56+
/* Types of HW-TEE platforms where KBC is located, such as "tdx", "sev-snp", etc. */
57+
"tee": "",
58+
/* Access token to avoid multiple attempts triggered by consecutive requests. */
59+
"token": "",
60+
/* Reserved fields are used to support some special requests sent by HW-TEE. */
61+
"extra-params": {}
62+
}
63+
}
64+
```
65+
66+
- `protocol-version`
67+
68+
The protocol version number supported by KBC. KBS needs to judge whether this KBC can communicate
69+
normally according to this field.
70+
71+
- `tee`
72+
73+
Used to declare the type of HW-TEE platform where KBC is located, the valid values now is `tdx`, `sgx` and `sev-snp`.
74+
75+
- `token`
76+
77+
If other requests have been made before this request, in the previous response KBS would return a
78+
token to KBC. There are two cases for the contents of this field:
79+
80+
1. A token is provided, which means a previous attestation was done. If the token is valid,
81+
the Challenge/Attestation part can be skipped. If it is not valid, KBS will send a Challenge.
82+
83+
2. Left blank, which means the KBC is implictly expecting to go through attestation
84+
and KBS will reply with a Challenge.
85+
86+
- `extra-params`
87+
88+
In the run-time attesation scenario (TDX, SEV-SNP, SGX), the `extra-params` not be used, so it is keeped empty.
89+
However, for the attestation of some special HW-TEE platforms, this field may be used to transfer some specific information,
90+
for example, some attestations depend on Diffie–Hellman to build a secure channel and transfer secret messages
91+
(Such as the SEV(-ES) pre-attesattion).
92+
93+
## Challenge
94+
95+
After KBS receives the request, if the token is found to be empty or expired, KBS will return an
96+
attestation challenge to KBC. The payload format is as follows:
97+
98+
```json
99+
{
100+
"challenge": {
101+
/* To ensure the freshness of evidence. */
102+
"nonce": "",
103+
/* Extra parameters to support some special HW-TEE attestation. */
104+
"extra-params": {}
105+
}
106+
}
107+
```
108+
109+
- `nonce`
110+
111+
The fresh number passed to KBC. KBC needs to place it in the evidence sent to KBS in the next
112+
step to prevent replay attacks.
113+
114+
- `extra-params`
115+
116+
The reserved extra parameter field which is used to pass the additional information provided by
117+
the KBS when some specific HW-TEE needs to be attested.
118+
119+
## Attestation
120+
121+
After receiving the invitation challenge, KBC collects the attestation evidence of HW-TEE
122+
platform and organizes it into the following payload format:
123+
124+
```json
125+
{
126+
"evidence": {
127+
/* The nonce in the Chanllenge, Its hash needs to be included in HW-TEE evidence and
128+
signed by HW-TEE hardware. */
129+
"nonce": "",
130+
/* TEE type name */
131+
"tee": "",
132+
/* The public key generated by KBC in HW-TEE, it is valid until the next time an attestation is required.
133+
Its hash needs to be included in HW-TEE evidence and signed by HW-TEE hardware. */
134+
"tee-pubkey": {
135+
"algorithm": "",
136+
"pubkey-length": "",
137+
"pubkey": ""
138+
},
139+
/* The content of evidence. Its format is specified by Attestation-Service. */
140+
"tee-evidence": {}
141+
}
142+
}
143+
```
144+
145+
- `nonce`
146+
147+
This is the nonce received by KBC in `Chanllenge` to prove the freshness of the evidence to KBS.
148+
KBS will match the evidence corresponding to the request through this nonce.
149+
In addition to providing nonce here, its hash needs to be included in HW-TEE evidence payload and signed by HW-TEE.
150+
151+
- `tee`
152+
153+
Used to declare the type of HW-TEE platform where evidence is from, the valid values now is `tdx`, `sgx` and `sev-snp`.
154+
155+
- `tee-pubkey`
156+
157+
After KBC receives the attestation challenge, a pair of temporary asymmetric keys are generated
158+
in HW-TEE. The private key is stored in HW-TEE. The public key and its description information
159+
are exported and placed in the `tee-pubkey` field and sent to KBS together with evidence. The
160+
hash of the `tee-pubkey` field needs to be included in the custom field of HW-TEE evidence and
161+
signed by HW-TEE hardware. This public key is valid until the next time KBC receives this KBS's
162+
attestation challenge.
163+
164+
- `tee-evidence`
165+
166+
The specific content of evidence related to the HW-TEE platform software and hardware in KBC's
167+
environment, different `tee-evidence` formats will be defined according to the type of TEE. This
168+
format is defined by the Attestation-Service.
169+
**KBS will not analyze the content of this structure, but will directly forward it to the Attestation-Service for verification**.
170+
171+
## Response
172+
173+
If Attestation-Service fails to verify the evidence, KBS returns error response information to
174+
KBC.
175+
176+
If KBS verified the token or the attestation evidence successfully, it will return a response to KBC in the following format:
177+
178+
```json
179+
{
180+
"response": {
181+
/* The output of KBS service API, needs to be encrypted by a symmetric key randomly generated by KBS. */
182+
"output": "",
183+
/* Symmetric key and algorithm information for encrypting `output`. */
184+
"crypto-annotation": {
185+
"algorithm": "",
186+
"symkey-length": "",
187+
/* The symmetric key used to encrypt `output`, which is encrypted by HW-TEE's public key */
188+
"enc-symkey": ""
189+
},
190+
/* The token issued by KBS to KBC. If there is a token in the request, this field will be left blank. */
191+
"token": "",
192+
}
193+
}
194+
```
195+
196+
- `output`
197+
198+
The output of KBS service API, it needs to be encrypted by a symmetric key randomly generated by KBS.
199+
200+
- `crypto-annotation`
201+
202+
The symmetric key and algorithm used to encrypt `output`. Because the output of KBS service
203+
API may contain large data, it is inefficient to directly use HW-TEE's public key for encryption.
204+
Therefore, digital envelope technology is used here, KBS generate a random symmetric key to
205+
encrypt `output`, and then use HW-TEE's public key to encrypt the random symmetric key.
206+
207+
- `token`
208+
209+
If the attestation evidence sent by KBC is verified before returning the response, KBS will issue
210+
a token to KBC in this field and sign it with KBS's root key. KBS will maintain the corresponding
211+
relationship between each issued token and its original attestation result. KBC can use this token
212+
to request resources or services from KBS without Challenge and Attestation within the validity period of
213+
the token. If there is already a token in the KBC's request, no new token will be issued and this
214+
field will be left blank.
215+
216+
The [JSON web token](https://jwt.io/) standard is adopted for the token. The format is as follows:
217+
218+
(Note that the `/*...*/` comments are not valid in JSON web token, and must not be used in real token.)
219+
220+
```json
221+
{
222+
/* JWT header */
223+
"alg": "HS256",
224+
"typ": "JWT"
225+
}.
226+
{
227+
/* JWT Payload official claim set */
228+
229+
/* Token's expiration time */
230+
"exp": 1568187398,
231+
/* Token's issuing time */
232+
"iat": 1568158598,
233+
/* Token's issuer, which is the URL address of KBS */
234+
"iss": "https://xxxxxx",
235+
236+
/* JWT payload custom claim set */
237+
238+
/* The HW-TEE's public key sent by KBC in the attestation evidence,
239+
which is valid within the validity period of the token. */
240+
"tee-pubkey": {
241+
"algo": "",
242+
"pubkey-length": "",
243+
"pubkey": ""
244+
}
245+
}.
246+
[Signature]
247+
```
248+
249+
The header part of the token declares the format standard of the token and the signature algorithm used.
250+
251+
The payload part is divided into official claim set and custom claim set. In the official claim
252+
set, we select three fields, `exp`, `iat`' and `iss`, which respectively declare the expiration
253+
time, issuing time and issuer (KBS URL address) of the token. The custom field in the payload
254+
contains the HW-TEE's public key sent by KBC along with the attestation evidence, which is valid
255+
within the validity period of the token. When KBC uses the token to request resources or services
256+
of KBS service API, KBS uses this public key recorded in the token to encrypt the symmetric key used to
257+
encrypt the `output`.
258+
259+
At the end of the token, KBS signs the header and payload with its root key to confirm that the
260+
token is indeed issued by KBS itself.
261+
262+
Within the validity period of the token, KBC can provide the token encoded by Base64 as the
263+
content of the `token` field in the request to KBS, so as to quickly obtain the required
264+
resources or service result.
265+
266+
# Error information
267+
268+
In addition to using the standard HTTPS status code to represent the returned error type,
269+
it is also necessary to provide a detailed description of the attestation error.
270+
We define the error return payload as follows:
271+
272+
```json
273+
{
274+
"error": {
275+
"info": ""
276+
}
277+
}
278+
```
279+
280+
# Integration
281+
282+
KBS uses HTTPS protocol for request and response by default.
283+
The above "RCAR" attestation message can be passed as the payload of HTTPS request and response.
284+
The following examples illustrate the integration of "RCAR" semantics with HTTPS request and response:
285+
286+
For example, KBC needs to request a key, and the URL is `/kbs/key/key_id`, the steps are as follows:
287+
288+
1. KBC sends `GET /kbs/key/key_id` request. The request payload is the `Request` message in the "RCAR" semantics.
289+
2. If no token is provided in the request payload or the token is invalid, KBS returns `HTTPS 200` response to KBC,
290+
but the payload of the response is the `Challenge` message in the "RCAR" semantics.
291+
If a valid token is provided in the request payload, KBS directly jumps to step 4.
292+
3. KBC sends `GET /kbs/key/key_id` request to KBS again, but the payload of this request is the `Attestation` message in the "RCAR" semantics.
293+
4. KBS returns an `HTTPS 200` response to KBC and the payload is the `Response` message in the "RCAR" semantics.
294+
295+

0 commit comments

Comments
 (0)