gnu-pw-mgr(1)

NAME
*[B-Font]gnu-pw-mgr - derive a password from an id

SYNOPSIS
*[B-Font]gnu-pw-mgr [*[B-Font]-flags] [*[B-Font]-flag [*[I-Font]value]] [*[B-Font]--option-name[[=| ]*[I-Font]value]] [ <pw-id> ]

DESCRIPTION
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.

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.

define a seed for a series of passwords.

    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 three 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.

    ver The version of gnu-pw-mgr used to initially store the seed. This is used to determine the password tweaking algorithm to use when the generated password does not meet the site criteria (@pxref{gnu-pw-mgr password-options,, the password character class option}). On rare occasions, new character class restrictions may cause a change in the algorithm used to tweak passwords. When this is done, the old algorithm is still used to tweak passwords from the older seeds.

    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 triplet 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.

seed tag.
    This option may not be preset with environment variables or in initialization (rc) files. This option must not appear in combination with any of the following options: login-id, cclass, length, specials, no-header, pbkdf2.

    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.

seed text.
    This option may not be preset with environment variables or in initialization (rc) files. This option must appear in combination with the following options: tag.

    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 the text is shorter than 64 characters, it will be padded out. In such a case, you will need to save the configuration file some place secure or it will be extremely difficult to reconstruct it, should that become necessary.

  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.

a reminder of your login id.
    This option may not be preset with environment variables or in initialization (rc) files.

    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.

sets password length.
    This option may not be preset with environment variables or in initialization (rc) files. This option takes an integer number as its argument. The value of *[I-Font]number is constrained to being:
    in the range  4 through 128
    The default *[I-Font]number for this option is:
     16

    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. The default length is 16.

    Password lengths beyond 40 characters force the use of the pbkdf2 algorithm. i.e. --no-pbkdf2 is ignored. This limit is derived from "MIN_BUF_LEN - 8".

password character class.
    This option may not be preset with environment variables or in initialization (rc) files. This option takes a keyword as its argument list. Each entry turns on or off membership bits. The bits are set by name or numeric value and cleared by preceding the name or number with an exclamation character ('!'). They can all be cleared with the magic name none and they can all be set with all. A single option will process a list of these values. The available keywords are:
    alpha       upper       lower       digit
    special     no-special  no-alpha    no-triplets
    pin         alnum       two-upper   two-lower
    two-digit   two-special
    or their numeric equivalent.

    The default *[I-Font]set-member for this option is:
     alpha + digit

    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, one 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.

    two-* Two of a particular character class are required. Specifying this implies "at least one of" the specified type. Two upper case, lower case, punctuation (special) and digit characters may be specified this way.

compute password with PKCS#5 PBKDF2.
    The no-pbkdf2 form will disable the option. This option is enabled by default. This option may not be preset with environment variables or in initialization (rc) files. This option takes an integer number as its argument. The default *[I-Font]number for this option is:
     10007

    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.

    Normally, this option should not be used. If, however, you are getting invalid password complaints by your web site, this option might be used to change the computed password. Any value other than 10007 will yield a completely different password. For the several users of a pre-release version of this program, specify no-pbkdf2 to yield the original password result.

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

set alternate special characters.
    This option may not be preset with environment variables or in initialization (rc) files. The default *[I-Font]string for this option is:
     /+-

    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 include these three: /+-. Therefore, specify this option with exactly three characters in the string argument. They will be used to replace the three characters above. The first two may be the same, but the third must be different from the first two. This option is accepted, but serves no purpose if no-special has been specified in the --cclass option.

select only certain bytes of a password.

    There exists at least one web site that asks you to enter just some of the password characters, like the second, tenth and sixteenth. With long, memorable resistant passwords, this can be difficult to do. For such web sites, provide this option with the string "2,10,16" as the option argument. The characters to select are space or comma separated values. The result cannot be longer than the original password.

  Options for management and output format.

omit printing the password headers.
    This option may not be preset with environment variables or in initialization (rc) files.

    By default, the output includes column headers. Suppressing it is intended for automated logins. The login name hint will not be provided, but the tag is printed.

Show status of a password id.
    This option may not be preset with environment variables or in initialization (rc) files.

    Show all the modified password attributes for a password id. If there are no special attributes, the word "default" is printed. No password id is invalid, but some may have all default values, consequently there is no special information kept about it.

    Command line options will affect the output, but will not be stored for future use.

Remove a password entry.
    This option may not be preset with environment variables or in initialization (rc) files.

    This will print out the attributes associated with a particular password id and remove them from the configuration file.

  Options supported by the AutoOpts option library.

Display usage information and exit.

Pass the extended usage information through a pager.

Load options from cfgfile.
    The no-load-opts form will disable the loading of earlier config/rc/ini files. --no-load-opts is handled early, out of order.

Output version of program and exit.  The default mode is `v', a simple
    version. The `c' mode will print copyright information and `n' will print the full copyright notice.

OPTION PRESETS
Any option that is not marked as not presettable may be preset by loading values from configuration ("RC" or ".INI") file(s).

FILES
See OPTION PRESETS for configuration files.

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>

EXIT STATUS
One of the following exit values will be returned:

Successful program execution.

the option/argument configuration is invalid

insufficient memory

no password entry for current user

home directory could not be found

config file improperly protected

config file missing

cannot update config file

no seeds were specified in the config file

The seed value was invalid

the list of characters for the --select-chars option is bad

There is a coding error that should be reported

A specified configuration file could not be loaded.

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

AUTHORS
Written by Bruce Korb.

COPYRIGHT
Copyright (C) 2013-2014 Bruce Korb all rights reserved. This program is released under the terms of the GNU General Public License, version 3 or later.

BUGS
Please send bug reports to: bkorb@gnu.org

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.

This manual page was AutoGen-erated from the gnu-pw-mgr option definitions.