kms

README

miniKMS Official Go SDK

The official Go client for miniKMS, a lightweight Key Management Service designed for demos, local development, and portfolio‑grade backend/security engineering projects.

The SDK provides a clean, mechanical API for:

• Creating and managing customer master keys (CMKs)
• Encrypting and decrypting data
• Generating and decrypting data keys (envelope encryption)
• Rotating, enabling, and disabling keys
• Retrieving key metadata

It’s dependency‑minimal, concurrency‑safe, and structured the way Go developers expect.

---

Installation

go get github.com/michaeljmartin28/minikms/sdk/go

Quickstart

package main

import (
    "context"
    "fmt"
    "github.com/michaeljmartin28/minikms/sdk/go/kms"
)

func main() {
    ctx := context.Background()

    client := kms.NewClient("http://localhost:8080")

    // Create a new CMK
    key, err := client.CreateKey(ctx, kms.CreateKeyParams{
        Algorithm: "AES-256_GCM",
        Name:      "example-key",
    })
    if err != nil {
        panic(err)
    }

    fmt.Println("Created key:", key.KeyID)

    // Encrypt some data
    enc, err := client.Encrypt(ctx, key.KeyID, kms.EncryptParams{
        Plaintext: []byte("hello world"),
    })
    if err != nil {
        panic(err)
    }

    // Decrypt it
    dec, err := client.Decrypt(ctx, key.KeyID, kms.DecryptParams{
        Ciphertext: enc.Ciphertext,
    })
    if err != nil {
        panic(err)
    }

    fmt.Println("Decrypted:", string(dec.Plaintext))
}

Client

client := kms.NewClient("http://localhost:8080")

The client is safe for concurrent use and performs:

• JSON marshaling/unmarshaling
• HTTP request construction
• error propagation
• typed response decoding

Key Lifecycle

Creating Keys

key, err := client.CreateKey(ctx, kms.CreateKeyParams{
    Name:      "my-key",
    Algorithm: "AES-256-GCM",
})

Returns:

type Key struct {
    KeyID     string
    Version   uint32
    CreatedAt time.Time
}

Enable a key:

_, err := client.EnableKey(ctx, key.KeyID)

Disable a key:

_, err := client.DisableKey(ctx, key.KeyID)

Rotate a key:

rot, err := client.RotateKey(ctx, key.KeyID)
fmt.Println(rot.Version)

Each returns updated metadata.

Encrypting Data

enc, err := client.Encrypt(ctx, key.KeyID, kms.EncryptParams{
    Plaintext:      []byte("hello world"),
    AdditionalData: []byte("optional AAD"),
})

Returns:

type EncryptResponse struct {
    Ciphertext []byte
    AdditionalData []byte
    Version    uint32
    Algorithm  string
}

Decrypting Data

dec, err := client.Decrypt(ctx, key.KeyID, kms.DecryptParams{
    Ciphertext: enc.Ciphertext,
    AdditionalData: enc.AdditionalData,
    Version:    enc.Version,
})

Returns:

type DecryptResponse struct {
    Plaintext []byte
}

Data Keys (Envelope Encryption)

Generate a data key

dk, err := client.GenerateDataKey(ctx, key.KeyID)
fmt.Println(dk.PlaintextKey)  // []byte
fmt.Println(dk.EncryptedKey)  // base64-encoded []byte

Decrypt a data key:

pt, err := client.DecryptDataKey(ctx, key.KeyID, kms.DecryptDataKeyParams{
    EncryptedKey: dk.EncryptedKey,
})
fmt.Println(pt.PlaintextKey)

Error Handling

All SDK methods return Go error values. Future versions will include typed errors such as:

• ErrKeyDisabled
• ErrKeyNotFound
• ErrInvalidCiphertext

Versioning

All SDK calls target:

/v1/...

When the API introduces /v2, the SDK will expose a new client or options without breaking existing code.

License MIT

Documentation

Index

• type Client
  • func NewClient(baseURL string) *Client
  • func (c *Client) CreateKey(ctx context.Context, params CreateKeyParams) (*KeyMetadata, error)
  • func (c *Client) Decrypt(ctx context.Context, keyID string, params DecryptParams) (*DecryptResponse, error)
  • func (c *Client) DecryptDEK(ctx context.Context, keyID string, params DecryptDataKeyParams) (*DecryptDataKeyResponse, error)
  • func (c *Client) DisableKey(ctx context.Context, keyID string) (*KeyMetadata, error)
  • func (c *Client) EnableKey(ctx context.Context, keyID string) (*KeyMetadata, error)
  • func (c *Client) Encrypt(ctx context.Context, keyID string, params EncryptParams) (*EncryptResponse, error)
  • func (c *Client) GenerateDEK(ctx context.Context, keyID string, params GenerateDataParams) (*GenerateDataKeyResponse, error)
  • func (c *Client) RotateKey(ctx context.Context, keyID string) (*RotateKeyResponse, error)
