ela
Contents

ManualPackages

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-inDoes
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.NAMEThe secret stored under NAME, as keyring.lookup("NAME") gives it
keyring.NAME = valueStores 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.NAME reads the environment, in code, in a command and in a double-quoted string, so a script needs no .env file. keyring is built in, as env is: no variable, constant, parameter, proc or import can take the name, and a script that tries, keyring = 1 anywhere, stops before line 1. A name the keyring does not hold is an error that names has(keyring.list(), "NAME"), the test for a secret that may be missing. NAME is a name as a variable's is; a secret named with a - or a ., such as github-token, is read with keyring.lookup("github-token").

  • keyring.NAME = value. Stores a secret as env.NAME = value sets a variable: it is keyring.store("NAME", value), waits for a locked keyring and fails as the store does, and the value is a string. keyring.NAME = null removes the secret, as keyring.clear("NAME") does and as env.NAME = null removes a variable; a name that was not there is fine. A name with a - or a . is stored with keyring.store. A name is one line: keyring.store refuses 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 first keyring. call, never before, so a script that does not use the keyring starts as it would without one, and loads no desktop library. ela --doctor says which: the keyring locked or unlocked, no session bus, no secret service, or no libsecret.

  • A locked keyring. keyring.lookup, keyring.store and keyring.clear each 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 what vars, which, procs, aliases and history print, wherever it appears.

  • Not written in the line. keyring.store("name", "the-secret") and keyring.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, and ela --lint reports 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_file of its own. ela's own procs read the path too, as file.read does.
  • A pipe holds a mebibyte, unless /proc/sys/fs/pipe-max-size says otherwise; longer text is an error.
  • ela --lint warns of a value from $keyring.NAME, keyring.lookup or ask.secret that reaches a command's arguments, through the variables and strings it is put in, and names secret_file. A shell built-in, such as cd, 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/