[Top] [Contents] [Index] [ ? ]

gnu-pw-mgr - derive a password from an id

This program is designed to make it easy to reconstruct difficult passwords when they are needed while limiting the risk of attack. The user of this program inputs a self-defined transformation of a web site URL and obtains the password and user name hint for that web site. You must, however, be able to remember this password id, or the password is lost forever.

The Wikipedia has an excellent article on passwords in general and there is a paper published at Stanford* that describes a browser plug-in that is substantially similar to this program.

* Blake Ross; Collin Jackson, Nicholas Miyake, Dan Boneh and John C. Mitchell (2005). "Stronger Password Authentication Using Browser Extensions". Proceedings of the 14th Usenix Security Symposium. USENIX. pp. 17–32


1. Introduction to password management

This introductory chapter will superficially cover password management issues and describe how this program addresses them.


1.1 How evil-doers access your accounts

First and foremost, because people give them their credentials (user name and password). Not deliberately, of course. They leave them around or reply to a phishing scam or whatever. There’s nothing providers of security assistance can do about it. That’s the user’s responsibility. Be careful out there. Keep your systems clean of spyware and watch for phishers.

The next most common method is for a site to get “hacked” and the crooks make off with password files. Hopefully, they’ve been hash encoded, but they are sometimes in the clear. If they are hashed, then the crackers will try to reverse the hash and see how far and wide they can use your credentials.

Other possibilities are telescopes, line taps, wireless sniffing and so on. Unless you are a secret agent working on national security matters, these possibilities are not terribly likely possibilities.

The purpose of this software is to render useless, limit the potential damage, or, at least, make it difficult to gain much use out of any information captured. And, also, make it convenient enough to use that it is actually used. A very secure password scheme that is a nuisance to use, won’t be used, and is therefore not very useful.


1.2 How to keep evil-doers at bay

First and foremost, make sure you know which web site you are interacting with when you supply credentials. Do not blindly click an email that looks like one from Pay Pal or your bank. Go to your financial institutions via a bookmark or a well-established link.

Next, use different passwords at different web sites. Unless you restrict yourself to very few web sites, this means you must manage them somehow. Pieces of paper get lost. Password list files can wind up getting compromised. If that happens, your entire online world is now open. Encrypted password list files can get decrypted, yielding the same possibility.

Do not use either words or common transformations of words for passwords. Such techniques severly limit possibilities and constrained possibilities are searched more quickly.

Use long passwords. The longer they are, the more difficult (compute costly) they are to break.


1.3 How gnu-pw-mgr helps

Passwords must be long, not based on dictionary words, never repeated, and not recorded where they can be gotten at. You can’t do it by memory.

This program addresses the recording problem by not recording passwords. They get re-computed every time, based on two separate factors each of which is unlikely to come into the hands of miscreants. The first factor is a series of one or more password “seeds” or “salts”. You specify a tag for it and the seed itself is a block of text that contains at least 64 characters. The second factor is a transformation of the web site address. That transformation should be easy to remember, fairly easy to type, include odd capitalization, use multiple unusual punctuation characters, have a secret word or two and never, ever be written down.

The text, the URL transform and the tag get hashed together to construct the password. Since different web sites have different password requirements and allowances, the result is trimmed and tweaked until it meets the requirements. It is always possible that new requirements might pop up, and the password polishing code has been written to be extensible.

Using this program not only makes it simple to have different passwords for different web sites, it actually makes it inconvenient to use the same password. It does not support the same password, so you would have to remember the jumble of letters and numbers for any alternate web site. You won’t do that.

gnu-pw-mgr works by storing the seed in a private configuration file and obtaining the password identifier either from the command line or by reading it from standard input. This configuration file must be secured from reading and writing by other users, but obtaining access will not reveal passwords. The key to this is the password identifier. It is the second factor in the authentication (password re-creation) that is never recorded.

The configuration file does not need to be super secret. What needs to be super secret is the transformation used for constructing password identifiers. That transform includes a prefix, a suffix, alternate capitalizations and a variety of word separators. For example, you could prefix every domain name with “access” and suffix it with “por-favor”, then use an unusual spelling of the domain, perhaps “ExAmplE.moC”. This yields a password id of “access/ExAmplE+moC=por-favor”. You can remember that fairly easily. If a bad actor gets your seed file, they won’t work out the transform any time soon.

On the other hand, if someone does happen to see you create the transform, it will still do no good, unless they also get the second factor: the seed file. This is true even if they also get one password. There is no way to derive the seed file from the password id and the resulting password. It is a one way hash function. It is not an encryption.

Finally, since every site has their own set of attributes that make for acceptable passwords, the hash of the inputs must be modified. The hash of the password id by itself is used as a key to look up any previously established password constraints (see section password options). These password attributes are lentgh, character types required and/or prohibited from being in the password and some hint about your login name or id. That name need not be exactly your login name, just something that will remind you about which one you use for the site. It may be omitted, if you are sure you can remember.

These site specific options are then used to format the password display.


2. Invoking gnu-pw-mgr




Example usage can be seen in the example section below.



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

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


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:
                                - 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

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
Separate these with punctuation characters to make dictionary attacks more

are assembled into one password id with space characters separating the
original operands.

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>


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):


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


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.


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:


There must be at least one upper case letter.


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


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.


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


There must be at least one decimal digit character.


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


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


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


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


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.


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.


2.5 presetting/configuring gnu-pw-mgr





or by

<?program gnu-pw-mgr>

Do not mix these styles within one configuration file.



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




version (-v)



Only print the version. This is the default.


Name the copyright usage licensing terms.


Print the full copyright usage licensing terms.


2.6 gnu-pw-mgr 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


no seeds were specified in the config file


The seed value was invalid


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.


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):

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


2.8 gnu-pw-mgr Authors

Written by Bruce Korb.


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.


3. Warnings

Things to consider.


3.1 Cleanups that need doing



    This will always work.






3.2 Shell history


If you use BASH for your shell,





3.3 Best gnu-pw-mgr practices






3.4 Password reset arrangements



A. GNU Free Documentation License

Version 1.3, 3 November 2008


Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.


























    4. Preserve all the copyright notices of the Document.
    8. Include an unaltered copy of this License.
    15. Preserve any Warranty Disclaimers.
































ADDENDUM: How to use this License for your documents


  Copyright (C)  year  your name.
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  Free Documentation License''.


    with the Invariant Sections being list their titles, with
    being list.



[Top] [Contents] [Index] [ ? ]

Table of Contents

[Top] [Contents] [Index] [ ? ]

About This Document


The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back Previous section in reading order 1.2.2
[ > ] Forward Next section in reading order 1.2.4
[ Up ] Up Up section 1.2
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

