pkg

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package pkg provides the public API for Volta. Audit logging types are re-exported from internal/audit.

Package pkg provides the public API for Volta. Options are re-exported from internal/vault.

Package pkg provides the public API for Volta. Types and interfaces for storage backends are re-exported from internal/persist.

Package pkg provides the public API surface for the Volta vault service. This package contains the public types and interfaces that external consumers can import and use.

NOTE: This package re-exports types from internal/vault to provide a stable public API. The internal implementation types are aliased here to ensure type compatibility across the public interface.

Package pkg provides the public API for Volta.

Index

Constants

View Source 
const (
	FileAuditType   = audit.FileAuditType
	SyslogAuditType = audit.SyslogAuditType
	NoOp            = audit.NoOp
)

Audit types

View Source 
const (
	StoreTypeFileSystem = persist.StoreTypeFileSystem
	StoreTypeS3         = persist.StoreTypeS3
)

Supported storage types.

Variables

View Source 
var (
	ContentTypeText   = vault.ContentTypeText
	ContentTypeJSON   = vault.ContentTypeJSON
	ContentTypeTOML   = vault.ContentTypeTOML
	ContentTypeXML    = vault.ContentTypeXML
	ContentTypeYAML   = vault.ContentTypeYAML
	ContentTypePEM    = vault.ContentTypePEM
	ContentTypeBinary = vault.ContentTypeBinary
)

Re-export ContentType constants for convenience

View Source 
var (
	KeyStatusActive   = vault.KeyStatusActive
	KeyStatusInactive = vault.KeyStatusInactive
)

KeyStatus constants

View Source 
var (
	ChaCha20Poly1305 = vault.ChaCha20Poly1305
)

CryptoAlgorithm constants

View Source 
var NewFileLogger = audit.NewFileLogger

NewFileLogger creates a new file-based audit logger

View Source 
var NewFileSystemStore = persist.NewFileSystemStore

NewFileSystemStore creates a new FileSystemStore.

View Source 
var NewFileSystemStoreFromConfig = persist.NewFileSystemStoreFromConfig

NewFileSystemStoreFromConfig creates a FileSystemStore from StoreConfig.

View Source 
var NewLogger = audit.NewLogger

NewLogger creates an appropriate logger based on configuration

View Source 
var NewNoOpLogger = audit.NewNoOpLogger

NewNoOpLogger creates a new no-op logger

View Source 
var NewS3Store = persist.NewS3Store

NewS3Store creates a new S3Store.

View Source 
var NewS3StoreFromConfig = persist.NewS3StoreFromConfig

NewS3StoreFromConfig creates a new S3Store from StoreConfig.

View Source 
var NewStore = persist.NewStore

NewStore factory function to create storage backends.

View Source 
var NewSyslogLogger = audit.NewSyslogLogger

NewSyslogLogger creates a new syslog audit logger with options

Functions

This section is empty.

Types

type AuditSummary 

type AuditSummary = vault.AuditSummary

AuditSummary provides aggregated audit statistics for tenant activity analysis.

type BackupContainer 

type BackupContainer = persist.BackupContainer

BackupContainer represents the outer backup format with metadata.

type BackupData 

type BackupData = persist.BackupData

BackupData represents the actual vault data to be backed up.

type BackupInfo 

type BackupInfo = persist.BackupInfo

BackupInfo holds essential metadata about a backup.

type BulkOperationResult 

type BulkOperationResult = vault.BulkOperationResult

BulkOperationResult represents the outcome of a bulk operation on a tenant.

type ConcurrencyError 

type ConcurrencyError = persist.ConcurrencyError

ConcurrencyError represents version conflict errors.

type Config 

type Config = audit.Config

Config defines audit logging configuration

type ConfigType 

type ConfigType = audit.ConfigType

ConfigType is the type of audit configuration

type ContentType 

type ContentType = vault.ContentType

ContentType is an alias for vault.ContentType

