Documentation
¶
Overview ¶
Package algorithm holds keyforge's algorithm registry: the identifiers written in envelopes, their exact names, and the construction of the primitive for each.
Every protection of stored data and keys goes through an algorithm from this registry. The set is compiled in; configuration can narrow it and cannot add to it. Adding an algorithm is a release with a new identifier and known-answer vectors.
The registry currently holds AES-256-GCM only.
Index ¶
- Variables
- func New(id ID, key []byte) (cipher.AEAD, error)
- type Config
- type ID
- type NotPermittedError
- type Profile
- type Selection
- type Selector
- func (s *Selector) Check(id ID, sel Selection) error
- func (s *Selector) CheckWrite(id ID, sel Selection) error
- func (s *Selector) Profile() Profile
- func (s *Selector) Select(sel Selection) (ID, error)
- func (s *Selector) String() string
- func (s *Selector) Validate(purposes map[string]Selection) error
- func (s *Selector) ValidateSelection(sel Selection) error
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnknown is returned for an identifier that is not in the registry. ErrUnknown = errors.New("algorithm: unknown algorithm") // ErrKeySize is returned when a key does not have the size the algorithm // requires. ErrKeySize = errors.New("algorithm: wrong key size") )
var ( // ErrNotPermitted is returned when an algorithm is outside the profile in // force. It is never answered with a fallback. ErrNotPermitted = errors.New("algorithm: not permitted by the profile") // ErrNoPermitted is returned when a write finds no algorithm the profile // and the purpose's list both permit. The operation fails closed. ErrNoPermitted = errors.New("algorithm: no permitted algorithm") // ErrInvalidSelection is returned for a purpose configuration that widens // a profile or names an algorithm that does not exist. ErrInvalidSelection = errors.New("algorithm: invalid selection") // ErrUnknownProfile is returned for a profile name or value that is not // defined. ErrUnknownProfile = errors.New("algorithm: unknown profile") )
Functions ¶
Types ¶
type Config ¶
type Config struct {
// Profile is the active profile. The zero value means [DefaultProfile].
Profile Profile
// Deny removes algorithms from the active profile. It can only narrow.
Deny []ID
}
Config configures a Selector.
type ID ¶
type ID uint8
ID is an algorithm identifier as written in the envelope header.
const ( // AES256GCM is AES-256-GCM with a random 96-bit nonce generated by // [cipher.NewGCMWithRandomNonce], the only GCM constructor permitted // under GODEBUG=fips140=only. AES256GCM ID = 1 )
func (ID) NonceSize ¶
NonceSize returns the size in bytes of the nonce stored in the envelope header, or 0 for an unknown identifier.
func (ID) String ¶
String returns the algorithm's exact name, mode and size included, or a placeholder for an identifier that is not in the registry.
type NotPermittedError ¶
NotPermittedError reports the algorithm and the profile it was refused by.
func (*NotPermittedError) Error ¶
func (e *NotPermittedError) Error() string
Error implements error.
func (*NotPermittedError) Unwrap ¶
func (e *NotPermittedError) Unwrap() error
Unwrap lets errors.Is match ErrNotPermitted.
type Profile ¶
type Profile uint8
Profile is a named set of algorithms. The sets are compiled in and reviewed; configuration can narrow a profile and cannot add an algorithm to it.
const ( // ProfileStandard is the default profile outside FIPS mode. Every // algorithm in the registry is a member. ProfileStandard Profile = 1 // ProfileFIPS holds only algorithms that FIPS 140-3 approves. It is the // default when the process runs in FIPS mode, and may be selected outside // it, where it restricts the algorithm set without module validation. ProfileFIPS Profile = 2 )
func DefaultProfile ¶
func DefaultProfile() Profile
DefaultProfile returns the profile a process uses when none is configured: FIPS when the process runs in FIPS 140-3 mode, and standard otherwise.
func ParseProfile ¶
ParseProfile parses "standard" or "fips".
func (Profile) Algorithms ¶
Algorithms returns the profile's members in preference order. The caller owns the returned slice.
type Selection ¶
type Selection struct {
// Profile pins the purpose to a profile that is no wider than the active
// one. The zero value inherits the active profile.
Profile Profile
// Allowed is the ordered preference list for writes, a subset of the
// profile. Empty means the profile's own order.
Allowed []ID
}
Selection is a purpose's algorithm configuration. It can only narrow what the active profile permits.
type Selector ¶
type Selector struct {
// contains filtered or unexported fields
}
Selector chooses algorithms for writes and checks algorithms on reads under the active profile. It is immutable and safe for concurrent use.
func NewSelector ¶
NewSelector returns a selector for cfg. It fails if the profile or a denied algorithm is not defined.
func (*Selector) Check ¶
Check decides whether an envelope that names id may be read. Reads follow the profile in force, not the purpose's write list, so narrowing the list does not strand data already written. Migration is a re-encryption in a process whose profile permits the old algorithm.
An algorithm outside the profile fails with a *NotPermittedError that reports the algorithm and the profile; there is no fallback.
func (*Selector) CheckWrite ¶
CheckWrite decides whether id may be used to write under sel: it must pass Selector.Check and, when the purpose lists algorithms, be one of them. A data key created under an algorithm that has since left the list fails here, so the caller rotates to a new epoch instead of writing with it.
func (*Selector) Select ¶
Select returns the algorithm to write with: the first entry of the purpose's list that the profile in force permits, or the profile's first permitted algorithm when the list is empty. If there is none it returns ErrNoPermitted; it never falls back to an algorithm outside the profile.
func (*Selector) String ¶
String describes the selector for logs and status: the active profile and any denied algorithms.
func (*Selector) Validate ¶
Validate checks every purpose's configuration and reports all violations, so startup fails fast with the whole list. Purposes are checked in name order.
func (*Selector) ValidateSelection ¶
ValidateSelection checks one purpose's configuration against the active profile: a pinned profile must be no wider, and every listed algorithm must exist, appear once, and be permitted. It also requires that a write has an algorithm to use.
Source Files