Skip to content

Commit aa6b020

Browse files
mpetersmpeters
committed
Adding enhancement #98 for SPIRE integration
Signed-off-by: Michael Peters <[email protected]>
1 parent dd59fc8 commit aa6b020

File tree

1 file changed

+227
-0
lines changed

1 file changed

+227
-0
lines changed

‎98_spire_integration.md

+227
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
<!--
2+
**Note:** When your enhancement is complete, all of these comment blocks should be removed.
3+
4+
To get started with this template:
5+
6+
- [ ] **Fill out this file as best you can.**
7+
At minimum, you should fill in the "Summary", and "Motivation" sections.
8+
These should be easy if you've preflighted the idea of the enhancement with the
9+
appropriate SIG(s).
10+
- [ ] **Merge early and iterate.**
11+
Avoid getting hung up on specific details and instead aim to get the goals of
12+
the enhancement clarified and merged quickly. The best way to do this is to just
13+
start with the high-level sections and fill out details incrementally in
14+
subsequent PRs.
15+
-->
16+
# enhancement-98: SPIRE Integration
17+
18+
<!--
19+
A table of contents is helpful for quickly jumping to sections of a enhancement and for
20+
highlighting any additional information provided beyond the standard enhancement
21+
template.
22+
-->
23+
24+
<!-- toc -->
25+
- [Release Signoff Checklist](#release-signoff-checklist)
26+
- [Summary](#summary)
27+
- [Motivation](#motivation)
28+
- [Goals](#goals)
29+
- [Non-Goals](#non-goals)
30+
- [Proposal](#proposal)
31+
- [User Stories (optional)](#user-stories-optional)
32+
- [Story 1](#story-1)
33+
- [Story 2](#story-2)
34+
- [Notes/Constraints/Caveats (optional)](#notesconstraintscaveats-optional)
35+
- [Risks and Mitigations](#risks-and-mitigations)
36+
- [Design Details](#design-details)
37+
- [Test Plan](#test-plan)
38+
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
39+
- [Drawbacks](#drawbacks)
40+
- [Alternatives](#alternatives)
41+
- [Infrastructure Needed (optional)](#infrastructure-needed-optional)
42+
<!-- /toc -->
43+
44+
## Release Signoff Checklist
45+
46+
<!--
47+
**ACTION REQUIRED:** In order to merge code into a release, there must be an
48+
issue in [keylime/enhancements] referencing this enhancement and targeting a release**.
49+
50+
For enhancements that make changes to code or processes/procedures in core
51+
Keylime i.e., [keylime/keylime], we require the following Release
52+
Signoff checklist to be completed.
53+
54+
Check these off as they are completed for the Release Team to track. These
55+
checklist items _must_ be updated for the enhancement to be released.
56+
-->
57+
58+
- [ ] Enhancement issue in release milestone, which links to pull request in [keylime/enhancements]
59+
- [ ] Core members have approved the issue with the label `implementable`
60+
- [ ] Design details are appropriately documented
61+
- [ ] Test plan is in place
62+
- [ ] User-facing documentation has been created in [keylime/keylime-docs]
63+
64+
<!--
65+
**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
66+
-->
67+
68+
## Summary
69+
70+
SPIFFE/SPIRE is an elegant solution to workload identity that is pluggable
71+
in it's node and workload attestors. Keylime would be a perfect candidate
72+
for node attestation if it had a few extra APIs that would allow the
73+
SPIRE agent and SPIRE server to be able to verify the following:
74+
75+
* Is the node where the SPIRE agent being attested by Keylime?
76+
* Is the attestation passing?
77+
78+
We propose new APIs on the agent and verifier to allow SPIRE to verify
79+
these things. But since SPIRE will also need plugins (agent and server)
80+
for the node attestation we have some flexibility in how these APIs
81+
appear. If we keep them generic enough, they could theoretically be used
82+
by any system that wants to independently verify the state of given node
83+
in Keylime.
84+
85+
## Motivation
86+
87+
* To expand Keylime's usefulness and reach in the cloud-native landscape.
88+
* To have a better hardware root-of-trust for software identity
89+
* To have a more complete Zero Trust solution
90+
91+
### Goals
92+
93+
When complete, this proposal will allow SPIRE plugins to be written to
94+
target Keylime as an attestor and provide useful properties in keylime
95+
as selectors in SPIRE. This will allow a user to craft authentication
96+
and authorization policy that takes into account a machine's boot and
97+
file integration attestation state.
98+
99+
### Non-Goals
100+
101+
Although these APIs will be generic, no direct effort will be made to
102+
support other non-SPIRE entities.
103+
104+
## Proposal
105+
106+
107+
### User Stories (optional)
108+
109+
#### Story 1
110+
111+
A developer will be able to develop a SPIRE agent and server plugin
112+
that communitcates with the Keylime agent and verifier to be able to
113+
independenly prove that the agent in question is on the same node as the
114+
SPIRE agent and also that the agent is passing it's attestation policies
115+
in Keylime.
116+
117+
This integration will also pull in various properties of the Keylime setup
118+
(agent configuration, policy, etc) to use as selectors for SPIRE.
119+
120+
### Notes/Constraints/Caveats (optional)
121+
122+
None
123+
124+
125+
### Risks and Mitigations
126+
127+
Care will need to be taken so that we don't leak any sensitive data in
128+
these APIs and that our verification/signing process is secure and leads
129+
to the guarantees we are making (that the SPIRE and Keylime agents are
130+
on the same node).
131+
132+
The security of the information flows has been reviewed by several
133+
members of the Keylime development team as well as SPIRE participants. The
134+
implementation will need thorough review as well.
135+
136+
137+
## Design Details
138+
139+
The following flow is anticipated for the full Keylime SPIRE plugins:
140+
141+
```
142+
┌───────────────────────────────────────────────┐ ┌───────────────┐
143+
│ │ │ │
144+
│ Node #3 │ │ SPIRE │
145+
│ ┌───────────────────────────────────┼────────────────────► SERVER │
146+
│ ┌────────┴────┐ │ │ │
147+
│ │ SPIRE │ #1 │ │ │
148+
│ │ Agent ◄────────────────┐ │ └─────┬─────────┘
149+
│ │ │ │ │ │
150+
│ └─────────┬───┘ │ │ │ #4
151+
│ │#2 ┌────▼─────┐ │ │
152+
│ ┌──▼──────┐ │ Keylime │ │ ┌─────▼─────────┐
153+
│ │ TPM │ │ Agent │ │ │ │
154+
│ │ │ │ │ │ │ Keylime │
155+
│ └─────────┘ └──────────┘ │ │ Verifier │
156+
│ │ │ │
157+
└───────────────────────────────────────────────┘ └───────────────┘
158+
```
159+
160+
This flow has the following steps:
161+
162+
1. SPIRE Agent queries node-local /info API on keylime agent to get information like the Keylime UUID
163+
2. SPIRE Agent creates a nonce that is sent to the TPM’s AK (keylime created) for signing
164+
3. SPIRE Agent sends the information to the Spire Server
165+
4. SPIRE Server queries Keylime Verifier about the agent. Does it exist? Is it passing attestation? If so, can you unencrypt (verify signature) of this nonce? If all are true, then SPIRE attestation passed and identity is issued.
166+
167+
168+
In order to accomodate this flow, this enhancement will consist of the following:
169+
170+
1. A new node-local, non-TLS API on the keylime agent responding the the `/info` path. It will return information about the keylime agent which will be used to not only identity the agent, but also be used to perform a signature verification. A 3rd party can use the credential created by the agent in the TPM to sign a nonce which can then be verified by the verifier. The new API will return the following information:
171+
172+
* agent_uuid
173+
* tpm_hash_alg
174+
* tpm_encryption_alg
175+
* tpm_signing_alg
176+
* ek_handle
177+
178+
2. A new API on the verifier that can take a signed payload from a TPM and given agent's UUID verify that it came from a TPM associated with that agent. This will be used to independently verify that the Keylime agent resides on a node with that TPM.
179+
180+
3. An expansion of the existing `/agents` GET API on the verifier to return enough information for use as selectors in SPIRE.
181+
182+
183+
### Test Plan
184+
185+
The individual new APIs will have tests written for them. And the new
186+
SPIRE plugins written to use those APIs will also have their own CI/CD
187+
tests/pipelines to test against those APIs, targetting specific versions
188+
of the Keylime agent and verifier.
189+
190+
### Upgrade / Downgrade Strategy
191+
192+
These will be net-new APIs and will require a minor bump in the Keylime
193+
API version number. It's not believed that they will require database
194+
schema changes, nor any upgrade migrations. As such, there doesn't need
195+
to be a downgrade strategy.
196+
197+
### Dependency requirements
198+
199+
It is not believed that we will require any new dependencies for these
200+
APIs as they will just re-use existing libraries for any cryptographic
201+
signing or verification of those signatures.
202+
203+
## Drawbacks
204+
205+
It's possible that these APIs won't be useful outside of the SPIRE
206+
integration, but it's our belief they will be generic enough to be evolved
207+
for any 3rd party that wants to do deep verification of an node's status
208+
in Keylime.
209+
210+
## Alternatives
211+
212+
It's already possible to create an integration of Keylime with SPIRE
213+
by using the x509pop plugin, but there are several limitations with
214+
this approach:
215+
216+
* You need to have a key management solution for those certs
217+
* It's very automatic and requires a lot of setup/configuration for the users
218+
* It relies on using the payload delivery mechanism of the keylime tenant which some users turn off for security
219+
* It doesn't propagate any information about the Keylime setup into SPIRE properties for use in auth policy.
220+
* There's no way to revoke the certificate if attestation fails in the future
221+
222+
This enhancement should allow for full Keylime/SPIRE plugins to fix all
223+
of those problems and make it really easy and convenient for users.
224+
225+
## Infrastructure Needed (optional)
226+
227+
This enhancement shouldn't need any additional infrastructure.

0 commit comments

Comments
 (0)