The hermetic Reference Manual

Table of Contents

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

The hermetic Reference Manual

This is the hermetic Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:56:25 2018 GMT+0.


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

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.


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

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

Description
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
Source

hermetic.asd (file)

Component

src (module)


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

3 Modules

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


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

3.1 hermetic/src

Parent

hermetic (system)

Location

src/

Component

hermetic.lisp (file)


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

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 files   [Contents][Index]

4.1.1 hermetic.asd

Location

hermetic.asd

Systems

hermetic (system)

Packages

hermetic-asd


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

4.1.2 hermetic/src/hermetic.lisp

Parent

src (module)

Location

src/hermetic.lisp

Packages

hermetic

Exported Definitions
Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 hermetic-asd

Source

hermetic.asd

Use List

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

5.2 hermetic

Source

hermetic.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Macros

Macro: auth (&rest ROLES) PAGE &optional DENIED-PAGE
Package

hermetic

Source

hermetic.lisp (file)

Macro: logged-in-p ()
Package

hermetic

Source

hermetic.lisp (file)

Macro: login PARAMS ON-SUCCESS ON-FAILURE ON-NO-USER
Package

hermetic

Source

hermetic.lisp (file)

Macro: role-p ROLE
Package

hermetic

Source

hermetic.lisp (file)

Macro: roles ()
Package

hermetic

Source

hermetic.lisp (file)

Macro: setup &key USER-P USER-PASS USER-ROLES SESSION DENIED

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

Package

hermetic

Source

hermetic.lisp (file)


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

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [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 (file)

Special Variable: *session*

The expression for accessing the session object.

Package

hermetic

Source

hermetic.lisp (file)

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 (file)

Special Variable: *user-pass*

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

Package

hermetic

Source

hermetic.lisp (file)

Special Variable: *user-roles*

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

Package

hermetic

Source

hermetic.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Macros

Macro: logout ON-SUCCESS ON-FAILURE
Package

hermetic

Source

hermetic.lisp (file)

Macro: user-name ()
Package

hermetic

Source

hermetic.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Functions

Function: authorize USER PASS
Package

hermetic

Source

hermetic.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   H   L   M  
Index Entry  Section

F
File, Lisp, hermetic.asd: The hermetic<dot>asd file
File, Lisp, hermetic/src/hermetic.lisp: The hermetic/src/hermetic<dot>lisp file

H
hermetic.asd: The hermetic<dot>asd file
hermetic/src: The hermetic/src module
hermetic/src/hermetic.lisp: The hermetic/src/hermetic<dot>lisp file

L
Lisp File, hermetic.asd: The hermetic<dot>asd file
Lisp File, hermetic/src/hermetic.lisp: The hermetic/src/hermetic<dot>lisp file

M
Module, hermetic/src: The hermetic/src module

Jump to:   F   H   L   M  

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

A.2 Functions

Jump to:   A   F   L   M   R   S   U  
Index Entry  Section

A
auth: Exported macros
authorize: Internal functions

F
Function, authorize: Internal functions

L
logged-in-p: Exported macros
login: Exported macros
logout: Internal macros

M
Macro, auth: Exported macros
Macro, logged-in-p: Exported macros
Macro, login: Exported macros
Macro, logout: Internal macros
Macro, role-p: Exported macros
Macro, roles: Exported macros
Macro, setup: Exported macros
Macro, user-name: Internal macros

R
role-p: Exported macros
roles: Exported macros

S
setup: Exported macros

U
user-name: Internal macros

Jump to:   A   F   L   M   R   S   U  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*denied-page*: Internal special variables
*session*: Internal special variables
*user-p*: Internal special variables
*user-pass*: Internal special variables
*user-roles*: Internal special variables

S
Special Variable, *denied-page*: Internal special variables
Special Variable, *session*: Internal special variables
Special Variable, *user-p*: Internal special variables
Special Variable, *user-pass*: Internal special variables
Special Variable, *user-roles*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   H   P   S  
Index Entry  Section

H
hermetic: The hermetic system
hermetic: The hermetic package
hermetic-asd: The hermetic-asd package

P
Package, hermetic: The hermetic package
Package, hermetic-asd: The hermetic-asd package

S
System, hermetic: The hermetic system

Jump to:   H   P   S