The cl-scram Reference Manual

Table of Contents

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

The cl-scram Reference Manual

This is the cl-scram Reference Manual, version 0.1, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 14:00:44 2018 GMT+0.


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

1 Introduction

cl-scram

Introduction

I started developing this library when I was trying to use MongoDB with the cl-mongo driver, and it became apparent that the driver had not been updated to use mongo's modern SCRAM-SHA1 authentication method.

Given the choices of relying on an antiquated MD5-based login method or writing a shiny new library, I chose the latter. The purpose of cl-scram is to allow for everything the client needs to do SCRAM login with the SHA1 hash algorithm.

The library is dependent on ironclad for all cryptographic functions. It does not rely on any DIY crypto.

License

The project is licensed under the Revised BSD License.

Copyright (c) 2015, Matt Prelude
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of Matt Prelude nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL MATT PRELUDE BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Installation

Use ASDF to install cl-scram as it has a number of dependencies. I will be looking to include cl-scram in Quicklisp later on.

* (asdf:load-system :cl-scram)

All of the functions are in the #:cl-scram package.

Testing

TODO: Add regression tests.

Usage

Generating a client nonce

The first step in a SCRAM request is to generate a nonce for the request. This can be done as follows:

* (gen-client-nonce)

"x6uHptrIM6PAFMtmbGCN8uuy0LSnZCww"

This is fully supported by cl-scrams message-generating functions, which accept a :nonce parameter.

Generating first client message

Next, we need to generate the first client message. To generate an un-encoded message, you can call the gen-client-initial-message function with the username & nonce:

* (gen-client-initial-message :username "username" :nonce "x6uHptrIM6PAFMtmbGCN8uuy0LSnZCww")

"n,,n=username,r=x6uHptrIM6PAFMtmbGCN8uuy0LSnZCww"

You'll need to pass this to the server.

Generating final client message

The server should respond with a base64-encoded string, which when decoded looks something like this:

r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,s=QSXCR+Q6sek8bf92,i=4096

In order to generate the final response, we'll need to create a new request (this is based on the exchange from the RFC document, in order to show that it creates the same final message):

* (gen-client-final-message 
    :password "pencil" 
    :client-nonce "fyko+d2lbbFgONRv9qkxdawL" 
    :client-initial-message "n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL" 
    :server-response "r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,s=QSXCR+Q6sek8bf92,i=4096")

