Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-scram Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:46:14 2020 GMT+0.
• Introduction | What cl-scram 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 |
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.
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.
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.
TODO: Add regression tests.
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-scram
s message-generating functions, which accept a :nonce
parameter.
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.
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.
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.
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.
The server should respond with a base64-encoded string, when decoded, this will have three parameters:
r=6d442b5d9e51a740f369e3dcecf3178ec12b3985bbd4a8e6f814b422ab766573,s=Vdptv0j/N6fs2qtVADc1Xg==,i=8192
r
is the nonce.s
is the salt (base64-encoded).i
is the number of iterations.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"
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The cl-scram system |
Matt Prelude <me@mprelu.de>
Revised BSD License (see LICENSE)
Common lisp library to implement SCRAM-SHA1 SASL mechanism.
0.1
cl-scram.asd (file)
Modules are listed depth-first from the system components tree.
• The cl-scram/src module |
cl-scram (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files | ||
• Static files |
Next: Static files, Previous: Files, Up: Files [Contents][Index]
• The cl-scram.asd file | ||
• The cl-scram/src/packages.lisp file | ||
• The cl-scram/src/conditions.lisp file | ||
• The cl-scram/src/utils.lisp file | ||
• The cl-scram/src/scram.lisp file |
Next: The cl-scram/src/packages․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-scram.asd
cl-scram (system)
Next: The cl-scram/src/conditions․lisp file, Previous: The cl-scram․asd file, Up: Lisp files [Contents][Index]
Next: The cl-scram/src/utils․lisp file, Previous: The cl-scram/src/packages․lisp file, Up: Lisp files [Contents][Index]
packages.lisp (file)
src (module)
src/conditions.lisp
Next: The cl-scram/src/scram․lisp file, Previous: The cl-scram/src/conditions․lisp file, Up: Lisp files [Contents][Index]
conditions.lisp (file)
src (module)
src/utils.lisp
Previous: The cl-scram/src/utils․lisp file, Up: Lisp files [Contents][Index]
utils.lisp (file)
src (module)
src/scram.lisp
Previous: Lisp files, Up: Files [Contents][Index]
• The cl-scram/readme.md file | ||
• The cl-scram/license file |
Next: The cl-scram/license file, Previous: Static files, Up: Static files [Contents][Index]
cl-scram (system)
README.md
Previous: The cl-scram/readme․md file, Up: Static files [Contents][Index]
cl-scram (system)
LICENSE
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The cl-scram-asd package | ||
• The cl-scram package |
Next: The cl-scram package, Previous: Packages, Up: Packages [Contents][Index]
cl-scram.asd
Previous: The cl-scram-asd package, Up: Packages [Contents][Index]
packages.lisp (file)
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 functions |
Previous: Exported definitions, Up: Exported definitions [Contents][Index]
utils.lisp (file)
utils.lisp (file)
utils.lisp (file)
scram.lisp (file)
scram.lisp (file)
scram.lisp (file)
Generate a random 32-character nonce.
utils.lisp (file)
utils.lisp (file)
scram.lisp (file)
scram.lisp (file)
scram.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal functions | ||
• Internal generic functions | ||
• Internal conditions |
Next: Internal generic functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Create a positive integer from a bit-vector.
utils.lisp (file)
Takes a key & a message, and generates a HMAC digest.
utils.lisp (file)
Takes a key, and generates a SHA1 digest.
utils.lisp (file)
Create a bit-vector from a positive integer.
utils.lisp (file)
scram.lisp (file)
Next: Internal conditions, Previous: Internal functions, Up: Internal definitions [Contents][Index]
scram.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
scram.lisp (file)
error (condition)
text (method)
:text
text (generic function)
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 S |
---|
Jump to: | C F L M S |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | B F G I M P T |
---|
Jump to: | B F G I M P T |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | S T |
---|
Index Entry | Section | ||
---|---|---|---|
| |||
S | |||
Slot, text : | Internal conditions | ||
| |||
T | |||
text : | Internal conditions | ||
|
Jump to: | S T |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C P S U |
---|
Jump to: | C P S U |
---|