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, or you may need multiple credentials for the same domain. Either way, a password id is formed by surrounding the domain name with unlikely prefixes, suffixes and punctuations.

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 each
        seed stored in the password configuration file.

One password is printed for every configured seed value with a matching --shared option state. Seed values are added by specifying just the --tag and --text options, with or without the --shared option. When passwords are printed, the tag is also printed in plain text.

Passwords are changed by specifying the -r or --rehash
        option with a new numeric value. The day this happens will be noted
        in the password configuration file and printed in the password header.

Password ids are never stored anywhere.

Please be sure to read the "Warnings" section in the full documentation.

NOTE: the --load-opts option is supported by the option
        processing library. This program actually prohibits its usage. The
        password configuration database is normally found in a standard
        location. It may be overridden at invocation time by the
        --config-file option. Using --load-opts on the command
        line will lead to a conflict error.

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 values consist of four 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.

    shared The presence of this sub-option specifies that the seed is only to be used with password ids that are also marked as --shared. Without this sub-option, the seed is only used with password ids that are not marked as --shared.

    The way to change a password is to specify the rehash count.
            It defaults to 10007. You can determine the current value with the
            --status option.

    Specify only the --tag and --text (and maybe --shared) command line options and the program will initialize or insert a new value into the configuration file. Specify only the tag and no other command line arguments, and the associated seed entry will be removed. All passwords using that seed will become unavailable.
            You cannot remove the last seed.

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, length, cclass, rehash, specials, no-header, select-chars, confirm, status, delete.

    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>".
            There must always be at least one. Multiple text seeds will
            cause multiple passwords to be printed out.

    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.

            The original expectation was that passwords would be updated on an
            occasional basis. Now that I have over 100 login credentials, it is
            clearly infeasible to go around and update them all. Instead, I have
            to decide which are important to update and use the --rehash
            option to change the rehash count. The date of the last rehash count change is recorded with the password id options.

shared tag.
    The no-shared form will disable the option. This option may not be preset with environment variables or in initialization (rc) files.

    If this option is used on conjunction with the text option, that seed is marked as a shared password seed and derived passwords are only printed for password ids that have been marked as shared. When used in conjunction with a password id, then the password id will be marked as a shared. Passwords will only be printed for seeds and ids that have matching “shared” settings.

set default character classes.
    The no-default-cclass form will disable the option. This option may not be preset with environment variables or in initialization (rc) files.

    When present on the command line by itself, the value is stashed in the configuration file and used in future invocations of “gnu-pw-mgr”.

    The GNU password manager defaults to requiring one alphabetic character (upper or lower case) and one digit. Most passwords are required to have something more complicated. Once this option has been provided, the new default will be applied whenever a new password identifier is detected. This detection is based on not finding any attributes stored in the configuration file. This means that if you rely on all defaults for some login (you never provided any "password options" for the id), the generated password might change.

    You cannot adjust previous values. The classes you select will become the default character classes from then on. Previous password ids will continue using the value assigned when the password was first created.

  Options for specifying password attributes.
The --cclass, --length, --tag, --shared and --specials options are stored in the configuration file. They are associated with a password ID via a clipped 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.

    Also, there are now some sites that send password credentials to a
            validation domain that is common among several domains. Since this
            application forces you to use different passwords for different domains
            and these domains force you to use the same password for different
            domains, this option solves the irresistable force and immovable
            object dilemma. For each of the dependent domains, specify this option
            that will remind you of the correct password id.

    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. 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. Use at least 24, if you can.

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
    no-sequence 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 (or their alternates), 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.

    no-sequence The password must not contain a consecutive sequence of three or more characters.

    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. “two-alpha” is not supported.

Change the password rehash count.
    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  1 through 100000

    Passwords are created with the SHA256 hash of the "seed
            string", the password id, and the tag text associated with the
            seed. The result is then "rehashed" with the pbkdf2 function.
            By default, this is done 10007 times. This can be changed by
            specifying a different count between 1 and 100,000. You can
            change this either directly with a count or by prefixing a
            number with a '+' or '-' character. The prefix will cause the
            previous value to be adjusted. Changing the count will change
            the password and will mark the entry with the date of the most
            recent password change.

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

rehash 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

    This option is for internal use only. The rehash count is stored in the configuration file as a "pbkdf2" value.

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 computed password is a base64 encoding of a sha256 hash of various inputs. Base64 encoding uses '+' and '/' characters. However, when this program is required to have at least one special character in the result, and neither the '+' nor '-' get encoded, one character will be replaced with a hyphen (-).

    Some web sites require particular special characters in their passwords that do not include these three default characters. For those passwords, 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.

  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. For confirmation output, the two values will have column labels, and for password output, it will contain any login hint and the date the last time the --rehash count was changed. (Password was changed.)

    Suppressing it is intended for automated logins. The login name hint will not be provided, but the tag is printed.

select only certain bytes of a password.
    This option may not be preset with environment variables or in initialization (rc) files.

    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.

confirmation question answers (see man page).
    This option may not be preset with environment variables or in initialization (rc) files.

    Some web sites use "confirmation questions" that, supposedly, only you know the answer to. Unfortunately, these are often times questions that can be researched by others or they can be questions that you have forgotten the answers to or may have multiple answers for. The net result is that you are locked out. This option makes it easy to get consistent answers to these questions and have these answers be different for every web site, just like your password.

    Providing this option will cause the argument to be merged into the hash source (changing the resulting password). Exactly 12 letters will be extracted from the hash and converted to lower case. The string argument to this option should be the last word or two from the question, yielding an easy-to-remember way of obtaining a consistent answer to these inscrutable questions.

    You will need to update your confirmation question answers when you update your password seed. However, since that can be highly
            inconvenient also, this option will print TWO results. The first
            will be dependent on the current password hash, the second will
            depend only on the confirmation question and password id.
            Consequently, the second one will be stable going forward.
            The first answer is now deprecated.

out-of-date confirmation question answers.
    This option may not be preset with environment variables or in initialization (rc) files.

    Use this method of answering confirmation questions only if you have to. When your password changes, this will change, too. Inconvenient.

    NOTE: THIS OPTION IS DEPRECATED

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

a reminder of domains used for password id.
    This option may appear an unlimited number of times. This option may not be preset with environment variables or in initialization (rc) files.

    If you create a lot of passwords, it is easy to forget which domains have an associated password. You do not want to specify a password id, merely note the domains for which you have a password id. With well over 100 passwords, I found I need to be able to know which need to be updated occasionally. This option will cause a separate text database to be updated with a domain name and an update date. With a single hyphen as the option argument, that database will be printed out in chronological order.

specify configuration file.
    This option may not be preset with environment variables or in initialization (rc) files.

    If you need an alternate location for storing your password seed files, use this option. It must be specified on the
            command line every time it is needed. You are responsible to
            ensure that the directory already exists. The file will be
            left read-only when gnu-pw-mgr exits. The containing directory permissions will not be checked or altered.

  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

no password id was specified

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