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/protocol_config.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];

    // The protocol config of the Computation. This is used to validate that
    // EDPs and the MPC are using the same protocol config.
    //
    // Required for HonestMajorityShareShuffle protocol. LiquidLegionsV2
    // protocols will require this field in the future.
    ProtocolConfig protocol_config = 4;

    // Protocol specified values for HonestMajorityShareShuffle.
    //
    // A Requisition of HonestMajorityShareShuffle protocol is fulfilled by
    // either a seed or a blob of `BodyChunk`s.
    message HonestMajorityShareShuffle {
      // The seed is sampled by the DataProvider and can be expanded into a
      // deterministic blob using the same PRNG function.
      //
      // If the seed is not specified, it means the requisition is
      // fulfilled by a blob of `BodyChunk`s.
      bytes seed = 1;
    }
    // Protocol specified values.
    oneof protocol {
      // Honest Majority Shuffle based secret sharing protocol. Fulfilled by
      // either chunks (a blob), or a seed.
      HonestMajorityShareShuffle honest_majority_share_shuffle = 5;
    }
  }

  // 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` and
    // `ProtocolConfig`.
    //
    // If the `Requisition` is for an encrypted sketch for LiquidLegionV2
    // protocols, this is the register data as documented in the `Sketch`
    // message (sketch.proto) encrypted using the combined `Duchy` ElGamal
    // public keys.
    //
    // If the `Requisition` is a sketch for HonestMajorityShareShuffle protocol,
    // this is an array of counts as registers.
    //
    // 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];
}