• type CreateKeyParams
• type CreateKeyResponse
• type DecryptDataKeyParams
• type DecryptDataKeyResponse
• type DecryptParams
• type DecryptResponse
• type DisableReponse
• type EnableReponse
• type EncryptParams
• type EncryptResponse
• type ErrorResponse
  • func (e ErrorResponse) Error() string
• type GenerateDataKeyResponse
• type GenerateDataParams
• type KeyMetadata
• type RotateKeyResponse

Types

type Client

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

func NewClient

func NewClient(baseURL string) *Client

func (*Client) CreateKey

func (c *Client) CreateKey(ctx context.Context, params CreateKeyParams) (*KeyMetadata, error)

func (*Client) Decrypt

func (c *Client) Decrypt(ctx context.Context, keyID string, params DecryptParams) (*DecryptResponse, error)

func (*Client) DecryptDEK

func (c *Client) DecryptDEK(ctx context.Context, keyID string, params DecryptDataKeyParams) (*DecryptDataKeyResponse, error)

func (*Client) DisableKey

func (c *Client) DisableKey(ctx context.Context, keyID string) (*KeyMetadata, error)

func (*Client) EnableKey

func (c *Client) EnableKey(ctx context.Context, keyID string) (*KeyMetadata, error)

func (*Client) Encrypt

func (c *Client) Encrypt(ctx context.Context, keyID string, params EncryptParams) (*EncryptResponse, error)

func (*Client) GenerateDEK

func (c *Client) GenerateDEK(ctx context.Context, keyID string, params GenerateDataParams) (*GenerateDataKeyResponse, error)

func (*Client) RotateKey

func (c *Client) RotateKey(ctx context.Context, keyID string) (*RotateKeyResponse, error)

type CreateKeyParams

type CreateKeyParams struct {
	Name      string `json:"name"`
	Algorithm string `json:"algorithm"`
}

type CreateKeyResponse

type CreateKeyResponse struct {
	KeyMetadata KeyMetadata `json:"keyMetadata"`
}

type DecryptDataKeyParams

type DecryptDataKeyParams struct {
	EncryptedDEK   []byte `json:"encryptedDEK"`
	Version        uint32 `json:"version"`
	AdditionalData []byte `json:"additionalData,omitempty"`
}

type DecryptDataKeyResponse

type DecryptDataKeyResponse struct {
	PlaintextDEK []byte `json:"plaintextDEK"`
}

type DecryptParams

type DecryptParams struct {
	Ciphertext     []byte `json:"ciphertext"`
	Version        uint32 `json:"version"`
	AdditionalData []byte `json:"additionalData,omitempty"`
}

type DecryptResponse

type DecryptResponse struct {
	Plaintext []byte `json:"plaintext"`
}

type DisableReponse

type DisableReponse struct {
	KeyMetadata KeyMetadata `json:"keyMetadata"`
}

type EnableReponse

type EnableReponse struct {
	KeyMetadata KeyMetadata `json:"keyMetadata"`
}

type EncryptParams

type EncryptParams struct {
	Plaintext      []byte `json:"plaintext"`
	AdditionalData []byte `json:"additionalData,omitempty"`
}

type EncryptResponse

type EncryptResponse struct {
	Ciphertext []byte `json:"ciphertext"`
	Version    uint32 `json:"version"`
	KeyID      string `json:"keyID"`
	Algorithm  string `json:"algorithm"`
}

type ErrorResponse

type ErrorResponse struct {
	ErrorMsg string `json:"error"`
	Code     string `json:"code"`
}

func (ErrorResponse) Error

func (e ErrorResponse) Error() string

type GenerateDataKeyResponse

type GenerateDataKeyResponse struct {
	PlaintextDEK []byte `json:"plaintextDEK"`
	EncryptedDEK []byte `json:"encryptedDEK"`
	Version      uint32 `json:"version"`
}

type GenerateDataParams

type GenerateDataParams struct {
	AdditionalData []byte `json:"additionalData,omitempty"`
}

type KeyMetadata

type KeyMetadata struct {
	KeyID         string    `json:"keyId"`
	CreatedAt     time.Time `json:"createdAt"`
	State         string    `json:"state"`
	Algorithm     string    `json:"algorithm"`
	LatestVersion uint32    `json:"latestVersion"`
}

type RotateKeyResponse

type RotateKeyResponse struct {
	Version uint32 `json:"version"`
}