=========
 abraxas
=========

------------------------------
collaborative password utility
------------------------------

:Author: Kale and Ken Kundert <abraxas@nurdletech.com>
:Date: 2016-08-14
:Version: 1.8
:Manual section: 1

.. :Copyright: Kale and Ken Kundert
.. :Manual group: Utilities

SYNOPSIS
========
**abraxas** [*options*] [*account*]

OPTIONS
=======
-P, --password          Output the password (default if nothing else is 
                        specified).
-N, --username          Output the username.
-Q <N>, --question <N>  Output the answer to security question *N*.
-A, --account-number    Output the account number.
-E, --email             Output the email associated with this account.
-U, --url               Output the website address.
-R, --remarks           Output remarks.
-i, --info              Output all account information except the 
                        secrets (the password and the answers to the 
                        security questions).
-a, --all               Same as --info except also output the password.

-q, --quiet             Disable all non-essential output.
-c, --clipboard         Write output to clipboard rather than stdout.
-t, --autotype          Mimic a keyboard to send output to the active 
                        window rather than stdout. In this case any 
                        command line arguments that specify what to 
                        output are ignored and the *autotype* entry 
                        directs what is to be output.

-f <str>, --find <str>  List any account that contains the given string 
                        in its ID.
-s <str>, --search <str>
                        List any account that contains the given string 
                        in username, account, email, url, remarks, or its ID.

-S, --stateless         Do not use master password or accounts file.
-T <template>, --template <template>
                        Template to use if account is not found.

-b, --default-browser   Open account in the default browser.
-B <browser>, --browser <browser>
                        Open account in the specified browser.

-n, --notify            Output messages to notifier.

-l, --list              List available master passwords and templates 
                        (only pure templates are listed, not accounts, 
                        even though accounts can be used as templates)

-w <secs>, --wait <secs>
                        Wait this log before clearing the secret (use 
                        0 to disable clearing).

--archive               Archive all the secrets to 
                        ~/.config/abraxas/archive.gpg.
--changed               Identify all the secrets that have changed since 
                        last archived.

-I <GPG-ID>, --init <GPG-ID>
                        Initialize the master password and accounts 
                        files in ~/.config/abraxas (but only if they do 
                        not already exist).

-h, --help              Show a brief summary of available command line
                        options.

DIAGNOSTICS
===========

A log file is created in ~/.config/abraxas/log (the location of this 
file can be specified in the *log_file* variable in the accounts file).

DESCRIPTION
===========
Abraxas is password utility that can store or generate your passwords 
and produce them from the command line. It can also be configured to 
autotype your username and password into the current window so that you 
can log in with a simple keystroke. 

Abraxas is capable of generating two types of passwords, character based 
(pass words) or word based (pass phrases).  Pass phrases are generally 
preferred if you have a choice, but many websites will not take them. 
The benefit of pass phrases is that they are relatively easy to remember 
and type, and they are very secure. The pass phrases generated by 
Abraxas generally consist of four words, each word is drawn from 
a dictionary of 10,000 words.  Thus, even if a bad guy knew that four 
lower case words were being used for your pass phrase, there are still 
10,000,000,000,000,000 possible combinations for him to try (this 
represents a minimum entropy of 53 bits).  Using six words results in 80 
bits of entropy, which meets the threshold recommended by NIST for the 
most secure pass phrases. For more on this, see 'How Much Entropy is 
Enough' below.

For another perspective on the attractiveness of pass phrases, see 
`<http://xkcd.com/936/>`_.

Unlike password vaults, Abraxas produces a highly unpredictable password 
from a master password and the name of the account for which the 
password is to be used. The process is completely repeatable. If you 
give the same master password and account name, you will get the same 
password. As such, the passwords do not have to be saved; instead they 
are regenerated on the fly.

As a password generator, Abraxas provides three important advantages 
over conventional password vaults.  First, it allows groups of people to 
share access to accounts without having to securely share each password.  
Instead, one member of the group creates a master password that is 
securely shared with the group once. From then on any member of the 
group can create a new account, share the name of the account, and all 
members will know the password needed to access the account. The second 
advantage is that it opens up the possibility of using high-quality 
passwords for stealth accounts, which are accounts where you remember 
the name of the account but do not store any information about even the 
existence of the account on your computer.  With Abraxas, you only need 
to remember the name of the account and it will regenerate the password 
for you. This is perfect for your TrueCrypt hidden volume password.  
Finally, by securely storing a small amount of information, perhaps on 
a piece of paper in your safe-deposit box, you can often recover most if 
not all of your passwords even if you somehow lose your accounts file.  
You can even recover passwords that were created after you created your 
backup. This is because Abraxas combines the master password with some 
easily reconstructed information, such as the account name, to create 
the password. If you save the master password, the rest should be 
recoverable.

