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