Keyring
In the terminalela --spec keyring
Secrets by name in the desktop's secret store (gnome-keyring on a Mint or GNOME desktop), through libsecret, so a script never keeps a token in its text or in a file.
| Built-in | Does |
|---|---|
keyring.lookup(name) | Returns the secret stored under exactly name, as a string |
keyring.store(name, secret) | Stores secret under name, replacing what was there |
keyring.store(name) | Asks for the secret at the terminal as ask.secret does, and stores it |
keyring.clear(name) | Removes the secret under name; a name that was not there is fine |
keyring.list() | Returns the names of ela's secrets, sorted: names only, never a secret |
$keyring.NAME | The secret stored under NAME, as keyring.lookup("NAME") gives it |
keyring.NAME = value | Stores value under NAME, as keyring.store("NAME", value) does; null removes it |
keyring.store("github") # typed unseen at the terminal, onceauth = "Authorization: Bearer $keyring.github"curl -H @${secret_file($auth)} https://api.github.example/user
$keyring.NAME. Reads a secret as$env.NAMEreads the environment, in code, in a command and in a double-quoted string, so a script needs no.envfile.keyringis built in, asenvis: no variable, constant, parameter, proc or import can take the name, and a script that tries,keyring = 1anywhere, stops before line 1. A name the keyring does not hold is an error that nameshas(keyring.list(), "NAME"), the test for a secret that may be missing.NAMEis a name as a variable's is; a secret named with a-or a., such asgithub-token, is read withkeyring.lookup("github-token").keyring.NAME = value. Stores a secret asenv.NAME = valuesets a variable: it iskeyring.store("NAME", value), waits for a locked keyring and fails as the store does, and the value is a string.keyring.NAME = nullremoves the secret, askeyring.clear("NAME")does and asenv.NAME = nullremoves a variable; a name that was not there is fine. A name with a-or a.is stored withkeyring.store. A name is one line:keyring.storerefuses one holding a line break, a tab or another control character.Where it works. In a desktop session, or wherever a secret service answers on the session bus. With none, as over ssh, in CI or from cron, every call is an error saying there is no keyring here: such a script takes the secret from an environment variable and reads it as
$env.NAME. libsecret is loaded at the firstkeyring.call, never before, so a script that does not use the keyring starts as it would without one, and loads no desktop library.ela --doctorsays which: the keyring locked or unlocked, no session bus, no secret service, or no libsecret.A locked keyring.
keyring.lookup,keyring.storeandkeyring.cleareach wait 30 seconds for the keyring's unlock prompt, then stop with an error saying the keyring is locked. One the keyring refused, its unlock prompt dismissed or impossible to show, says so too.No secret in a message. An error never shows a secret, nor its length: every secret the script has looked up or stored, and every answer to
ask.secret, is replaced by<secret>in every message and in whatvars,which,procs,aliasesandhistoryprint, wherever it appears.Not written in the line.
keyring.store("name", "the-secret")andkeyring.name = "the-secret"are errors, since the script and the shell's history would keep the secret: leave it out to type it unseen, or pass it from a variable. The run refuses one before it asks the keyring, andela --lintreports one as an error. At the prompt such a line is written neither to the history file nor to the list Up walks.keyring.store(name)needs a terminal, and reads from it, never from stdin.The secrets are ela's own, stored under its app id with the name as their one attribute and the label
ela: <name>in Passwords and Keys.What the keyring guards. Secrets at rest: out of the script, out of files and
.env, out of the history and out of commits. It does not guard them from a process of the same user while the keyring is unlocked, which can ask the secret service as ela does, nor from a command given one in its arguments (Secrets in commands).
Secrets in commands #
A command's arguments are readable by every user on the machine, in /proc/<pid>/cmdline and
in what ps prints, and its environment by every process of the same user. A secret goes to a
command in a file instead, for the many tools that read one (curl -H @file,
docker login --password-stdin, --password-file).
secret_file(text)puts the text in a pipe and gives the pipe's path,/dev/fd/N. The text is held in memory, never written to disk, and the path holds nothing secret.- The first command started whose arguments or redirects name the path is given the pipe, at
the same number, and reads the text from it; no other command has it. ela then closes its own
end, so the pipe is read once: a later command that names the path finds no file there, and
each command takes a
secret_fileof its own. ela's own procs read the path too, asfile.readdoes. - A pipe holds a mebibyte, unless
/proc/sys/fs/pipe-max-sizesays otherwise; longer text is an error. ela --lintwarns of a value from$keyring.NAME,keyring.lookuporask.secretthat reaches a command's arguments, through the variables and strings it is put in, and namessecret_file. A shell built-in, such ascd, runs inside ela and is not warned of;spin's command is.
token = $keyring.registrydocker login --password-stdin registry.example < ${secret_file($token)}password = ask.secret("Backup host's password? ")sshpass -f ${secret_file($password)} rsync -a /srv/ ada@backup.example:/srv/