proto/api.proto

// Copyright 2019-2020 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 "trillian.proto";

message InclusionProof {
  trillian.Proof proof = 1;
  trillian.SignedLogRoot sth = 2;
}

message AddVBMetaRequest {
  // 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 64kB.
  bytes vbmeta = 1;

  // Serialized SignedVBMetaPrimaryAnnotation. This annotation contains the hash
  // of the vbmeta structure. It is signed using the manufacturer key.
  // See types/types.go.
  bytes signed_vbmeta_primary_annotation = 2;
}

message AddVBMetaResponse {
  // Inclusion proof and the leaf that was added to the log, which contains
  // the annotation on VBMeta.
  // 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 annotation_proof = 1;
  bytes          annotation_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 AnnotateVBMetaWithBuildRequest {
  // Serialized SignedVBMetaBuildAnnotation.  This annotation contains the hash
  // of the full build image. See types/types.go.
  bytes signed_vbmeta_build_annotation = 1;

  // Bytes of the binary images. The hash value of the concatenation of these
  // chunk is contained in SignedVBMetaBuildAnnotation.
  // 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 AnnotateVBMetaWithBuildResponse {
  // 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  annotation_proof = 1;
  bytes           annotation_leaf = 2;
}

service AFTLog {

  // Insert a new VBMeta structure into the log.
  // This request will effectively create 2 log entries:
  //  - VBMeta itself
  //  - Vendor annotations, which includes a reference to the VBMeta.
  rpc AddVBMeta(AddVBMetaRequest) returns (AddVBMetaResponse) {}

  // Upload (or copy) the complete firmware image.
  rpc AnnotateVBMetaWithBuild(stream AnnotateVBMetaWithBuildResponse) returns (AnnotateVBMetaWithBuildResponse) {}

  // TODO(tweek): GetProofByHash, GetSthConsistency, GetEntries, GetRootKeys
}