proto/api.proto

// Copyright 2019 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package aftl;
option go_package = "proto";

import "aftl.proto";

message AddFirmwareInfoRequest {
  // VBMeta structure as described in
  // https://android.googlesource.com/platform/external/avb/+/master/README.md.
  // In case of chained partitions, each VBMeta is added via a separate call.
  // The default size for gRPC payload is about 4MB. We expect vbmeta to be
  // in the order of 1kB.
  bytes vbmeta = 1;

  SignedFirmwareInfo fw_info = 2;
}

message AddFirmwareInfoResponse {
  // Inclusion proof and the leaf that was added to the log, which contains
  // information on the firmware.
  // It is required to have the complete leaf to validate the inclusion proof.
  // For on-device verification, only these first 2 fields are required to
  // validate the inclusion.
  InclusionProof fw_info_proof = 1;
  bytes          fw_info_leaf = 2;

  // Inclusion proof and leaf that was added to the log, which contains the full
  // vbmeta partition.
  // These fields are NOT required for validation but can still be recorded by a
  // vendor to prove that the complete VBMeta was submitted.
  InclusionProof vbmeta_proof = 3;
  bytes          vbmeta_leaf = 4;
}

message AddFirmwareImageRequest {

  SignedFirmwareImageInfo fw_image_info = 1;

  // Bytes of the binary images. These are not signed as their final
  // hash value is already signed in fw_image_info.hash
  // This is ignored if any of the requests origin_url is set.
  bytes image_chunk = 2;

  // Origin location of image. It is used to get a copy of the binary image
  // from another server (e.g., Google Cloud Storage).
  string origin_url = 3;
}

message AddFirmwareImageResponse {

  // Inclusion proof and leaf for the firmware image. The leaf contains the URL
  // where the image was stored.
  // It is not required for vendors to keep this information. However, this can
  // be used for their records to ensure the correctness of the log.
  InclusionProof fw_image_info_proof = 1;
  Leaf           fw_image_info_leaf = 2;
}

service AFTLog {

  // Insert a new VBMeta structure into the log.
  // This request will effectively create 2 log entries:
  //  - VBMeta itself
  //  - Vendor annotations, including a reference to the VBMeta leaf.
  rpc AddFirmwareInfo(AddFirmwareInfoRequest) returns (AddFirmwareInfoResponse) {}

  // Upload (or copy) the complete firmware image.
  rpc AddFirmwareImage(stream AddFirmwareImageRequest) returns (AddFirmwareImageResponse) {}

  // TODO GetProofByHash, GetSthConsistency, GetEntries, GetRootKeys
}