The hermetic Reference Manual

This is the hermetic Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 05:26:42 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 hermetic

Author

Fernando Borretti

Home Page

https://github.com/eudoxia0/hermetic

License

MIT

Long Description

# Hermetic

Simple authentication for [Clack](http://clacklisp.org/)-based Common Lisp web applications.

# Usage

See the demo app for a complete example.

## Available Password-Hashing Functions

To mitigate the risks of the NSA convincing people to hash passwords with things like SHA-256, only PBKDF2 (And eventually scrypt) is supported

* ‘:pbkdf2-sha1‘
* ‘:pbkdf2-sha256‘
* ‘:pbkdf2-sha512‘

## ‘setup‘

Hermetic is not opinionated, doesn’t integrate into an existing database or create any models. As such, it needs to be told how to find a user’s information to provide authentication. This is what ‘setup‘ is for:

“‘lisp
(setup
:user-p ;; str->bool, t if a username exists, nil otherwise :user-pass ;; str->str, maps a username to a password (hash, hopefully) :user-roles ;; str->(list sym), maps a username to a list of roles,
;; for example: (:user) (:user :tester :staff) (:user :admin) :session ;; the /expression/ for the session object. ningle:*session* on ;; Ningle <https://github.com/fukamachi/ningle>.
:denied ;; A function that displays an "access denied" message )
“‘

For example, if your users are stored in a simple in-memory hash-table as in the demo app:

“‘lisp
(defmacro get-user (username)
‘(gethash ,username *users*))

(setup
:user-p #’(lambda (user) (get-user user))
:user-pass #’(lambda (user) (getf (get-user user) :pass))
:user-roles #’(lambda (user) (getf (get-user user) :roles))
:session *session*)
“‘

## ‘login‘

When creating your login view, the ‘login‘ macro handles most of the work for you.

## ‘auth‘

Grants access to a site only to users whose roles intersect with the roles in the first argument.

If an access denied page is not provided, the global one is used instead.

Example:

“‘lisp
(setf (route *app* "/user/profile/:userid" :method :GET)
(lambda (params
(auth (:user)
(render-template "templates/profile.html")
(render-error "You have to log in to view user profiles."))))) “‘

## Misc.

When ‘auth‘ isn’t enough to determine who gets to use what, Hermetic provides a few functions for accessing user data from inside a view.

* ‘logged-in-p‘: Exactly what it says on the tin.
* ‘user-name‘: Returns the username of the current user.
* ‘roles‘: Returns the list of roles of the current user.
* ‘role-p‘: Checks if a user has a role.

## ‘logout‘

Logs the user out. Takes two expressions, ‘on-success‘ and ‘on-failure‘.

# License

Copyright (c) 2013 Fernando Borretti (eudoxiahp@gmail.com).

Licensed under the MIT License.

Version

0.1

Dependencies
  • clack (system).
  • cl-pass (system).
Source

hermetic.asd.

Child Component

src (module).


3 Modules

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


3.1 hermetic/src

Source

hermetic.asd.

Parent Component

hermetic (system).

Child Component

hermetic.lisp (file).


4 Files

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


4.1 Lisp


4.1.1 hermetic/hermetic.asd

Source

hermetic.asd.

Parent Component

hermetic (system).

ASDF Systems

hermetic.

Packages

hermetic-asd.


4.1.2 hermetic/src/hermetic.lisp

Source

hermetic.asd.

Parent Component

src (module).

Packages

hermetic.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 hermetic-asd

Source

hermetic.asd.

Use List
  • asdf/interface.
  • common-lisp.

5.2 hermetic

Source

hermetic.lisp.

Use List
  • cl-pass.
  • common-lisp.
Public Interface
Internals

6 Definitions

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


6.1 Public Interface


6.1.1 Macros

Macro: auth ((&rest roles) page &optional denied-page)
Package

hermetic.

Source

hermetic.lisp.

Macro: logged-in-p ()
Package

hermetic.

Source

hermetic.lisp.

Macro: login (params on-success on-failure on-no-user)
Package

hermetic.

Source

hermetic.lisp.

Macro: logout (on-success on-failure)
Package

hermetic.

Source

hermetic.lisp.

Macro: role-p (role)
Package

hermetic.

Source

hermetic.lisp.

Macro: roles ()
Package

hermetic.

Source

hermetic.lisp.

Macro: setup (&key user-p user-pass user-roles session denied)

Provide functions for *user-p* and *user-pass*

Package

hermetic.

Source

hermetic.lisp.

Macro: user-name ()
Package

hermetic.

Source

hermetic.lisp.


6.2 Internals


6.2.1 Special variables

Special Variable: *denied-page*

A function that gets called when a user tries to access a page without sufficient privileges

Package

hermetic.

Source

hermetic.lisp.

Special Variable: *session*

The expression for accessing the session object.

Package

hermetic.

Source

hermetic.lisp.

Special Variable: *user-p*

A function that takes a username string, and returns t
if a user by that name exists in the database, otherwise nil.

Package

hermetic.

Source

hermetic.lisp.

Special Variable: *user-pass*

A function to retrieve the hash of a user’s password from its username

Package

hermetic.

Source

hermetic.lisp.

Special Variable: *user-roles*

A function that maps a username to a list of roles.

Package

hermetic.

Source

hermetic.lisp.


6.2.2 Ordinary functions

Function: authorize (user pass)
Package

hermetic.

Source

hermetic.lisp.


Appendix A Indexes


A.1 Concepts