Key manager protocol
このコンテンツはまだ日本語訳がありません。
The services, messages, and enums of the package my.plugin.key_manager.v1, which key_manager.proto defines.
Keeping the key-encryption key (KEK) of the server’s secrets in a service of the operator’s choice, such as Vault or an HSM. The requests hold data-encryption keys in plaintext and the responses open them, so a plugin must never log dek, aad, or wrapped, and the server refuses plain TCP to this kind. Whoever runs the plugin can read every secret of the server.
A plugin answers with an outcome, and fails with an HTTP or a Connect error when it cannot answer. The server does not fall back on anything: a failure fails the request or the job that needed the key, and the job retries.
Services
Section titled “Services”KeyManagerService
Section titled “KeyManagerService”Describe
Section titled “Describe”rpc Describe(DescribeRequest) returns (DescribeResponse);Request: DescribeRequest. Response: DescribeResponse.
Describe returns the ID of the KEK that WrapKey uses now. The server calls it at each start, and a failure stops the start. It has no side effect.
WrapKey
Section titled “WrapKey”rpc WrapKey(WrapKeyRequest) returns (WrapKeyResponse);Request: WrapKeyRequest. Response: WrapKeyResponse.
WrapKey encrypts a data-encryption key under the current KEK, authenticating aad. Wrapping the same key twice must give different values: use a fresh nonce. The server keeps what comes back beside the secret, for as long as the secret lasts.
UnwrapKey
Section titled “UnwrapKey”rpc UnwrapKey(UnwrapKeyRequest) returns (UnwrapKeyResponse);Request: UnwrapKeyRequest. Response: UnwrapKeyResponse.
UnwrapKey opens what WrapKey returned. It must refuse a changed wrapped value and a different aad with OUTCOME_DECRYPT: that is what keeps a secret from being copied to another row. The server tests this at each start, with a key it throws away, and refuses to start on a plugin that does not.
Messages
Section titled “Messages”DescribeRequest
Section titled “DescribeRequest”No fields.
DescribeResponse
Section titled “DescribeResponse”outcome(Outcome, field 1): A name in JSON. Anything but OUTCOME_OK, an empty response included, is a failure.key_id(string, field 2): With OUTCOME_OK, the ID of the current KEK: 1 to 248 bytes of visible ASCII. It is no secret: the server stores it in plain text beside each wrapped key, and names it in logs and in the output of commands.
WrapKeyRequest
Section titled “WrapKeyRequest”dek(bytes, field 1): The data-encryption key in plaintext, 32 bytes.aad(bytes, field 2): The additional authenticated data, which ties the key to where the secret is stored. It holds row IDs and column names.
WrapKeyResponse
Section titled “WrapKeyResponse”outcome(Outcome, field 1): A name in JSON. Anything but OUTCOME_OK, an empty response included, is a failure, and the server stores nothing.key_id(string, field 2): With OUTCOME_OK, the ID of the KEK that wrapped the key, in the form of DescribeResponse.key_id. A KEK that rotated shows here: the server takes it as the current one.wrapped(bytes, field 3): With OUTCOME_OK, the wrapped key: 1 to 65,535 bytes, in which the plaintext of the key does not appear.
UnwrapKeyRequest
Section titled “UnwrapKeyRequest”key_id(string, field 1): The ID of the KEK that wrapped the key, as WrapKey returned it. It may be an ID older than the current one.wrapped(bytes, field 2): The wrapped key, as WrapKey returned it.aad(bytes, field 3): The additional authenticated data of the WrapKey call.
UnwrapKeyResponse
Section titled “UnwrapKeyResponse”outcome(Outcome, field 1): A name in JSON. Anything but a value below, an empty response included, is a failure.dek(bytes, field 2): With OUTCOME_OK, the data-encryption key in plaintext.
Outcome
Section titled “Outcome”The result of a call. The server treats a value it does not know as a failure. Connect errors and HTTP errors say only that the call failed in transport, which is a failure too: a plugin must not answer OUTCOME_DECRYPT or OUTCOME_UNKNOWN_KEY when its key store is out of reach.
OUTCOME_UNSPECIFIED= 0OUTCOME_OK= 1: The call succeeded, and the response holds its result.OUTCOME_UNKNOWN_KEY= 2: UnwrapKey: the plugin does not hold the KEK of key_id.OUTCOME_DECRYPT= 3: UnwrapKey: wrapped or aad does not authenticate.
LLM とコーディングエージェント向け:llms.txt,llms-full.txt, llms-small.txt