[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Invoking gnu-pw-mgr

The password id should contain a fairly consistent permutation of the URL you are logging in to. "Fairly" because you may wish to vary your financial institutions differently than your newspaper. e.g. "my/banK$moC" versus "bLog-oRg". And then surround the id with prefixes and suffixes. Separate these with punctuation characters to make dictionary attacks more difficult.

Only the passwords for one password id are ever printed. If the command line contains multiple operands (arguments after the options), then they are assembled into one password id with space characters separating the original operands.

One password is printed for every configured seed value. Seed values are added by specifying just the --tag and --text options. The tag is also printed with each password. The --login-id, --length, --cclass and --specials options are associated with each password id. Password ids are never stored anywhere.

Example usage can be seen in the example section below.

This chapter was generated by AutoGen, using the agtexi-cmd template and the option descriptions for the gnu-pw-mgr program. This software is released under the GNU General Public License, version 3 or later.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 gnu-pw-mgr help/usage (‘--help’)

This is the automatically generated usage text for gnu-pw-mgr.

The text printed is the same whether selected with the help option (‘--help’) or the more-help option (‘--more-help’). more-help will print the usage text by passing it through a pager program. more-help is disabled on platforms without a working fork(2) function. The PAGER environment variable is used to select the program, defaulting to ‘more’. Both will exit with a status code of 0.

 
gnu-pw-mgr - derive a password from an id - Ver. 1.0.8-8224-dirty
Usage:  gnu-pw-mgr [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <pw-id> ]

Options for adding and removing seeds in the configuration file.:

  Flg Arg Option-Name    Description
   -t Str tag            seed tag
                                - prohibits these options:
                                login-id
                                cclass
                                length
                                specials
                                no-header
                                use-pbkdf2
                                - may not be preset
   -s Str text           seed text
                                - requires the option 'tag'
                                - may not be preset

Options for specifying password attributes.:

  Flg Arg Option-Name    Description
   -i Str login-id       a reminder of your login id
                                - may not be preset
   -l Num length         sets password length
                                - it must be in the range:
                                  4 to 42
                                - may not be preset
   -c Mbr cclass         password character class
                                - may not be preset
                                - is a set membership option
      Num use-pbkdf2     compute password with PKCS#5 PBKDF2
                                - disabled as '--no-pbkdf2'
                                - enabled by default
                                - may not be preset
      Str specials       set alternate special characters
                                - may not be preset

Options for specifying output format.:

  Flg Arg Option-Name    Description
   -H no  no-header      omit printing the password headers
                                - may not be preset

Options supported by the AutoOpts option library.:

  Flg Arg Option-Name    Description
   -v opt version        output version information and exit
   -h no  help           display extended usage information and exit
   -M no  more-help      extended usage information passed thru pager
      Str load-opts      load options from a config file
                                - disabled as '--no-load-opts'
                                - may appear multiple times

Options are specified by doubled hyphens and their name or by a single
hyphen and the flag character.

The valid "cclass" option keywords are:
  alpha upper lower digit special no-special no-alpha no-triplets pin alnum
  or an integer mask with any of the lower 10 bits set
or you may use a numeric representation.  Preceding these with a '!'
will clear the bits, specifying 'none' will clear all bits, and 'all'
will set them all.  Multiple entries may be passed as an option
argument list.
The password id should contain a fairly consistent permutation of the URL
you are logging in to.  "Fairly" because you may wish to vary your
financial institutions differently than your newspaper.  e.g.  "my/banK$moC"
versus "bLog-oRg".  And then surround the id with prefixes and suffixes.
Separate these with punctuation characters to make dictionary attacks more
difficult.

Only the passwords for one password id are ever printed.  If the command
line contains multiple operands (arguments after the options), then they
are assembled into one password id with space characters separating the
original operands.

One password is printed for every configured seed value.  Seed values are
added by specifying just the '--tag' and '--text' options.  The tag is also
printed with each password.  The '--login-id', '--length', '--cclass' and
'--specials' options are associated with each password id.  Password ids
are never stored anywhere.

Please send bug reports to:  <bkorb@gnu.org>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 seed-options options

Options for adding and removing seeds in the configuration file.. The --text option or the --tag option (when by itself) tell the program to manage password "seeds" in its database (configuration file). Both options together add a new seed, and --tag, by itself on the command line, removes a seed.

seed option.

This is the “define a seed for a series of passwords” option. This option takes a hierarchy argument ‘SEED’. This option is not a command line option. It is also the only option that is directly processed from the config file.

The seed value consists of two named parts (sub-options):

tag

These are displayed next to each displayed password to help identify them.

text

This is not displayed, but is used for the SHA initial value. This may be arbitrarily long.

It is expected that when you must create a new password for an existing site, you will add a seed to your config file. Specify only the --tag and --text command line options and the program will insert the new pair into the configuration file. Specify only the tag and no other command line arguments, and the associated seed entry will be removed. After that, every password id will have a new "most recent" password associated with it. You are expected to gradually update all of your passwords and retire "seed" values no longer in use.

New sites will not need a new seed. Simply supplying the new <pw-id> command argument will yield a new password.

tag option (-t).

This is the “seed tag” option. This option takes a string argument ‘TAG’.

This option has some usage constraints. It:

The tag for a seed to be added to or removed from the config file. The use depends on whether or not there is a --text option.

text option (-s).

This is the “seed text” option. This option takes a string argument ‘TEXT’.

This option has some usage constraints. It:

The text for a password seed to be added to the config file. This text cannot include the 7 character sequence "</text>".

This text must be at least 64 characters long. The expectation is you will write a sentence or two that you can easily remember, including any capitalization, punctuation and spacing. You should include some non-alphabetic, non-digit characters here and there to make a dictionary attack more difficult. But if you need to reconstruct this, you need to remember them.

If you provide an empty string, you will have a seed text of 64 random characters. If your string gets padded, you will need to save the configuration file some place secure or it will be extremely difficult to reconstruct it.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3 password-options options

Options for specifying password attributes.. The --cclass, --length, --tag and --specials options are stored in the configuration file. They are associated with a password ID via the sha check sum of the id. They will be recalled the next time that id is used.

login-id option (-i).

This is the “a reminder of your login id” option. This option takes a string argument.

This option has some usage constraints. It:

It is sometimes difficult to remember your login name for a given site. Or even, perhaps, if you have ever set up an account on a particular site. By specifying this option, you will know both that you have set it up and you will have a reminder what your login name is. Avoid using your real login name.

The login-id has no effect on the final password, so it may be specified or altered at any time.

length option (-l).

This is the “sets password length” option. This option takes a number argument.

This option has some usage constraints. It:

Some web sites are more restrictive. Some are more generous. Set this value in your home config file to change your default and specify it on the command line for specific sites. Use of this option requires a <pw-id> operand.

Password lengths of 4 through 7 characters are limited to "pin" numbers. "pin" numbers are 4 or more digits. All other passwords must be at least 8 characters long.

cclass option (-c).

This is the “password character class” option. This option takes a set-member argument.

This option has some usage constraints. It:

This option augments or specifies which character classes either must or must not appear in the final password.

Some sites disallow special characters, other sites require them, and still others require them, but only certain ones. If disallowed, specify no-special and special characters will be replaced with digits. If special is specified specifically, then in the absence of a ’+’ or ’/’ character, the second character will be replaced with a hyphen. Other characters may be substituted for these three special characters with the --specials option.

Explanations of the keywords:

upper

There must be at least one upper case letter.

lower

There must be at least one lower case letter. Both this and ‘upper’ together require one of each.

alpha

There must be at least one alphabetic character, either upper or lower If either ‘upper’ or ‘lower’ is specified, this attribute is a no-op.

no-alpha

Alphabetic characters are prohibited. This conflicts with ‘upper’, ‘lower’ and ‘alpha’.

digit

There must be at least one decimal digit character.

no-triplets

When three characters in a row are the same, the third is fiddled. Letters are changed to the next letter and z becomes a. Digits are handled similarly. Special characters are replaced with the third possible special character (-, unless modified with --specials). (Yes, there are a few such sites.)

special

The password must contain at least one ‘special character’ (a non-alphabetic, non-digit character).

no-special

The password must not contain any characters that are not alphabetic or decimal digits.

pin

The password is all digits, a Personal Identification Number. This is an abbreviation for no-alpha + no-special + digit.

alnum

This is an abbreviation for alpha + digit.

pbkdf2 option.

This is the “compute password with pkcs#5 pbkdf2” option. This option takes a number argument.

This option has some usage constraints. It:

By default, passwords are created by hashing together using the pbkdf2 funcion with SHA1 as the HMAC function. The seed string is passed as the salt data and the password id glued to the tag text for each seed is passed as the password data. The data are processed 10007 times. This can be over-ridden by disabling pbkdf2 entirely or by specifying a different count.

Please see RFC 2898 for a specification of the PBKDF2 (Password-Based Key Derivation Function version 2) function.

specials option.

This is the “set alternate special characters” option. This option takes a string argument.

This option has some usage constraints. It:

The password is a base64 encoding of a sha256 hash of various inputs. Base64 encoding uses ’+’ and ’/’ characters and when this program is required to have at least one special character in the result, it will replace one character with a hyphen (-).

However, some web sites require special characters and constrain them to be in a particular set that does not these three: ‘/+-’. Therefore, specify this option with exactly three characters in the string argument. They will be used to replace the three characters above. They may all be the same. This option is accepted, but serves no purpose if no-special has been specified in the --cclass option.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4 formatting-options options

Options for specifying output format..

no-header option (-H).

This is the “omit printing the password headers” option.

This option has some usage constraints. It:

By default, the output includes column headers. Suppressing it is intended for automated logins.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5 presetting/configuring gnu-pw-mgr

Any option that is not marked as not presettable may be preset by loading values from configuration ("rc" or "ini") files.

Configuration files may be in a wide variety of formats. The basic format is an option name followed by a value (argument) on the same line. Values may be separated from the option name with a colon, equal sign or simply white space. Values may be continued across multiple lines by escaping the newline with a backslash.

Multiple programs may also share the same initialization file. Common options are collected at the top, followed by program specific segments. The segments are separated by lines like:

 
[GNU-PW-MGR]

or by

 
<?program gnu-pw-mgr>

Do not mix these styles within one configuration file.

Compound values and carefully constructed string values may also be specified using XML syntax:

 
<option-name>
   <sub-opt>...&lt;...&gt;...</sub-opt>
</option-name>

yielding an option-name.sub-opt string value of

 
"...<...>..."

AutoOpts does not track suboptions. You simply note that it is a hierarchicly valued option. AutoOpts does provide a means for searching the associated name/value pair list (see: optionFindValue).

The command line options relating to configuration and/or usage help are:

version (-v)

Print the program version to standard out, optionally with licensing information, then exit 0. The optional argument specifies how much licensing detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the first letter of the argument is examined:

version

Only print the version. This is the default.

copyright

Name the copyright usage licensing terms.

verbose

Print the full copyright usage licensing terms.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.6 gnu-pw-mgr exit status

One of the following exit values will be returned:

0 (EXIT_SUCCESS)

Successful program execution.

1 (EXIT_INVALID)

the option/argument configuration is invalid

2 (EXIT_NO_MEM)

insufficient memory

3 (EXIT_BAD_USER)

no password entry for current user

4 (EXIT_HOMELESS)

home directory could not be found

5 (EXIT_PERM)

config file improperly protected

6 (EXIT_NO_CONFIG)

config file missing

7 (EXIT_NO_SEED)

no seeds were specified in the config file

8 (EXIT_BAD_SEED)

The seed value was invalid

9 (EXIT_CODING_ERROR)

There is a coding error that should be reported

66 (EX_NOINPUT)

A specified configuration file could not be loaded.

70 (EX_SOFTWARE)

libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.7 gnu-pw-mgr Examples

Before running the program to print a password, you must first initialize its database with at least one seed.

 
gnu-pw-mgr --tag "first-seed-tag" --text \
"This is only a 'test'.  Were it *real*,
you _would_ likely know?"

These two strings along with a password id are used to create a ‘sha256’ hash code password. So, now you are able to print a password.

 
gnu-pw-mgr --login-id "user-name" --length 32 \\
    --cclass=upper,lower,digit,special \\
    my example.com

In this example, the password id is the string "my example.com". The space character is inserted between the command line operands. The options are associated with this id via another ‘sha256’ sum of just the id. The "user-name" would typically be either your actual user name for the site, or something that could readily remind you of the login id. If omitted, just do not forget it. The length specifies the maximum length allowed for a password on the site. You will get a password of that length. The --cclass defines the allowed and/or required character class(es) for the passwords for the site.

With the above seed and invocation, you will see printed out exactly this:

 
seed-tag     login id hint: user-name   pw:
first-seed-tag iQiF1g5aLQ0JqFIUbR/svpTS+F/PCeoy

Henceforth typing just ‘gnu-pw-mgr my example.com’ will always yield this output. The options above are now associated with the password id via a hash code. The gnu-pw-mgr database (either ‘~/.local/gnupwmgr.cfg’ or ‘~/.gnupwmgrrc’, but the former preferred) will now be this (hash code abbreviated):

 
<seed>
  <tag>first-seed-tag</tag>
  <text>This is only a 'test'.  Were it *real*,
you _would_ likely know?</text>
</seed>
<program per_pw_id>
<pwtag id="*HASH*">
  cclass = =alpha + upper + lower + digit + special
</pwtag>
<pwtag id="*HASH*">length = 32</pwtag>
<pwtag id="*HASH*">login-id = 'user-name'</pwtag>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.8 gnu-pw-mgr Authors

Written by Bruce Korb.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.9 gnu-pw-mgr Notes

This program specifies its own configuration file and disallows the use of any other. This file should be modified by running this program and not by editing it. The --seed and --load-opts options cannot be specified on the command line and the --seed option is only recognized in a configuration file.

Password ids should have some always-used prefix and/or suffix glued onto a domain name or some trivial permutation of the domain name. If you forget your password id, then the associated password is irretrievably lost. The prefix and suffix should be easily remembered. If you do not add a prefix or suffix and the configuration file becomes compromised, then you have lost the keys to all your passwords because it becomes trivial to guess password ids.

For example, always prepending ‘_mine_’ to a domain would yield ‘_mine_example.com’ for your password id at ‘example.com’. Password ids are not stored anywhere.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Bruce Korb on November 14, 2013 using texi2html 1.82.