1// Copyright 2020 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//     https://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.
14
15// Proto definitions for SecureMessage format
16
17syntax = "proto2";
18
19package securemessage;
20
21option optimize_for = LITE_RUNTIME;
22option java_package = "com.google.security.cryptauth.lib.securemessage";
23option java_outer_classname = "SecureMessageProto";
24option objc_class_prefix = "SMSG";
25
26message SecureMessage {
27  // Must contain a HeaderAndBody message
28  required bytes header_and_body = 1;
29  // Signature of header_and_body
30  required bytes signature = 2;
31}
32
33// Supported "signature" schemes (both symmetric key and public key based)
34enum SigScheme {
35  HMAC_SHA256 = 1;
36  ECDSA_P256_SHA256 = 2;
37  // Not recommended -- use ECDSA_P256_SHA256 instead
38  RSA2048_SHA256 = 3;
39}
40
41// Supported encryption schemes
42enum EncScheme {
43  // No encryption
44  NONE = 1;
45  AES_256_CBC = 2;
46}
47
48message Header {
49  required SigScheme signature_scheme = 1;
50  required EncScheme encryption_scheme = 2;
51  // Identifies the verification key
52  optional bytes verification_key_id = 3;
53  // Identifies the decryption key
54  optional bytes decryption_key_id = 4;
55  // Encryption may use an IV
56  optional bytes iv = 5;
57  // Arbitrary per-protocol public data, to be sent with the plain-text header
58  optional bytes public_metadata = 6;
59  // The length of some associated data this is not sent in this SecureMessage,
60  // but which will be bound to the signature.
61  optional uint32 associated_data_length = 7 [default = 0];
62}
63
64message HeaderAndBody {
65  // Public data about this message (to be bound in the signature)
66  required Header header = 1;
67  // Payload data
68  required bytes body = 2;
69}
70
71// Must be kept wire-format compatible with HeaderAndBody. Provides the
72// SecureMessage code with a consistent wire-format representation that
73// remains stable irrespective of protobuf implementation choices. This
74// low-level representation of a HeaderAndBody should not be used by
75// any code outside of the SecureMessage library implementation/tests.
76message HeaderAndBodyInternal {
77  // A raw (wire-format) byte encoding of a Header, suitable for hashing
78  required bytes header = 1;
79  // Payload data
80  required bytes body = 2;
81}
82
83// -------
84// The remainder of the messages defined here are provided only for
85// convenience. They are not needed for SecureMessage proper, but are
86// commonly useful wherever SecureMessage might be applied.
87// -------
88
89// A list of supported public key types
90enum PublicKeyType {
91  EC_P256 = 1;
92  RSA2048 = 2;
93  // 2048-bit MODP group 14, from RFC 3526
94  DH2048_MODP = 3;
95}
96
97// A convenience proto for encoding NIST P-256 elliptic curve public keys
98message EcP256PublicKey {
99  // x and y are encoded in big-endian two's complement (slightly wasteful)
100  // Client MUST verify (x,y) is a valid point on NIST P256
101  required bytes x = 1;
102  required bytes y = 2;
103}
104
105// A convenience proto for encoding RSA public keys with small exponents
106message SimpleRsaPublicKey {
107  // Encoded in big-endian two's complement
108  required bytes n = 1;
109  optional int32 e = 2 [default = 65537];
110}
111
112// A convenience proto for encoding Diffie-Hellman public keys,
113// for use only when Elliptic Curve based key exchanges are not possible.
114// (Note that the group parameters must be specified separately)
115message DhPublicKey {
116  // Big-endian two's complement encoded group element
117  required bytes y = 1;
118}
119
120message GenericPublicKey {
121  required PublicKeyType type = 1;
122  optional EcP256PublicKey ec_p256_public_key = 2;
123  optional SimpleRsaPublicKey rsa2048_public_key = 3;
124  // Use only as a last resort
125  optional DhPublicKey dh2048_public_key = 4;
126}
127