Documentation
¶
Overview ¶
Package keys keeps the owner key and the agent keys of each instance in the key file of the CLI, keys.json in the state folder.
The file has mode 0600, in a folder with mode 0700. Its accounts have the names of the legacy keychain items: "owner@<instance>" and "agent:<name>@<instance>". Each write is atomic: a temporary file in the same folder, an fsync, and a rename. A lock on the file keys.json.lock lets one process at a time read or change the file. Thus two CLIs or bridges at the same time do not lose a key.
mai 3.0 and 3.1 kept the keys in the system keychain, and the manifest of the state folder recorded each item. When the key file has no key for an account, Get reads the legacy item, writes the key to the key file, and then deletes the legacy item.
On a self-run instance, a program that can use the Docker socket controls mai fully. Thus the key file gives the same protection as the keychain, with no prompt.
Index ¶
- Constants
- Variables
- func AgentAccount(instance, agent string) string
- func InstanceOf(account string) string
- func OwnerAccount(instance string) string
- type Accepts
- type Conflict
- type File
- func (f *File) Accounts() ([]string, error)
- func (f *File) Add(account, key string) (stored string, added bool, err error)
- func (f *File) Candidates(instance string, recorded []string) ([]string, error)
- func (f *File) Check() error
- func (f *File) Delete(account string) error
- func (f *File) DeleteInstance(instance string) ([]string, error)
- func (f *File) DeleteLegacy(account string) error
- func (f *File) Get(account string) (string, error)
- func (f *File) Has(account string) (bool, error)
- func (f *File) HasLegacy() bool
- func (f *File) HasLegacyItem(account string) (bool, error)
- func (f *File) LegacyItems(accounts []string) ([]string, error)
- func (f *File) MoveAll(accounts []string, accepts Accepts) (MoveReport, error)
- func (f *File) OfInstance(instance string) ([]string, error)
- func (f *File) Path() string
- func (f *File) Peek(account string) (string, error)
- func (f *File) RemoveEmpty() ([]string, error)
- func (f *File) Set(account, key string) error
- type LegacyError
- type ModeError
- type MoveReport
- type Stay
Constants ¶
const FileName = "keys.json"
FileName is the name of the key file in the state folder.
Variables ¶
var ErrBusy = errors.New("keys: the key file is busy")
ErrBusy means that a different process held the lock of the key file for more than the wait. A subsequent try can succeed.
var ErrNotFound = errors.New("keys: no key for the account")
ErrNotFound means that the key file and the legacy keychain have no key for the account.
Functions ¶
func AgentAccount ¶
AgentAccount is the account of the key of one agent of an instance.
func InstanceOf ¶
InstanceOf gives the instance of an account: the text after the last "@". It gives "" for an account with no "@".
func OwnerAccount ¶
OwnerAccount is the account of the owner key of an instance.
Types ¶
type Accepts ¶
Accepts tells if the server accepts the key of the account. It gives an error when it cannot tell, for example when the server does not run.
type Conflict ¶
type Conflict struct {
Account string
// Checked tells if the check of the server occurred. When it is false, the other fields
// tell nothing about the server.
Checked bool
// FileAccepted and LegacyAccepted tell if the server accepts the key of the key file and
// the key of the legacy item.
FileAccepted, LegacyAccepted bool
// Err is the error of the check of the server, or nil.
Err error
}
Conflict is a legacy item whose key is not the key of the key file, with the result of the check of the server. The legacy item and the key of the key file stay.
type File ¶
type File struct {
// contains filtered or unexported fields
}
File is the key file of the CLI. Make it with Open or Default.
func Default ¶
Default returns the key file in the state folder of the CLI, with the system keychain as the legacy keychain. With MAI_HOME, the key file has no legacy keychain, because the items of the keychain are of the home of the user and not of that folder.
func Open ¶
Open returns the key file in the folder dir. legacy is the keychain of mai 3.0 and 3.1, or nil for no move of legacy items.
func (*File) Add ¶
Add writes the key of the account to the key file only when the file has no key for the account. The check and the write occur with one lock. Add gives the key that the file has after the call, and added tells if it is key. Thus Add never replaces a key that a different process wrote.
func (*File) Candidates ¶
Candidates gives each account of the instance that can have a legacy keychain item, sorted: the owner account, each account in recorded, each account that the manifest in the folder of the key file records for the instance, and each account of the instance in the key file. It ignores an account of recorded with a different instance. Thus a command finds the legacy item of an agent through its record, also when the caller gives no record.
func (*File) Check ¶
Check examines the key file and its folder, and reads no key. It gives nil when the file does not exist. "mai doctor" uses it.
func (*File) Delete ¶
Delete removes the key of the account from the key file. It gives ErrNotFound when the key file has no key for the account. It does not change the legacy keychain.
func (*File) DeleteInstance ¶
DeleteInstance removes each key of the instance from the key file, and gives the accounts that it removed, sorted. The keys of the other instances stay.
func (*File) DeleteLegacy ¶
DeleteLegacy removes the legacy keychain item of the account. An item that does not exist is not an error.
func (*File) Get ¶
Get gives the key of the account. When the key file has no key for the account, Get moves the legacy keychain item of the account to the key file. It gives ErrNotFound when no key exists. When no keychain is available, Get gives ErrNotFound only when the manifest records no legacy item for the account. mai 3.0 and 3.1 did not operate with no keychain, thus then no legacy item exists.
func (*File) Has ¶
Has tells if the key file has a key for the account. It does not read the legacy keychain.
func (*File) HasLegacyItem ¶
HasLegacyItem tells if the account has a legacy keychain item. It reads no secret.
func (*File) LegacyItems ¶
LegacyItems gives each account of accounts that has a legacy keychain item, and reads no secret. When the legacy keychain is not available, the error is keychain.ErrUnavailable.
func (*File) MoveAll ¶
func (f *File) MoveAll(accounts []string, accepts Accepts) (MoveReport, error)
MoveAll moves the legacy keychain item of each account to the key file. When the key file has a key for the account of a legacy item, also a key that a different process wrote during the move, MoveAll deletes the legacy item only when it holds the same key, or when accepts tells that the server accepts the key of the key file and refuses the key of the legacy item. When accepts tells that the server accepts only the key of the legacy item, MoveAll writes that key to the key file and deletes the legacy item. Else the legacy item stays, and the report has a conflict. When the delete of a legacy item fails, the report has a stay. accepts can be nil. The error joins the failure of each account.
func (*File) OfInstance ¶
OfInstance gives each account of the instance in the key file, sorted.
func (*File) Peek ¶ added in v3.3.0
Peek gives the key of the account in the key file, for a command that changes nothing. It does not read the legacy keychain, and it makes no file and no folder. It gives ErrNotFound when the key file has no key for the account.
func (*File) RemoveEmpty ¶
RemoveEmpty removes the key file and its lock file when the key file holds no key. The check and the remove of the key file occur with the lock. Thus a key that a different process writes before the remove stays. RemoveEmpty gives the accounts of a key file that stays. After the remove, a process that waited for the lock writes a new key file.
type LegacyError ¶
LegacyError means that the key file has no key for the account, and that the read of its legacy keychain item failed, for example because the user refused the prompt of macOS. It is not ErrNotFound: the legacy item can hold the key. A keychain that is not available gives a LegacyError only when the manifest records a legacy item for the account. The text of the error gives the step for the user.
func (*LegacyError) Error ¶
func (e *LegacyError) Error() string
func (*LegacyError) Unwrap ¶
func (e *LegacyError) Unwrap() error
type ModeError ¶
ModeError means that a group or other users can read or change the key file. The CLI then refuses the file. The error tells the command that corrects the mode.
type MoveReport ¶
type MoveReport struct {
// Moved holds each account whose key went from the keychain to the key file, and whose
// legacy item MoveAll deleted.
Moved []string
// Cleaned holds each account whose legacy item MoveAll deleted, because the key file
// had the same key, or because the server accepts the key of the key file and refuses
// the key of the legacy item.
Cleaned []string
// Replaced holds each account whose key MoveAll replaced in the key file with the key of
// the legacy item, because the server accepts the key of the legacy item and refuses the
// key of the key file. MoveAll then deleted the legacy item.
Replaced []string
// Conflicts holds each legacy item that stays, because the key file has a different key
// for its account, and nothing proves that the server accepts the key of the key file.
// A conflict is not in the error of MoveAll.
Conflicts []Conflict
// Stays holds each legacy item whose delete failed, although the key file has the key of
// its account. A stay is not in the error of MoveAll.
Stays []Stay
Unavailable bool
}
MoveReport tells what MoveAll did.