KMS v2 API Reference¶

sceau serves the Kubernetes KMS v2 gRPC API defined in proto/kms/v2/api.proto — a trimmed copy of k8s.io/kms/apis/v2/api.proto containing exactly the subset a plugin must implement. sceau has no CRDs and no other API surface; the semantics behind each message are described in KMS v2 Protocol.

Package: v2 · proto3

Service: KeyManagementService¶

service KeyManagementService {
    rpc Status(StatusRequest) returns (StatusResponse) {}
    rpc Decrypt(DecryptRequest) returns (DecryptResponse) {}
    rpc Encrypt(EncryptRequest) returns (EncryptResponse) {}
}

RPC	Purpose	sceau's behaviour
`Status`	Version and health of the plugin.	Always `version="v2"`, `healthz="ok"`, and the SRK-derived `key_id`.
`Encrypt`	Encrypt a DEK generated by kube-apiserver.	Seals the DEK under the TPM SRK; returns the envelope + `key_id`.
`Decrypt`	Decrypt a DEK previously returned by `Encrypt`.	Validates `key_id`, loads the envelope under the SRK, unseals.

Messages¶

StatusRequest¶

Empty.

StatusResponse¶

Field	Type	Description
`version`	`string`	Version of the KMS API: must be `"v2"`.
`healthz`	`string`	`"ok"` when the plugin can serve Encrypt/Decrypt.
`key_id`	`string`	ID of the key currently used for encryption. Must be non-empty before kube-apiserver will use the plugin. sceau: `sceau-<16 hex chars>`, derived from the SRK name.

EncryptRequest¶

Field	Type	Description
`plaintext`	`bytes`	The DEK to encrypt. Kubernetes DEKs are 32 bytes; sceau accepts up to 128 (the TPM sealed-data capacity).
`uid`	`string`	Unique identifier for this request. Logged by sceau for correlation.

EncryptResponse¶

Field	Type	Description
`ciphertext`	`bytes`	The encrypted DEK. sceau: the TPM envelope `version(1) \\|\\| public_len(u16 BE) \\|\\| public \\|\\| private` — see TPM Sealing.
`key_id`	`string`	ID of the key used. kube-apiserver stores this and sends it back on `Decrypt`.
`annotations`	`map<string, bytes>`	Optional metadata stored with the ciphertext. Empty in current sceau.

DecryptRequest¶

Field	Type	Description
`ciphertext`	`bytes`	The data to decrypt, as returned by `Encrypt`.
`uid`	`string`	Unique identifier for the `Encrypt` request this data came from.
`key_id`	`string`	The `key_id` the apiserver recorded for this ciphertext. sceau rejects any value other than its own with `INVALID_ARGUMENT`.
`annotations`	`map<string, bytes>`	Annotations returned by `Encrypt`.

DecryptResponse¶

Field	Type	Description
`plaintext`	`bytes`	The decrypted DEK.

Error model¶

gRPC status	When
`INVALID_ARGUMENT`	`Decrypt` with a `key_id` this TPM does not serve; malformed envelope (wrong version byte, truncated, unmarshalling failure).
`INTERNAL`	Any TPM command failure; plaintext exceeding the 128-byte seal capacity. Only the error class is returned — TPM internals are not leaked to the apiserver.

Trying it by hand¶

grpcurl -plaintext -unix /run/sceau/sceau.sock \
  -import-path proto -proto kms/v2/api.proto \
  v2.KeyManagementService/Status

A full seal/unseal walkthrough is in the Quickstart.