covidshield.proto

syntax = "proto2";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

package covidshield;
option go_package="pkg/proto/covidshield";

// Clients will receive a One Time Code via some external channel (i.e. SMS or
// verbal). Then, upon issuing THIS request, they will generate a new keypair.
// If the response comes back successful, the app_public_key (and the
// corresponding private key) and the returned server_public_key will be kept in
// local storage for the duration of this reporting window (the next 14 days).
//
// app_public_keys must not be re-used for new KeyClaimRequests, or the requests
// will fail.
message KeyClaimRequest {
  // one_time_code is the code received from the testing portal.
  required string one_time_code = 1; // 8 numerical digits
  // app_public_key is generated locally and saved upon successful request
  // completion.
  required bytes app_public_key = 2; // 32 bytes
}

// KeyClaimResponse is received from the server in response to a
// KeyClaimRequest. If the request was successful, error will be NONE and
// server_public_key will be set.
message KeyClaimResponse {
  enum ErrorCode {
    NONE = 0;
    UNKNOWN = 1;
    INVALID_ONE_TIME_CODE = 2;
    SERVER_ERROR = 3;
    // Indicates the key is invalid, or already registered.
    INVALID_KEY = 4;
    TEMPORARY_BAN = 5;
  }
  optional ErrorCode error = 1;
  optional bytes server_public_key = 2; // 32 bytes
  optional uint32 tries_remaining = 3;
  optional google.protobuf.Duration remaining_ban_duration = 4;
}

// We are using a NaCl Box (Curve25519+XSalsa20+Poly1305) to encrypt and
// authorize messages.
//
// Note that we are not *explicitly* signing the payload: NaCl Box provides
// non-repudiability for the receiving party.  The receiving party (and only
// the receiving party) could forge the sender's signature on this message, but
// we there's no need or possibility for third-party verification in this
// scheme.
//
// See "Security Model" at https://nacl.cr.yp.to/box.html
message EncryptedUploadRequest {
  // server_public_key is provided by the Diagnosis Server to the App, and is
  // used to encrypt the payload. This key should be stored locally for 14
  // days, and used to submit the follow-up Diagnosis Key.
  required bytes server_public_key = 1; // 32 bytes
  // app_public_key is the public side of a keypair generated once by the
  // application and linked to the server_public_key. These are linked in the
  // Diagnosis Server, so that only one app_public_key is authorized to upload
  // for a given server_public_key. If a new server_public_key is issued to an App
  // (e.g. months later), a new app_public_key should be generated.
  required bytes app_public_key = 2; // 32 bytes
  // nonce must be 24 random bytes, and absolutely must NOT be re-used between
  // subsequent submissions of Diagnosis Keys. This nonce is passed to the
  // encryption library to generate the ciphertext.
  required bytes nonce = 3; // 24 bytes
  // payload is the result of encoding/marshalling, and then encrypting, an
  // `Upload` message. It is done this way rather than as an embedded message
  // field, because we need to encrypt a byte stream, not an object.
  required bytes payload = 4; // variable length
}

// EncryptedUploadResponse is received from the server in response to a
// EncryptedUploadRequest. If the request was successful, error will be NONE.
message EncryptedUploadResponse {
  enum ErrorCode {
    NONE = 0;
    UNKNOWN = 1;
    INVALID_KEYPAIR = 2;
    DECRYPTION_FAILED = 3;
    INVALID_PAYLOAD = 4;
    SERVER_ERROR = 5;
    INVALID_CRYPTO_PARAMETERS = 6;
    TOO_MANY_KEYS = 7;
    // The timestamp in the Upload message must be no more than one hour old,
    // otherwise this error is generated.
    INVALID_TIMESTAMP = 8;
    INVALID_ROLLING_PERIOD = 10;
    INVALID_KEY_DATA = 11;
    INVALID_ROLLING_START_INTERVAL_NUMBER = 12;
    INVALID_TRANSMISSION_RISK_LEVEL = 13;
    NO_KEYS_IN_PAYLOAD = 14;
  }
  required ErrorCode error = 1;
}

// Upload is the decrypted type of the `payload` field in EncryptedUploadRequest.
message Upload {
  // timestamp is just the current device time at message generation.
  required google.protobuf.Timestamp timestamp = 1;
  // keys returns from the ExposureNotification API.
  repeated TemporaryExposureKey keys = 2;
}

// Remaining messages imported from:
// https://developer.apple.com/documentation/exposurenotification/setting_up_an_exposure_notification_server
//
// And also referencing:
// https://developers.google.com/android/exposure-notifications/exposure-key-file-format
//
// The format of the /keys endpoints is a stream of serialized File
// messages, each length-prefixed with a big-endian uint32. Clients should take
// care to verify that the batch_size from the headers matches the total number
// of records received.
//
// Note, as a special case, that if there are no keys at all in the requested
// range, the total content of the response will be "\x00\x00\x00\x00"; that
// is, a big-endian uint32 of zero.
//
// In general, these definitions are copied from the resources above, but some
// of the documentation is clarified or merged.

message TemporaryExposureKeyExport {
  // Time window of keys in the file, based on arrival
  // at the server, in UTC seconds.
  optional fixed64 start_timestamp = 1;
  optional fixed64 end_timestamp = 2;

  // Region from which these keys came (for example, MCC, however, some schemes
  // use e.g. ISO-3166-2. There's no apparent hard requirement by the protocol
  // for the contents here).
  optional string region = 3;

  // Reserved for future use. Both batch_num and batch_size
  // must be set to a value of 1.
  optional int32 batch_num = 4;
  optional int32 batch_size = 5;

  // Information about associated signatures.
  repeated SignatureInfo signature_infos = 6;

  // The temporary exposure keys themselves.
  repeated TemporaryExposureKey keys = 7;
}

message SignatureInfo {
  // The first two fields have been deprecated
  reserved 1, 2;
  reserved "app_bundle_id", "android_package";

  // Key version in case the EN server signing key is rotated.
  optional string verification_key_version = 3;

  // Additional information to uniquely identify the public key associated with
  // the EN server's signing key (for example, the EN server might serve the
  // app from different countries with different keys).
  //
  // Three-digit mobile country code (MCC) for validating the key file.
  // If a region has more than one MCC, the server can choose
  // which MCC to use. This value does not have to match the client's MCC,
  // but must correspond to one of the supported MCCs for its region.
  optional string verification_key_id = 4;

  // All keys must be signed using the SHA-256 with ECDSA algorithm.
  // This field must contain the string "1.2.840.10045.4.3.2".
  optional string signature_algorithm = 5;
}

message TemporaryExposureKey {
  // Temporary exposure key.
  optional bytes key_data = 1;

  // Varying risk associated with a key depending on the diagnosis method.
  optional int32 transmission_risk_level = 2;

  // Number representing the beginning interval for temporary exposure
  // key validity (ENIntervalNumber).
  optional int32 rolling_start_interval_number = 3;

  // Number of intervals in a period.
  optional int32 rolling_period = 4 [default = 144];
}

message TEKSignatureList {
  // Information about associated signatures.
  repeated TEKSignature signatures = 1;
}

message TEKSignature {
  // Information to uniquely identify the public key associated 
  // with the EN server's signing key.
  optional SignatureInfo signature_info = 1;

  // Reserved for future use. Both batch_num and batch_size
  // must be set to a value of 1.
  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;
}