ssk

README

sops-sakura-kms

A SOPS wrapper that enables SOPS (Secrets OPerationS) to use Sakura Cloud KMS for data key encryption.

This tool acts as a Vault Transit Engine compatible HTTP server, allowing SOPS to encrypt and decrypt data keys using Sakura Cloud KMS through the SOPS_VAULT_URIS environment variable.

Features

• SOPS Integration: Seamlessly integrates SOPS with Sakura Cloud KMS
• Vault Compatibility: Implements Vault Transit Engine compatible API
• Automatic Configuration: Automatically configures SOPS with the correct Vault Transit URI
• Transparent Operation: Works as a wrapper around SOPS, passing through all SOPS commands

Installation

Homebrew

brew install fujiwara/tap/sops-sakura-kms

Binary releases

Download the latest binary from the releases page.

From source

go install github.com/fujiwara/sops-sakura-kms/cmd/sops-sakura-kms@latest

GitHub Action

You can install sops-sakura-kms in your GitHub Actions workflows.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: fujiwara/sops-sakura-kms@main
        with:
          version: 'v0.0.4' # or 'latest'
          # version-file: './.version'

This action sets up sops-sakura-kms and makes it available in the PATH. The sops command needs to be installed separately.

Prerequisites

• SOPS must be installed and available in your PATH
• Sakura Cloud API credentials must be set in environment variables

Configuration

Set the following environment variables:

# Sakura Cloud API credentials
export SAKURACLOUD_ACCESS_TOKEN="your-access-token"
export SAKURACLOUD_ACCESS_TOKEN_SECRET="your-access-token-secret"

# Sakura Cloud KMS Resource ID (12-digit number as string, e.g., 123456789012)
export SAKURACLOUD_KMS_KEY_ID="123456789012"

Usage

Use sops-sakura-kms as a drop-in replacement for the sops command:

# Encrypt a file
sops-sakura-kms -e secrets.yaml > secrets.enc.yaml

# Decrypt a file
sops-sakura-kms -d secrets.enc.yaml

# Edit an encrypted file
sops-sakura-kms secrets.enc.yaml

How it works

1. sops-sakura-kms starts a local Vault Transit Engine compatible HTTP server on 127.0.0.1:8200
2. Automatically sets the SOPS_VAULT_URIS environment variable to http://127.0.0.1:8200/v1/transit/encrypt/{key_id}
3. Sets required environment variables (VAULT_ADDR, VAULT_TOKEN)
4. Executes SOPS with the configured environment
5. The server handles encryption/decryption requests from SOPS using Sakura Cloud KMS

SOPS Configuration

You can use the standard SOPS configuration file (.sops.yaml) without specifying the hc_vault_transit_uri:

creation_rules:
  - path_regex: \.yaml$
    # No need to specify hc_vault_transit_uri - it's automatically configured via SOPS_VAULT_URIS

Note: The wrapper automatically sets the SOPS_VAULT_URIS environment variable, so you don't need to configure it manually in .sops.yaml or pass it as a command-line argument.

API Endpoints

The tool provides the following Vault Transit Engine compatible endpoints:

• GET /health - Health check endpoint
• PUT /v1/transit/encrypt/{key_id} - Encrypt data using specified KMS key
• PUT /v1/transit/decrypt/{key_id} - Decrypt data using specified KMS key

Development

Running Tests

# Run all tests
go test ./...

# Run tests with actual Sakura Cloud KMS (requires credentials and KEY_ID)
KEY_ID=123456789012 go test ./...

Building

make build

License

MIT License - see LICENSE file for details

Author

FUJIWARA Shunichiro

Documentation

Index

• Constants
• Variables
• func DecryptHandlerFunc(cipher Cipher) func(w http.ResponseWriter, r *http.Request)
• func EncryptHandlerFunc(cipher Cipher) func(w http.ResponseWriter, r *http.Request)
• func NewMux(cipher Cipher) *http.ServeMux
• func Run(ctx context.Context) error
• func RunWrapper(ctx context.Context, sopsArgs []string) error
• type Cipher
• type SakuraKMS
  • func NewSakuraKMS() (*SakuraKMS, error)
  • func (c *SakuraKMS) Decrypt(ctx context.Context, keyID string, ciphertext string) ([]byte, error)
  • func (c *SakuraKMS) Encrypt(ctx context.Context, keyID string, plaintext []byte) (string, error)
