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. 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 AEAD = 4; 40} 41 42// Supported encryption schemes 43enum EncScheme { 44 // No encryption 45 NONE = 1; 46 AES_256_CBC = 2; 47 AES_256_GCM_SIV = 3; 48} 49 50message Header { 51 required SigScheme signature_scheme = 1; 52 required EncScheme encryption_scheme = 2; 53 // Identifies the verification key 54 optional bytes verification_key_id = 3; 55 // Identifies the decryption key 56 optional bytes decryption_key_id = 4; 57 // Encryption may use an IV 58 optional bytes iv = 5; 59 // Arbitrary per-protocol public data, to be sent with the plain-text header 60 optional bytes public_metadata = 6; 61 // The length of some associated data this is not sent in this SecureMessage, 62 // but which will be bound to the signature. 63 optional uint32 associated_data_length = 7 [default = 0]; 64 // Encryption may use a nonce. Required for AES-256-GCM-SIV. 65 optional bytes nonce = 8; 66} 67 68message HeaderAndBody { 69 // Public data about this message (to be bound in the signature) 70 required Header header = 1; 71 // Payload data 72 required bytes body = 2; 73} 74 75// ------- 76// The remainder of the messages defined here are provided only for 77// convenience. They are not needed for SecureMessage proper, but are 78// commonly useful wherever SecureMessage might be applied. 79// ------- 80 81// A list of supported public key types 82enum PublicKeyType { 83 EC_P256 = 1; 84 RSA2048 = 2; 85 // 2048-bit MODP group 14, from RFC 3526 86 DH2048_MODP = 3; 87} 88 89// A convenience proto for encoding NIST P-256 elliptic curve public keys 90message EcP256PublicKey { 91 // x and y are encoded in big-endian two's complement (slightly wasteful) 92 // Client MUST verify (x,y) is a valid point on NIST P256 93 required bytes x = 1; 94 required bytes y = 2; 95} 96 97// A convenience proto for encoding RSA public keys with small exponents 98message SimpleRsaPublicKey { 99 // Encoded in big-endian two's complement 100 required bytes n = 1; 101 optional int32 e = 2 [default = 65537]; 102} 103 104// A convenience proto for encoding Diffie-Hellman public keys, 105// for use only when Elliptic Curve based key exchanges are not possible. 106// (Note that the group parameters must be specified separately) 107message DhPublicKey { 108 // Big-endian two's complement encoded group element 109 required bytes y = 1; 110} 111 112message GenericPublicKey { 113 required PublicKeyType type = 1; 114 optional EcP256PublicKey ec_p256_public_key = 2; 115 optional SimpleRsaPublicKey rsa2048_public_key = 3; 116 // Use only as a last resort 117 optional DhPublicKey dh2048_public_key = 4; 118} 119