The hunchentoot-auth Reference Manual

Table of Contents

The hunchentoot-auth Reference Manual

This is the hunchentoot-auth Reference Manual, version 0.2.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 18:19:32 2020 GMT+0.

1 Introduction

hunchentoot-auth

This package is for implementing user authentication with passwords
for the hunchentoot Common Lisp web server.

The core unit of hunchentoot-auth is the realm. Currently a realm is
just a persistent "bag" for holding users and their associated (hashed)
passwords, along with the beginnings of support for groups. 

In the initial incarnation, realms use the cl-store module for storing
the users and groups information for the realm. This is clearly not
the most efficient approach, but works well enough for a small number
of users.

To create a realm, one can use a lisp expression such as:


  (defparamter *test-realm-directory "/tmp/myrealm/")

  (ensure-directories-exist *test-realm-directory*)

  (defparameter *test-realm*
    (make-instance 'ht-auth:realm
                   :user-storage-path
                   (merge-pathnames "users.store"
                                    *test-realm-directory*)
                   :group-storage-path
                   (merge-pathnames "groups.store"
                                    *test-realm-directory*)))


Then to add users to the realm, one would use the following code:


  (ht-auth:add-user *test-realm* "alice" "secret1")


This would add the user "alice" to the realm with the password
"secret1". Note that the password is not directly stored in the
persistent storage, but rather the password is appended to a random
(per-user) salt (which is stored in the persistent database) and this
salted uesr name is then hashed using the MD5 hashing algorithm. The
hash of the salted password is stored in the database. To subsequently
verify if a given password matches that of the user, the (per-user)
salt is prepened to the candidate password, this string is then hashed
and compared to the hash stored in the realm.

2 Systems

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

2.1 hunchentoot-auth

Author

Cyrus Harmon <ch-lisp@bobobeach.com>

License

BSD

Version

0.2.1

Dependencies

• hunchentoot
• cl-who
• cl-store
• bordeaux-threads

Source

hunchentoot-auth.asd (file)

Components

• defpackage.lisp (file)
• realm.lisp (file)
• hunchentoot-auth.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 hunchentoot-auth.asd

Location

hunchentoot-auth.asd

Systems

hunchentoot-auth (system)

3.1.2 hunchentoot-auth/defpackage.lisp

Parent

hunchentoot-auth (system)

Location

defpackage.lisp

Packages

hunchentoot-auth

3.1.3 hunchentoot-auth/realm.lisp

Dependency

defpackage.lisp (file)

Parent

hunchentoot-auth (system)

Location

realm.lisp

Exported Definitions

• add-group (generic function)
• add-group (method)
• add-user (generic function)
• add-user (method)
• check-password (generic function)
• check-password (method)
• check-password (method)
• delete-user (generic function)
• delete-user (method)
• get-realm-user (function)
• get-realm-user-names (function)
• get-realm-users (function)
• read-realm-groups (generic function)
• read-realm-groups (method)
• read-realm-users (generic function)
• read-realm-users (method)
• realm (class)
• set-password (generic function)
• set-password (method)
• set-password (method)
• user-name (method)
• (setf user-name) (method)

Internal Definitions

• *password-file-lock* (special variable)
• *password-lock* (special variable)
• add-group-user (method)
• get-realm-group-names (function)
• get-realm-groups (function)
• group (class)
• group-name (method)
• (setf group-name) (method)
• group-users (method)
• (setf group-users) (method)
• hash-keys (function)
• hash-values (function)
• random-string (function)
• realm-group-storage-path (method)
• (setf realm-group-storage-path) (method)
• realm-groups (method)
• (setf realm-groups) (method)
• realm-user-storage-path (method)
• (setf realm-user-storage-path) (method)
• realm-users (method)
• (setf realm-users) (method)
• store-realm-groups (generic function)
• store-realm-groups (method)
• store-realm-users (generic function)
• store-realm-users (method)
• user (class)
• user-full-name (method)
• (setf user-full-name) (method)
• user-password (method)
• (setf user-password) (method)
• user-password-salt (method)
• (setf user-password-salt) (method)

3.1.4 hunchentoot-auth/hunchentoot-auth.lisp

Dependencies

• defpackage.lisp (file)
• realm.lisp (file)

Parent

hunchentoot-auth (system)

Location

hunchentoot-auth.lisp

Exported Definitions

• authorized-page (macro)
• generate-html-login (function)
• session-realm-user (function)
• (setf session-realm-user) (function)
• session-realm-user-authenticated-p (function)
• (setf session-realm-user-authenticated-p) (function)

Internal Definitions

• create-authorized-dispatcher (function)
• login-page (function)
• parse-host-name-and-port (function)
• with-html (macro)
• with-html-page (macro)

