sanctum

README

sanctum-sdk-go

Native Go bindings for the Sanctum credential vault, powered by CGo wrapping sanctum-ffi.

Installation

go get github.com/SanctumSec/sanctum-sdk-go

Note: This package ships a prebuilt libsanctum_ffi.dylib for macOS (arm64). Linux support coming soon.

Quick Start

package main

import (
    "fmt"
    "log"

    sanctum "github.com/SanctumSec/sanctum-sdk-go"
)

func main() {
    // Initialize a new vault
    vault, err := sanctum.Init("/path/to/vault", []byte("passphrase"))
    if err != nil {
        log.Fatal(err)
    }
    defer vault.Close()

    // Store a credential
    vault.Store("api-key", []byte("sk-secret"), "my-agent", "")

    // Retrieve it
    secret, _ := vault.Retrieve("api-key", "my-agent")
    fmt.Printf("Secret: %s\n", secret)

    // Check audit log
    logJSON, _ := vault.AuditLog("")
    fmt.Println(logJSON)
}

API

Function	Description
Init(path, passphrase)	Create and initialize a new vault
Open(path, passphrase)	Open an existing vault
vault.Close()	Free the vault handle
vault.Store(name, secret, agentID, policyJSON)	Store a credential
vault.Retrieve(name, agentID)	Retrieve a credential's secret
vault.CheckPolicy(name, agentID)	Check if an agent has access
vault.AuditLog(agentIDFilter)	Get audit log as JSON

Errors

Sentinel errors are provided for all FFI result codes:

• ErrNotFound — credential not found
• ErrAccessDenied — policy denies access
• ErrNotInitialized — vault not initialized
• ErrCrypto — cryptographic error
• See errors.go for the full list

License

MIT

Documentation

Overview

Package sanctum provides Go bindings for the Sanctum credential vault via CGo wrapping the sanctum-ffi C library.

Index

• Variables
• type Vault
  • func Init(path string, passphrase []byte) (*Vault, error)
  • func Open(path string, passphrase []byte) (*Vault, error)
  • func (v *Vault) AuditLog(agentIDFilter string) (string, error)
  • func (v *Vault) CheckPolicy(name string, agentID string) error
  • func (v *Vault) Close()
  • func (v *Vault) Delete(name string, agentID string) error
  • func (v *Vault) ListCredentials(agentID string) (string, error)
  • func (v *Vault) Retrieve(name string, agentID string) ([]byte, error)
  • func (v *Vault) Store(name string, secret []byte, agentID string, policyJSON string) error

Variables

var (
	ErrNullPointer    = errors.New("sanctum: null pointer")
	ErrInvalidUTF8    = errors.New("sanctum: invalid UTF-8")
	ErrNotInitialized = errors.New("sanctum: vault not initialized")
	ErrAccessDenied   = errors.New("sanctum: access denied")
	ErrNotFound       = errors.New("sanctum: credential not found")
	ErrCrypto         = errors.New("sanctum: cryptographic error")
	ErrBufferTooSmall = errors.New("sanctum: buffer too small")
	ErrJSON           = errors.New("sanctum: JSON error")
	ErrPanic          = errors.New("sanctum: panic caught at FFI boundary")
	ErrUnknown        = errors.New("sanctum: unknown error")
)

Types

type Vault

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

Vault wraps an opaque SanctumVault handle from the FFI layer.

func Init

func Init(path string, passphrase []byte) (*Vault, error)

Init creates and initializes a new vault at the given path with the supplied passphrase.

func Open

func Open(path string, passphrase []byte) (*Vault, error)

Open unlocks an existing vault at the given path with the supplied passphrase.

func (*Vault) AuditLog

func (v *Vault) AuditLog(agentIDFilter string) (string, error)

AuditLog returns the audit log as a JSON string. If agentIDFilter is non-empty, only entries for that agent are returned.

func (*Vault) CheckPolicy

func (v *Vault) CheckPolicy(name string, agentID string) error

CheckPolicy checks whether an agent is allowed to retrieve a credential. Returns nil if allowed, ErrAccessDenied if not.

func (*Vault) Close

func (v *Vault) Close()

Close frees the underlying vault handle. Safe to call multiple times.

func (*Vault) Delete

func (v *Vault) Delete(name string, agentID string) error

Delete removes a credential from the vault.

func (*Vault) ListCredentials

func (v *Vault) ListCredentials(agentID string) (string, error)

ListCredentials returns credential paths as a JSON array string.

func (*Vault) Retrieve

func (v *Vault) Retrieve(name string, agentID string) ([]byte, error)

Retrieve fetches a credential's secret bytes from the vault.

func (*Vault) Store

func (v *Vault) Store(name string, secret []byte, agentID string, policyJSON string) error

Store saves a credential in the vault. policyJSON may be empty for no policy; agentID identifies the storing agent.