package covidshield

Get desktop application:
View/edit binary Protocol Buffers messages

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

• required bytes server_public_key = 1

  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.

  32 bytes

• required bytes app_public_key = 2

  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.

  32 bytes

• required bytes nonce = 3

  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.

  24 bytes

• required bytes payload = 4

  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.

  variable length

EncryptedUploadResponse is received from the server in response to a EncryptedUploadRequest. If the request was successful, error will be NONE.

• required EncryptedUploadResponse.ErrorCode error = 1

Used in: EncryptedUploadResponse

• NONE = 0

• UNKNOWN = 1

• INVALID_KEYPAIR = 2

• DECRYPTION_FAILED = 3

• INVALID_PAYLOAD = 4

• SERVER_ERROR = 5

• INVALID_CRYPTO_PARAMETERS = 6

• TOO_MANY_KEYS = 7

• INVALID_TIMESTAMP = 8

  The timestamp in the Upload message must be no more than one hour old, otherwise this error is generated.

• INVALID_ROLLING_PERIOD = 10

• INVALID_KEY_DATA = 11

• INVALID_ROLLING_START_INTERVAL_NUMBER = 12

• INVALID_TRANSMISSION_RISK_LEVEL = 13

• NO_KEYS_IN_PAYLOAD = 14

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.

• required string one_time_code = 1

  one_time_code is the code received from the testing portal.

  8 numerical digits

• required bytes app_public_key = 2

  app_public_key is generated locally and saved upon successful request completion.

  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.

• optional KeyClaimResponse.ErrorCode error = 1

• optional bytes server_public_key = 2

  32 bytes

• optional uint32 tries_remaining = 3

• optional google.protobuf.Duration remaining_ban_duration = 4

Used in: KeyClaimResponse

• NONE = 0

• UNKNOWN = 1

• INVALID_ONE_TIME_CODE = 2

• SERVER_ERROR = 3

• INVALID_KEY = 4

  Indicates the key is invalid, or already registered.

• TEMPORARY_BAN = 5

Used in: TEKSignature, TemporaryExposureKeyExport

• optional string verification_key_version = 3

  Key version in case the EN server signing key is rotated.

• optional string verification_key_id = 4

  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 signature_algorithm = 5

  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".

Used in: TEKSignatureList

• optional SignatureInfo signature_info = 1

  Information to uniquely identify the public key associated with the EN server's signing key.

• optional int32 batch_num = 2

  Reserved for future use. Both batch_num and batch_size must be set to a value of 1.

• optional int32 batch_size = 3

• optional bytes signature = 4

  Signature in X9.62 format (ASN.1 SEQUENCE of two INTEGER fields).

• repeated TEKSignature signatures = 1

  Information about associated signatures.

Used in: TemporaryExposureKeyExport, Upload

• optional bytes key_data = 1

  Temporary exposure key.

• optional int32 transmission_risk_level = 2

  Varying risk associated with a key depending on the diagnosis method.

• optional int32 rolling_start_interval_number = 3

  Number representing the beginning interval for temporary exposure key validity (ENIntervalNumber).

• optional int32 rolling_period = 4

  Number of intervals in a period.

• optional fixed64 start_timestamp = 1

  Time window of keys in the file, based on arrival at the server, in UTC seconds.

• optional fixed64 end_timestamp = 2

• optional string region = 3

  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 int32 batch_num = 4

  Reserved for future use. Both batch_num and batch_size must be set to a value of 1.

• optional int32 batch_size = 5

• repeated SignatureInfo signature_infos = 6

  Information about associated signatures.

• repeated TemporaryExposureKey keys = 7

  The temporary exposure keys themselves.

Upload is the decrypted type of the `payload` field in EncryptedUploadRequest.

• required google.protobuf.Timestamp timestamp = 1

  timestamp is just the current device time at message generation.

• repeated TemporaryExposureKey keys = 2

  keys returns from the ExposureNotification API.