• type VaultDecryptRequest
• type VaultDecryptResponse
• type VaultEncryptRequest
• type VaultEncryptResponse
• type VaultErrorResponse

Constants

const (
	VaultPrefix    = "vault:v1:"
	KeyIDPathParam = "key_id"
	EnvKeyID       = "SAKURACLOUD_KMS_KEY_ID"
	ServerAddr     = "127.0.0.1:8200"
	SOPSbin        = "sops"
)

Variables

var Version = "v0.0.4"

Functions

func DecryptHandlerFunc

func DecryptHandlerFunc(cipher Cipher) func(w http.ResponseWriter, r *http.Request)

DecryptHandlerFunc returns an HTTP handler for Vault Transit Engine decrypt endpoint.

func EncryptHandlerFunc

func EncryptHandlerFunc(cipher Cipher) func(w http.ResponseWriter, r *http.Request)

EncryptHandlerFunc returns an HTTP handler for Vault Transit Engine encrypt endpoint.

func NewMux

func NewMux(cipher Cipher) *http.ServeMux

NewMux creates a new HTTP ServeMux with Vault Transit Engine compatible API endpoints.

func Run

func Run(ctx context.Context) error

Run starts a Vault Transit Engine compatible API server for Sakura Cloud KMS. The server listens on 127.0.0.1:8200 and provides encrypt/decrypt endpoints.

func RunWrapper

func RunWrapper(ctx context.Context, sopsArgs []string) error

RunWrapper starts a Vault Transit Engine compatible API server and executes SOPS command. It automatically configures SOPS to use Sakura Cloud KMS via SOPS_VAULT_URIS environment variable. Requires SAKURA_KMS_KEY_ID environment variable to be set.

Types

type Cipher

type Cipher interface {
	// Encrypt encrypts plaintext using the specified key ID.
	// Returns base64-encoded ciphertext string.
	Encrypt(ctx context.Context, keyID string, plaintext []byte) (string, error)
	// Decrypt decrypts ciphertext using the specified key ID.
	// Accepts base64-encoded ciphertext string and returns plaintext bytes.
	Decrypt(ctx context.Context, keyID string, ciphertext string) ([]byte, error)
}

Cipher defines the interface for encryption and decryption operations.

type SakuraKMS

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

SakuraKMS implements Cipher interface using Sakura Cloud KMS.

func NewSakuraKMS

func NewSakuraKMS() (*SakuraKMS, error)

NewSakuraKMS creates a new SakuraKMS instance. It reads credentials from environment variables (SAKURACLOUD_ACCESS_TOKEN, SAKURACLOUD_ACCESS_TOKEN_SECRET).

func (*SakuraKMS) Decrypt

func (c *SakuraKMS) Decrypt(ctx context.Context, keyID string, ciphertext string) ([]byte, error)

Decrypt decrypts ciphertext using Sakura Cloud KMS.

func (*SakuraKMS) Encrypt

func (c *SakuraKMS) Encrypt(ctx context.Context, keyID string, plaintext []byte) (string, error)

Encrypt encrypts plaintext using Sakura Cloud KMS with AES-256-GCM algorithm.

type VaultDecryptRequest

type VaultDecryptRequest struct {
	Ciphertext string `json:"ciphertext"`
}

VaultDecryptRequest represents the request body for Vault Transit Engine decrypt API. Ciphertext must include "vault:v1:" prefix.

type VaultDecryptResponse

type VaultDecryptResponse struct {
	Plaintext string `json:"plaintext"`
}

VaultDecryptResponse represents the response body for Vault Transit Engine decrypt API. Plaintext is returned as base64-encoded string.

type VaultEncryptRequest

type VaultEncryptRequest struct {
	Plaintext string `json:"plaintext"`
}

VaultEncryptRequest represents the request body for Vault Transit Engine encrypt API. Plaintext must be base64-encoded string.

type VaultEncryptResponse

type VaultEncryptResponse struct {
	Ciphertext string `json:"ciphertext"`
}

VaultEncryptResponse represents the response body for Vault Transit Engine encrypt API. Ciphertext includes "vault:v1:" prefix followed by the encrypted data.

type VaultErrorResponse

type VaultErrorResponse struct {
	Errors []string `json:"errors"`
}

VaultErrorResponse represents the error response body for Vault API. Errors is an array of error message strings.