The cl-bcrypt Reference Manual

This is the cl-bcrypt Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 03:44:23 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 cl-bcrypt

Common Lisp system for generating and parsing of bcrypt password hashes

Long Name

cl-bcrypt

Maintainer

Marin Atanasov Nikolov <>

Author

Marin Atanasov Nikolov <>

Home Page

https://github.com/dnaeon/cl-bcrypt

Source Control

https://github.com/dnaeon/cl-bcrypt

Bug Tracker

https://github.com/dnaeon/cl-bcrypt

License

BSD 2-Clause

Long Description

# 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

Version

0.1.0

Dependencies
  • binascii (system).
  • ironclad (system).
  • cl-ppcre (system).
Source

cl-bcrypt.asd.

Child Component

core (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 cl-bcrypt/core

Source

cl-bcrypt.asd.

Parent Component

cl-bcrypt (system).

Child Component

bcrypt.lisp (file).


4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 cl-bcrypt/cl-bcrypt.asd

Source

cl-bcrypt.asd.

Parent Component

cl-bcrypt (system).

ASDF Systems

cl-bcrypt.

Packages

cl-bcrypt-system.


4.1.2 cl-bcrypt/core/bcrypt.lisp

Source

cl-bcrypt.asd.

Parent Component

core (module).

Packages

cl-bcrypt.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 cl-bcrypt

Source

bcrypt.lisp.

Nickname

bcrypt

Use List

common-lisp.

Public Interface
Internals

5.2 cl-bcrypt-system

Source

cl-bcrypt.asd.

Use List
  • asdf/interface.
  • common-lisp.

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Special variables

Special Variable: *default-cost-factor*

The default cost factor

Package

cl-bcrypt.

Source

bcrypt.lisp.


6.1.2 Ordinary functions

Function: b64-decode (octets)

base64 decodes the given octets using our alphabet

Package

cl-bcrypt.

Source

bcrypt.lisp.

Function: b64-encode (octets)

base64 encodes the given octets using our alphabet

Package

cl-bcrypt.

Source

bcrypt.lisp.

Function: decode (hash-string)

Decodes the given HASH-STRING into a PASSWORD instance

Package

cl-bcrypt.

Source

bcrypt.lisp.

Function: encode (password)

Encodes the given PASSWORD instance into its text representation

Package

cl-bcrypt.

Source

bcrypt.lisp.

Function: generate-salt ()

Generates a random 16 bytes size salt

Package

cl-bcrypt.

Source

bcrypt.lisp.

Function: make-password (password &key salt cost identifier)

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.

Package

cl-bcrypt.

Source

bcrypt.lisp.

Function: parse-hash (hash-string)

Parses an encoded bcrypt hash from the given HASH-STRING

Package

cl-bcrypt.

Source

bcrypt.lisp.

Function: parse-hash-or-lose (hash-string)
Package

cl-bcrypt.

Source

bcrypt.lisp.

Function: password= (password-string hash-string)

Test whether the PASSWORD-STRING is equal to HASH-STRING when encoded

Package

cl-bcrypt.

Source

bcrypt.lisp.


6.1.3 Generic functions

Generic Reader: algorithm-identifier (object)
Package

cl-bcrypt.

Methods
Reader Method: algorithm-identifier ((password password))

The hash algorithm identifier

Source

bcrypt.lisp.

Target Slot

algorithm-identifier.

Generic Reader: bcrypt-error-description (condition)
Package

cl-bcrypt.

Methods
Reader Method: bcrypt-error-description ((condition bcrypt-error))
Source

bcrypt.lisp.

Target Slot

description.

Generic Reader: cost-factor (object)
Package

cl-bcrypt.

Methods
Reader Method: cost-factor ((password password))

The password cost factor

Source

bcrypt.lisp.

Target Slot

cost-factor.

Generic Reader: password-hash (object)
Package

cl-bcrypt.

Methods
Reader Method: password-hash ((password password))

The hashed password

Source

bcrypt.lisp.

Target Slot

password-hash.

Generic Reader: salt (object)
Package

cl-bcrypt.

Methods
Reader Method: salt ((password password))

16 bytes size salt

Source

bcrypt.lisp.

Target Slot

salt.


6.1.4 Conditions

Condition: bcrypt-error

Bcrypt error condition

Package

cl-bcrypt.

Source

bcrypt.lisp.

Direct superclasses

simple-error.

Direct methods

bcrypt-error-description.

Direct slots
Slot: description
Initargs

:description

Readers

bcrypt-error-description.

Writers

This slot is read-only.


6.1.5 Classes

Class: password

Class which represents a bcrypt password

Package

cl-bcrypt.

Source

bcrypt.lisp.

Direct methods
Direct slots
Slot: algorithm-identifier

The hash algorithm identifier

Initform

(error "must specify hash algorithm identifier")

Initargs

:algorithm-identifier

Readers

algorithm-identifier.

Writers

This slot is read-only.

Slot: cost-factor

The password cost factor

Initform

(error "must specify cost factor")

Initargs

:cost-factor

Readers

cost-factor.

Writers

This slot is read-only.

Slot: salt

16 bytes size salt

Initform

(error "must specify password salt")

Initargs

:salt

Readers

salt.

Writers

This slot is read-only.

Slot: password-hash

The hashed password

Initform

(error "must specify password hash")

Initargs

:password-hash

Readers

password-hash.

Writers

This slot is read-only.


6.2 Internals


6.2.1 Constants

Constant: +encoded-hash-size+

Number of characters in the encoded password hash

Package

cl-bcrypt.

Source

bcrypt.lisp.

Constant: +encoded-salt-size+

Number of characters that represent an encoded salt

Package

cl-bcrypt.

Source

bcrypt.lisp.

Constant: +max-plain-text-password-size+

Maximum number of characters of a plain-text password

Package

cl-bcrypt.

Source

bcrypt.lisp.

Constant: +raw-hash-bytes-to-encode+

Number of bytes from the raw hash to be encoded

Package

cl-bcrypt.

Source

bcrypt.lisp.

Constant: +raw-hash-size+

Number of bytes in the raw password hash

Package

cl-bcrypt.

Source

bcrypt.lisp.

Constant: +raw-salt-size+

Number of bytes in the raw salt

Package

cl-bcrypt.

Source

bcrypt.lisp.


6.2.2 Special variables

Special Variable: *alphabet*

Alphabet used for base64 encoding and decoding of bcrypt password hashes

Package

cl-bcrypt.

Source

bcrypt.lisp.

Special Variable: *b64-decode-table*

Table used for base64 decoding of a password hash

Package

cl-bcrypt.

Source

bcrypt.lisp.

Special Variable: *b64-encode-table*

Table used for base64 encoding of a password hash

Package

cl-bcrypt.

Source

bcrypt.lisp.

Special Variable: *bcrypt-hash-regex-scanner*

Regex used to match bcrypt hashes

Package

cl-bcrypt.

Source

bcrypt.lisp.

Special Variable: *supported-algorithm-identifiers*

Supported algorithm identifiers

Package

cl-bcrypt.

Source

bcrypt.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   D   E   F   G   M   P   S  
Index Entry  Section

A
algorithm-identifier: Public generic functions
algorithm-identifier: Public generic functions

B
b64-decode: Public ordinary functions
b64-encode: Public ordinary functions
bcrypt-error-description: Public generic functions
bcrypt-error-description: Public generic functions

C
cost-factor: Public generic functions
cost-factor: Public generic functions

D
decode: Public ordinary functions

E
encode: Public ordinary functions

F
Function, b64-decode: Public ordinary functions
Function, b64-encode: Public ordinary functions
Function, decode: Public ordinary functions
Function, encode: Public ordinary functions
Function, generate-salt: Public ordinary functions
Function, make-password: Public ordinary functions
Function, parse-hash: Public ordinary functions
Function, parse-hash-or-lose: Public ordinary functions
Function, password=: Public ordinary functions

G
generate-salt: Public ordinary functions
Generic Function, algorithm-identifier: Public generic functions
Generic Function, bcrypt-error-description: Public generic functions
Generic Function, cost-factor: Public generic functions
Generic Function, password-hash: Public generic functions
Generic Function, salt: Public generic functions

M
make-password: Public ordinary functions
Method, algorithm-identifier: Public generic functions
Method, bcrypt-error-description: Public generic functions
Method, cost-factor: Public generic functions
Method, password-hash: Public generic functions
Method, salt: Public generic functions

P
parse-hash: Public ordinary functions
parse-hash-or-lose: Public ordinary functions
password-hash: Public generic functions
password-hash: Public generic functions
password=: Public ordinary functions

S
salt: Public generic functions
salt: Public generic functions


A.3 Variables

Jump to:   *   +  
A   C   D   P   S  
Index Entry  Section

*
*alphabet*: Private special variables
*b64-decode-table*: Private special variables
*b64-encode-table*: Private special variables
*bcrypt-hash-regex-scanner*: Private special variables
*default-cost-factor*: Public special variables
*supported-algorithm-identifiers*: Private special variables

+
+encoded-hash-size+: Private constants
+encoded-salt-size+: Private constants
+max-plain-text-password-size+: Private constants
+raw-hash-bytes-to-encode+: Private constants
+raw-hash-size+: Private constants
+raw-salt-size+: Private constants

A
algorithm-identifier: Public classes

C
Constant, +encoded-hash-size+: Private constants
Constant, +encoded-salt-size+: Private constants
Constant, +max-plain-text-password-size+: Private constants
Constant, +raw-hash-bytes-to-encode+: Private constants
Constant, +raw-hash-size+: Private constants
Constant, +raw-salt-size+: Private constants
cost-factor: Public classes

D
description: Public conditions

P
password-hash: Public classes

S
salt: Public classes
Slot, algorithm-identifier: Public classes
Slot, cost-factor: Public classes
Slot, description: Public conditions
Slot, password-hash: Public classes
Slot, salt: Public classes
Special Variable, *alphabet*: Private special variables
Special Variable, *b64-decode-table*: Private special variables
Special Variable, *b64-encode-table*: Private special variables
Special Variable, *bcrypt-hash-regex-scanner*: Private special variables
Special Variable, *default-cost-factor*: Public special variables
Special Variable, *supported-algorithm-identifiers*: Private special variables