type CryptoAlgorithm 

type CryptoAlgorithm = vault.CryptoAlgorithm

CryptoAlgorithm is an alias for vault.CryptoAlgorithm

type DetailedBackupInfo 

type DetailedBackupInfo = persist.DetailedBackupInfo

DetailedBackupInfo provides detailed information regarding a backup.

type Event 

type Event = audit.Event

Event represents an audit log event

type FileOptions 

type FileOptions = audit.FileOptions

FileOptions for file-based audit logging

type KeyMetadata 

type KeyMetadata = vault.KeyMetadata

KeyMetadata is an alias for vault.KeyMetadata

type KeyStatus 

type KeyStatus = vault.KeyStatus

KeyStatus is an alias for vault.KeyStatus

type Logger 

type Logger = audit.Logger

Logger interface for pluggable audit implementations

type NoOpLogger 

type NoOpLogger = audit.NoOpLogger

NoOpLogger is a no-op implementation for when auditing is disabled

type Options 

type Options = vault.Options

Options contains vault configuration options. This is an alias for internal vault.Options.

type QueryOptions 

type QueryOptions = audit.QueryOptions

QueryOptions for filtering audit logs

type QueryResult 

type QueryResult = audit.QueryResult

QueryResult contains the results of an audit query

type S3Config added in v0.2.1 

type S3Config = persist.S3Config

S3Config contains the configuration required to connect to S3 (MinIO).

type SecretEntry 

type SecretEntry = vault.SecretEntry

SecretEntry is an alias for vault.SecretEntry

type SecretListEntry 

type SecretListEntry = vault.SecretListEntry

SecretListEntry is an alias for vault.SecretListEntry

type SecretListOptions 

type SecretListOptions = vault.SecretListOptions

SecretListOptions is an alias for vault.SecretListOptions

type SecretMetadata 

type SecretMetadata = vault.SecretMetadata

SecretMetadata is an alias for vault.SecretMetadata

type SecretResult 

type SecretResult = vault.SecretResult

SecretResult is an alias for vault.SecretResult

type SecretWithContext 

type SecretWithContext = vault.SecretWithContext

SecretWithContext is an alias for vault.SecretWithContext

type SecretsContainer 

type SecretsContainer = vault.SecretsContainer

SecretsContainer is an alias for vault.SecretsContainer

type Store 

type Store = persist.Store

Store is the interface for persisting vault data.

type StoreConfig 

type StoreConfig = persist.StoreConfig

StoreConfig provides configuration for different storage backends.

type StoreType 

type StoreType = persist.StoreType

StoreType represents the different types of storage backends.

type SyslogOptions 

type SyslogOptions = audit.SyslogOptions

SyslogOptions for syslog-based audit logging

type VaultManagerService 

type VaultManagerService interface {
	// GetVault retrieves a VaultService instance for a specific tenant.
	GetVault(tenantID string) (VaultService, error)

	// CloseTenant gracefully shuts down and cleans up resources for a tenant.
	CloseTenant(tenantID string) error

	// CloseAll performs graceful shutdown of all active tenant vaults.
	CloseAll() error

	// ListTenants returns identifiers for all currently active tenants.
	ListTenants() ([]string, error)

	// RotateAllTenantKeys performs encryption key rotation for multiple tenants.
	RotateAllTenantKeys(tenantIDs []string, reason string) ([]BulkOperationResult, error)

	// RotateAllTenantPassphrases updates master passphrases for multiple tenants.
	RotateAllTenantPassphrases(tenantIDs []string, newPassphrase string, reason string) ([]BulkOperationResult, error)

	// QueryAuditLogs performs flexible audit log queries with advanced filtering.
	QueryAuditLogs(options QueryOptions) (*QueryResult, error)

	// GetAuditSummary generates aggregated audit statistics for a tenant.
	GetAuditSummary(tenantID string, since *time.Time) (AuditSummary, error)

	// QueryKeyOperations retrieves audit events for cryptographic key operations.
	QueryKeyOperations(tenantID string, keyID string, since *time.Time) ([]Event, error)

	// QuerySecretAccess retrieves audit events for secret access operations.
	QuerySecretAccess(tenantID string, secretID string, since *time.Time) ([]Event, error)

	// QueryFailedOperations retrieves audit events for failed operations.
	QueryFailedOperations(tenantID string, since *time.Time) ([]Event, error)

	// QueryPassphraseAccessLogs retrieves audit events for passphrase operations.
	QueryPassphraseAccessLogs(tenantID string, since *time.Time) ([]Event, error)

	// QueryAllTenantsAuditLogs performs cross-tenant audit log queries.
	QueryAllTenantsAuditLogs(options QueryOptions) (map[string]QueryResult, error)

	// QueryTenantAuditLogs performs comprehensive audit queries for a single tenant.
	QueryTenantAuditLogs(tenantID string, options QueryOptions) (QueryResult, error)

	// DeleteTenant securely removes all resources associated with a specified tenant.
	DeleteTenant(tenantID string) error
}

