commit 39085a45d49602d0e54bbff4ff7f5a6d9dcd4298
parent 4863f6fd6ec7f2717be692641b88a88bce9db8df
Author: Tim Kuijsten <info+git@netsend.nl>
Date: Fri, 13 Dec 2019 17:18:40 +0100
refactored and updated manpage and readme
* update key space sizes based on a source from November 2019
* let the readme refer to the manpage for documentation
* replace the SHA256 example with one using PBKDF2-HMAC-SHA256
* remove bugs section from manual and extend general description and
examples
Diffstat:
| M | README.md | | | 63 | ++++++++++++++++++++++++++++++++++----------------------------- |
| M | rpass.1 | | | 86 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------ |
2 files changed, 94 insertions(+), 55 deletions(-)
diff --git a/README.md b/README.md
@@ -1,12 +1,32 @@
# rpass
-Strong password generator for humans.
+## Strong password generator for humans
Features:
* Both visually and phonetically unambiguous
* No shift or alternate keyboard needed when typing
* Blanks can be inserted at arbitrary places to enhance visual representation
+## Requirements
+
+Build requirements:
+* A C89 compiler
+
+Run-time requirements:
+* Any POSIX-compliant system that supports [arc4random_uniform(3)]. I.e. OpenBSD
+ or macOS.
+
+## Install on OpenBSD
+```sh
+$ make
+$ doas make install
+```
+
+## Install on macOS
+```sh
+$ make
+$ sudo make install
+```
## Examples
Random password from a 40 bit key space:
@@ -21,40 +41,22 @@ $ rpass 60
loltuk zahxok takrep
```
-Usage:
-```sh
-$ rpass -h
-usage: rpass [bitlen]
-```
-
-
-## Install on macOS
-```sh
-$ make && sudo make install
-```
-
-
-## Install on OpenBSD
-```sh
-$ make && doas make install
-```
+## Key space requirements
+The 40 bit key space relies on the following requirements: the
+password is stored using [bcrypt(3)] with 2^10 rounds, it should only be
+secure for one year and the adversary has no more than $25,000.00 to
+spend on brute forcing the password (as of 2019). Additional details about this
+calculation can be found in the [manual].
+## Documentation
-## Key space requirements
-The 40 bit default relies on strong storage of the password, i.e. bcrypt(3) with
-sufficient rounds. If your password is going to be stored using a weaker
-cryptographic construct, you have to use a bigger key space. E.g. say you want
-to generate a password you can use for one year and is stored using sha256(1).
-Furthermore your adversary has $20,000.00 to spend. According to [8x Nvidia GTX
-1080 Hashcat Benchmarks] as of 2016 the adversary can try 230 billion hashes per
-second, this makes that you'll need a key space of 64 bit (hashes per second *
-3600 * 24 * 365 * 2).
+All features are documented in the manual: [rpass(1)].
## License
ISC
-Copyright (c) 2017 Tim Kuijsten
+Copyright (c) 2017, 2019 Tim Kuijsten
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
@@ -69,4 +71,7 @@ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-[8x Nvidia GTX 1080 Hashcat Benchmarks]: https://gist.github.com/epixoip/a83d38f412b4737e99bbef804a270c40
+[arc4random_uniform(3)]: https://man.openbsd.org/arc4random_uniform.3
+[bcrypt(3)]: https://man.openbsd.org/bcrypt.3
+[rpass(1)]: https://netsend.nl/rpass/rpass.1.html
+[manual]: https://netsend.nl/rpass/rpass.1.html
diff --git a/rpass.1 b/rpass.1
@@ -1,4 +1,18 @@
-.Dd Apr 25, 2017
+.\" Copyright (c) 2017, 2019 Tim Kuijsten
+.\"
+.\" Permission to use, copy, modify, and/or distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 13 2019 $
.Dt RPASS 1
.Os
.Sh NAME
@@ -6,50 +20,70 @@
.Nd strong password generator for humans
.Sh SYNOPSIS
.Nm
-.Op Fl h
.Op Ar bitlen
.Sh DESCRIPTION
.Nm
-is a strong password generator for human beings. The generated passwords are both visually and phonetically unambiguous. There is no alternation between keyboards when typing the password. And blanks can be inserted at arbitrary places to enhance visual representation.
-.Pp
+is a strong password generator for human beings.
+The generated passwords are both visually and phonetically unambiguous.
+The passwords are case-insensitive so that there is no alternation between
+keyboards when typing the password and blanks can be inserted at arbitrary
+places to enhance visual representation.
.Bl -tag -width Ds
-.It Fl h
-Print usage.
.It Ar bitlen
-Use a key space of the specified bit length.
+Use a key space of the specified bit length, defaults to 40.
.El
.Pp
-By default
-.Nm
-uses a 40 bit key space.
+In order to determine the right
+.Ar bitlen
+three factors should be considered:
+.Bl -enum -offset Ds
+.It
+the hashing mechanism used to store the password
+.It
+the time for which this password has to be secure
+.It
+the processing power of the adversary
+.El
+.Pp
+The default
+.Ar bitlen
+of 40 bits relies on the following requirements: the password is stored using
+.Xr bcrypt 3
+with 2^10 rounds, it should only be secure for one year and the adversary
+has no more than $25,000.00 to spend on brute forcing the password (as of 2019).
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
-.Pp
Random password from the default key space:
.Bd -literal -offset 4n
$ rpass
jikmus xuzjex
.Ed
.Pp
-Random password from a 60 bit key space:
+Random password from an 80 bit key space:
.Bd -literal -offset 4n
-$ rpass 60
-loltuk zahxok takrep
+$ rpass 80
+jultar ramlap rinwun bemvuh
.Ed
-.Sh BUGS
-.Nm
-relies on strong storage of the password, i.e.
-.Xr bcrypt 3
-with sufficient rounds. If your password is going to be stored using a weaker hashing mechanism, use a bigger key space. E.g. say you want to generate a password you can use for one year and is stored using
-.Xr sha256 1 .
-Furthermore your adversary has $20,000.00 to spend. According to
-.Dq 8x Nvidia GTX 1080 Hashcat Benchmarks
-as of 2016 the adversary can try 230 billion hashes per second, this makes that you'll need a key space of 64 bit (hashes per second * 3600 * 24 * 365 * 2).
+.Pp
+In order to calculate the required
+.Ar bitlen
+let's consider a scenario with the following requirements.
+The generated password will be used for at most half a year and is
+stored using PBKDF2-HMAC-SHA256 with a million iterations.
+Furthermore the adversary has $25,000.00 to spend.
+According to
+.Dq 8x Nvidia GTX 1080 Ti Hashcat Benchmarks
+as of 2019 the adversary can try 15 million hashes per second on
+PBKDF2-HMAC-SHA256 with a thousand iterations.
+This would be 15 thousand hashes per second on PBKDF2-HMAC-SHA256 with a million
+iterations.
+Hence a key space of 15,000 * 3,600 * 24 * 183 * 2 = 38.8 bit would be
+sufficient.
.Sh SEE ALSO
-.Xr sha256 1 ,
.Xr bcrypt 3 ,
-.Lk https://gist.github.com/epixoip/a83d38f412b4737e99bbef804a270c40 8x Nvidia GTX 1080 Hashcat Benchmarks
+.Lk https://gist.github.com/epixoip/ace60d09981be09544fdd35005051505 8x Nvidia GTX 1080 Ti Hashcat Benchmarks
+.Lk https://tools.ietf.org/html/rfc8018 PKCS #5: Password-Based Cryptography Specification
.Sh AUTHORS
.An -nosplit
-.An Tim Kuijsten Aq Mt tim@netsend.nl
+.An Tim Kuijsten