To use it, one creates a file that contains information about each of 
his or her non-stealth accounts.  Among that information would be 
information that controls how the passwords are generated. This file is 
generally not encrypted, though you can encrypt it if you like).  
Another file is created that contains one or more master passwords.  
This file is always GPG encrypted.

The intent is for these files to not include the passwords for your 
accounts.  Rather, the passwords are regenerated when needed from the 
account information and from the master password. This makes it easy to 
share passwords with others without having to pass the passwords back 
and forth.  It is only necessary to create a shared master password in 
advance. Then new passwords can be created on the fly by either party.

Basic Use
+++++++++
To generate a password for an account that exists in your accounts file, 
you would use::

    abraxas <account>

where <account> is the name of your account. For example, to get your 
gmail password you might use::

    $ abraxas gmail
    PASSWORD: preview secretary eschew cobra

The $ represents the shell prompt, you do not type it.

The password generator is also capable of generating answers to the 
security questions that are the bane of most websites these days.  
Simply add the questions to your accounts file and the password 
generator will produce an unpredictable yet consistent and easily 
communicated response for each question.  For example::

    $ abraxas -q0 gmail
    name of elementary school: balaclava essence guildhall persimmon

There is a very good reason not to actually provide your personal 
information as a response to these questions. Often it is friends and 
family members that are the most likely to attempt to surreptitiously 
access your account. As with most crime, it comes down to opportunity 
and motive. The opportunity comes from the fact that they know you and 
so are more likely to know the information, like the answers to these 
security questions, that allows them access to your account.  The motive 
generally comes eventually. It is hard to live one's life without 
angering a friend or family member at some point, and then they may feel 
justified in helping themselves to your accounts.

Abraxas outputs account information upon request.  It is a command line 
program, so you just specify the right command line options to have it 
print out the username, account number, url, etc.::

    $ abraxas -i gmail
    USERNAME: derrickAsh
    EMAIL: derrick.ash@yahoo.com
    URL: https://accounts.google.com

The output can be produced in three different ways.

The first is that it is simply displayed on standard output. It tries to 
keep the secret information (such as the password and answers to the 
security questions) secure by displaying it for a minute and then 
erasing it. The program continues to run while the password is 
displayed. To clear the password early, just kill the program by typing 
Ctrl-C.

The second way is to send it to the clipboard. For security reasons, the 
clipboard is cleared after a minute.

Finally, the password generator can output the information by mimicking 
the keyboard and 'typing' it to active window.  This is referred to as 
'autotype'.

Account Discovery
+++++++++++++++++
If no account is specified, Abraxas examines the window title and from 
it tries to determine which account to use. In its most simple form 
window titles can be specified in the accounts, and the account with the 
matching title is used. Multiple title strings can be associated with 
each account, and those strings support globbing. In addition, Abraxas 
can sometimes recognize components of the window title, components such 
as the URL, the protocol, etc., and it can compare those component to 
fields in the account to determine which account to use.  In particular, 
Abraxas comes with the ability to recognize the title components created 
by 'Hostname in Titlebar', an add-on to Firefox that puts the URL and 
protocol in the title bar (with Chrome, use 'Url in Title').

If the title matches multiple accounts, a dialog box opens with the list 
of each of those accounts. Use the up or *k* and down or *j* keys to 
navigate to the account you want and select it with *Enter* or *Return*.  
You can cancel using *Esc*.

The combination of autotype and account discovery is very powerful if 
you configure your window manager to run Abraxas because it makes it 
possible to login to websites and such with a single keystroke.

Autotype can sometimes be a bit problematic. Some programs can 
occasionally stubbornly ignore particular autotyped characters, 
particularly $ and newline. This can occur with Firefox, whereas in 
those cases it did not occur with Chrome. If this affects you, you 
might want to simply remove $ from your character set for your 
passwords (newline is not as problematic as it generally occurs last, 
and so can be added by hand).

