1// Copyright 2023 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//      http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14syntax = "proto3";
15
16package cobalt;
17
18option java_multiple_files = true;
19option java_package = "com.google.cobalt";
20
21////////////////////////////////////////////////////////////////////////////////
22// NOTE: This file is used by the Cobalt client and the Cobalt servers.
23// The source-of-truth of this file is located in Google's internsl code
24// repository, and the file is copied to Android where it is used by the Cobalt
25// client. Do not edit the copy of this file in this Android repo as those edits
26// will be overwritten when the file is next copied.
27////////////////////////////////////////////////////////////////////////////////
28
29// An EncryptedMessage carries the encrypted bytes of another proto message,
30// along with information about how it is encrypted.
31//
32// Observations collected via Cobalt are doubly encrypted. First each individual
33// message is encrypted to the Analyzer that will process it. Second each
34// Envelope containing many observations is encrypted to the Shuffler. We use
35// the EncryptedMessage proto to carry the ciphertext in both cases.
36//
37message EncryptedMessage {
38
39  // The different schemes used in Cobalt to encrypt a message.
40  enum EncryptionScheme {
41    // The message is not encrypted. |ciphertext| contains plaintext bytes of a
42    // serialized protocol buffer message. This scheme must only be used in
43    // tests.
44    NONE = 0;
45
46    // Hybrid Cipher using elliptic curve Diffie-Hellman, version 1.
47    HYBRID_ECDH_V1 = 1;
48
49    // Hybrid cipher compatible with Tink hybrid encryption/decryption
50    // primitives declared in
51    // third_party/tink/cc/hybrid/hybrid_key_templates.h
52    // Multiple hybrid encryption schemes are supported and indicated by the
53    // type of key used.
54    HYBRID_TINK = 2;
55  }
56  // Which scheme was used to encrypt this message?
57  EncryptionScheme scheme = 1;
58
59  // Which key was used to encrypt this message?
60  // This key is mutually exclusive with |scheme| being set.
61  uint32 key_index = 4;
62
63  // 32-byte fingerprint (SHA256) of the recipient’s public key.
64  // This is used to facilitate key rotation.
65  bytes public_key_fingerprint = 2;
66
67  //  The |contribution_id| field is a cryptographically-secure random number
68  //  generated and attached by the Cobalt client. The shuffler counts the
69  //  number of unique ids to determine the contribution count per report.
70  //
71  //  This field should only be set when the |ciphertext| contains a
72  //  cobalt.Observation that should be counted towards the shuffler threshold.
73  //  All other encrypted messages should not receive a |contribution_id|.
74  //
75  //  Once an observation is encrypted and assigned a |contribution_id| it
76  //  should never be given another id or stored unencrypted.
77  bytes contribution_id = 5;
78
79  // The |ciphertext| field contains the bytes of the encryption of the standard
80  // serialization of one of the following types of proto messages:
81  //
82  // - A cobalt.Envelope, as defined in Cobalt's envelope.proto.
83  //   EncryptedMessages containing Envelopes are the input to the Shuffler.
84  //
85  // - A cobalt.Observation, as defined in Cobalt's observation.proto.
86  //   An ObservationBatch (defined in observation_batch.proto) contains
87  //   EncryptedMessages of this type. ObservationBatches are output from the
88  //   Shuffler.
89  bytes ciphertext = 3;
90}
91