Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introducing protobuf file for the new /uuid endpoint #1284

Merged
merged 1 commit into from
Aug 11, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 25 additions & 1 deletion api/APIv2.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down
26 changes: 26 additions & 0 deletions api/proto/uuid/uuid.proto
Original file line number Diff line number Diff line change
@@ -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
}