export.proto

// Copyright 2020 the Exposure Notifications Server 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 = "proto2";

option go_package = "github.com/google/exposure-notifications-server/internal/pb/export;export";

// Protobuf definition for exports of confirmed temporary exposure keys.
//
// The full file format is documented under "Exposure Key Export File Format
// and Verification" at https://www.google.com/covid19/exposurenotifications/
//
// These files have a 16-byte, space-padded header before the protobuf data
// starts. They will be contained in a zip archive, alongside a signature
// file verifying the contents.
message TemporaryExposureKeyExport {
  // Time window of keys in this file based on arrival to server, in UTC
  // seconds. start_timestamp, end_timestamp, and batch_num must be unique
  // at any given snapshot of the index for a server. If multiple
  // files are used for a specific time period, and batch_num/batch_size
  // are both 1 (See below), then offsetting the end_timestamp is the
  // suggested method for forcing uniqueness.
  optional fixed64 start_timestamp = 1;
  optional fixed64 end_timestamp = 2;

  // Region for which these keys came from (e.g., country)
  optional string region = 3;

  // E.g., Batch 2 of 10. Ordinal, 1-based numbering.
  // Note: Not yet supported on iOS. Use values of 1 for both.
  optional int32 batch_num = 4;
  optional int32 batch_size = 5;

  // Information about signatures
  // If there are multiple entries, they must be ordered in descending
  // time order by signing key effective time (most recent one first).
  // There is a limit of 10 signature infos per export file (mobile OS may
  // not check anything after that).
  repeated SignatureInfo signature_infos = 6;

  // The TemporaryExposureKeys for initial release of keys.
  // Keys should be included in this list for initial release,
  // whereas revised or revoked keys should go in revised_keys.
  repeated TemporaryExposureKey keys = 7;

  // TemporaryExposureKeys that have changed status.
  // Keys should be included in this list if they have changed status
  // or have been revoked.
  repeated TemporaryExposureKey revised_keys = 8;
}

message SignatureInfo {
  // No longer need to set these. Old code that still does will be fine
  // as these were largely noops anyway.
  reserved 1, 2;
  reserved "app_bundle_id", "android_package";
  // Key version for rollovers
  // Must be in character class [a-zA-Z0-9_]. E.g., 'v1'
  optional string verification_key_version = 3;
  // Alias with which to identify public key to be used for verification
  // Must be in character class [a-zA-Z0-9_]
  // For cross-compatibility with Apple, use MCC
  // (https://en.wikipedia.org/wiki/Mobile_country_code).
  optional string verification_key_id = 4;
  // ASN.1 OID for Algorithm Identifier. Supported algorithms are
  // either 1.2.840.10045.4.3.2 or 1.2.840.10045.4.3.4
  optional string signature_algorithm = 5;
}

message TemporaryExposureKey {
  // Key of infected user
  optional bytes key_data = 1;

  // Varying risks associated with exposure depending on type of verification
  // Ignored by the v1.5 client API when report_type is set.
  optional int32 transmission_risk_level = 2 [deprecated = true];

  // The interval number since epoch for which a key starts
  optional int32 rolling_start_interval_number = 3;

  // Increments of 10 minutes describing how long a key is valid
  optional int32 rolling_period = 4 [default = 144];  // defaults to 24 hours

  // Data type representing why this key was published.
  enum ReportType {
    UNKNOWN = 0;  // Never returned by the client API.
    CONFIRMED_TEST = 1;
    CONFIRMED_CLINICAL_DIAGNOSIS = 2;
    SELF_REPORT = 3;
    RECURSIVE = 4;
    REVOKED = 5;  // Used to revoke a key, never returned by client API.
  }

  // Type of diagnosis associated with a key.
  optional ReportType report_type = 5;

  // Number of days elapsed between symptom onset and the TEK being used.
  // E.g. 2 means TEK is 2 days after onset of symptoms.
  optional sint32 days_since_onset_of_symptoms = 6;

  // Tag 7 is reserved for future use.

  // Data type representing a variant of concern.
  enum VariantOfConcern {
    VARIANT_TYPE_UNKNOWN = 0;
    VARIANT_TYPE_1 = 1;  // Vaccine is effective
    VARIANT_TYPE_2 = 2;  // Highly transmissive
    VARIANT_TYPE_3 = 3;  // High severity
    VARIANT_TYPE_4 = 4;  // Vaccine breakthrough
  }

  // Type of variant of concern associated with a key.
  optional VariantOfConcern variant_of_concern = 8 [default = VARIANT_TYPE_UNKNOWN];
}

message TEKSignatureList {
  // When there are multiple signatures, they must be sorted in time order
  // by first effective date for the signing key in descending order.
  // The most recent effective signing key must appear first.
  // There is a limit of 10 signature infos per export file (mobile OS may
  // not check anything after that).
  repeated TEKSignature signatures = 1;
}

message TEKSignature {
  // Info about the signing key, version, algorithm, etc.
  optional SignatureInfo signature_info = 1;
  // E.g., Batch 2 of 10
  // Must match fields from TemporaryExposureKeyExport, see
  // documentation on that message.
  optional int32 batch_num = 2;
  optional int32 batch_size = 3;
  // Signature in X9.62 format (ASN.1 SEQUENCE of two INTEGER fields)
  optional bytes signature = 4;
}