ext

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 18, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
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.

View Source
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) Enum

func (KeyMaterial_Cipher) EnumDescriptor deprecated

func (KeyMaterial_Cipher) EnumDescriptor() ([]byte, []int)

Deprecated: Use KeyMaterial_Cipher.Descriptor instead.

func (KeyMaterial_Cipher) Number

func (KeyMaterial_Cipher) String

func (x KeyMaterial_Cipher) String() string

func (KeyMaterial_Cipher) Type

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL