/authinfo

KISS password manager

Primary LanguageCGNU General Public License v3.0GPL-3.0

What is authinfo?

Authinfo is supposed to be a “keep it simple stupid” and “don’t reinvent the wheel” password manager. It’s simple in that the passwords are stored in a human readable text file. Actually, it doesn’t even support updating that file. It doesn’t reinvent the wheel because it reuses the file format that has been there for decades, namely netrc with extensions introduced in Emacs. Similarly, authinfo can read files that are encrypted with GnuPG. Since authinfo cannot update password file on its own, it’s should be used in conjunction with your favorite text editor. It’s especially convenient if your editor can also seamlessly decrypt GnuPG files (like Emacs does).

Getting authinfo

Building from source

Authinfo follows usual GNU Autotools build procedure:

# Only required if you're missing ./configure (e.g. you're building from git)
$ ./autogen.sh

# Check build deps and configure the project.
$ ./configure

# Compile and install everything.
$ make all install

If you encounter an error about undefined macro AM_PATH_GPGME_PTHREAD when running ./autogen.sh you will need to install the libgpgme autoconf macros. On Ubuntu/Debian install the libgpgme-dev package, on Fedora or other RPM based distros install the gpgme-devel package.

Optional features:

  • GPG support (default is on)

    To disable pass --disable-gpg flag to configure script. When enabled, GPGME must be installed in the system.

  • Python2 bindings (default is on)

    To disable pass --disable-python flag to configure script. Minimal supported python version is 2.5. Python3 is not supported.

  • CLI tool (default is on)

    To disable pass --disable-cli flag to configure script.

Using it

Password file

By default authinfo will look for password file in the following locations (in order):

  • $HOME/.authinfo.gpg (if GPG support is enabled)
  • $HOME/.authinfo
  • $HOME/.netrc.gpg (if GPG support is enabled)
  • $HOME/.netrc
  • /etc/authinfo.gpg (if GPG support is enabled)
  • /etc/authinfo
  • /etc/netrc.gpg (if GPG support is enabled)
  • /etc/netrc

When password file has .gpg extension, it is assumed to be GPG encrypted and authinfo will try to decrypt it.

Password file format

Authinfo uses extended netrc file format introduced by Gnus. In short, password file consists of one or more lines of the following format:

host <host> [user <user>] [password <password>] [port <port>] [force true|yes]

Some keywords has synonyms:

  • machine is synonymous to host
  • login and account are synonymous to user
  • protocol is synonymous to port

The meaning of the most keywords should be obvious. Keyword force has no practical use, it’s supported just for compliance with Gnus.

Additionally, host <host> key/value pair can be substituted by a single keyword default. The latter matches any host, so it should (but not required) be the last one in the file.

Any of the key/value pairs can be omitted.

Password can be specified in two formats: plain text and GPG-encrypted. Plain text passwords can be optionally put in double quotes. This allows to use password having white-space characters. Double quote can be escaped inside double-quoted password by prepending it by backslash. Similarly, backslash can be escaped by another backslash. GPG-encrypted passwords are of the form gpg:<base64 GPG-encrypted password>.

There’s also macdef construct that is supported only for compliance with original netrc file format. It’s a multi-line construct that starts with a line of the form macdef <name> and ends with an empty line. See also example below.

Lines that start with # character are considered comments.

Password files are processed line by line in order. This means that more specific entries should be put first, more general ones should be put in the end of the file.

Example of password file:

# macro definition (silently ignored)
macdef test
test

# password is 'pass"\ word'
host hostname user username password "pass\"\\ word" protocol protocol

