This is the cl-bcrypt Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Jun 15 03:47:07 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
cl-bcryptCommon Lisp system for generating and parsing of bcrypt password hashes
cl-bcrypt
Marin Atanasov Nikolov <dnaeon@gmail.com>
Marin Atanasov Nikolov <dnaeon@gmail.com>
BSD 2-Clause
# 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
binascii (system).
ironclad (system).
cl-ppcre (system).
core (module).
Modules are listed depth-first from the system components tree.
Files are sorted by type and then listed depth-first from the systems components trees.
cl-bcrypt/core/bcrypt.lispcore (module).
*default-cost-factor* (special variable).
algorithm-identifier (reader method).
b64-decode (function).
b64-encode (function).
bcrypt-error (condition).
bcrypt-error-description (reader method).
cost-factor (reader method).
decode (function).
encode (function).
generate-salt (function).
make-password (function).
parse-hash (function).
parse-hash-or-lose (function).
password (class).
password-hash (reader method).
password= (function).
salt (reader method).
*alphabet* (special variable).
*b64-decode-table* (special variable).
*b64-encode-table* (special variable).
*bcrypt-hash-regex-scanner* (special variable).
*supported-algorithm-identifiers* (special variable).
+encoded-hash-size+ (constant).
+encoded-salt-size+ (constant).
+max-plain-text-password-size+ (constant).
+raw-hash-bytes-to-encode+ (constant).
+raw-hash-size+ (constant).
+raw-salt-size+ (constant).
Packages are listed by definition order.
cl-bcryptbcrypt
common-lisp.
*default-cost-factor* (special variable).
algorithm-identifier (generic reader).
b64-decode (function).
b64-encode (function).
bcrypt-error (condition).
bcrypt-error-description (generic reader).
cost-factor (generic reader).
decode (function).
encode (function).
generate-salt (function).
make-password (function).
parse-hash (function).
parse-hash-or-lose (function).
password (class).
password-hash (generic reader).
password= (function).
salt (generic reader).
*alphabet* (special variable).
*b64-decode-table* (special variable).
*b64-encode-table* (special variable).
*bcrypt-hash-regex-scanner* (special variable).
*supported-algorithm-identifiers* (special variable).
+encoded-hash-size+ (constant).
+encoded-salt-size+ (constant).
+max-plain-text-password-size+ (constant).
+raw-hash-bytes-to-encode+ (constant).
+raw-hash-size+ (constant).
+raw-salt-size+ (constant).
Definitions are sorted by export status, category, package, and then by lexicographic order.
The default cost factor
base64 decodes the given octets using our alphabet
base64 encodes the given octets using our alphabet
Decodes the given HASH-STRING into a PASSWORD instance
Encodes the given PASSWORD instance into its text representation
Generates a random 16 bytes size salt
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.
Parses an encoded bcrypt hash from the given HASH-STRING
Test whether the PASSWORD-STRING is equal to HASH-STRING when encoded
bcrypt-error)) ¶Bcrypt error condition
simple-error.
:description
This slot is read-only.
Class which represents a bcrypt password
The hash algorithm identifier
(error "must specify hash algorithm identifier")
:algorithm-identifier
This slot is read-only.
The password cost factor
(error "must specify cost factor")
:cost-factor
This slot is read-only.
16 bytes size salt
(error "must specify password salt")
:salt
salt.
This slot is read-only.
The hashed password
(error "must specify password hash")
:password-hash
This slot is read-only.
Number of characters in the encoded password hash
Number of characters that represent an encoded salt
Maximum number of characters of a plain-text password
Number of bytes from the raw hash to be encoded
Number of bytes in the raw password hash
Number of bytes in the raw salt
Alphabet used for base64 encoding and decoding of bcrypt password hashes
Table used for base64 decoding of a password hash
Table used for base64 encoding of a password hash
Regex used to match bcrypt hashes
Supported algorithm identifiers
| Jump to: | A B C D E F G M P S |
|---|
| Jump to: | A B C D E F G M P S |
|---|
| Jump to: | *
+
A C D P S |
|---|
| Jump to: | *
+
A C D P S |
|---|
| Jump to: | B C F M P S |
|---|
| Jump to: | B C F M P S |
|---|