4 Packages

Packages are listed by definition order.

4.1 hunchentoot-auth

Source

defpackage.lisp (file)

Nickname

ht-auth

Use List

• hunchentoot
• cl-who
• common-lisp

Exported Definitions

• add-group (generic function)
• add-group (method)
• add-user (generic function)
• add-user (method)
• authorized-page (macro)
• check-password (generic function)
• check-password (method)
• check-password (method)
• delete-user (generic function)
• delete-user (method)
• generate-html-login (function)
• get-realm-user (function)
• get-realm-user-names (function)
• get-realm-users (function)
• read-realm-groups (generic function)
• read-realm-groups (method)
• read-realm-users (generic function)
• read-realm-users (method)
• realm (class)
• session-realm-user (function)
• (setf session-realm-user) (function)
• session-realm-user-authenticated-p (function)
• (setf session-realm-user-authenticated-p) (function)
• set-password (generic function)
• set-password (method)
• set-password (method)
• user-name (generic function)
• user-name (method)
• (setf user-name) (method)
• (setf user-name) (generic function)

Internal Definitions

• *password-file-lock* (special variable)
• *password-lock* (special variable)
• add-group-user (generic function)
• add-group-user (method)
• create-authorized-dispatcher (function)
• get-realm-group-names (function)
• get-realm-groups (function)
• group (class)
• group-name (generic function)
• group-name (method)
• (setf group-name) (method)
• (setf group-name) (generic function)
• group-users (generic function)
• group-users (method)
• (setf group-users) (method)
• (setf group-users) (generic function)
• hash-keys (function)
• hash-values (function)
• login-page (function)
• parse-host-name-and-port (function)
• random-string (function)
• realm-group-storage-path (generic function)
• realm-group-storage-path (method)
• (setf realm-group-storage-path) (method)
• (setf realm-group-storage-path) (generic function)
• realm-groups (generic function)
• realm-groups (method)
• (setf realm-groups) (method)
• (setf realm-groups) (generic function)
• realm-user-storage-path (generic function)
• realm-user-storage-path (method)
• (setf realm-user-storage-path) (method)
• (setf realm-user-storage-path) (generic function)
• realm-users (generic function)
• realm-users (method)
• (setf realm-users) (method)
• (setf realm-users) (generic function)
• store-realm-groups (generic function)
• store-realm-groups (method)
• store-realm-users (generic function)
• store-realm-users (method)
• user (class)
• user-full-name (generic function)
• user-full-name (method)
• (setf user-full-name) (method)
• (setf user-full-name) (generic function)
• user-password (generic function)
• user-password (method)
• (setf user-password) (method)
• (setf user-password) (generic function)
• user-password-salt (generic function)
• user-password-salt (method)
• (setf user-password-salt) (method)
• (setf user-password-salt) (generic function)
• with-html (macro)
• with-html-page (macro)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: authorized-page (REALM &key USE-SSL SSL-PORT LOGIN-PAGE-FUNCTION) &rest BODY

Package

hunchentoot-auth

Source

hunchentoot-auth.lisp (file)

5.1.2 Functions

Function: generate-html-login &key USER PASSWORD

Package

hunchentoot-auth

Source

hunchentoot-auth.lisp (file)

Function: get-realm-user REALM NAME

Package

hunchentoot-auth

Source

realm.lisp (file)

Function: get-realm-user-names REALM

Package

hunchentoot-auth

Source

realm.lisp (file)

Function: get-realm-users REALM

Package

hunchentoot-auth

Source

realm.lisp (file)

Function: session-realm-user REALM

Function: (setf session-realm-user) VALUE REALM

Package

hunchentoot-auth

Source

hunchentoot-auth.lisp (file)

Function: session-realm-user-authenticated-p REALM

Function: (setf session-realm-user-authenticated-p) VALUE REALM

Package

hunchentoot-auth

Source

hunchentoot-auth.lisp (file)

5.1.3 Generic functions

Generic Function: add-group REALM GROUP

Adds a new group named group with the specified realm.

Package

hunchentoot-auth

Source

realm.lisp (file)

Methods

Method: add-group (REALM realm) (NAME string)

Generic Function: add-user REALM USER PASSWORD &key FULL-NAME

Adds a new user with the specified password in this realm.

Package

hunchentoot-auth

Source

realm.lisp (file)

Methods

Method: add-user (REALM realm) (NAME string) (PASSWORD string) &key FULL-NAME

Generic Function: check-password REALM USER PASSWORD

Returns T if the given user/password combination is valid in this realm, otherwise returns NIL.

Package

hunchentoot-auth

Source

