From 8a4d2c2f305d5b265f8c253bd5b219a2b7480efb Mon Sep 17 00:00:00 2001 From: Hariharasubramanian C S Date: Mon, 10 Aug 2020 16:12:30 +0530 Subject: [PATCH] Introducing protobuf file for the new /uuid endpoint - Once attestation feature is enabled in Controller, the /config endpoint will fail incoming requests without an integrity token associated with the request. As a result, the initial getUuid() method in zedclient will fail, since it starts early before attestation, and at that point system will not have any integrity token to use. - Since zedclient uses /config primarily for getting UUID of the device and other fields such as Manufacturer, Model etc, having a separate endpoint for that makes sense, and this PR adds protobuf fields for the same. Signed-off-by: Hariharasubramanian C S --- api/APIv2.md | 26 +++++++++++++++++++++++++- api/proto/uuid/uuid.proto | 26 ++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 api/proto/uuid/uuid.proto diff --git a/api/APIv2.md b/api/APIv2.md index e80b4e2499..d562184b8c 100644 --- a/api/APIv2.md +++ b/api/APIv2.md @@ -56,6 +56,7 @@ In general, there is one directory for each API endpoint: * `logs`: The LogBundle message sent from Device to Controller containing internal device logs. * `apps/instanceid/{app-instance-uuid}/logs`: The LogBundle message sent from Device to Controller containing application console device logs. * `certs`: The ZControllerCert message is sent from Controller to Device, and contains the list of certificates used by Controller. Each ZControllerCert message replaces the current list on the device with the new list of certificates. Therefore, if an empty list is sent, it resets the list on the receiving side. +* `uuid`: This API is used by the device to fetch its unique idenitifier allocated by the Controller. Along with the uuid, the reply for this request will also contain manufacturer and product model of the device. * `attest`: This API anchors all trust and attestation operations from the device. At the top level, the device does a POST of `ZAttestReq` and gets `ZAttestResp` as the response from Controller. `ZAttestReq` supports 4 types of requests: @@ -189,7 +190,6 @@ The response MUST NOT contain any body content. Retrieve configuration for a specific Device. - POST /api/v2/edgeDevice/config (if the uuid is not yet known) POST /api/v2/edgeDevice/id/{uuid}/config Return codes: @@ -472,6 +472,30 @@ Edge Devices are expected to have intermittent connectivity, with limited bandwi The choice of which messages to keep, how long to keep them, which to discard, and how to handle these overflows are implementation-dependent and are NOT specified in this document. +### UUID + +Retrieve uuid for a specific Device. + + POST /api/v2/edgeDevice/uuid + +Return codes: + +* Unauthenticated or invalid credentials: `401` +* Valid credentials without authorization: `403` +* Success: `200` +* Unknown Device: `400` +* Controller is unavailable e.g., being upgraded: `503` + +Request: + +The request mime type MUST be "application/x-proto-binary". +The request MUST have the body of a single protobuf message of type AuthContainer where the AuthBody is a protobuf message of type [uuid.UuidRequest](./proto/uuid/uuid.proto). The message should include device certificate of the edge device. + +Response: + +The response mime type MUST be "application/x-proto-binary". +The response MUST contain a single protobuf message of type AuthContainer where the AuthBody is a protobuf message of type [uuid.UuidResponse](./proto/uuid/uuid.proto). It must include UUID of the device, along with other fields such as device's registered name, Manufacturer, Model, Enterprise. + ## HTTP MetaData Edge Devices may send some MetaData in HTTP header to the controller. This will help diff --git a/api/proto/uuid/uuid.proto b/api/proto/uuid/uuid.proto new file mode 100644 index 0000000000..1b2a6b295a --- /dev/null +++ b/api/proto/uuid/uuid.proto @@ -0,0 +1,26 @@ +// Copyright(c) 2020 Zededa, Inc. +// All rights reserved. + +syntax = "proto3"; + +package org.lfedge.eve.uuid; + +option go_package = "github.com/lf-edge/eve/api/go/uuid"; +option java_package = "org.lfedge.eve.uuid"; +option java_multiple_files = true; +option java_outer_classname = "EveUuid"; + +// This is the request payload for POST /api/v2/edgeDevice/uuid +// The message is assumed to be protected by signing envelope +message UuidRequest{ + bytes device_cert = 1; //Device certificate +} + +// This is the response payload for POST /api/v2/edgeDevice/uuid +// The message is assumed to be protected by signing envelope +message UuidResponse{ + string uuid = 1; //UUID of this edge device + string manufacturer = 2; //Manufacturer, as per Controller + string product_name = 3; //Product name, as per Controller +} +