((CL-SCRAM::SERVER-SIGNATURE
  . #(174 97 125 166 165 124 75 187 46 2 134 86 141 174 29 37 25 5 176 164))
 (CL-SCRAM::FINAL-MESSAGE
  . "c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts="))

Your application will want to send the final-message back to the server, and store the server-signature for validating the server's final response.

Dealing with final server message

The server will respond with a base64-encoded string. If this is the same as the server-signature from the last step, then authentication was successful.

Donations

If this library has been helpful to you, I don't seek any donations, but please feel free to donate to Quicklisp, one of the most important projects in the CL ecosystem.

Understanding the first server response

The server should respond with a base64-encoded string, when decoded, this will have three parameters:

r=6d442b5d9e51a740f369e3dcecf3178ec12b3985bbd4a8e6f814b422ab766573,s=Vdptv0j/N6fs2qtVADc1Xg==,i=8192

cl-scram provides three convenience methods to access & validate the data.

To get the nonce (and confirm that it correctly starts with the client nonce), call parse-server-nonce passing the decoded message response & the client nonce:

* (parse-server-nonce :nonce "6d44" :response "r=6d442b5d9e51a740f369e3dcecf3178ec12b3985bbd4a8e6f814b422ab766573,s=Vdptv0j/N6fs2qtVADc1Xg==,i=8192")

"6d442b5d9e51a740f369e3dcecf3178ec12b3985bbd4a8e6f814b422ab766573"

And to get the salt (base64-decoded), call parse-server-salt:

* (parse-server-salt :response "r=6d442b5d9e51a740f369e3dcecf3178ec12b3985bbd4a8e6f814b422ab766573,s=Vdptv0j/N6fs2qtVADc1Xg==,i=8192")

"UÚm¿Hÿ7§ìÚ«U75^"

And finally, to get the number of iterations, you can call parse-server-iterations:

* (parse-server-iterations :response "r=6d442b5d9e51a740f369e3dcecf3178ec12b3985bbd4a8e6f814b422ab766573,s=Vdptv0j/N6fs2qtVADc1Xg==,i=8192")

"8192"

TODO

  1. Implement SASLprep algorithm to support the full gamut of passwords. For now, using the library with passwords containing unsupported characters is considered unsupported behavior.
  2. Add regression tests.
  3. Support algorithms other than

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

Author

Matt Prelude <me@mprelu.de>

License

Revised BSD License (see LICENSE)

Description

Common lisp library to implement SCRAM-SHA1 SASL mechanism.

Version

0.1

Dependencies
Source

cl-scram.asd (file)

Components

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-scram/src

Parent

cl-scram (system)

Location

src/

Components

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

4 Files

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


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

4.1 Lisp


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

4.1.1 cl-scram.asd

Location

cl-scram.asd

Systems

cl-scram (system)

Packages

cl-scram-asd


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

4.1.2 cl-scram/src/packages.lisp

Parent

src (module)

Location

src/packages.lisp

Packages

cl-scram


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

4.1.3 cl-scram/src/conditions.lisp

Dependency

packages.lisp (file)

Parent

src (module)

Location

src/conditions.lisp


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

4.1.4 cl-scram/src/utils.lisp

Dependency

conditions.lisp (file)

Parent

src (module)

Location

src/utils.lisp

Exported Definitions
Internal Definitions

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

4.1.5 cl-scram/src/scram.lisp

Dependency

utils.lisp (file)

Parent

src (module)

Location

src/scram.lisp

Exported Definitions
Internal Definitions

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

4.2 Other


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

4.2.1 cl-scram/README.md

Parent

cl-scram (system)

Location

README.md


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

4.2.2 cl-scram/LICENSE

Parent

cl-scram (system)

Location

LICENSE


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

5 Packages

Packages are listed by definition order.


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

5.1 cl-scram-asd

Source

cl-scram.asd

Use List

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

5.2 cl-scram

Source

packages.lisp (file)

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


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

6.1.1 Functions

Function: base64-decode STRING
Package

cl-scram

Source

utils.lisp (file)

Function: base64-encode STRING
Package

cl-scram

Source

utils.lisp (file)

Function: base64-encode-octets OCTETS
Package

cl-scram

Source

utils.lisp (file)

Function: gen-client-encoded-initial-message &key USERNAME NONCE
Package

cl-scram

Source

scram.lisp (file)

Function: gen-client-final-message &key PASSWORD CLIENT-NONCE CLIENT-INITIAL-MESSAGE SERVER-RESPONSE
Package

cl-scram

Source

scram.lisp (file)

Function: gen-client-initial-message &key USERNAME NONCE
Package

cl-scram

Source

scram.lisp (file)

Function: gen-client-nonce ()

Generate a random 32-character nonce.

Package

cl-scram

Source

utils.lisp (file)

Function: gen-sasl-password PASSWORD
Package

cl-scram

Source

utils.lisp (file)

Function: parse-server-iterations &key RESPONSE
Package

cl-scram

Source

scram.lisp (file)

Function: parse-server-nonce &key RESPONSE NONCE
Package

cl-scram

Source

scram.lisp (file)

Function: parse-server-salt &key RESPONSE
Package

cl-scram

Source

scram.lisp (file)


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

6.2 Internal definitions


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

6.2.1 Functions

Function: bit-vector->integer BIT-VECTOR

Create a positive integer from a bit-vector.

Package

cl-scram

Source

utils.lisp (file)

Function: gen-hmac-digest &key KEY MESSAGE

Takes a key & a message, and generates a HMAC digest.

Package

cl-scram

Source

utils.lisp (file)

Function: gen-sha1-digest &key KEY

Takes a key, and generates a SHA1 digest.

Package

cl-scram

Source

utils.lisp (file)

Function: integer->bit-vector INTEGER

Create a bit-vector from a positive integer.

Package

cl-scram

Source

utils.lisp (file)

Function: parse-server-response &key RESPONSE
Package

cl-scram

Source

scram.lisp (file)


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

6.2.2 Generic functions

Generic Function: text CONDITION
Package

cl-scram

Methods
Method: text (CONDITION unexpected-nonce)
Source

scram.lisp (file)


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

6.2.3 Conditions

Condition: unexpected-nonce ()
Package

cl-scram

Source

scram.lisp (file)

Direct superclasses

error (condition)

Direct methods

text (method)

Direct slots
Slot: text
Initargs

:text

Readers

text (generic function)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M   O  
Index Entry  Section

C
cl-scram.asd: The cl-scram<dot>asd file
cl-scram/LICENSE: The cl-scram/license file
cl-scram/README.md: The cl-scram/readme<dot>md file
cl-scram/src: The cl-scram/src module
cl-scram/src/conditions.lisp: The cl-scram/src/conditions<dot>lisp file
cl-scram/src/packages.lisp: The cl-scram/src/packages<dot>lisp file
cl-scram/src/scram.lisp: The cl-scram/src/scram<dot>lisp file
cl-scram/src/utils.lisp: The cl-scram/src/utils<dot>lisp file

F
File, Lisp, cl-scram.asd: The cl-scram<dot>asd file
File, Lisp, cl-scram/src/conditions.lisp: The cl-scram/src/conditions<dot>lisp file
File, Lisp, cl-scram/src/packages.lisp: The cl-scram/src/packages<dot>lisp file
File, Lisp, cl-scram/src/scram.lisp: The cl-scram/src/scram<dot>lisp file
File, Lisp, cl-scram/src/utils.lisp: The cl-scram/src/utils<dot>lisp file
File, other, cl-scram/LICENSE: The cl-scram/license file
File, other, cl-scram/README.md: The cl-scram/readme<dot>md file

L
Lisp File, cl-scram.asd: The cl-scram<dot>asd file
Lisp File, cl-scram/src/conditions.lisp: The cl-scram/src/conditions<dot>lisp file
Lisp File, cl-scram/src/packages.lisp: The cl-scram/src/packages<dot>lisp file
Lisp File, cl-scram/src/scram.lisp: The cl-scram/src/scram<dot>lisp file
Lisp File, cl-scram/src/utils.lisp: The cl-scram/src/utils<dot>lisp file

M
Module, cl-scram/src: The cl-scram/src module

O
Other File, cl-scram/LICENSE: The cl-scram/license file
Other File, cl-scram/README.md: The cl-scram/readme<dot>md file

Jump to:   C   F   L   M   O  

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

A.2 Functions

Jump to:   B   F   G   I   M   P   T  
Index Entry  Section

B
base64-decode: Exported functions
base64-encode: Exported functions
base64-encode-octets: Exported functions
bit-vector->integer: Internal functions

F
Function, base64-decode: Exported functions
Function, base64-encode: Exported functions
Function, base64-encode-octets: Exported functions
Function, bit-vector->integer: Internal functions
Function, gen-client-encoded-initial-message: Exported functions
Function, gen-client-final-message: Exported functions
Function, gen-client-initial-message: Exported functions
Function, gen-client-nonce: Exported functions
Function, gen-hmac-digest: Internal functions
Function, gen-sasl-password: Exported functions
Function, gen-sha1-digest: Internal functions
Function, integer->bit-vector: Internal functions
Function, parse-server-iterations: Exported functions
Function, parse-server-nonce: Exported functions
Function, parse-server-response: Internal functions
Function, parse-server-salt: Exported functions

G
gen-client-encoded-initial-message: Exported functions
gen-client-final-message: Exported functions
gen-client-initial-message: Exported functions
gen-client-nonce: Exported functions
gen-hmac-digest: Internal functions
gen-sasl-password: Exported functions
gen-sha1-digest: Internal functions
Generic Function, text: Internal generic functions

I
integer->bit-vector: Internal functions

M
Method, text: Internal generic functions

P
parse-server-iterations: Exported functions
parse-server-nonce: Exported functions
parse-server-response: Internal functions
parse-server-salt: Exported functions

T
text: Internal generic functions
text: Internal generic functions

Jump to:   B   F   G   I   M   P   T  

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

A.3 Variables

Jump to:   S   T  
Index Entry  Section

S
Slot, text: Internal conditions

T
text: Internal conditions

Jump to:   S   T  

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

A.4 Data types

Jump to:   C   P   S   U  
Index Entry  Section

C
cl-scram: The cl-scram system
cl-scram: The cl-scram package
cl-scram-asd: The cl-scram-asd package
Condition, unexpected-nonce: Internal conditions

P
Package, cl-scram: The cl-scram package
Package, cl-scram-asd: The cl-scram-asd package

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

U
unexpected-nonce: Internal conditions

Jump to:   C   P   S   U