blob: cfc125fe82f31e49988faf544f143c3d8b0b40a9 [file] [log] [blame]
// Copyright 2017 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////
// Definitions for Cloud Crypto SDK (Tink) library.
syntax = "proto3";
package google.crypto.tink;
option java_package = "com.google.crypto.tink.proto";
option java_multiple_files = true;
option objc_class_prefix = "TINKPB";
option go_package = "github.com/google/tink/proto/tink_go_proto";
// Each instantiation of a Tink primitive is identified by type_url,
// which is a global URL pointing to a *Key-proto that holds key material
// and other parameters of the instantiation. For standard Tink key types
// the value of type_url follows the structure of type_url-field of
// google.protobuf.Any-protos, and is given as:
//
// type.googleapis.com/packagename.messagename
//
// For example, for an HMAC key defined in proto google.cloud.tink.HmacKey
// the value of type_url is:
//
// type.googleapis.com/google.cloud.tink.HmacKey
//
// For each type_url, in addition to the *Key proto, there exist two
// related structures:
// 1. *Params: parameters of an instantiation of the primitive,
// needed when a key is being used.
// 2. *KeyFormat: parameters needed to generate a new key; these
// include the corresponding Params, since when a factory generates
// a key based on KeyFormat, it must add Params to the resulting
// key proto with the actual key material.
// The actual *KeyFormat proto is wrapped in a KeyTemplate message.
// By convention, the name of the *KeyFormat-proto must be equal
// to the name of the *Key-proto from type_url-field suffixed with "Format".
message KeyTemplate {
// Required.
string type_url = 1; // in format type.googleapis.com/packagename.messagename
// Optional.
// If missing, it means the key type doesn't require a *KeyFormat proto.
bytes value = 2; // contains specific serialized *KeyFormat proto
// Optional.
// If missing, uses OutputPrefixType.TINK.
OutputPrefixType output_prefix_type = 3;
}
enum KeyStatusType {
UNKNOWN_STATUS = 0;
ENABLED = 1; // Can be used for crypto operations.
DISABLED = 2; // Cannot be used, but exists and can become ENABLED.
DESTROYED = 3; // Key data does not exist in this Keyset any more.
}
// Tink produces and accepts ciphertexts or signatures that consist
// of a prefix and a payload. The payload and its format is determined
// entirely by the primitive, but the prefix has to be one of the following
// 4 types:
// - Legacy: prefix is 5 bytes, starts with \x00 and followed by a 4-byte
// key id that is computed from the key material.
// - Crunchy: prefix is 5 bytes, starts with \x00 and followed by a 4-byte
// key id that is generated randomly.
// - Tink : prefix is 5 bytes, starts with \x01 and followed by 4-byte
// key id that is generated randomly.
// - Raw : prefix is 0 byte, i.e., empty.
enum OutputPrefixType {
UNKNOWN_PREFIX = 0;
TINK = 1;
LEGACY = 2;
RAW = 3;
// CRUNCHY is like LEGACY, but with two differences:
// - Its key id is generated randomly (like TINK)
// - Its signature schemes don't append zero to sign messages
CRUNCHY = 4;
}
// Each *Key proto by convention contains a version field, which
// identifies the version of implementation that can work with this key.
// message SomeInstantiationKey {
// uint32 version = 1;
// ...
// }
// Version is a monotonic counter: each implementation of a primitive
// has its associated "current version", which starts at 0 and is incremented
// upon updates of the code/key proto. A key with version n needs
// an implementation version n or higher to work.
// For public key primitives, the public and private keys are distinct entities
// and represent distinct primitives. However, by convention, the private key
// of a public-key primitive contains the corresponding public key proto.
// The actual *Key-proto is wrapped in a KeyData message, which in addition
// to this serialized proto contains also type_url identifying the
// definition of *Key-proto (as in KeyFormat-message), and some extra metadata
// about the type key material.
message KeyData {
// Required.
string type_url = 1; // In format type.googleapis.com/packagename.messagename
// Required.
bytes value = 2; // contains specific serialized *Key proto
enum KeyMaterialType {
UNKNOWN_KEYMATERIAL = 0;
SYMMETRIC = 1;
ASYMMETRIC_PRIVATE = 2;
ASYMMETRIC_PUBLIC = 3;
REMOTE = 4; // points to a remote key, i.e., in a KMS.
}
// Required.
KeyMaterialType key_material_type = 3;
}
// A Tink user works usually not with single keys, but with keysets,
// to enable key rotation. The keys in a keyset can belong to different
// implementations/key types, but must all implement the same primitive.
// Any given keyset (and any given key) can be used for one primitive only.
message Keyset {
message Key {
// Contains the actual, instantiation specific key proto.
// By convention, each key proto contains a version field.
KeyData key_data = 1;
KeyStatusType status = 2;
// Identifies a key within a keyset, is a part of metadata
// of a ciphertext/signature.
uint32 key_id = 3;
// Determines the prefix of the ciphertexts/signatures produced by this key.
// This value is copied verbatim from the key template.
OutputPrefixType output_prefix_type = 4;
}
// Identifies key used to generate new crypto data (encrypt, sign).
// Required.
uint32 primary_key_id = 1;
// Actual keys in the Keyset.
// Required.
repeated Key key = 2;
}
// Represents a "safe" Keyset that doesn't contain any actual key material,
// thus can be used for logging or monitoring. Most fields are copied from
// Keyset.
message KeysetInfo {
message KeyInfo {
// the type url of this key,
// e.g., type.googleapis.com/google.crypto.tink.HmacKey.
string type_url = 1;
// See Keyset.Key.status.
KeyStatusType status = 2;
// See Keyset.Key.key_id.
uint32 key_id = 3;
// See Keyset.Key.output_prefix_type.
OutputPrefixType output_prefix_type = 4;
}
// See Keyset.primary_key_id.
uint32 primary_key_id = 1;
// KeyInfos in the KeysetInfo.
// Each KeyInfo is corresponding to a Key in the corresponding Keyset.
repeated KeyInfo key_info = 2;
}
// Represents a keyset that is encrypted with a master key.
message EncryptedKeyset {
// Required.
bytes encrypted_keyset = 2;
// Optional.
KeysetInfo keyset_info = 3;
}