Documentation
¶
Overview ¶
Package auth provides credential storage and a small grant-based authorization model for the S3 server. It is deliberately a table, not a policy engine: each access key maps to a secret and a set of (bucket-pattern → permission) grants, and buckets may be flagged public-read.
The zero value is not useful; construct a Store with NewStore and swap its snapshot atomically via Set for hot reload.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrKeyExists = errors.New("access key already exists")
ErrKeyExists reports an access key that already exists.
var ErrKeyImmutable = errors.New("access key is defined in config and cannot be modified at runtime")
ErrKeyImmutable reports an attempt to modify a config-defined credential.
var ErrKeyNotFound = errors.New("access key not found")
ErrKeyNotFound reports an unknown managed access key.
Functions ¶
func NewAccessKey ¶ added in v0.8.0
func NewAccessKey() string
NewAccessKey returns an AWS-style 20-character access key ID.
func NewSecretKey ¶ added in v0.8.0
func NewSecretKey() string
NewSecretKey returns a 40-character secret access key.
Types ¶
type Action ¶
type Action int
Action is the access level a request requires, derived from its method.
type Config ¶
type Config struct {
// Keys are the credentials the server accepts.
Keys []Key
// PublicReadBuckets may be read anonymously (unsigned GET/HEAD/list).
PublicReadBuckets []string
}
Config is the declarative auth configuration, suitable for loading from a file or building programmatically.
type CreateInput ¶
CreateInput describes a credential to create. AccessKey and SecretKey are generated when empty.
type Created ¶
Created is a newly created credential, including the secret — returned only once, at creation.
type Grant ¶
type Grant struct {
Pattern string
Permission Permission
}
Grant authorizes an access key for buckets matching Pattern (a glob using path.Match semantics; "*" matches all buckets) up to Permission.
type Identity ¶ added in v0.10.0
type Identity struct {
// UserID is the canonical user ID. Defaults to the access key.
UserID string
// DisplayName is the human-readable owner name. Defaults to UserID.
DisplayName string
}
Identity is the S3 owner a credential acts as. It appears as the <Owner> of buckets, objects and ACLs; S3 clients compare these values to decide what a caller owns, so they must be stable for a given credential.
type Key ¶
type Key struct {
AccessKey string
SecretKey string
// UserID is the canonical owner ID reported for objects this key writes.
// Empty means "use the access key".
UserID string
// DisplayName is the human-readable owner name. Empty means "use UserID".
DisplayName string
Grants []Grant
}
Key is a credential: an access/secret pair, the identity it acts as, and its grants.
type KeyInfo ¶
KeyInfo describes a credential without exposing its secret. It is what the admin API lists.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns the live auth Store and adds runtime CRUD over credentials. Config/env credentials form a read-only base; runtime-created credentials are persisted to a JSON file and merged over the base. Every mutation rebuilds the Store snapshot atomically, so live requests immediately see the change.
func NewManager ¶
NewManager builds a Manager from a base Config (config/env credentials) and a persistence path for runtime-created credentials. It loads any previously persisted credentials and applies the merged set to a new Store. path may be empty to keep runtime credentials in memory only.
func (*Manager) Create ¶
func (m *Manager) Create(in CreateInput) (*Created, error)
Create adds a runtime credential, generating the access key and/or secret when not supplied, persists it, and applies it to the live Store. The returned Created carries the secret (the only time it is exposed).
func (*Manager) List ¶
List returns every credential (config + managed), secrets omitted, sorted by access key.
type Permission ¶
type Permission int
Permission is an access level. Higher levels include lower ones: Admin ⊇ Write ⊇ Read.
const ( // Read allows GET/HEAD/list operations. Read Permission = iota // Write allows Read plus PUT/POST/DELETE (including bucket create/delete). Write // Admin allows everything Write does, and is the level future admin-only // operations will require. Admin )
func ParsePermission ¶ added in v0.8.0
func ParsePermission(s string) (Permission, error)
ParsePermission is the inverse of Permission.String. It rejects any spelling other than "read", "write" or "admin".
func (Permission) String ¶ added in v0.8.0
func (p Permission) String() string
String returns the canonical name of a permission ("read", "write" or "admin"), the spelling used in config and the admin API.
type Sealer ¶ added in v0.8.0
type Sealer struct {
// contains filtered or unexported fields
}
Sealer seals and opens credential secrets with an AES-256-GCM key derived from the cluster secret via HKDF-SHA256. It exists so credentials stored in the cluster control plane (etcd) are encrypted at rest: a leaked etcd backup or a compromised control plane yields only ciphertext, not usable secret keys. The cluster secret is the sole key material; it never touches etcd.
A Sealer is safe for concurrent use.
func NewSealer ¶ added in v0.8.0
NewSealer derives the sealing key from clusterSecret and returns a Sealer. clusterSecret must be non-empty (the cluster secret is validated to be at least 16 bytes upstream).
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds the active auth configuration behind an atomic pointer, so Set hot-reloads it without locking readers.
func (*Store) Allow ¶
Allow reports whether the access key may perform action on bucket. A bucket of "" (e.g. ListBuckets) is allowed for any known key. Unknown keys are denied.
func (*Store) Owner ¶ added in v0.10.0
Owner returns the identity an access key acts as. Unknown keys report false.
func (*Store) PublicRead ¶
PublicRead reports whether bucket permits anonymous reads.
Source Files