Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
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.
Next: Systems, Previous: The hermetic Reference Manual, Up: The hermetic Reference Manual [Contents][Index]
Simple authentication for Clack-based Common Lisp web applications.
See the demo app for a complete example.
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-sha512setupHermetic 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*)
loginWhen creating your login view, the login macro handles most of the work for
you.
authGrants 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.")))))
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.logoutLogs the user out. Takes two expressions, on-success and on-failure.
Copyright (c) 2013 Fernando Borretti (eudoxiahp@gmail.com).
Licensed under the MIT License.
Next: Modules, Previous: Introduction, Up: The hermetic Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Fernando Borretti
MIT
# 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.
0.1
src (module).
Next: Files, Previous: Systems, Up: The hermetic Reference Manual [Contents][Index]
Modules are listed depth-first from the system components tree.
Next: Packages, Previous: Modules, Up: The hermetic Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: hermetic/src/hermetic.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
hermetic (system).
Previous: hermetic/hermetic.asd, Up: Lisp [Contents][Index]
src (module).
Next: Definitions, Previous: Files, Up: The hermetic Reference Manual [Contents][Index]
Packages are listed by definition order.
Previous: hermetic-asd, Up: Packages [Contents][Index]
Next: Indexes, Previous: Packages, Up: The hermetic Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Previous: Public Interface, Up: Public Interface [Contents][Index]
Provide functions for *user-p* and *user-pass*
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Internals, Up: Internals [Contents][Index]
A function that gets called when a user tries to access a page without sufficient privileges
The expression for accessing the session object.
A function that takes a username string, and returns t
if a user by that name exists in the database, otherwise nil.
A function to retrieve the hash of a user’s password from its username
A function that maps a username to a list of roles.
Previous: Special variables, Up: Internals [Contents][Index]
Previous: Definitions, Up: The hermetic Reference Manual [Contents][Index]
| Jump to: | A F L M R S U |
|---|
| Jump to: | A F L M R S U |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
S |
|---|
| Jump to: | *
S |
|---|
| Jump to: | F H M P S |
|---|
| Jump to: | F H M P S |
|---|