Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-bcrypt Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:32:10 2021 GMT+0.
| • Introduction | What cl-bcrypt is all about | |
| • Systems | The systems documentation | |
| • Modules | The modules documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
cl-bcrypt is a Common Lisp system for generating, parsing and
verification of bcrypt password hashes.
Clone the cl-bcrypt repo in your Quicklisp local-projects directory.
git clone https://github.com/dnaeon/cl-bcrypt.git
Load the system.
CL-USER> (ql:quickload :cl-bcrypt)
The supported hash algorithm identifiers are 2a and 2b.
The following section provides some examples to get you started with the cl-bcrypt system.
The functions discussed here are availabe in the CL-BCRYPT (and its
nickname BCRYPT) package.
In order to create a new bcrypt password you need to use the
BCRYPT:MAKE-PASSWORD function, e.g.
CL-USER> (defparameter *password*
(bcrypt:make-password "my-secret-password"))
*PASSWORD*
BCRYPT:MAKE-PASSWORD accepts keyword parameters, which allow you to
specify a different salt (e.g. obtained by BCRYPT:GENERATE-SALT),
different cost factor than the default, and a different algorithm
identifier than the default (e.g. 2a).
If you don't specify explicitely a salt, a random one will be
generated for you by the BCRYPT:GENERATE-SALT function.
This example specifies a cost factor of 16 and a hash algorithm
identifier 2a.
CL-USER> (defparameter *password*
(bcrypt:make-password "my-secret-password" :cost 16 :identifier "2a"))
*PASSWORD*
You can use the BCRYPT:ALGORITHM-IDENTIFIER, BCRYPT:COST-FACTOR,
BCRYPT:SALT and BCRYPT:PASSWORD-HASH readers to inspect the
returned BCRYPT:PASSWORD instance from the BCRYPT:MAKE-PASSWORD
function, e.g.
CL-USER> (bcrypt:algorithm-identifier *password*)
"2a"
CL-USER> (bcrypt:cost-factor *password*)
16
CL-USER> (bcrypt:salt *password*)
#(18 117 245 59 29 97 63 72 199 11 254 164 52 87 213 169)
CL-USER> (bcrypt:password-hash *password*)
#(94 0 171 116 90 235 30 220 57 45 147 214 210 77 244 223 63 14 153 13 140 213 183)
The BCRYPT:SALT and BCRYPT:PASSWORD-HASH readers return the raw
bytes of the salt and the password hash respectively.
In order to encode a BCRYPT:PASSWORD instance into its text
representation you need to use the BCRYPT:ENCODE function.
CL-USER> (bcrypt:encode *password*)
"$2a$16$ClVzMvzfNyhFA94iLDdToOVeApbDppFru3JXNUyi1y1x6MkO0KzZa"
A bcrypt password hash can be decoded using the BCRYPT:DECODE function,
which will return a new instance of BCRYPT:PASSWORD, e.g.
CL-USER> (bcrypt:decode "$2a$16$ClVzMvzfNyhFA94iLDdToOVeApbDppFru3JXNUyi1y1x6MkO0KzZa")
#<CL-BCRYPT:PASSWORD {1002207AD3}>
If you encode back the returned instance you should get the same hash string as the one that was decoded.
The BCRYPT:PARSE-HASH function returns a property list of the
parts that comprise the bcrypt hash string.
CL-USER> (bcrypt:parse-hash "$2a$16$ClVzMvzfNyhFA94iLDdToOVeApbDppFru3JXNUyi1y1x6MkO0KzZa")
(:ALGORITHM-IDENTIFIER "2a"
:COST-FACTOR "16"
:SALT "ClVzMvzfNyhFA94iLDdToO"
:PASSWORD-HASH "VeApbDppFru3JXNUyi1y1x6MkO0KzZa")
When you need to test whether a given bcrypt hash matches a given
password you can use the BCRYPT:PASSWORD= predicate, e.g.
CL-USER> (bcrypt:password= "my-secret-password"
"$2a$16$ClVzMvzfNyhFA94iLDdToOVeApbDppFru3JXNUyi1y1x6MkO0KzZa")
T
Tests are provided as part of the cl-bcrypt.test system.
In order to run the tests you can evaluate the following expressions.
CL-USER> (ql:quickload :cl-bcrypt.test)
CL-USER> (asdf:test-system :cl-bcrypt.test)
Or you can run the tests in a Docker container instead.
First, build the Docker image.
docker build -t cl-bcrypt .
Run the tests.
docker run --rm cl-bcrypt
cl-bcrypt is hosted on Github. Please contribute by
reporting issues, suggesting features or by sending patches using pull
requests.
This project is Open Source and licensed under the BSD License.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The cl-bcrypt system |
cl-bcrypt
Marin Atanasov Nikolov <dnaeon@gmail.com>
Marin Atanasov Nikolov <dnaeon@gmail.com>
BSD 2-Clause
Common Lisp system for generating and parsing of bcrypt password hashes
# cl-bcrypt
‘cl-bcrypt‘ is a Common Lisp system for generating, parsing and
verification of [bcrypt][bcrypt] password hashes.
## Requirements
* [Quicklisp][Quicklisp]
## Installation
Clone the [cl-bcrypt][cl-bcrypt] repo in your [Quicklisp
local-projects directory][Quicklisp FAQ].
“‘ shell
git clone https://github.com/dnaeon/cl-bcrypt.git
“‘
Load the system.
“‘ common-lisp
CL-USER> (ql:quickload :cl-bcrypt)
“‘
## Supported Algorithm Identifiers
The supported hash algorithm identifiers are ‘2a‘ and ‘2b‘.
## Usage
The following section provides some examples to get you started
with the [cl-bcrypt][cl-bcrypt] system.
The functions discussed here are availabe in the ‘CL-BCRYPT‘ (and its
nickname ‘BCRYPT‘) package.
In order to create a new bcrypt password you need to use the
‘BCRYPT:MAKE-PASSWORD‘ function, e.g.
“‘ common-lisp
CL-USER> (defparameter *password*
(bcrypt:make-password "my-secret-password"))
*PASSWORD*
“‘
‘BCRYPT:MAKE-PASSWORD‘ accepts keyword parameters, which allow you to
specify a different salt (e.g. obtained by ‘BCRYPT:GENERATE-SALT‘),
different cost factor than the default, and a different algorithm
identifier than the default (e.g. ‘2a‘).
If you don’t specify explicitely a salt, a random one will be
generated for you by the ‘BCRYPT:GENERATE-SALT‘ function.
This example specifies a cost factor of ‘16‘ and a hash algorithm
identifier ‘2a‘.
“‘ common-lisp
CL-USER> (defparameter *password*
(bcrypt:make-password "my-secret-password" :cost 16 :identifier "2a"))
*PASSWORD*
“‘
You can use the ‘BCRYPT:ALGORITHM-IDENTIFIER‘, ‘BCRYPT:COST-FACTOR‘,
‘BCRYPT:SALT‘ and ‘BCRYPT:PASSWORD-HASH‘ readers to inspect the
returned ‘BCRYPT:PASSWORD‘ instance from the ‘BCRYPT:MAKE-PASSWORD‘
function, e.g.
“‘ common-lisp
CL-USER> (bcrypt:algorithm-identifier *password*)
"2a"
CL-USER> (bcrypt:cost-factor *password*)
16
CL-USER> (bcrypt:salt *password*)
#(18 117 245 59 29 97 63 72 199 11 254 164 52 87 213 169)
CL-USER> (bcrypt:password-hash *password*)
#(94 0 171 116 90 235 30 220 57 45 147 214 210 77 244 223 63 14 153 13 140 213 183)
“‘
The ‘BCRYPT:SALT‘ and ‘BCRYPT:PASSWORD-HASH‘ readers return the raw
bytes of the salt and the password hash respectively.
In order to encode a ‘BCRYPT:PASSWORD‘ instance into its text
representation you need to use the ‘BCRYPT:ENCODE‘ function.
“‘ common-lisp
CL-USER> (bcrypt:encode *password*)
"$2a$16$ClVzMvzfNyhFA94iLDdToOVeApbDppFru3JXNUyi1y1x6MkO0KzZa"
“‘
A bcrypt password hash can be decoded using the ‘BCRYPT:DECODE‘ function,
which will return a new instance of ‘BCRYPT:PASSWORD‘, e.g.
“‘ common-lisp
CL-USER> (bcrypt:decode "$2a$16$ClVzMvzfNyhFA94iLDdToOVeApbDppFru3JXNUyi1y1x6MkO0KzZa")
#<CL-BCRYPT:PASSWORD {1002207AD3}>
“‘
If you encode back the returned instance you should get the same hash
string as the one that was decoded.
The ‘BCRYPT:PARSE-HASH‘ function returns a property list of the
parts that comprise the bcrypt hash string.
“‘ common-lisp
CL-USER> (bcrypt:parse-hash "$2a$16$ClVzMvzfNyhFA94iLDdToOVeApbDppFru3JXNUyi1y1x6MkO0KzZa")
(:ALGORITHM-IDENTIFIER "2a"
:COST-FACTOR "16"
:SALT "ClVzMvzfNyhFA94iLDdToO"
:PASSWORD-HASH "VeApbDppFru3JXNUyi1y1x6MkO0KzZa")
“‘
When you need to test whether a given bcrypt hash matches a given
password you can use the ‘BCRYPT:PASSWORD=‘ predicate, e.g.
“‘ common-lisp
CL-USER> (bcrypt:password= "my-secret-password"
"$2a$16$ClVzMvzfNyhFA94iLDdToOVeApbDppFru3JXNUyi1y1x6MkO0KzZa")
T
“‘
## Tests
Tests are provided as part of the ‘cl-bcrypt.test‘ system.
In order to run the tests you can evaluate the following expressions.
“‘ common-lisp
CL-USER> (ql:quickload :cl-bcrypt.test)
CL-USER> (asdf:test-system :cl-bcrypt.test)
“‘
Or you can run the tests in a Docker container instead.
First, build the Docker image.
“‘ shell
docker build -t cl-bcrypt .
“‘
Run the tests.
“‘ shell
docker run –rm cl-bcrypt
“‘
## Contributing
‘cl-bcrypt‘ is hosted on [Github][cl-bcrypt]. Please contribute by
reporting issues, suggesting features or by sending patches using pull
requests.
## Authors
* Marin Atanasov Nikolov (dnaeon@gmail.com)
## License
This project is Open Source and licensed under the [BSD
License][BSD License].
[bcrypt]: https://en.wikipedia.org/wiki/Bcrypt
[Quicklisp]: https://www.quicklisp.org/beta/
[Quicklisp FAQ]: https://www.quicklisp.org/beta/faq.html
[cl-bcrypt]: https://github.com/dnaeon/cl-bcrypt
[BSD License]: http://opensource.org/licenses/BSD-2-Clause
0.1.0
cl-bcrypt.asd (file)
core (module)
Modules are listed depth-first from the system components tree.
| • The cl-bcrypt/core module |
cl-bcrypt (system)
src/
bcrypt.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The cl-bcrypt.asd file | ||
| • The cl-bcrypt/core/bcrypt.lisp file |
Next: The cl-bcrypt/core/bcrypt․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-bcrypt.asd
cl-bcrypt (system)
Previous: The cl-bcrypt․asd file, Up: Lisp files [Contents][Index]
core (module)
src/bcrypt.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The cl-bcrypt-system package | ||
| • The cl-bcrypt package |
Next: The cl-bcrypt package, Previous: Packages, Up: Packages [Contents][Index]
cl-bcrypt.asd
Previous: The cl-bcrypt-system package, Up: Packages [Contents][Index]
bcrypt.lisp (file)
bcrypt
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported conditions | ||
| • Exported classes |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
The default cost factor
bcrypt.lisp (file)
Next: Exported generic functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
base64 decodes the given octets using our alphabet
bcrypt.lisp (file)
base64 encodes the given octets using our alphabet
bcrypt.lisp (file)
Decodes the given HASH-STRING into a PASSWORD instance
bcrypt.lisp (file)
Encodes the given PASSWORD instance into its text representation
bcrypt.lisp (file)
Generates a random 16 bytes size salt
bcrypt.lisp (file)
Creates a new bcrypt password instance.
The PASSWORD should be no more than 72 characters long.
The COST should be a number between 4 and 31. The SALT is a random 16
bytes sequence, which will be generated, unless explicitely provided.
Supported IDENTIFIER values are 2a and 2b.
bcrypt.lisp (file)
Parses an encoded bcrypt hash from the given HASH-STRING
bcrypt.lisp (file)
bcrypt.lisp (file)
Test whether the PASSWORD-STRING is equal to HASH-STRING when encoded
bcrypt.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
The hash algorithm identifier
bcrypt.lisp (file)
bcrypt.lisp (file)
The password cost factor
bcrypt.lisp (file)
The hashed password
bcrypt.lisp (file)
16 bytes size salt
bcrypt.lisp (file)
Next: Exported classes, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Bcrypt error condition
bcrypt.lisp (file)
simple-error (condition)
bcrypt-error-description (method)
:description
bcrypt-error-description (generic function)
Previous: Exported conditions, Up: Exported definitions [Contents][Index]
Class which represents a bcrypt password
bcrypt.lisp (file)
standard-object (class)
The hash algorithm identifier
:algorithm-identifier
(error "must specify hash algorithm identifier")
algorithm-identifier (generic function)
The password cost factor
:cost-factor
(error "must specify cost factor")
cost-factor (generic function)
16 bytes size salt
:salt
(error "must specify password salt")
salt (generic function)
The hashed password
:password-hash
(error "must specify password hash")
password-hash (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal constants | ||
| • Internal special variables |
Next: Internal special variables, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Number of characters in the encoded password hash
bcrypt.lisp (file)
Number of characters that represent an encoded salt
bcrypt.lisp (file)
Maximum number of characters of a plain-text password
bcrypt.lisp (file)
Number of bytes from the raw hash to be encoded
bcrypt.lisp (file)
Number of bytes in the raw password hash
bcrypt.lisp (file)
Number of bytes in the raw salt
bcrypt.lisp (file)
Previous: Internal constants, Up: Internal definitions [Contents][Index]
Alphabet used for base64 encoding and decoding of bcrypt password hashes
bcrypt.lisp (file)
Table used for base64 decoding of a password hash
bcrypt.lisp (file)
Table used for base64 encoding of a password hash
bcrypt.lisp (file)
Regex used to match bcrypt hashes
bcrypt.lisp (file)
Supported algorithm identifiers
bcrypt.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L M |
|---|
| Jump to: | C F L M |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | A B C D E F G M P S |
|---|
| Jump to: | A B C D E F G M P S |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
+
A C D P S |
|---|
| Jump to: | *
+
A C D P S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | B C P S |
|---|
| Jump to: | B C P S |
|---|