remote

package
v0.0.1 Latest Latest
Warning

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

Go to latest
Published: Apr 2, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package remote provides a configurable HTTPS-based HSMProvider that delegates DEK wrap and unwrap operations to any remote KMS service over TLS. For production use, configure TLSClientCert and TLSClientKey to enable mTLS so the remote service can authenticate the caller.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// URL is the HTTPS endpoint for wrap operations. Required.
	URL string

	// UnwrapURL overrides URL for unwrap operations when the service uses
	// separate endpoints. Defaults to URL when empty.
	UnwrapURL string

	// Method is the HTTP verb used for wrap and unwrap requests. Defaults to POST.
	Method string

	// Headers are static HTTP headers added to every request.
	// Use this for Authorization, X-Vault-Token, and similar.
	Headers map[string]string

	// TLSCACert is the path to a PEM-encoded CA certificate bundle for
	// private or custom PKI. Uses the system root pool when empty.
	TLSCACert string

	// TLSClientCert and TLSClientKey enable mutual TLS authentication.
	// Both must be set together; if either is empty mTLS is not configured.
	TLSClientCert string
	TLSClientKey  string

	// InsecureSkipVerify disables TLS certificate verification.
	// This MUST NOT be used in production. It exists only for local test servers.
	InsecureSkipVerify bool

	// Timeout is the per-request deadline. Defaults to defaultRequestTimeout.
	Timeout time.Duration

	// WrapRequestTemplate is a Go text/template rendered before the wrap POST.
	// The template receives a single string field {{.DEK}} which is the
	// base64-encoded DEK bytes. When empty, the raw base64 DEK is sent as
	// the request body with Content-Type: text/plain.
	WrapRequestTemplate string

	// WrapResponseJSONPath is a dot-separated key path into the JSON response
	// body to extract the wrapped ciphertext, e.g. "ciphertext" or "data.ciphertext".
	// When empty the entire response body is treated as base64 ciphertext.
	WrapResponseJSONPath string

	// UnwrapRequestTemplate mirrors WrapRequestTemplate for the unwrap request.
	// The template field is {{.Wrapped}} (base64-encoded wrapped ciphertext).
	UnwrapRequestTemplate string

	// UnwrapResponseJSONPath mirrors WrapResponseJSONPath for the unwrap response.
	// The extracted value must be the base64-encoded plaintext DEK.
	UnwrapResponseJSONPath string

	// ExpectedStatusCodes lists HTTP status codes treated as success.
	// Defaults to [200, 204] when nil.
	ExpectedStatusCodes []int

	// RetryCount is the number of retry attempts on transient errors. Default 3.
	RetryCount int

	// RetryBackoff is the initial wait between retries. Default 500 ms.
	// Retries use exponential backoff capped at 8 × RetryBackoff.
	RetryBackoff time.Duration
}

Config holds all parameters for a RemoteKMSProvider. URL and at least one of WrapResponseJSONPath/UnwrapResponseJSONPath are required.

func AWSKMS

func AWSKMS(region, keyID string) Config

AWSKMS returns a Config pre-populated for AWS Key Management Service. This adapter calls the AWS KMS HTTP API directly without the AWS SDK. region is the AWS region (e.g. us-east-1) and keyID is the KMS key ID or ARN. AWS SigV4 request signing is not handled here; use the Headers field to supply a pre-signed Authorization header or an AWS API Gateway pass-through token.

func GCPKMS

func GCPKMS(project, location, keyRing, key string) Config

GCPKMS returns a Config pre-populated for Google Cloud KMS. project, location, keyRing, and key identify the CryptoKey resource. Set Headers["Authorization"] = "Bearer <access-token>" before use.

func VaultTransit

func VaultTransit(address, token, keyName string) Config

VaultTransit returns a Config pre-populated for HashiCorp Vault's Transit secrets engine. address is the Vault server address (e.g. https://vault:8200), token is the Vault token, and keyName is the Transit key name.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider implements keeper.HSMProvider by delegating to a remote KMS service. It is safe for concurrent use.

func New

func New(cfg Config) (*Provider, error)

New constructs a Provider from cfg, building the TLS-aware http.Client. Returns an error if the TLS configuration is invalid or cert files cannot be read.

func (*Provider) Ping

func (p *Provider) Ping(ctx context.Context) error

Ping sends a HEAD request to the configured URL to verify reachability. Used by the jack.Doctor health patient.

func (*Provider) UnwrapDEK

func (p *Provider) UnwrapDEK(wrapped []byte) ([]byte, error)

UnwrapDEK base64-encodes wrapped, sends it to the configured unwrap endpoint, and returns the decoded plaintext DEK bytes. The plaintext DEK must not be logged or stored beyond the immediate caller's stack frame.

func (*Provider) WrapDEK

func (p *Provider) WrapDEK(dek []byte) ([]byte, error)

WrapDEK base64-encodes dek, sends it to the configured wrap endpoint, and returns the base64-decoded ciphertext from the response.

Jump to

Keyboard shortcuts

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