EVE Nodes are managed from EVC(Edge Virtualization Controller). EVE uses HTTPS APIs to talk to the EVC for fetching the configuration and exporting operational information. These APIs are HTTP URI endpoints, and the connection is secured through a TLS session. To establish trust either way, mutual TLS authentication scheme is used, where both EVE(the client) and EVC(the server) need to prove their identity. For this EVE and EVC exchange their X.509 certificates.
However this mechanism does not work if the TLS session is intercepted by a network proxy, e.g. a HTTPS proxy doing lawful inspection of the payload exchanged between the client and server or a TLS terminating HTTPS load-balancer. This is because the proxy server may terminate TLS connection from EVE, and sometimes break that into 2 separate TLS sessions, one facing the server and another one facing the client. The one facing the client will act as server, and one facing the server will act as client. So this poses the following issues:
Therefore, to enable EVE connectivity in such environments where proxy is used, following mechanism is used.
To protect the payload from getting modified in transit, the payload needs to be signed End-to-End between EVE and EVC. EVE or EVC, when they receive payload from the other, will hash the payload and compute signature of the digest, and compare it with the signature that accompanied the payload. We call this additional data that goes with the payload, and carries the signature of the payload, as the "Envelope". If the signature in the envelope is different from the signature computed from the payload, then one can detect that the payload has been modified during the transit. Therefore "Envelopes" help detect that payload has been modified during the transit. This mechanism is as strong as the signing method used, so the following method is used to compute the signature of the payload:
To use payload envelopes, both EVE and EVC need to know the certificates of the other party, before they can start sending payloads with envelopes carrying signatures of the payload. This is how they are provisioned:
With these steps, EVE and EVC are ready to sign and also validate the signature of the other party.
EVE does the following whenever it does a POST to EVC's v2 API:
2. EVE sends this envelope as the payload to the v2 version of the API
EVE does the following whenever it receives a POST response to a v2 API:
EVC does the following whenever it receives a POST request for a v2 API:
EVC does the following whenever it prepares response to a POST of a v2 API:
The eventual goal is to EOL the v1 APIs, and support only v2 APIs in EVC. But today we might already have EVE instances talking v1 APIs to a given EVC. Following is the plan to transition EVE and EVC to v2
Let the current EVC software version be 3.0 and EVE version be 3.0, and there is no support for v2 API in either of EVC and EVE versions. Also, assume that some of the EVE instances are running slightly older versions, say 2.0.
Now, following is the transitioning order to move to v2
If EVC decides to change the signing keys it is using, it can do the following steps:
Then,
One of the issues discussed above was to secure the sensitive information in the payload from getting exposed in transit, due to termination of TLS at proxy server. To address this, sensitive parts of the configuration will be encrypted using a shared symmetric key. The details on how this shared symmetric key is arrived at, and how the encryption and decryption happen, can be found at Secure Storage of Sensitive Information on EVE
This is a normative reference to the various EVC APIs, their v1/v2 differences, the payload fields, components of envelope etc.
Order | API | Version | Operation | TLS Client Cert | Args | Response | Request Enveloped? | Response Enveloped? | Context of invocation |
---|---|---|---|---|---|---|---|---|---|
1 | edgeDevice/register | v1 | POST | onboarding certificate | serial, soft serial, device cert | standard HTTP response code | No | No | initial onboarding |
1 | edgeDevice/register | v2 | POST | None | onboarding key, serial, soft serial device cert | standard HTTP response code | Yes, signed by onboarding certificate | No | initial onboarding |
2 | edgeDevice/Certs (new) | v1/v2 | GET | None. Preference is to use HTTP if proxy supports. | None | Controller Certs, and HTTP response code | No | No | at every boot, if device does not have any controller cert |
3 | edgeDevice/config | v1 | POST | device certificate | device certificate | Device Configuration | No | No | at boot time. When we act on PCR values, PCR Quote will have to be sent along with the config request |
3 | edgeDevice/config | v2 | POST | None | device certificate | Device Configuration | Yes, signed by device certificate, and contains device certificate | Yes, signed by Controller Cert shared in Order 2 | at boot time. When we act on PCR values, PCR Quote will have to be sent along with the config request |
4 | edgeDevice/id/<uuid>/attest Sub-type ATTEST_REQ_CERT | v2 | POST | None | Additional Certs created by Device | standard HTTP response code | Yes, signed by device certificate. Envelope has device UUID | No | at boot time |
5 | edgeDevice/id/<uuid>/attest Sub-type ATTEST_REQ_NONCE | v2 | POST | None | None | Nonce | Yes, signed by device certificate. Envelope has device UUID | Yes, signed by Controller Cert shared in Order 2 | Precedes PCR Quote POST |
6 | edgeDevice/id/<uuid>/attest Sub-type ATTEST_REQ_QUOTE | v2 | POST | None | Nonce, PCR Quote. Quote is signed with restricting signing key from device | AttestResult(pass, fail) along with standard HTTP response code | Yes, signed by device certificate. Envelope has device UUID | Yes, signed by Controller Cert shared in Order 2 | Precedes config request |
7 | edgeDevice/config | v1 | POST | device certificate | device UUID, hash of current config | Device Configuration, sensitive data encrypted with shared symmetric key | No | No | When we act on PCR values, PCR Quote will have to be sent along with the config request |
7 | edgeDevice/config | v2 | POST | device certificate | device UUID, hash of current config | Device Configuration, sensitive data encrypted with shared symmetric key | Yes, signed by device certificate. Envelope has device UUID | Yes, signed by Controller Cert shared in Order 2 | When we act on PCR values, PCR Quote will have to be sent along with the config request |