Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-sasl Reference Manual, version 0.3.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:32:54 2020 GMT+0.
| • Introduction | What cl-sasl is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
This is an SASL client library for Common Lisp. SASL is described in
RFC 2222.
* Dependencies
This library depends on the Ironclad cryptography library. Find it in
Debian (as cl-ironclad), though asdf-install (as ironclad) or on cliki.
* Supported mechanisms
Currently PLAIN, DIGEST-MD5 and ANONYMOUS are supported.
* Usage
** Choose a mechanism
Choose a mechanism to use. If you know what mechanism you want to
use, pass its name to GET-MECHANISM, which returns a symbol naming a
class, or NIL if that mechanism is not implemented.
If the server has given a list of mechanisms, and you want to choose
the best one that satisfies certain criteria, use the CHOOSE-MECHANISM
function. Its first argument is a list of strings naming the
available mechanisms. It takes two keyword arguments:
- CLEARTEXT: if true, accept mechanisms that send passwords in clear
text or with weak encryption (default false)
- ANONYMOUS: if and only if true, use mechanisms that acquire
anonymous access (default false)
CHOOSE-MECHANISM returns a symbol naming a class, or NIL if no
appropriate mechanism was found.
** Create a mechanism instance
Create an instance of the mechanism you want to use. Initargs common
to most mechanisms are:
:AUTHENTICATION-ID The name of the user whose password you have.
:AUTHORIZATION-ID The name of the user you want to impersonate.
If omitted, same as authentication-id.
:PASSWORD The password as a string, or a function of no
arguments that returns a password.
:SERVICE The service name, e.g. "xmpp" or "imap".
:HOST The hostname of the service.
:SERV-NAME The server you are connecting to.
If omitted, same as hostname.
The ANONYMOUS mechanism ignores all initargs except:
:TRACE Trace information (defaults to the empty string)
Example:
(let* ((mechanism "DIGEST-MD5")
(client (make-instance (sasl:get-mechanism mechanism)
:authentication-id "username"
:password "secret"
:service "imap"
:host "server")))
...
)
** Perform authentication
Once you have such an instance, do the following:
1. If the protocol you are using permits the client to send an initial
"response", call CLIENT-STEP with NIL as second argument. If it
returns a byte vector with non-zero length, use that as initial
response.
2. If the server presents a challenge, call CLIENT-STEP with the
challenge as second argument in byte vector form. CLIENT-STEP
returns either a byte vector to send as a response, or :FAILURE,
in which case authentication should be aborted.
Repeat this step as needed.
3. If the server reports successful authentication, you are still not
done. Some mechanisms perform mutual authentication, so you need
confirmation from CLIENT-STEP.
If the protocol allows it, and the server sends additional data
along with the success notification, pass that data to CLIENT-STEP
as if it were a challenge. CLIENT-STEP returns either :FAILURE,
which means that authentication should be aborted, or a response
that can be ignored.
After that, call CLIENT-STEP with :SUCCESS as second argument.
CLIENT-STEP returns either :SUCCESS or :FAILURE.
4. If the server reports authentication failure, no interaction with
this library is required.
* Compatibility
I have tested this code on CLISP and SBCL, but it should work on other
implementations as well. The code assumes that CHAR-CODE returns the
Unicode code point for every character in the given arguments, and for
ASCII characters.
* Contact
Web page: http://xn--9dbdkw.se/cl-sasl.html
Git repository: http://github.com/legoscia/cl-sasl/
You can use the discussion page of the former or the issue tracker of
the latter, or contact me directly by magnus.henoch@gmail.com (e-mail)
or magnus.henoch@jabber.se (Jabber/XMPP).
Local variables:
mode: outline
End:
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The cl-sasl system |
Magnus Henoch <magnus.henoch@gmail.com>
BSD-style
SASL library
0.3.2
ironclad
cl-sasl.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The cl-sasl.asd file | ||
| • The cl-sasl/packages.lisp file | ||
| • The cl-sasl/util.lisp file | ||
| • The cl-sasl/client.lisp file | ||
| • The cl-sasl/plain.lisp file | ||
| • The cl-sasl/digest-md5.lisp file |
Next: The cl-sasl/packages․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-sasl.asd
cl-sasl (system)
Next: The cl-sasl/util․lisp file, Previous: The cl-sasl․asd file, Up: Lisp files [Contents][Index]
Next: The cl-sasl/client․lisp file, Previous: The cl-sasl/packages․lisp file, Up: Lisp files [Contents][Index]
packages.lisp (file)
cl-sasl (system)
util.lisp
Next: The cl-sasl/plain․lisp file, Previous: The cl-sasl/util․lisp file, Up: Lisp files [Contents][Index]
cl-sasl (system)
client.lisp
Next: The cl-sasl/digest-md5․lisp file, Previous: The cl-sasl/client․lisp file, Up: Lisp files [Contents][Index]
client.lisp (file)
cl-sasl (system)
plain.lisp
Previous: The cl-sasl/plain․lisp file, Up: Lisp files [Contents][Index]
client.lisp (file)
cl-sasl (system)
digest-md5.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The cl-sasl-system package | ||
| • The sasl package |
Next: The sasl package, Previous: Packages, Up: Packages [Contents][Index]
cl-sasl.asd
Previous: The cl-sasl-system package, Up: Packages [Contents][Index]
packages.lisp (file)
cl-sasl
common-lisp
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 | ||
| • Exported generic functions | ||
| • Exported classes |
Next: Exported generic functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Choose an SASL mechanism from AVAILABLE.
Return the class implementing the mechanism, or nil if no mechanism
is suitable.
AVAILABLE is a list of strings, naming the mechanisms offered by the
server.
If CLEARTEXT is true, accept mechanisms that send passwords in clear
text or with weak encryption.
If ANONYMOUS is true, use mechanisms that acquire anonymous access.
client.lisp (file)
Return the class name for the mechanism called NAME, or nil if not implemented.
client.lisp (file)
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
The authentication id.
This is the user whose credentials you are providing to the server.
client.lisp (file)
The authorization id.
This is the user you want to act as. You don’t need to provide it
unless it is different from the authentication id.
client.lisp (file)
Perform a step in the SASL authentication.
SERVER-INPUT is a byte vector containing the response from the
server, or NIL if the client should start the exchange, or the
keyword :SUCCESS if the server reported successful
authentication.
Returns a byte vector to be sent in response to the server, or :SUCCESS if the client should consider authentication successful, or :FAILURE if the client should consider authentication failed. Obeying this result is important, as some mechanisms provide mutual authentication.
client.lisp (file)
digest-md5.lisp (file)
plain.lisp (file)
The hostname of the service.
client.lisp (file)
automatically generated reader method
client.lisp (file)
The password.
This is either a string, or a function taking no arguments and
returning the password.
client.lisp (file)
The realm to which the user’s account belongs.
If it is not specified, the first realm that the server advertises will
be chosen. Many servers don’t use realms.
digest-md5.lisp (file)
The specific server you are connecting to (if different from the hostname).
client.lisp (file)
The service name.
Common values include "xmpp" and "imap".
client.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Abstract base class for SASL clients using various mechanisms.
client.lisp (file)
standard-object (class)
The authentication id.
This is the user whose credentials you are providing to the server.
:authentication-id
authc-id (generic function)
(setf authc-id) (generic function)
The authorization id.
This is the user you want to act as. You don’t need to provide it
unless it is different from the authentication id.
:authorization-id
authz-id (generic function)
(setf authz-id) (generic function)
The password.
This is either a string, or a function taking no arguments and
returning the password.
(or string function)
:password
password (generic function)
(setf password) (generic function)
The service name.
Common values include "xmpp" and "imap".
:service
service (generic function)
(setf service) (generic function)
The hostname of the service.
:host
host (generic function)
(setf host) (generic function)
The specific server you are connecting to (if different from the hostname).
:serv-name
serv-name (generic function)
(setf serv-name) (generic function)
:class
mechanism-name (generic function)
Client-side implementation of the SASL DIGEST-MD5 mechanism, as specified in RFC 2831.
digest-md5.lisp (file)
client (class)
The realm to which the user’s account belongs.
If it is not specified, the first realm that the server advertises will
be chosen. Many servers don’t use realms.
:realm
realm (generic function)
(setf realm) (generic function)
:start
state (generic function)
(setf state) (generic function)
nonce (generic function)
(setf nonce) (generic function)
cnonce (generic function)
(setf cnonce) (generic function)
digest-uri-value (generic function)
(setf digest-uri-value) (generic function)
"digest-md5"
Client-side implementation of the SASL PLAIN mechanism, as specified in RFC 2595, section 6.
plain.lisp (file)
client (class)
:start
state (generic function)
(setf state) (generic function)
"plain"
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal functions | ||
| • Internal generic functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
List of SASL mechanisms in order of preference.
Each element is a list describing a mechanism. The first item is
the name of the mechanism. The second item is the class
implementing it. The remaining items are properties of the
mechanism:
:CLEARTEXT Password is sent in clear text or with weak encryption :ANONYMOUS Mechanism negotiates anonymous access
client.lisp (file)
Next: Internal generic functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
client.lisp (file)
Return non-nil if CHAR is in the ISO 8859-1 character set.
Parse CHALLENGE and return it as an alist. Start at index START.
digest-md5.lisp (file)
digest-md5.lisp (file)
Convert STRING to ISO 8859-1 if possible, else to UTF-8. Return a byte vector.
digest-md5.lisp (file)
Convert STRING to UTF-8. Return a vector of unsigned-bytes.
Convert STRING to UTF-8. Return a vector of unsigned-bytes.
Previous: Internal functions, Up: Internal definitions [Contents][Index]
automatically generated reader method
digest-md5.lisp (file)
automatically generated writer method
digest-md5.lisp (file)
automatically generated reader method
digest-md5.lisp (file)
automatically generated writer method
digest-md5.lisp (file)
automatically generated reader method
digest-md5.lisp (file)
automatically generated writer method
digest-md5.lisp (file)
digest-md5.lisp (file)
automatically generated reader method
digest-md5.lisp (file)
automatically generated writer method
digest-md5.lisp (file)
automatically generated reader method
plain.lisp (file)
automatically generated writer method
plain.lisp (file)
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 |
|---|
| Jump to: | C F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | (
A C D F G H I M N P R S |
|---|
| Jump to: | (
A C D F G H I M N P R S |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | A C D H M N P R S |
|---|
| Jump to: | A C D H M N P R S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C D P S |
|---|
| Jump to: | C D P S |
|---|