# GPG-encrypted password
host hostname user username password gpg:hQEMA2iK9nrzfXUQAQf+NNAyrTm6HH9T267LOdDIpxGgkG2yvd+2C179zHrTmxLqGs0oVH1Fi2kQIlnACATF/JxoCN9+dKJ1qOmNRx0l9bSkoLBqGPOI8yDu0jyYMZw35Bz7+12uMaDFtapluYq6YZrNcLIpHkSB/dq5is127+abUY68C1+lvGgO9ry+r74e5AcHl8xBOFly3rj/hTuRTDwPemog6kZ2gs9Swjffiqt5kJm/fgctKRhntPqWYQz3jfcc1oQQN9SRuy6y3cy4jaqB7VyQNi38630vqHiuf0Ha+kFe9xYonkWtAxpJyPPzQMegjd0IsCjvZyKezyQeX9EcMSEd1b9U/Ot0KS+1+9JDAd0Z87Cp7q+rYThR5OThbIu3iW9L4ofIqMolHqwsXux2BbiRafzjzF/RVzoy+KkBv0P5GBX0lPXR0ytWlwsTWRSLkQ==

# default password
default password default-password

Password file can be checked for syntactical correctness by authinfo CLI utility as follows:

authinfo --validate --path <path to password file>

CLI tool

$ authinfo --help
Usage: authinfo [COMMAND] [OPTIONS]

Supported commands:
   --query      query authinfo file for matching entries
        --user             match user name
        --host             match host name
        --protocol         match protocol
        --path             use this authinfo file instead of autodiscovered
   --validate   check authinfo file for syntax errors
        --path             use this authinfo file instead of autodiscovered
   --version    print version info
   --help       print this help

The CLI tool can work in syntax checking and querying mode.

Syntax checking

In syntax checking mode only the syntax of password file is checked and in case there exist any errors they are reported:

$ echo "hostt hostname password password" > /tmp/authinfo
$ authinfo --path /tmp/authinfo --validate
Parsing /tmp/authinfo.
  1:0: Unknown keyword used
  1:5: Unknown keyword used
  1:0: Host not specified
$ echo "host hostname password password" > /tmp/authinfo
$ authinfo --path /tmp/authinfo --validate
Parsing /tmp/authinfo.
  No errors found

Querying

In querying mode the first entry that matches user input is returned. This mode is desgined to be used in conjunction with shell eval function. It will set several environment variables to the corresponding values from the matching entry:

$ echo "host hostname user user password password protocol 80" > /tmp/authinfo
$ echo "default password default-password" >> /tmp/authinfo
$ eval $(authinfo --path /tmp/authinfo --query --host hostname --user user)
$ env | grep AUTHINFO_
AUTHINFO_PROTOCOL=80
AUTHINFO_USER=user
AUTHINFO_PASSWORD=password
AUTHINFO_HOST=hostname
$ eval $(authinfo --path /tmp/authinfo --query --host other-host --user user)
AUTHINFO_PROTOCOL=
AUTHINFO_USER=
AUTHINFO_PASSWORD=default-password
AUTHINFO_HOST=

In case password file contains syntax errors, authinfo reports to the standard error the first encountered error and exits with non-zero exit code.

$ echo "hostt hostname password password" > /tmp/authinfo
$ vars=$(authinfo --path /tmp/authinfo --query hostname)
authinfo: parse error at /tmp/authinfo:1:0 (Unknown keyword used)
$ echo $?
1

Library

C

authinfo can be used as a library. API is briefly documented using Doxygen. As an example of using the API one can refer to authinfo cli.

Python

Authinfo provides Python bindings for a subset of functionality. Refer to the source for details. This script can also be used as an example.

OfflineImap

Authinfo can be used for storing passwords for OfflineImap. Just copy docs/offlineimap.py to ~/.offlineimap.py. And then use it from your .offlineimaprc:

[general]
accounts = Gmail
maxsyncaccounts = 3
pythonfile = ~/.offlineimap.py

[Account Gmail]
localrepository = Local
remoterepository = Remote

[Repository Local]
type = Maildir
localfolders = ~/mail/aliaksiej.artamonau@gmail.com

[Repository Remote]
type = IMAP
remotehost = imap.gmail.com
remoteuser = aliaksiej.artamonau@gmail.com
remotepasseval = get_password("imap.gmail.com", "aliaksiej.artamonau@gmail.com")
ssl = yes
maxconnections = 1
realdelete = no
cert_fingerprint = b0ba392bba326e6feb1add4d04fa0fb86cd173fa

Pidgin

Authinfo can also be used to keep passwords for libpurple based IM clients like Pidgin. Please refer to pidgin-authinfo page for details.