VaultManagerService provides multi-tenant vault orchestration and administration.

All types used in method signatures (QueryOptions, QueryResult, Event, AuditSummary, BulkOperationResult) are defined and accessible from this package, ensuring that external consumers never need to import any internal package.

func NewVaultManagerFileStore 

func NewVaultManagerFileStore(options Options, basePath string, auditLogger Logger) VaultManagerService

NewVaultManagerFileStore creates a new VaultManager with file system storage.

func NewVaultManagerS3Store 

func NewVaultManagerS3Store(options Options, storeConfig S3Config, auditLogger Logger) (VaultManagerService, error)

NewVaultManagerS3Store creates a new VaultManager with S3 storage.

func NewVaultManagerWithStoreConfig 

func NewVaultManagerWithStoreConfig(options Options, storeConfig StoreConfig, auditLogger Logger) VaultManagerService

NewVaultManagerWithStoreConfig creates a new VaultManager with store configuration.

func NewVaultManagerWithStoreFactory 

func NewVaultManagerWithStoreFactory(options Options, storeFactory func(tenantID string) (Store, error), auditLogger Logger) VaultManagerService

NewVaultManagerWithStoreFactory creates a new VaultManager with a custom store factory.

type VaultService 

type VaultService interface {

	// Encrypt encrypts plaintext data using the current active key.
	Encrypt(plaintext []byte) (ciphertextWithKeyID string, err error)

	// Decrypt decrypts data that was previously encrypted by this vault instance.
	Decrypt(base64CiphertextWithKeyID string) (plaintext []byte, err error)

	// RotateDataEncryptionKey generates a new data encryption key (DEK), makes it the active key for
	// new encryptions, and deactivates the previously active key.
	RotateDataEncryptionKey(reason string) (*KeyMetadata, error)

	// DestroyKey permanently removes an inactive key and its material from the vault.
	DestroyKey(keyID string) error

	// Backup creates an encrypted backup of all non-decommissioned keys,
	// their operational metadata, and the vault's derivation salt to the
	// specified destination directory.
	Backup(destinationDir, passphrase string) error

	// Restore recovers vault state from a previously created backup.
	Restore(destinationDir, passphrase string) error

	// ListKeyMetadata returns metadata for all known keys managed by the vault.
	ListKeyMetadata() ([]KeyMetadata, error)

	// GetActiveKeyMetadata returns the metadata for the key currently
	// active for encryption operations.
	GetActiveKeyMetadata() (KeyMetadata, error)

	// StoreSecret encrypts and stores secret data with optional metadata.
	StoreSecret(secretID string, secretData []byte, tags []string, contentType ContentType) (*SecretMetadata, error)

	// GetSecret retrieves a secret by its ID.
	GetSecret(secretID string) (*SecretResult, error)

	// UpdateSecret updates existing secret data and increments the version number.
	UpdateSecret(secretID string, secretData []byte, tags []string, contentType ContentType) (*SecretMetadata, error)

	// DeleteSecret removes a secret and its metadata from the vault.
	DeleteSecret(secretID string) error

	// SecretExists checks if a secret exists without retrieving its data.
	SecretExists(secretID string) (bool, error)

	// ListSecrets returns secret metadata based on filter options.
	ListSecrets(options *SecretListOptions) ([]*SecretListEntry, error)

	// GetSecretMetadata returns only the metadata for a secret without decrypting the data.
	GetSecretMetadata(secretID string) (*SecretMetadata, error)

	// Close securely wipes all sensitive key material from the vault's memory
	// and releases associated resources.
	Close() error

	// UseSecret executes a function with a secret and ensures automatic cleanup.
	UseSecret(secretID string, fn func(data []byte) error) error

	// UseSecretWithTimeout executes a function with a secret with automatic timeout.
	UseSecretWithTimeout(secretID string, timeout time.Duration, fn func(data []byte) error) error

	// UseSecretWithContext executes a function with a secret using a custom context.
	UseSecretWithContext(ctx context.Context, secretID string, fn func(data []byte) error) error

	// UseSecretString executes a function with a secret as a string and ensures cleanup.
	UseSecretString(secretID string, fn func(secret string) error) error

	// GetSecretWithTimeout retrieves a secret with automatic timeout-based cleanup.
	GetSecretWithTimeout(secretID string, timeout time.Duration) (*SecretWithContext, error)

	// GetSecretWithContext retrieves a secret with custom context-based cleanup.
	GetSecretWithContext(ctx context.Context, secretID string) (*SecretWithContext, error)

	// UseSecrets provides secure access to multiple secrets within a single callback.
	UseSecrets(secretIDs []string, fn func(secrets map[string][]byte) error) error

	// UseSecretsString provides secure access to multiple secrets as UTF-8 strings.
	UseSecretsString(secretIDs []string, fn func(secrets map[string]string) error) error

	// UseSecretPair provides secure access to exactly two secrets with ergonomic API.
	UseSecretPair(secretID1, secretID2 string, fn func(secret1, secret2 []byte) error) error

	// UseSecretPairString provides secure access to exactly two secrets as UTF-8 strings.
	UseSecretPairString(secretID1, secretID2 string, fn func(secret1, secret2 string) error) error

	// SecureMemoryProtection returns information about the memory protection
	// mechanisms currently active for this vault instance.
	SecureMemoryProtection() string

	// RotateKeyEncryptionKey changes the vault's master passphrase used for key derivation.
	RotateKeyEncryptionKey(newPassphrase string, reason string) error

	// GetAudit returns the audit logger instance used by this vault.
	GetAudit() Logger

	// DeleteTenant securely removes all resources associated with a specified tenant.
	DeleteTenant(tenantID string) error
}

VaultService defines the public interface for interacting with the vault.

The vault manages its primary keys internally and ensures they are not directly exportable. It uses these keys to encrypt and decrypt provided data while maintaining strict separation between key material and application data.

Key Design Principles:

  • Zero-trust: Keys are never exposed outside the vault instance
  • Fail-secure: Operations fail safely when keys are unavailable
  • Audit-first: All operations are logged for compliance and security monitoring
  • Memory-safe: Sensitive data is cleared from memory when no longer needed

Thread Safety: Implementations of VaultService should be thread-safe for concurrent access, though individual operations may acquire locks as needed for consistency.

Error Handling: All operations return errors that provide sufficient detail for troubleshooting while avoiding information disclosure that could aid attackers.

func NewWithStore 

func NewWithStore(options Options, store Store, auditLogger Logger, tenantID string) (VaultService, error)

NewWithStore creates a new vault instance with the given store.

type VersionedData 

type VersionedData = persist.VersionedData

VersionedData represents data with its version information.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.