[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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] | [ ? ] |
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. 2.3.2 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 no shared shared tag - disabled as '--no-shared' - 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 128 - may not be preset -c Mbr cclass password character class - may not be preset - is a set membership option -r Num rehash rehash password with PKCS#5 PBKDF2 - prohibits the option 'use-pbkdf2' - it must be in the range: 1 to 100000 - may not be preset Num use-pbkdf2 rehash 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 management and output format.: Flg Arg Option-Name Description -H no no-header omit printing the password headers - may not be preset Str select-chars select only certain bytes of a password - may not be preset -C Str confirm confirmation question answers (see man page) - may not be preset -S no status Show status of a password id - may not be preset -d no delete Remove a password id entry - may not be preset Str domain a reminder of domains used for password id - may not be preset - may appear multiple times Str config-file specify configuration file - 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 no-sequence pin alnum two-upper two-lower two-digit two-special or an integer mask with any of the lower 15 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, 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. Please send bug reports to: <bkorb@gnu.org> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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 values consist of four 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.
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
(see section 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.
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.
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.
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>". 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.
This is the “shared tag” option.
This option has some usage constraints. It:
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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.
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.
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.
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.
This is the “password character class” option. This option takes a set-member argument.
This option has some usage constraints. It:
alpha upper lower digit special no-special no-alpha no-triplets no-sequence pin alnum two-upper two-lower two-digit two-special |
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:
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.
of three or more characters.
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
.
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.
This is the “rehash password with pkcs#5 pbkdf2” option. This option takes a number argument.
This option has some usage constraints. It:
By default, passwords are created with the SHA256 hash of the "seed string", the password id and the tag text associated with the seed. If not disabled, the pbkdf2 funcion (with SHA1 as the HMAC function) is used to rehash the result a number of times. By default, this is done 10007 times. This can be over-ridden by specifying a different count. 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.
This is the “rehash password with pkcs#5 pbkdf2” option. This option takes a number argument.
This option has some usage constraints. It:
This is the deprecated spelling for the -r/–rehash option. This will be marked as not-for-command-line-use with the next release.
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 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Options for management and output format..
This is the “omit printing the password headers” option.
This option has some usage constraints. It:
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.
This is the “select only certain bytes of a password” option. This option takes a string argument.
This option has some usage constraints. It:
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.
This is the “confirmation question answers (see man page)” option. This option takes a string argument.
This option has some usage constraints. It:
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.
This is the “show status of a password id” option.
This option has some usage constraints. It:
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.
This is the “remove a password id entry” option.
This option has some usage constraints. It:
This will print out the attributes associated with a particular password id and remove them from the configuration file.
This is the “a reminder of domains used for password id” option. This option takes a string argument ‘DOMAIN’.
This option has some usage constraints. It:
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.
This is the “specify configuration file” option. This option takes a string argument ‘CONFIG-FILE’.
This option has some usage constraints. It:
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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>...<...>...</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:
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 information may be selected with an option argument. Only the first letter of the argument is examined:
Only print the version. This is the default.
Name the copyright usage licensing terms.
Print the full copyright usage licensing terms.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
Written by Bruce Korb.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 June 30, 2018 using texi2html 1.82.