Security
++++++++
The accounts file can be a simple ASCII file that contains somewhat 
sensitive information.  From this file one could infer the existence of 
an account and would have some identifying information such as the 
username and account number, but the passwords themselves are not 
contained in the file, only the parameters of the passwords (how many 
characters, the alphabet used, etc).  Because the file is somewhat 
sensitive, it is recommended that it should be readable only by the 
user. If you are uncomfortable with this level of protection, you can 
further protect the accounts file by encrypting it. To do so, run::

    $ cd ~/.config/abraxas
    $ gpg --armor --encrypt --recipient <your-gpg-id> accounts
    $ shred -u accounts

In some cases the mere existence of this file, even though encrypted, 
may be problematic. Once discovered, authorities may compel you hand 
over the decryption keys, which would expose the existence of all of 
your accounts and provide access to each of them.

It is possible to generate passwords for accounts that are not described 
in the accounts file. As such, these 'stealth' accounts are more secure 
since no information is retained that refers to these accounts; they 
provide plausible deniability. To generate a password or pass phrase for 
such an account you would simply give the name of the account on the 
command line. For example::

    $ abraxas my-secret-account
    warning: account 'my-secret-account' not found.
    PASSWORD: apologist imprint epigram return

You would need to remember the name of the account precisely. If you 
give even a slightly different account name you will get a different 
password.  In this case Abraxas generates a password with the default 
settings, which is actually a 4 word pass phrase, which most websites 
reject.  You can indicate that Abraxas should generate an actual 
password by giving the name of a template.  A template is simply a named 
collection of attributes that specify how to generate the password. You 
may configure as many templates as you wish.  By default, Abraxas comes 
with eight templates:

=words:
    A sequence of random English words. The default is to use 4 words, 
    which provides 53 bits of entropy.
=chars:
    A sequence of random letters (upper and lower case), digits and 
    symbols. The default is to use 12 characters, which provides 79 bits 
    of entropy.
=pin:
    A sequence of random digits. The default is to use 4 digits, which 
    provides 13 bits of entropy.  This is typically used for PIN 
    numbers.
=num:
    A sequence of random digits. The default is to use 8 digits, which 
    provides 26 bits of entropy.  This is also used for PIN numbers, but 
    it provides better security.
=word:
    A single random word. Chosen from a list of 10,000 words, this is 
    equivalent to a 4 digit PIN, but is easier to remember. It provides 
    13 bits of entropy.
=anum:
    A sequence of easily distinguishable random letters. The letters may 
    be both upper and lower case, but will not include any letters that 
    are easily confused with other letters or digits (Il1O0). Typically 
    used for web passwords.  The default is to use 12 characters, which 
    provides 78 bits of entropy.
=master:
    A sequence of random English words. The default is to use 8 words, 
    which provides 106 bits of entropy.
=extreme:
    A sequence of random letters (upper and lower case), digits and 
    symbols. The default is to use 64 characters, which provides 420 
    bits of entropy.

You can generate a pass word (a collection of characters) instead of 
a pass phrase (a collection of words) for a stealth account with::

    $ abraxas -T =anum my-secret-account
    warning: account 'my-secret-account' not found.
    PASSWORD: Rkybp9EFXLu4

It is possible to take this one step further. Specifying the ``-S`` or 
``--stateless`` command line option instructs Abraxas to avoid using any 
saved information when generating the password.  In this situation, you 
must give both the account name (on the command line) and the master 
password. As long as you use a master password or pass phrase that is 
memorable for you but difficult for everyone else to guess, you should 
be reasonably safe from someone figuring out your password even if they 
have full access to your private GPG keys and your Abraxas files. For 
example::

    $ abraxas --stateless my-secret-account
    Provide master password for account 'my-secret-account'.
    Password: my-secret-master-passphrase
    PASSWORD: toehold physical illusion washroom

When running in stateless mode you do not have access to any templates 
you may have created in your accounts file because that file is ignored, 
but you have access to the predefined templates described above::

    $ abraxas -S -T =anum my-secret-account
    Provide master password for account 'my-secret-account'.
    Password: my-secret-master-passphrase
    PASSWORD: LfCkPFygucg9

