Table of Contents
*****************
gnu-pw-mgr - derive a password from an id
1 Introduction to password management
1.1 How evil-doers access your accounts
1.2 How to keep evil-doers at bay
1.3 How gnu-pw-mgr helps
2 Invoking gnu-pw-mgr
2.1 gnu-pw-mgr help/usage (`--help')
2.2 seed-options options
2.3 password-options options
2.4 formatting-options options
2.5 presetting/configuring gnu-pw-mgr
2.6 gnu-pw-mgr exit status
2.7 gnu-pw-mgr Examples
2.8 gnu-pw-mgr Authors
2.9 gnu-pw-mgr Notes
3 Warnings
3.1 Cleanups that need doing
3.2 Shell history
3.3 Best gnu-pw-mgr practices
3.4 Password reset arrangements
Appendix A GNU Free Documentation License
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
(https://en.wikipedia.org/wiki/Password_strength) on passwords in
general and there is a paper published at Stanford
(http://crypto.stanford.edu/PwdHash/pwdhash.pdf)* 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 (*note password options:
gnu-pw-mgr 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
*********************
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.
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 [ - [] | --[{=| }] ]... [ ]
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:
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
`' 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:
* may not be preset with environment variables or configuration
(rc/ini) files.
* 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.
text option (-s).
-----------------
This is the "seed text" option. This option takes a string argument
`TEXT'.
This option has some usage constraints. It:
* may not be preset with environment variables or configuration
(rc/ini) files.
* 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 "".
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:
* may not be preset with environment variables or configuration
(rc/ini) 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.
length option (-l).
-------------------
This is the "sets password length" option. This option takes a number
argument.
This option has some usage constraints. It:
* may not be preset with environment variables or configuration
(rc/ini) files.
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 `' 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:
* may not be preset with environment variables or configuration
(rc/ini) files.
* This option takes a keyword as its argument list. Each entry
turns on or off membership bits. These bits can be tested with
bit tests against the option value macro (OPT_VALUE_CCLASS). The
available keywords are:
alpha upper lower
digit special no-special
no-alpha no-triplets pin
alnum
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:
* can be disabled with -no-pbkdf2 and enabled with -use-pbkdf2.
* It is enabled by default.
* may not be preset with environment variables or configuration
(rc/ini) files.
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:
* may not be preset with environment variables or configuration
(rc/ini) files.
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:
* may not be preset with environment variables or configuration
(rc/ini) files.
By default, the output includes column headers. Suppressing it is
intended for automated logins.
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
Do not mix these styles within one configuration file.
Compound values and carefully constructed string values may also be
specified using XML syntax:
...<...>...
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.
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.
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):
first-seed-tagThis is only a 'test'. Were it *real*,
you _would_ likely know?
cclass = =alpha + upper + lower + digit + special
length = 32login-id = 'user-name'
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
============================
It is entirely possible that there are some web sites out there with
password requirements that this program cannot (at present) necessarily
comply with. There are some possible workarounds:
1. use an alternate purturbation on the web site name. For the normal
variation on the web site name, apply a "-login-id" value that
tells you how to derive the alternate purturbation.
This will always work.
2. Request the addition of a new character classification flag. If
the issue can be satisfied by polishing the emitted password a
little bit, this is an easy way to fix it.
3. File a bug report that encourages me to add a "-purturb" option.
It would allow you to specify a purturbation specific for a certain
password id for a specific seed tag. For example:
gnu-pw-mgr --tag one --text 'some text'
gnu-pw-mgr --purturb one,xyz my example.com
For the seed tagged "one", the password id of "my example.com"
would have a purturbation string of "xyz" used for creating the
hash password. Hopefully, with one or two wiggles, you will wind
up with an acceptable password.
You'll need to explain why the first option, above, does not work.
This would be some work.
4. Something else, surely. Please send a bug report (preferably a
patch :) so the issue can be fixed.
3.2 Shell history
=================
It is imprudent to leave your invocations in your shell history. These
are often stored away in your home directory, unless you do something
to keep it out of your history. It should not be the end of the world
because it is troublesome to also obtain the configuration file.
Still, it is not wise to tempt fate.
If you use BASH for your shell,
HISTCONTROL=ignorespace
HISTIGNORE=gnu-pw-mgr *:*/gnu-pw-mgr *
unset HISTFILE
are your friends. Press the space bar before the command name, or
specify that anything that looks like a "gnu-pw-mgr" command should be
ignored or eliminate history entirely.
Also, if you put your password id's on the command line, they become
part of the process history and can be found. If that is a conceivable
problem, then you may prefer to not put it on the command line and then
type it in in response to a prompt. Your password id will not be echoed
back as you type it.
3.3 Best gnu-pw-mgr practices
=============================
Try out several password id transforms before changing all your
passwords on all your sites. You may decide it is too hard or too easy
and want to change it. However, once you have gone to the trouble of
changing the passwords on a lot of sites, you won't be especially eager
to do it again. So, play with it on one site you use a lot, change the
password a lot as you change the transform and then make a good
decision.
Once you need to or are required to change a password, add another
seed to your configuration file. Henceforth, you will be presented two
passwords. If you have updated your password, use the more recent one.
(That is what *Note the tags are for: gnu-pw-mgr seed-options.)
Otherwise, login with the old password and update to the new one.
Eventually, you should be able to retire the old seed.
When choosing your password id transform, use things that you can
easily remember. Especially if some nonsense thing can be easily
remembered. Separate the components with unusual things like multiple
punctuation characters. Do odd things with the top level domain.
cApitaliZe strangely. Use a slightly different transform for financial
institutions. If someone gets ahold of your seed file, you want to
hope that a dictionary attack will not be readily successful.
But lastly and most important: be sure you can remember your
transform(s). If you forget, your password is gone. So choose what
you can remember and be consistent.
3.4 Password reset arrangements
===============================
Some sites will allow you to set up password resets using alternate
channels (i.e. not your primary email address). Take advantage of this
whenever possible. If someone gains access to your email, you don't
want them to reset all your passwords, intercept the restore access
emails and, thus, gain access to all your password protected accounts.
Appendix A GNU Free Documentation License
*****************************************
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
`http://fsf.org/'
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book.
We recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it
can be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
"Document", below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as "you". You
accept the license if you copy, modify or distribute the work in a
way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in
the notice that says that the Document is released under this
License. If a section does not fit the above definition of
Secondary then it is not allowed to be designated as Invariant.
The Document may contain zero Invariant Sections. If the Document
does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images
composed of pixels) generic paint programs or (for drawings) some
widely available drawing editor, and that is suitable for input to
text formatters or for automatic translation to a variety of
formats suitable for input to text formatters. A copy made in an
otherwise Transparent file format whose markup, or absence of
markup, has been arranged to thwart or discourage subsequent
modification by readers is not Transparent. An image format is
not Transparent if used for any substantial amount of text. A
copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and
standard-conforming simple HTML, PostScript or PDF designed for
human modification. Examples of transparent image formats include
PNG, XCF and JPG. Opaque formats include proprietary formats that
can be read and edited only by proprietary word processors, SGML or
XML for which the DTD and/or processing tools are not generally
available, and the machine-generated HTML, PostScript or PDF
produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, "Title
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies
of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
"Acknowledgements", "Dedications", "Endorsements", or "History".)
To "Preserve the Title" of such a section when you modify the
Document means that it remains a section "Entitled XYZ" according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow
the conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the
title equally prominent and visible. You may add other material
on the covers in addition. Copying with changes limited to the
covers, as long as they preserve the title of the Document and
satisfy these conditions, can be treated as verbatim copying in
other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or
state in or with each Opaque copy a computer-network location from
which the general network-using public has access to download
using public-standard network protocols a complete Transparent
copy of the Document, free of added material. If you use the
latter option, you must take reasonably prudent steps, when you
begin distribution of Opaque copies in quantity, to ensure that
this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you
distribute an Opaque copy (directly or through your agents or
retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of
copies, to give them a chance to provide you with an updated
version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with
the Modified Version filling the role of the Document, thus
licensing distribution and modification of the Modified Version to
whoever possesses a copy of it. In addition, you must do these
things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of
previous versions (which should, if there were any, be listed
in the History section of the Document). You may use the
same title as a previous version if the original publisher of
that version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on
the Title Page. If there is no section Entitled "History" in
the Document, create one stating the title, year, authors,
and publisher of the Document as given on its Title Page,
then add an item describing the Modified Version as stated in
the previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in
the "History" section. You may omit a network location for a
work that was published at least four years before the
Document itself, or if the original publisher of the version
it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the
section all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section
titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this,
add their titles to the list of Invariant Sections in the Modified
Version's license notice. These titles must be distinct from any
other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end
of the list of Cover Texts in the Modified Version. Only one
passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the
Document already includes a cover text for the same cover,
previously added by you or by arrangement made by the same entity
you are acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination
all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one section
Entitled "History"; likewise combine any sections Entitled
"Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the
documents in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow
this License in all other respects regarding verbatim copying of
that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of
a storage or distribution medium, is called an "aggregate" if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual
works permit. When the Document is included in an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document's Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void,
and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly
and finally terminates your license, and (b) permanently, if the
copyright holder fails to notify you of the violation by some
reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from
that copyright holder, and you cure the violation prior to 30 days
after your receipt of the notice.
Termination of your rights under this section does not terminate
the licenses of parties who have received copies or rights from
you under this License. If your rights have been terminated and
not permanently reinstated, receipt of a copy of some or all of
the same material does not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
`http://www.gnu.org/copyleft/'.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License "or any later version" applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If
the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by the
Free Software Foundation. If the Document specifies that a proxy
can decide which future versions of this License can be used, that
proxy's public statement of acceptance of a version permanently
authorizes you to choose that version for the Document.
11. RELICENSING
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server.
A "Massive Multiauthor Collaboration" (or "MMC") contained in the
site means any set of copyrightable works thus published on the MMC
site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this
License somewhere other than this MMC, and subsequently
incorporated in whole or in part into the MMC, (1) had no cover
texts or invariant sections, and (2) were thus incorporated prior
to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the
site under CC-BY-SA on the same site at any time before August 1,
2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
====================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.