realm.lisp (file)

Methods

Method: check-password (REALM realm) (NAME string) PASSWORD

Method: check-password (REALM realm) (USER user) PASSWORD

Generic Function: delete-user REALM USER

Removes the user with the specified name from this realm.

Package

hunchentoot-auth

Source

realm.lisp (file)

Methods

Method: delete-user (REALM realm) (NAME string)

Generic Function: read-realm-groups REALM

Read the groups for this realm from the group file.

Package

hunchentoot-auth

Source

realm.lisp (file)

Methods

Method: read-realm-groups (REALM realm)

Generic Function: read-realm-users REALM

Read the users for this realm from the password file.

Package

hunchentoot-auth

Source

realm.lisp (file)

Methods

Method: read-realm-users (REALM realm)

Generic Function: set-password REALM USER PASSWORD

Sets the password for the specified user in this realm.

Package

hunchentoot-auth

Source

realm.lisp (file)

Methods

Method: set-password (REALM realm) (NAME string) PASSWORD

Method: set-password (REALM realm) (USER user) PASSWORD

Generic Function: user-name OBJECT

Generic Function: (setf user-name) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: user-name (USER user)

automatically generated reader method

Source

realm.lisp (file)

Method: (setf user-name) NEW-VALUE (USER user)

automatically generated writer method

Source

realm.lisp (file)

5.1.4 Classes

Class: realm ()

Objects of this class represent realms for which a given user/password scheme should apply.

Package

hunchentoot-auth

Source

realm.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• add-group-user (method)
• add-group (method)
• store-realm-groups (method)
• read-realm-groups (method)
• check-password (method)
• check-password (method)
• delete-user (method)
• add-user (method)
• set-password (method)
• set-password (method)
• store-realm-users (method)
• read-realm-users (method)
• shared-initialize (method)
• realm-group-storage-path (method)
• realm-group-storage-path (method)
• realm-groups (method)
• realm-groups (method)
• realm-user-storage-path (method)
• realm-user-storage-path (method)
• realm-users (method)
• realm-users (method)

Direct slots

Slot: users

A hash-table for the users and passwords
for this realm. The keys are the user names (strings) and the values are instances of the class user.

Initform

(make-hash-table :test (function equal))

Readers

realm-users (generic function)

Writers

(setf realm-users) (generic function)

Slot: user-storage-path

The path to the file in
which to store the password hash-table.

Initargs

:user-storage-path

Readers

realm-user-storage-path (generic function)

Writers

(setf realm-user-storage-path) (generic function)

Slot: groups

A hash-table for the groups for this
realm. The keys are the group names (strings) and the values instances of the class group

Initform

(make-hash-table :test (function equal))

Readers

realm-groups (generic function)

Writers

(setf realm-groups) (generic function)

Slot: group-storage-path

The path to the file in
which to store the group hash-table.

Initargs

:group-storage-path

Readers

realm-group-storage-path (generic function)

Writers

