From aadb9e2e90925a187877241e50110e4ce7ea80a1 Mon Sep 17 00:00:00 2001 From: Benjamin Barenblat Date: Sat, 14 Mar 2015 19:47:09 -0400 Subject: Imported Upstream version 1.3 --- secpwgen.1 | 293 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 293 insertions(+) create mode 100644 secpwgen.1 (limited to 'secpwgen.1') diff --git a/secpwgen.1 b/secpwgen.1 new file mode 100644 index 0000000..5d6761f --- /dev/null +++ b/secpwgen.1 @@ -0,0 +1,293 @@ +.\" (c) 2004-2005 Zeljko Vrba +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.Dd April 4, 2005 +.Dt secpwgen 1 +.Os +.Sh NAME +.Nm secpwgen +.Nd "secure password generator" +.Sh SYNOPSIS +.Nm +.Fl p[e] +.Ar n +.Nm +.Fl s[e] +.Ar n +.Nm +.Fl A[adhsy] +.Ar n +.Nm +.Fl r +.Ar n +.Nm +.Fl k +.Ar n +.Sh DESCRIPTION +The +.Nm +command is used to generate secure, high-entropy passwords by +several methods. It aims to generate passwords that are strong and secure +enough for cryptographic purposes (e.g. for protecting keys). The exact +method is chosen by the options listed below: +.Bl -tag -width ".Fl d" +.It Fl p +Diceware method with the diceware dictionary. +.Ar n +is the number of words in the password. If the method is specified as +.Fl pe +then an enhanced password is generated. +.It Fl s +Same as +.Fl p +and +.Fl pe +but with the S/Key dictionary. +.It Fl A +Generates an ASCII password of +.Ar n +parts. At least one letter after A is mandatory. Each letter incorporates +additional set of components from which random elements are drawn. See the +exact method description below. +.It Fl r +Generates a random password and outputs it as base-64 encoded string. +.Ar n +is the desired number of bits of entropy. It will be rounded up to the +next higher multiple of 8. +.It Fl k +Same as +.Fl r +but uses the "koremutake" encoding instead of base 64 encoding. Koremutake +is yet another way of producing pronouncible phrases from long bit strings. +.It Ar n +Specifies the size of the password. The exact meaning depends on the +method and is described above in options. +.El +.Pp +The program outputs the generated passphrase and a calculated entropy +of the passphrase. +.Sh METHOD DESCRIPTIONS +The following subsections give detailed explanations of the password +generation methods. +.Ss DICEWARE METHOD +This method selects +.Ar n +random words from the given dictionary. The diceware dictionary contains +8192 words, and the S/Key dictionary contains 2048 words. Both dictionaries +have been taken from the internet (see references). +.Ss ENHANCED DICEWARE METHOD +Extends the diceware method by chosing a random letter in each word +and replacing that letter with one of 32 special symbols and 4 upper-case +letters (all words in the dictionary are lower-case). +.Ss ASCII METHOD +Draws +.Ar n +random elements from randomly chosen allowed sets and concatenates +them in a single string. The allowed sets are specified by the letters +following the +.Fl A +flag and have these meanings: +.Pp +.Bl -tag -width "X" -compact +.It a +alphanumeric characters +.It d +decimal digits +.It h +hexadecimal digits +.It s +special characters +.It y +3- and 4-letter syllables +.El +.Pp +Note that these sets are not all mutually exclusive. Such combinations +will have the same effect as specifying a single "larger" set. +.Ss RANDOM METHODS +Rounds +.Ar n +up to the next higher multiple of 8 (7 in case of koremutake) bits (does +nothing if it is already a multiple) and generates +.Ar n/8 +( +.Ar n/7 +) +random bytes. The resulting passphrase is output as a base-64 or koremutake +encoded string. +.Pp +In case of koremutake, for programming simplicity, each random byte is taken +mod 128 and looked up in the syllable dictionary. Since the random number +generator is assumed to be secure, i.e. generates uniformly distributed +radnom numbers, there is no weakness by using the mod operation. +.Sh SECURITY +First of all, a +.Sy warning: +as recommended on the diceware site, NEVER actually put spaces between +individual words of the generated passphrase. On many keyboards the space +key has very distinctive sound which makes possible for the attacker to +learn the number of words and possibly the number of letters in each word +(in correct order). These facts divulge much information and make passphrase +easier to guess. +.Pp +In the author's opinion the program is written very carefully so that the +generated passphrase can't end up accidentaly on the swap or core file. The +steps taken in securing the program: +.Bl -bullet +.It +Dedicating a separate block of memory for all confidential data. +.It +Zeroing that block of memory upon program exit (by registering the atexit() +function). +.It +Locking all programs' memory with mlockall(MCL_FUTURE), if possible (the +program must be run with root privileges or installed setuid root to be +able to do that). +.Pp +On some systems, locking memory with mlockall causes the program to fail +(because some library routines try to allocate too much memory). In that +case mlock is used with reduced security: the stack is not locked in memory. +.It +Disabling core-dumps in the event of crash. +.It +Cryptographically strong random number generator (using OpenSSL or cryptlib). +The exact method for generation is described in its respective source file. +.El +.Pp +The strength of the chain equals the strength of its weakest link. You should +put as much trust in this program as you trust the implementation of any of +the following used components: C library, the cryptographic toolkit used for +random number generation, the kernel, and, ultimately, the system +administrator (although not a SW component :), a malicious sysadmin can modify +the kernel or system libraries to log somewhere all output of a program). +.Pp +You should build the program as statically linked, if at all possible. There +are numerous ways in which dynamic linking can be used to subvert this +programs' security. Unfortunately, there is no reliable nor portable way to +discover at run-time if the program is statically or dynamically linked. +.Ss OPENSSL NOTES +This program does not take any steps to initialize the entropy pool. OpenSSL +uses the system-provided /dev/[u]random as the source of randomness. +OpenSSL should report an error on systems that do not provide the /dev/random +device. If you are sure that your system does not support these +devices (most notably, WIN32 systems) and the program does not report an +error then +.Sy do not use it +if you want really secure and unguessable passwords. There are many real-life +examples where the system security was compromised because of poor random +number generators. +.Ss CRYPTLIB NOTES +For maximum security, it is recommended to use cryptlib if at all possible. +Citing its manual, it is designed around a B3 kernel and tries very hard to +protect and sanitize all sensitive data (including locking it in memory if +possible). Also, there are no issues about initializing the entropy pool. +.Sh EXAMPLES +Generate an 4-word enhanced passphrase from the diceware dictionary: +.Nm +command: +.Pp +.Dl "secpwgen -pe 4" +.Pp +gives the following typical output when run without root privileges: +.Pp +.Bd -literal -unfilled -offset indent +mlockall: Operation not permitted +WARNING: using insecure memory. +---------------- +ha'e ap.x ro|ue si+th ;ENTROPY=81.32 bits +---------------- +INFO: zeroing memory. +.Ed +.Sh DIAGNOSTICS +Exit status is 0 on success, and 1 if the command +encounters a fatal error. Informational messages are omitted from this +listing. Their meaning can be deduced from the source. +.Bl -diag +.It "WARNING: using insecure memory." +This message is not only pertained to memory; for example it can happen that +the program can't turn off core file generation. The exact cause is seen +in system error messages preceding the warning. +.Pp +If this message is printed, you must assume that the generated password can +end up in plain text on the swap device, core file or other from where it +could be retrieved by an adversary. +.It "FATAL: out of memory." +Cannot allocate enough memory. +.It "FATAL: system call failed. There is no way..." +The program, if installed as SUID root, drops its root privileges +as soon as it obtains secure memory. This didn't succeed, and +because of documented buffer overflows (see the +.Sx BUGS +section below) the program refuses to execute. Executing a SUID +program with the potential of buffer overflows is an extreme +security risk. +.It "FATAL: too small MAX_RANDOM_STATE_SIZE..." +The MAX_RANDOM_STATE_SIZE macro in secure_memory.h should be enlarged +to at least the size displayed after the message and the program +recompiled. +.It "FATAL: unhandled exception" +This is a real bug in the program. Report this to the author +along with the exact command-line arguments, the compiler used, +operating system, etc. +.It "ERROR: some garbage left to cryptlib." +This is an indication of the bug in the program. Report this to the author +along with other data described above. Nothing "bad" happened; everything +was properly cleaned by cryptlib on exit. It is just an indication that +some objects were not freed by the program before shutting down cryptlib. +.El +.Sh SEE ALSO +.Xr pwgen 1 , +.Xr mlockall 2 +.Rs +.%T "Diceware Passphrase Home Page" +.%O http://www.diceware.com +.Re +.Rs +.%T "Koremutake encoding" +.%O http://shorl.com/koremutake.php +.Re +.Rs +.%T "RFC1760: The S/KEY One-Time Password System" +.Re +.Rs +.%T "RFC2289: A One-Time Password System" +.Re +.Rs +.%A Peter Gutmann +.%T cryptlib +.%O http://www.cs.auckland.ac.nz/~pgut001/cryptlib/ +.Re +.Rs +.%T OpenSSL +.%O http://www.openssl.org +.Re +.Sh AUTHORS +The secpwgen program and this manual page were written by +.An Zeljko Vrba Aq zvrba@globalnet.hr . +.Sh BUGS +The program +.Sy will crash +if +.Ar n +is too big. No checks are made for the internal buffer sizes. However, since +this program is intended to be used by humans who must memorize their +passphrases, this is not an issue. The program works correctly for "reasonable" +sizes of +.Ar n +(e.g. less than 256). -- cgit v1.2.3