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