The cl-bcrypt Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-bcrypt Reference Manual

This is the cl-bcrypt Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Nov 04 11:58:05 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-bcrypt

cl-bcrypt is a Common Lisp system for generating, parsing and verification of bcrypt password hashes.

Requirements

Installation

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)

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 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

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

Contributing

cl-bcrypt is hosted on Github. Please contribute by reporting issues, suggesting features or by sending patches using pull requests.

Authors

License

This project is Open Source and licensed under the BSD License.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 cl-bcrypt

Long Name

cl-bcrypt

Maintainer

Marin Atanasov Nikolov <dnaeon@gmail.com>

Author

Marin Atanasov Nikolov <dnaeon@gmail.com>

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

Description

Common Lisp system for generating and parsing of bcrypt password hashes

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
Source

cl-bcrypt.asd (file)

Component

core (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

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


Previous: , Up: Modules   [Contents][Index]

3.1 cl-bcrypt/core

Parent

cl-bcrypt (system)

Location

src/

Component

bcrypt.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 cl-bcrypt.asd

Location

cl-bcrypt.asd

Systems

cl-bcrypt (system)

Packages

cl-bcrypt-system


Previous: , Up: Lisp files   [Contents][Index]

4.1.2 cl-bcrypt/core/bcrypt.lisp

Parent

core (module)

Location

src/bcrypt.lisp

Packages

cl-bcrypt

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 cl-bcrypt-system

Source

cl-bcrypt.asd

Use List

Previous: , Up: Packages   [Contents][Index]

5.2 cl-bcrypt

Source

bcrypt.lisp (file)

Nickname

bcrypt

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Special variables

Special Variable: *default-cost-factor*

The default cost factor

Package

cl-bcrypt

Source

bcrypt.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Functions

Function: b64-decode OCTETS

base64 decodes the given octets using our alphabet

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Function: b64-encode OCTETS

base64 encodes the given octets using our alphabet

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Function: decode HASH-STRING

Decodes the given HASH-STRING into a PASSWORD instance

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Function: encode PASSWORD

Encodes the given PASSWORD instance into its text representation

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Function: generate-salt ()

Generates a random 16 bytes size salt

Package

cl-bcrypt

Source

bcrypt.lisp (file)

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 (file)

Function: parse-hash HASH-STRING

Parses an encoded bcrypt hash from the given HASH-STRING

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Function: parse-hash-or-lose HASH-STRING
Package

cl-bcrypt

Source

bcrypt.lisp (file)

Function: password= PASSWORD-STRING HASH-STRING

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

Package

cl-bcrypt

Source

bcrypt.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Generic functions

Generic Function: algorithm-identifier OBJECT
Package

cl-bcrypt

Methods
Method: algorithm-identifier (PASSWORD password)

The hash algorithm identifier

Source

bcrypt.lisp (file)

Generic Function: bcrypt-error-description CONDITION
Package

cl-bcrypt

Methods
Method: bcrypt-error-description (CONDITION bcrypt-error)
Source

bcrypt.lisp (file)

Generic Function: cost-factor OBJECT
Package

cl-bcrypt

Methods
Method: cost-factor (PASSWORD password)

The password cost factor

Source

bcrypt.lisp (file)

Generic Function: password-hash OBJECT
Package

cl-bcrypt

Methods
Method: password-hash (PASSWORD password)

The hashed password

Source

bcrypt.lisp (file)

Generic Function: salt OBJECT
Package

cl-bcrypt

Methods
Method: salt (PASSWORD password)

16 bytes size salt

Source

bcrypt.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.4 Conditions

Condition: bcrypt-error ()

Bcrypt error condition

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Direct superclasses

simple-error (condition)

Direct methods

bcrypt-error-description (method)

Direct slots
Slot: description
Initargs

:description

Readers

bcrypt-error-description (generic function)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.5 Classes

Class: password ()

Class which represents a bcrypt password

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: algorithm-identifier

The hash algorithm identifier

Initargs

:algorithm-identifier

Initform

(error "must specify hash algorithm identifier")

Readers

algorithm-identifier (generic function)

Slot: cost-factor

The password cost factor

Initargs

:cost-factor

Initform

(error "must specify cost factor")

Readers

cost-factor (generic function)

Slot: salt

16 bytes size salt

Initargs

:salt

Initform

(error "must specify password salt")

Readers

salt (generic function)

Slot: password-hash

The hashed password

Initargs

:password-hash

Initform

(error "must specify password hash")

Readers

password-hash (generic function)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Constants

Constant: +encoded-hash-size+

Number of characters in the encoded password hash

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Constant: +encoded-salt-size+

Number of characters that represent an encoded salt

Package

cl-bcrypt

Source

bcrypt.lisp (file)

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

Maximum number of characters of a plain-text password

Package

cl-bcrypt

Source

bcrypt.lisp (file)

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

Number of bytes from the raw hash to be encoded

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Constant: +raw-hash-size+

Number of bytes in the raw password hash

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Constant: +raw-salt-size+

Number of bytes in the raw salt

Package

cl-bcrypt

Source

bcrypt.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

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 (file)

Special Variable: *b64-decode-table*

Table used for base64 decoding of a password hash

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Special Variable: *b64-encode-table*

Table used for base64 encoding of a password hash

Package

cl-bcrypt

Source

bcrypt.lisp (file)

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

Regex used to match bcrypt hashes

Package

cl-bcrypt

Source

bcrypt.lisp (file)

Special Variable: *supported-algorithm-identifiers*

Supported algorithm identifiers

Package

cl-bcrypt

Source

bcrypt.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-bcrypt.asd: The cl-bcrypt․asd file
cl-bcrypt/core: The cl-bcrypt/core module
cl-bcrypt/core/bcrypt.lisp: The cl-bcrypt/core/bcrypt․lisp file

F
File, Lisp, cl-bcrypt.asd: The cl-bcrypt․asd file
File, Lisp, cl-bcrypt/core/bcrypt.lisp: The cl-bcrypt/core/bcrypt․lisp file

L
Lisp File, cl-bcrypt.asd: The cl-bcrypt․asd file
Lisp File, cl-bcrypt/core/bcrypt.lisp: The cl-bcrypt/core/bcrypt․lisp file

M
Module, cl-bcrypt/core: The cl-bcrypt/core module

Jump to:   C   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

A
algorithm-identifier: Exported generic functions
algorithm-identifier: Exported generic functions

B
b64-decode: Exported functions
b64-encode: Exported functions
bcrypt-error-description: Exported generic functions
bcrypt-error-description: Exported generic functions

C
cost-factor: Exported generic functions
cost-factor: Exported generic functions

D
decode: Exported functions

E
encode: Exported functions

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

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

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

P
parse-hash: Exported functions
parse-hash-or-lose: Exported functions
password-hash: Exported generic functions
password-hash: Exported generic functions
password=: Exported functions

S
salt: Exported generic functions
salt: Exported generic functions

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

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

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

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

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

A
algorithm-identifier: Exported classes

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

D
description: Exported conditions

P
password-hash: Exported classes

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

Jump to:   *   +  
A   C   D   P   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   B   C   P   S  
Index Entry  Section

B
bcrypt-error: Exported conditions

C
cl-bcrypt: The cl-bcrypt system
cl-bcrypt: The cl-bcrypt package
cl-bcrypt-system: The cl-bcrypt-system package
Class, password: Exported classes
Condition, bcrypt-error: Exported conditions

P
Package, cl-bcrypt: The cl-bcrypt package
Package, cl-bcrypt-system: The cl-bcrypt-system package
password: Exported classes

S
System, cl-bcrypt: The cl-bcrypt system

Jump to:   B   C   P   S