GPG Security
++++++++++++
Abraxas inherits the security policies of GPG.  It is important to 
recognize that any weakness in your GPG security policy could result in 
your passwords being exposed. For example, if you enter your GPG pass 
phrase into your agent and it is retained while you walk away from your 
computer, then someone could use this program to access all of your 
passwords (with access to your accounts file, they would have everything 
they needed to know to break into each of your accounts).  Thus, it is 
important to both carefully consider your use of the GPG agent and it's 
password retention time. It is also important that you dutifully use 
screen locking when you walk away from your computer.

Archiving
+++++++++
There are features in Abraxas that could allow you to inadvertently and 
unknowingly change the passwords that are generated for an account.  For 
example, changing the master password would change the passwords for all 
accounts that linked to that master password. Similarly, changing the 
definition of a template would change the passwords for all accounts 
that employ that template. To avoid this, Abraxas allows you to quickly 
tell whether the passwords for any known account has changed. To use 
this feature, you must first archive your secrets.

You generate an archive of the secrets for all of the known accounts 
with::

    abraxas --archive

The resulting archive is encrypted and saved in your settings directory 
(~/.config/abraxas/archive.gpg). In addition, you can check your current 
list of secrets against those in the archive with::

    abraxas --changed

It is a good idea to do this when you have change your master password 
or accounts files and when you have update your version of Abraxas.  
Doing so will alert you to any unexpected changes. It is also 
recommended that you always confirm you only see the changes you expect 
before updating the archive.

How it Works
++++++++++++
A secret such as a password or the answer to a security question starts 
out as the simple stringing together of a few things: the account name, 
the version, and the master password.  For security questions, the 
question itself is added as well.  This combined string is then hashed 
into a very long number.  Even the smallest change in any of the 
components used to create it results in a very different number.  The 
number is then mapped into pass phrases or passwords with your choice of 
words or characters.  As long the master password is kept secure, this 
approach is very safe.  Even knowing the algorithm and having access to 
the source code of the Abraxas program would not allow someone to 
predict your passwords.

Getting Started
+++++++++++++++
Before using Abraxas you must have a GPG identity (a public/private key 
pair tagged to an email account). In addition, it is recommended that 
you run gpg-agent (add 'gpg-agent' alone on a line into your 
~/.gnupg/gpg.conf file and then start the agent).  Then you must create 
your accounts and master password file.  To do so, run::

    $ abraxas -I <gpg-id>

For example, if your GPG identity is linked to derrickAsh@gmail.com, 
then use:: 

    $ abraxas -I derrickAsh@gmail.com

This creates two files if they do not already exist, 
~/.config/abraxas/master.gpg and ~/.config/abraxas/accounts. Of the two, 
the master.gpg file is encrypted. If you would like the accounts file to 
be encrypted as well, encrypt it now using::

    $ gpg --armor --encrypt --recipient <gpg-id> accounts

To make it easy to change an encrypted file, it is recommended that you 
download and install the gpg plugin for vim, which can be found at 
http://www.vim.org/scripts/script.php?script_id=3645.  The file you will 
download is named gnupg.vim, simply move it into ~/.vim/plugin.  Once 
you have done this, edit the file with vim or gvim.  It should ask you 
for the GPG pass phrase associated with the GPG identity you specified.  
Once you have entered it you can edit the file. 

Then if desired, you can edit the accounts file and add an account. See 
'man 5 abraxas' for information about all of the fields that Abraxas 
uses.  For example, to add your gmail and bank accounts, you would add 
something like the following to your accounts file::

    accounts = {
        <skip over the templates at the start>
        "chase": {
            'template': "=chars",
            'username': "derrickash",
            'account': "6478-4789874",
            'email': "derrickAsh@gmail.com",
            'url': "https://chaseonline.chase.com",
        },
        "gmail": {
            'template': "=words",
            'username': "derrickAsh",
            'email': "derrick.ash@yahoo.com",
            'url': "https://accounts.google.com",
            'security questions': [
                "name of elementary school",
            ],
            'window': [
                'Google Accounts*',
                'Gmail*',
            ],
            'autotype': "{username}{tab}{password}{return}",
        },
    }

These fields are described in detail in abraxas(5).

How Much Entropy is Enough
++++++++++++++++++++++++++

