The hunchentools Reference Manual

Table of Contents

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

The hunchentools Reference Manual

This is the hunchentools Reference Manual, version 1.0.0, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 08:50:02 2018 GMT+0.


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

1 Introduction

hunchentools

Hunchentools is a utility library for the Hunchentoot web server. Hunchentools provides functions for creating dispatchers, aborting handlers, escaping strings, hardening session cookies, managing session users, and managing session CSRF tokens.

Hunchentools depends on Hunchentoot, Alexandria, CL-PPCRE, and Ironclad. Hunchentools is being developed with SBCL, CCL, and LispWorks on OS X. Hunchentools is being deployed with SBCL on Linux/AMD64.

Installation

(ql:quickload "hunchentools")

Example

(hunchentoot:define-easy-handler (handle-login :uri "/login")
    ((username :parameter-type 'parse-username :request-type :post)
     (password :parameter-type 'parse-password :request-type :post))
  (hunchentoot:start-session)
  (hunchentools:harden-session-cookie)
  (setf (hunchentoot:content-type*) "text/html; charset=utf-8")
  (case (hunchentoot:request-method*)
    (:get
     (with-output-to-string (stream)
       (render-login-page "Login" stream)))
    (:post
     (if (or (null username)
             (null password)
             (string/= username "root")
             (string/= password "foobar"))
         (with-output-to-string (stream)
           (render-login-page "Bad username and/or password." stream))
         (progn
           (setf (hunchentools:session-user) username)
           (hunchentoot:redirect "/guess"))))))

(defun render-guess-page (csrf-token message
                          &optional (stream *standard-output*))
  (with-html-page (stream)
    (:div
     (:p (cl-who:esc message))
     (:form :action "/guess" :method "post"
            (:input :type "hidden" :name "csrf-token"
                    :value (hunchentools:escape-string-custom
                            csrf-token
                            (constantly t)
                            #'write-char))
            (:input :type "text" :name "guess" :value "")
            (:input :type "submit" :value "Scan"))
     (:p (:a :href "/logout" "Logout")))))

(hunchentoot:define-easy-handler (handle-guess :uri "/guess")
    ((guess :parameter-type 'parse-guess :request-type :post))
  (hunchentoot:start-session)
  (hunchentools:harden-session-cookie)
  (setf (hunchentoot:content-type*) "text/html; charset=utf-8")
  (hunchentools:require-session-user "/logout")
  (case (hunchentoot:request-method*)
    (:get
     (with-output-to-string (stream)
       (render-guess-page (hunchentools:session-csrf-token)
                          "Guess a number."
                          stream)))
    (:post
     (hunchentools:require-session-csrf-token :post)
     (when (null guess)
       (hunchentools:abort-with-bad-request))
     (if (= guess 42)
         (hunchentoot:redirect "/guess")
         (with-output-to-string (stream)
           (render-guess-page (hunchentools:session-csrf-token)
                              "Nope. Guess again."
                              stream))))))

(defun handle-logout ()
  (hunchentoot:start-session)
  (hunchentools:harden-session-cookie)
  (hunchentools:delete-session-user)
  (hunchentoot:redirect "/login"))

(eval-when (:compile-toplevel :load-toplevel :execute)
  (push (hunchentools:create-uri-methods-dispatcher
          "/logout"
          :get
          'handle-logout)
        hunchentoot:*dispatch-table*))

License

Hunchentools is distributed under the MIT license. See 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 hunchentools

Author

Michael J. Forster <mike@forsterfamily.ca>

License

MIT

Description

Hunchentoot utility library

Version

1.0.0

Dependencies
Source

hunchentools.asd (file)

Components

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

3 Files

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


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

3.1 Lisp


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

3.1.1 hunchentools.asd

Location

hunchentools.asd

Systems

hunchentools (system)


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

3.1.2 hunchentools/package.lisp

Parent

hunchentools (system)

Location

package.lisp

Packages

hunchentools


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

3.1.3 hunchentools/abort.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

abort.lisp

Exported Definitions

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

3.1.4 hunchentools/dispatcher.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

dispatcher.lisp

Exported Definitions

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

3.1.5 hunchentools/string-escaping.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

string-escaping.lisp

Exported Definitions

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

3.1.6 hunchentools/session-cookie.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

session-cookie.lisp

Exported Definitions

harden-session-cookie (function)


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

3.1.7 hunchentools/session-user.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

session-user.lisp

Exported Definitions

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

3.1.8 hunchentools/session-csrf-token.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

session-csrf-token.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 hunchentools

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


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

5.1.1 Functions

Function: abort-with-bad-request ()

Abort handling of the request as if the handler had returned HUNCHENTOOT:+HTTP-BAD-REQUEST+.

Package

hunchentools

Source

abort.lisp (file)

Function: abort-with-forbidden ()

Abort handling of the request as if the handler had returned HUNCHENTOOT:+HTTP-FORBIDDEN+.

Package

hunchentools

Source

abort.lisp (file)

Function: abort-with-internal-server-error ()

Abort handling of the request as if the handler had returned HUNCHENTOOT:+HTTP-INTERNAL-SERVER-ERROR+.

Package

hunchentools

Source

abort.lisp (file)

Function: abort-with-not-found ()

Abort handling of the request as if the handler had returned HUNCHENTOOT:+HTTP-NOT-FOUND+.

Package

hunchentools

Source

abort.lisp (file)

Function: abort-with-return-code RETURN-CODE

Abort handling of the request as if the handler had returned RETURN-CODE.

Package

hunchentools

Source

abort.lisp (file)

Function: create-prefix-methods-dispatcher PREFIX METHODS HANDLER

Return a request dispatch function which will dispatch to the function denoted by HANDLER if the file name of the current request starts with the string PREFIX and the method of the current request is a member of the list denoted by METHODS. The dispatch function will return NIL if there is no match.

Package

hunchentools

Source

dispatcher.lisp (file)

Function: create-regex-methods-dispatcher REGEX METHODS HANDLER

Return a request dispatch function which will dispatch to the function denoted by HANDLER if the file name of the current request matches the CL-PPCRE regular expression REGEX and the method of the current request is a member of the list denoted by METHODS. The dispatch function will return NIL if there is no match.

Package

hunchentools

Source

dispatcher.lisp (file)

Function: create-uri-methods-dispatcher URI METHODS HANDLER

Return a request dispatch function which will dispatch to the function denoted by HANDLER if the file name of the current request matches the string URI and the method of the current request is a member of the list denoted by METHODS. The dispatch function will return NIL if there is no match.

Package

hunchentools

Source

dispatcher.lisp (file)

Function: delete-session-csrf-token ()

Remove the CSRF token, if any, from the session.

Package

hunchentools

Source

session-csrf-token.lisp (file)

Function: delete-session-user ()

Remove the user, if any, from the session.

Package

hunchentools

Source

session-user.lisp (file)

Function: escape-string-custom STRING TEST ESCAPE-WRITE-FUNCTION

Given a string STRING, return a new string, encoding with the
function denoted by ESCAPE-WRITE-FUNCTION every character for which the function denoted by TEST returns true.

Use this in place of CL-WHO:ESCAPE-STRING where custom encoding is required.

Package

hunchentools

Source

string-escaping.lisp (file)

Function: escape-string-js STRING

Given a string STRING, return a new string, escaping all ASCII values less than 256 with the xHH format and those greater than or equal to 256 with the uHHHH format.

Package

hunchentools

Source

string-escaping.lisp (file)

Function: harden-session-cookie &key SECUREP NAME

Set the HTTP-ONLY and secure flags of the outgoing cookie named NAME and set it to expire with the session. NAME defaults to "hunchentoot-session".

Package

hunchentools

Source

session-cookie.lisp (file)

Function: require-session-csrf-token REQUEST-TYPE &optional NAME

Abort handling the request, log a warning message, and remove any session CSRF token if the request of type denoted by REQUEST-TYPE does not provide a value for the parameter NAME, if the provided value does not match the session CSRF token, or if the session CSRF token has not been set. Othewise, do nothing. REQUEST-TYPE can be one
of :GET, :POST, :PUT, or :DELETE. NAME defaults to "csrf-token".

Package

hunchentools

Source

session-csrf-token.lisp (file)

Function: require-session-user &rest REDIRECT-ARGS

Log a warning message and redirect if no user is set for the session. Otherwise, do nothing. REDIRECT-ARGS are used as keyword arguments to HUNCHENTOOT:REDIRECT.

Package

hunchentools

Source

session-user.lisp (file)

Function: session-csrf-token ()

Return the current CSRF token set for the session or a new token if one has not been set. If the session does not exist, return NIL.

Package

hunchentools

Source

session-csrf-token.lisp (file)

Function: session-user ()

Return the user set for the session. Return NIL if the session does not exist or if no user has been set.

SETF of SESSION-USER can be used to set a new user for the session. If the session does not exist then one is created. Signal a correctable error of type TYPE-ERROR if SETF of SESSION-USER is called with a NIL value for user.

Package

hunchentools

Source

session-user.lisp (file)

Writer

(setf session-user) (function)

Function: (setf session-user) NEW-USER
Package

hunchentools

Source

session-user.lisp (file)

Reader

session-user (function)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *csrf-secret*
Package

hunchentools

Source

session-csrf-token.lisp (file)

Special Variable: *the-random-state*
Package

hunchentools

Source

session-csrf-token.lisp (file)


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

5.2.2 Functions

Function: next-csrf-token ()
Package

hunchentools

Source

session-csrf-token.lisp (file)

Function: random-string &optional N BASE

Return a random number (as a string) with base BASE and N digits.

Package

hunchentools

Source

session-csrf-token.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   H   L  
Index Entry  Section

F
File, Lisp, hunchentools.asd: The hunchentools<dot>asd file
File, Lisp, hunchentools/abort.lisp: The hunchentools/abort<dot>lisp file
File, Lisp, hunchentools/dispatcher.lisp: The hunchentools/dispatcher<dot>lisp file
File, Lisp, hunchentools/package.lisp: The hunchentools/package<dot>lisp file
File, Lisp, hunchentools/session-cookie.lisp: The hunchentools/session-cookie<dot>lisp file
File, Lisp, hunchentools/session-csrf-token.lisp: The hunchentools/session-csrf-token<dot>lisp file
File, Lisp, hunchentools/session-user.lisp: The hunchentools/session-user<dot>lisp file
File, Lisp, hunchentools/string-escaping.lisp: The hunchentools/string-escaping<dot>lisp file

H
hunchentools.asd: The hunchentools<dot>asd file
hunchentools/abort.lisp: The hunchentools/abort<dot>lisp file
hunchentools/dispatcher.lisp: The hunchentools/dispatcher<dot>lisp file
hunchentools/package.lisp: The hunchentools/package<dot>lisp file
hunchentools/session-cookie.lisp: The hunchentools/session-cookie<dot>lisp file
hunchentools/session-csrf-token.lisp: The hunchentools/session-csrf-token<dot>lisp file
hunchentools/session-user.lisp: The hunchentools/session-user<dot>lisp file
hunchentools/string-escaping.lisp: The hunchentools/string-escaping<dot>lisp file

L
Lisp File, hunchentools.asd: The hunchentools<dot>asd file
Lisp File, hunchentools/abort.lisp: The hunchentools/abort<dot>lisp file
Lisp File, hunchentools/dispatcher.lisp: The hunchentools/dispatcher<dot>lisp file
Lisp File, hunchentools/package.lisp: The hunchentools/package<dot>lisp file
Lisp File, hunchentools/session-cookie.lisp: The hunchentools/session-cookie<dot>lisp file
Lisp File, hunchentools/session-csrf-token.lisp: The hunchentools/session-csrf-token<dot>lisp file
Lisp File, hunchentools/session-user.lisp: The hunchentools/session-user<dot>lisp file
Lisp File, hunchentools/string-escaping.lisp: The hunchentools/string-escaping<dot>lisp file

Jump to:   F   H   L  

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

A.2 Functions

Jump to:   (  
A   C   D   E   F   H   N   R   S  
Index Entry  Section

(
(setf session-user): Exported functions

A
abort-with-bad-request: Exported functions
abort-with-forbidden: Exported functions
abort-with-internal-server-error: Exported functions
abort-with-not-found: Exported functions
abort-with-return-code: Exported functions

C
create-prefix-methods-dispatcher: Exported functions
create-regex-methods-dispatcher: Exported functions
create-uri-methods-dispatcher: Exported functions

D
delete-session-csrf-token: Exported functions
delete-session-user: Exported functions

E
escape-string-custom: Exported functions
escape-string-js: Exported functions

F
Function, (setf session-user): Exported functions
Function, abort-with-bad-request: Exported functions
Function, abort-with-forbidden: Exported functions
Function, abort-with-internal-server-error: Exported functions
Function, abort-with-not-found: Exported functions
Function, abort-with-return-code: Exported functions
Function, create-prefix-methods-dispatcher: Exported functions
Function, create-regex-methods-dispatcher: Exported functions
Function, create-uri-methods-dispatcher: Exported functions
Function, delete-session-csrf-token: Exported functions
Function, delete-session-user: Exported functions
Function, escape-string-custom: Exported functions
Function, escape-string-js: Exported functions
Function, harden-session-cookie: Exported functions
Function, next-csrf-token: Internal functions
Function, random-string: Internal functions
Function, require-session-csrf-token: Exported functions
Function, require-session-user: Exported functions
Function, session-csrf-token: Exported functions
Function, session-user: Exported functions

H
harden-session-cookie: Exported functions

N
next-csrf-token: Internal functions

R
random-string: Internal functions
require-session-csrf-token: Exported functions
require-session-user: Exported functions

S
session-csrf-token: Exported functions
session-user: Exported functions

Jump to:   (  
A   C   D   E   F   H   N   R   S  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*csrf-secret*: Internal special variables
*the-random-state*: Internal special variables

S
Special Variable, *csrf-secret*: Internal special variables
Special Variable, *the-random-state*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   H   P   S  
Index Entry  Section

H
hunchentools: The hunchentools system
hunchentools: The hunchentools package

P
Package, hunchentools: The hunchentools package

S
System, hunchentools: The hunchentools system

Jump to:   H   P   S