requisition_fulfillment_service.proto

// Copyright 2020 The Cross-Media Measurement Authors
//
// 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 wfa.measurement.api.v2alpha;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "wfa/measurement/api/v2alpha/requisition.proto";

option java_package = "org.wfanet.measurement.api.v2alpha";
option java_multiple_files = true;
option java_outer_classname = "RequisitionFulfillmentServiceProto";

// Duchy service for fulfilling `Requisition`s.
service RequisitionFulfillment {
  // Fulfills a `Requisition`.
  rpc FulfillRequisition(stream FulfillRequisitionRequest)
      returns (FulfillRequisitionResponse) {}
}

// Request message for `FulfillRequisition` method.
message FulfillRequisitionRequest {
  // The header message for this streaming request.
  // (-- api-linter: core::0123::resource-annotation=disabled
  //     aip.dev/not-precedent: This is not a resource message. --)
  message Header {
    // Resource name of the `Requisition`.
    string name = 1 [
      (google.api.resource_reference).type = "halo.wfanet.org/Requisition",
      (google.api.field_behavior) = REQUIRED
    ];

    // The fingerprint of the `Requisition`.
    //
    // This is defined as the SHA256 hash of the concatenation of:
    // 1. The `data` in `measurement_spec` from the `Requisition`.
    // 2. The SHA256 hash of `encrypted_requisition_spec` from the
    //    `Requisition`.
    bytes requisition_fingerprint = 2 [(google.api.field_behavior) = REQUIRED];

    // The `nonce` value from the `encrypted_requisition_spec`.
    // (-- api-linter: core::0141::forbidden-types=disabled
    //     aip.dev/not-precedent: This is a random 64-bit value. --)
    fixed64 nonce = 3 [(google.api.field_behavior) = REQUIRED];

    // Requisitions of ShuffleBasedSecretSharing protocol is fulfilled by either
    // a blob or a seed.
    message ShuffleBasedSecretSharing {
      // The seed can be expanded into a deterministic blob using the same PRNG.
      bytes seed = 1;
    }
    // Protocol specified values.
    oneof protocol {
      // Shuffle based secret sharing protocol. Fulfilled by either chunks (a
      // blob), or a seed.
      ShuffleBasedSecretSharing shuffle_based_secret_sharing = 4;
    }
  }

  // The chunk message for this streaming request.
  message BodyChunk {
    // The portion of the data for this `BodyChunk`.
    //
    // The format of the data depends on the corresponding `MeasurementSpec`. If
    // the `Requisition` is for an encrypted sketch, this is the register
    // data as documented in the `Sketch` message (sketch.proto) encrypted using
    // the combined `Duchy` ElGamal public keys. The only alignment requirement
    // is by bytes: a chunk might begin or end in the middle of a single
    // register.
    //
    // The optimal size of this field is one that would result in the
    // `FulfillRequisitionRequest` message being between 16KiB and 64KiB.
    // See https://github.com/grpc/grpc.github.io/issues/371
    bytes data = 1 [(google.api.field_behavior) = REQUIRED];
  }

  // Request message payload. Exactly one of these must be specified.
  oneof payload {
    // The header for this streaming request, specified as the payload for the
    // first request message.
    Header header = 1;

    // The body chunk for this streaming request, specified on subsequent
    // request messages to the first one containing the header.
    BodyChunk body_chunk = 2;
  }
}

// Response message for `FulfillRequisition` method.
message FulfillRequisitionResponse {
  // Resulting state of the `Requisition`.
  Requisition.State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}