A 4 word Abraxas password provides 53 bits of entropy, which seems like 
a lot, but NIST is recommending 80 bits for your most secure passwords.  
So, how much is actually required. It is worth exploring this question.  
Entropy is a measure of how hard the password is to guess. Specifically, 
it is the base two logarithm of the likelihood of guessing the password 
in a single guess. Every increase by one in the entropy represents 
a doubling in the difficulty of guessing your password. The actual 
entropy is hard to pin down, so generally we talk about the minimum 
entropy, which is the likelihood of an adversary guessing the password 
if he or she knows everything about the scheme used to generate the 
password but does not know the password itself.  So in this case the 
minimum entropy is the likelihood of guessing the password if it is 
known that we are using 4 space separated words as our pass phrase.  
This is very easy to compute.  There are roughly 10,000 words in our 
dictionary, so if there was only one word in our pass phrase, the chance 
of guessing it would be one in 10,000 or 13 bits of entropy. If we used 
a two word pass phrase the chance of guessing it in a single guess is 
one in 10,000*10,000 or one in 100,000,000 or 26 bits of entropy.

The probability of guessing our pass phrase in one guess is not our 
primary concern. Really what we need to worry about is given 
a determined attack, how long would it take to guess the password. To 
calculate that, we need to know how fast our adversary could try 
guesses. If they are trying guesses by typing them in by hand, their 
rate is so low, say one every 10 seconds, that even a one word pass 
phrase may be enough to deter them.  Alternatively, they may have 
a script that automatically tries pass phrases through a login 
interface.  Again, generally the rate is relatively slow.  Perhaps at 
most the can get is 1000 tries per second. In this case they would be 
able to guess a one word pass phrase in 10 seconds and a two word pass 
phrase in a day, but a 4 word pass phrase would require 300,000 years to 
guess in this way.

The next important thing to think about is how your password is stored 
by the machine or service you are logging into. The worst case situation 
is if they save the passwords in plain text. In this case if someone 
were able to break in to the machine or service, they could steal the 
passwords. Saving passwords in plain text is an extremely poor practice 
that was surprisingly common, but is becoming less common as companies 
start to realize their liability when their password files get stolen. 
Instead, they are moving to saving passwords as hashes.  A hash is 
a transformation that is very difficult to reverse, meaning that if you 
have the password it is easy to compute its hash, but given the hash it 
is extremely difficult to compute the original password. Thus, they save 
the hashes (the transformed passwords) rather than the passwords. When 
you log in and provide your password, it is transformed with the hash 
and the result is compared against the saved hash. If they are the same, 
you are allowed in. In that way, your password is no longer available to 
thieves that break in.  However, they can still steal the file of hashed 
passwords, which is not as good as getting the plain text passwords, but 
it is still valuable because it allows thieves to greatly increase the 
rate that they can try passwords. If a poor hash was used to hash the 
passwords, then passwords can be tried at a very high rate.  For 
example, it was recently reported that password crackers were able to 
try 8 billion passwords per second when passwords were hashed with the 
MD5 algorithm. This would allow a 4 word pass phrase to be broken in 14 
days, whereas a 6 word password would still require 4,000,000 years to 
break.  The rate for the more computational intensive sha512 hash was 
only 2,000 passwords per second. In this case, a 4 word pass phrase 
would require 160,000 years to break.

In most cases you have no control over how your passwords are stored on 
the machines or services that you log into.  Your best defense against 
the notoriously poor security practices of most sites is to always use 
a unique password for sites where you are not in control of the secrets.  
For example, you might consider using the same pass phrase for you login 
password and the pass phrase for an ssh key on a machine that you 
administer, but never use the same password for two different websites 
unless you do not care if the content of those sites become public.

So, if we return to the question of how much entropy is enough, you can 
say that for important passwords where you are in control of the 
password database and it is extremely unlikely to get stolen, then four 
randomly chosen words from a reasonably large dictionary is plenty (for 
Abraxas this is 53 bits of entropy).  If what the pass phrase is trying 
to protect is very valuable and you do not control the password database 
(ex., your brokerage account) you might want to follow the NIST 
recommendation and use 6 words to get 80 bits of entropy. If you are 
typing passwords on your work machine, many of which employ keyloggers 
to record your every keystroke, then no amount of entropy will protect 
you from anyone that has or gains access to the output of the keylogger.  
In this case, you should consider things like one-time passwords or 
two-factor authentication. Or better yet, only access sensitive accounts 
from your home machine and not from any machine that you do not control.

SEE ALSO
========
abraxas(3), abraxas(5)