The hermetic Reference Manual

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

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 Mon Aug 15 04:46:04 2022 GMT+0.

Table of Contents


1 Introduction

Hermetic

Simple authentication for Clack-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

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:

(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:

(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:

(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.

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.


2 Systems

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


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

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.


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

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.


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

4.1 Lisp


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

4.1.1 hermetic/hermetic.asd

Source

hermetic.asd.

Parent Component

hermetic (system).

ASDF Systems

hermetic.

Packages

hermetic-asd.


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

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.


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

5.1 hermetic-asd

Source

hermetic.asd.

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

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

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.


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

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


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

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.


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

6.2.2 Ordinary functions

Function: authorize (user pass)
Package

hermetic.

Source

hermetic.lisp.


Appendix A Indexes


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

A.1 Concepts