Documentation
¶
Index ¶
- Variables
- type KeyMaterial
- func (*KeyMaterial) Descriptor() ([]byte, []int)deprecated
- func (x *KeyMaterial) GetCipher() KeyMaterial_Cipher
- func (x *KeyMaterial) GetEncryptedDek() []byte
- func (x *KeyMaterial) GetNamespace() string
- func (x *KeyMaterial) GetNonce() []byte
- func (x *KeyMaterial) GetOpaque() []byte
- func (x *KeyMaterial) GetVersion() string
- func (km *KeyMaterial) Marshal() ([]byte, error)
- func (*KeyMaterial) ProtoMessage()
- func (x *KeyMaterial) ProtoReflect() protoreflect.Message
- func (x *KeyMaterial) Reset()
- func (x *KeyMaterial) String() string
- func (km *KeyMaterial) Validate() error
- type KeyMaterial_Cipher
- func (KeyMaterial_Cipher) Descriptor() protoreflect.EnumDescriptor
- func (x KeyMaterial_Cipher) Enum() *KeyMaterial_Cipher
- func (KeyMaterial_Cipher) EnumDescriptor() ([]byte, []int)deprecated
- func (x KeyMaterial_Cipher) Number() protoreflect.EnumNumber
- func (x KeyMaterial_Cipher) String() string
- func (KeyMaterial_Cipher) Type() protoreflect.EnumType
Constants ¶
This section is empty.
Variables ¶
var ( KeyMaterial_Cipher_name = map[int32]string{ 0: "CIPHER_UNSPECIFIED", 1: "CIPHER_AES_256_GCM", 2: "CIPHER_CHACHA20_POLY1305", 3: "CIPHER_XCHACHA20_POLY1305", } KeyMaterial_Cipher_value = map[string]int32{ "CIPHER_UNSPECIFIED": 0, "CIPHER_AES_256_GCM": 1, "CIPHER_CHACHA20_POLY1305": 2, "CIPHER_XCHACHA20_POLY1305": 3, } )
Enum value maps for KeyMaterial_Cipher.
var File_api_ext_v1_key_material_proto protoreflect.FileDescriptor
Functions ¶
This section is empty.
Types ¶
type KeyMaterial ¶
type KeyMaterial struct {
// encrypted_dek is the wrapped DEK, as produced by whatever wrapping the
// extension server performs. It is the one field that must be set.
EncryptedDek []byte `protobuf:"bytes,1,opt,name=encrypted_dek,json=encryptedDek,proto3" json:"encrypted_dek,omitempty"`
// version identifies which version of the wrapping key sealed
// encrypted_dek, so a server that rotates key material can select the same
// version again on decrypt. Empty means the server does not version its
// keys.
Version string `protobuf:"bytes,2,opt,name=version,proto3" json:"version,omitempty"`
// namespace is the pre-translation (local) namespace the DEK belongs to,
// copied from EncryptRequest.namespace. A server that derives a key per
// namespace needs it to derive the same key on decrypt, where the request no
// longer carries it. Empty means the server does not key off the namespace.
Namespace string `protobuf:"bytes,3,opt,name=namespace,proto3" json:"namespace,omitempty"`
// opaque belongs to the extension server. Neither the proxy nor this message
// gives it any meaning: it is round-tripped untouched, so a server that needs
// more than version and namespace to find its key can put its own encoding
// here instead of replacing this framing wholesale. Whatever goes in owns its
// own compatibility, since the proxy cannot migrate what it cannot read.
Opaque []byte `protobuf:"bytes,4,opt,name=opaque,proto3" json:"opaque,omitempty"`
// nonce is the per-seal nonce the cipher required. It is in the clear because
// a nonce is not a secret, only single-use, and it has a field of its own
// rather than a corner of opaque so that opaque stays entirely the server's.
// Empty means the server carries its nonce some other way, or needs none.
Nonce []byte `protobuf:"bytes,5,opt,name=nonce,proto3" json:"nonce,omitempty"`
// cipher is the AEAD that sealed encrypted_dek. Empty means the server did
// its own wrapping and this framing cannot describe it.
Cipher KeyMaterial_Cipher `protobuf:"varint,6,opt,name=cipher,proto3,enum=api.ext.v1.KeyMaterial_Cipher" json:"cipher,omitempty"`
// contains filtered or unexported fields
}
KeyMaterial is an optional framing for the ciphertext an extension server returns from Encrypt. Decrypt is handed nothing but that ciphertext, so anything the server needs to find the wrapping key again has to travel inside it. Rather than hand-roll a binary frame, a server can marshal this message as its ciphertext and unmarshal it on the way back.
The fields other than encrypted_dek are metadata in the clear: this is framing, not encryption. A namespace is not a secret (it already travels in gRPC metadata), but a server that would rather not expose one can leave namespace empty and identify its key through opaque instead.
Every byte of this message rides in the metadata of each payload it seals, and stays there for as long as the Workflow retention period. Carry what decrypt needs to find the key, and nothing else.
func UnmarshalKeyMaterial ¶
func UnmarshalKeyMaterial(raw []byte) (*KeyMaterial, error)
UnmarshalKeyMaterial decodes key material produced by KeyMaterial.Marshal. It does not check what it decoded: proto3 happily accepts bytes that set none of the fields, so call KeyMaterial.Validate on anything whose framing you did not produce yourself.
func (*KeyMaterial) Descriptor
deprecated
func (*KeyMaterial) Descriptor() ([]byte, []int)
Deprecated: Use KeyMaterial.ProtoReflect.Descriptor instead.
func (*KeyMaterial) GetCipher ¶
func (x *KeyMaterial) GetCipher() KeyMaterial_Cipher
func (*KeyMaterial) GetEncryptedDek ¶
func (x *KeyMaterial) GetEncryptedDek() []byte
func (*KeyMaterial) GetNamespace ¶
func (x *KeyMaterial) GetNamespace() string
func (*KeyMaterial) GetNonce ¶
func (x *KeyMaterial) GetNonce() []byte
func (*KeyMaterial) GetOpaque ¶
func (x *KeyMaterial) GetOpaque() []byte
func (*KeyMaterial) GetVersion ¶
func (x *KeyMaterial) GetVersion() string
func (*KeyMaterial) Marshal ¶
func (km *KeyMaterial) Marshal() ([]byte, error)
Marshal validates km and returns its wire encoding, ready to hand back as an EncryptResponse ciphertext.
func (*KeyMaterial) ProtoMessage ¶
func (*KeyMaterial) ProtoMessage()
func (*KeyMaterial) ProtoReflect ¶
func (x *KeyMaterial) ProtoReflect() protoreflect.Message
func (*KeyMaterial) Reset ¶
func (x *KeyMaterial) Reset()
func (*KeyMaterial) String ¶
func (x *KeyMaterial) String() string
func (*KeyMaterial) Validate ¶
func (km *KeyMaterial) Validate() error
Validate reports whether km carries a wrapped DEK, treating a nil km as one that does not. Every other field is optional: an extension server may version no keys, key off no namespace, and carry nothing of its own.
type KeyMaterial_Cipher ¶
type KeyMaterial_Cipher int32
Cipher names the AEAD that sealed encrypted_dek. A server that changes cipher has to keep opening what the previous one sealed, and the only way to know which to build is to have been told, so the choice travels with the material rather than living in the server's configuration.
Values from 128 up are reserved for ciphers a server registers itself and will never be assigned here. A value this proxy does not recognize is carried through rather than dropped, so material sealed by a newer server survives a round trip through an older one.
const ( // CIPHER_UNSPECIFIED is no cipher. Material that reached a reader without // one was framed by a server that does its own wrapping, and only that // server knows how to open it. KeyMaterial_CIPHER_UNSPECIFIED KeyMaterial_Cipher = 0 // CIPHER_AES_256_GCM is AES-256-GCM with a 12-byte nonce. KeyMaterial_CIPHER_AES_256_GCM KeyMaterial_Cipher = 1 // CIPHER_CHACHA20_POLY1305 is ChaCha20-Poly1305 with a 12-byte nonce. KeyMaterial_CIPHER_CHACHA20_POLY1305 KeyMaterial_Cipher = 2 // CIPHER_XCHACHA20_POLY1305 is XChaCha20-Poly1305 with a 24-byte nonce, // wide enough that random nonces need no counting. KeyMaterial_CIPHER_XCHACHA20_POLY1305 KeyMaterial_Cipher = 3 )
func (KeyMaterial_Cipher) Descriptor ¶
func (KeyMaterial_Cipher) Descriptor() protoreflect.EnumDescriptor
func (KeyMaterial_Cipher) Enum ¶
func (x KeyMaterial_Cipher) Enum() *KeyMaterial_Cipher
func (KeyMaterial_Cipher) EnumDescriptor
deprecated
func (KeyMaterial_Cipher) EnumDescriptor() ([]byte, []int)
Deprecated: Use KeyMaterial_Cipher.Descriptor instead.
func (KeyMaterial_Cipher) Number ¶
func (x KeyMaterial_Cipher) Number() protoreflect.EnumNumber
func (KeyMaterial_Cipher) String ¶
func (x KeyMaterial_Cipher) String() string
func (KeyMaterial_Cipher) Type ¶
func (KeyMaterial_Cipher) Type() protoreflect.EnumType