(setf realm-group-storage-path) (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *password-file-lock*

Package

hunchentoot-auth

Source

realm.lisp (file)

Special Variable: *password-lock*

Package

hunchentoot-auth

Source

realm.lisp (file)

5.2.2 Macros

Macro: with-html &body BODY

Executes BODY inside a cl-who:with-html-output body.

Package

hunchentoot-auth

Source

hunchentoot-auth.lisp (file)

Macro: with-html-page &body BODY

Executes BODY inside a cl-who:with-html-output-to-string body, directing the output to *standard-output* and setting :prologue to t.

Package

hunchentoot-auth

Source

hunchentoot-auth.lisp (file)

5.2.3 Functions

Function: create-authorized-dispatcher URI-BASE REALM DISPATCHER &key USE-SSL SSL-PORT LOGIN-PAGE-FUNCTION

Package

hunchentoot-auth

Source

hunchentoot-auth.lisp (file)

Function: get-realm-group-names REALM

Package

hunchentoot-auth

Source

realm.lisp (file)

Function: get-realm-groups REALM

Package

hunchentoot-auth

Source

realm.lisp (file)

Function: hash-keys HASH

Package

hunchentoot-auth

Source

realm.lisp (file)

Function: hash-values HASH

Package

hunchentoot-auth

Source

realm.lisp (file)

Function: login-page &key TITLE

Package

hunchentoot-auth

Source

hunchentoot-auth.lisp (file)

Function: parse-host-name-and-port HOST-AND-PORT

Package

hunchentoot-auth

Source

hunchentoot-auth.lisp (file)

Function: random-string LENGTH

Return a random string of the characters [a-zA-Z] of the specified length.

Package

hunchentoot-auth

Source

realm.lisp (file)

5.2.4 Generic functions

Generic Function: add-group-user REALM GROUP USER

Package

hunchentoot-auth

Methods

Method: add-group-user (REALM realm) (GROUP group) (USER user)

Source

realm.lisp (file)

Generic Function: group-name OBJECT

Generic Function: (setf group-name) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: group-name (GROUP group)

automatically generated reader method

Source

realm.lisp (file)

Method: (setf group-name) NEW-VALUE (GROUP group)

automatically generated writer method

Source

realm.lisp (file)

Generic Function: group-users OBJECT

Generic Function: (setf group-users) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: group-users (GROUP group)

automatically generated reader method

Source

realm.lisp (file)

Method: (setf group-users) NEW-VALUE (GROUP group)

automatically generated writer method

Source

realm.lisp (file)

Generic Function: realm-group-storage-path OBJECT

Generic Function: (setf realm-group-storage-path) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: realm-group-storage-path (REALM realm)

Method: (setf realm-group-storage-path) NEW-VALUE (REALM realm)

The path to the file in
which to store the group hash-table.

Source

realm.lisp (file)

Generic Function: realm-groups OBJECT

Generic Function: (setf realm-groups) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: realm-groups (REALM realm)

Method: (setf realm-groups) NEW-VALUE (REALM realm)

A hash-table for the groups for this
realm. The keys are the group names (strings) and the values instances of the class group

Source

realm.lisp (file)

Generic Function: realm-user-storage-path OBJECT

Generic Function: (setf realm-user-storage-path) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: realm-user-storage-path (REALM realm)

Method: (setf realm-user-storage-path) NEW-VALUE (REALM realm)

The path to the file in
which to store the password hash-table.

Source

realm.lisp (file)

Generic Function: realm-users OBJECT

Generic Function: (setf realm-users) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: realm-users (REALM realm)

Method: (setf realm-users) NEW-VALUE (REALM realm)

A hash-table for the users and passwords
for this realm. The keys are the user names (strings) and the values are instances of the class user.

Source

realm.lisp (file)

Generic Function: store-realm-groups REALM

Store the groups for this realm in the group file.

Package

hunchentoot-auth

Source

realm.lisp (file)

Methods

Method: store-realm-groups (REALM realm)

Generic Function: store-realm-users REALM

Store the users for this realm in the password file.

Package

hunchentoot-auth

Source

realm.lisp (file)

Methods

Method: store-realm-users (REALM realm)

Generic Function: user-full-name OBJECT

Generic Function: (setf user-full-name) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: user-full-name (USER user)

automatically generated reader method

Source

realm.lisp (file)

Method: (setf user-full-name) NEW-VALUE (USER user)

automatically generated writer method

Source

realm.lisp (file)

Generic Function: user-password OBJECT

Generic Function: (setf user-password) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: user-password (USER user)

automatically generated reader method

Source

realm.lisp (file)

Method: (setf user-password) NEW-VALUE (USER user)

automatically generated writer method

Source

realm.lisp (file)

Generic Function: user-password-salt OBJECT

Generic Function: (setf user-password-salt) NEW-VALUE OBJECT

Package

hunchentoot-auth

Methods

Method: user-password-salt (USER user)

automatically generated reader method

Source

realm.lisp (file)

Method: (setf user-password-salt) NEW-VALUE (USER user)

automatically generated writer method

Source

realm.lisp (file)

5.2.5 Classes

Class: group ()

Package

hunchentoot-auth

Source

realm.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• add-group-user (method)
• group-users (method)
• group-users (method)
• group-name (method)
• group-name (method)

Direct slots

Slot: name

Initargs

:name

Readers

group-name (generic function)

Writers

(setf group-name) (generic function)

Slot: users

Initform

(make-hash-table)

Readers

group-users (generic function)

Writers

(setf group-users) (generic function)

Class: user ()

Package

hunchentoot-auth

Source

realm.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• add-group-user (method)
• check-password (method)
• set-password (method)
• user-password-salt (method)
• user-password-salt (method)
• user-password (method)
• user-password (method)
• user-full-name (method)
• user-full-name (method)
• user-name (method)
• user-name (method)

Direct slots

Slot: name

Initargs

:name

Readers

user-name (generic function)

Writers

(setf user-name) (generic function)

Slot: full-name

Initargs

:full-name

Readers

user-full-name (generic function)

Writers

(setf user-full-name) (generic function)

Slot: password

Initargs

:password

Initform

""

Readers

user-password (generic function)

Writers

(setf user-password) (generic function)

Slot: password-salt

Initargs

:password-salt

Readers

user-password-salt (generic function)

Writers

(setf user-password-salt) (generic function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types