The hunchentools Reference Manual

Table of Contents

The hunchentools Reference Manual

This is the hunchentools Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 18:19:23 2020 GMT+0.

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.

2 Systems

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

2.1 hunchentools

Author

Michael J. Forster <mike@forsterfamily.ca>

License

MIT

Description

Hunchentoot utility library

Version

1.0.0

Dependencies

• hunchentoot
• alexandria
• cl-ppcre
• ironclad

Source

hunchentools.asd (file)

Components

• package.lisp (file)
• abort.lisp (file)
• dispatcher.lisp (file)
• string-escaping.lisp (file)
• session-cookie.lisp (file)
• session-user.lisp (file)
• session-csrf-token.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 hunchentools.asd

Location

hunchentools.asd

Systems

hunchentools (system)

3.1.2 hunchentools/package.lisp

Parent

hunchentools (system)

Location

package.lisp

Packages

hunchentools

3.1.3 hunchentools/abort.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

abort.lisp

Exported Definitions

• abort-with-bad-request (function)
• abort-with-forbidden (function)
• abort-with-internal-server-error (function)
• abort-with-not-found (function)
• abort-with-return-code (function)

3.1.4 hunchentools/dispatcher.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

dispatcher.lisp

Exported Definitions

• create-prefix-methods-dispatcher (function)
• create-regex-methods-dispatcher (function)
• create-uri-methods-dispatcher (function)

3.1.5 hunchentools/string-escaping.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

string-escaping.lisp

Exported Definitions

• escape-string-custom (function)
• escape-string-js (function)

3.1.6 hunchentools/session-cookie.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

session-cookie.lisp

Exported Definitions

harden-session-cookie (function)

3.1.7 hunchentools/session-user.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

session-user.lisp

Exported Definitions

• delete-session-user (function)
• require-session-user (function)
• session-user (function)
• (setf session-user) (function)

3.1.8 hunchentools/session-csrf-token.lisp

Dependency

package.lisp (file)

Parent

hunchentools (system)

Location

session-csrf-token.lisp

Exported Definitions

• delete-session-csrf-token (function)
• require-session-csrf-token (function)
• session-csrf-token (function)

Internal Definitions

• *csrf-secret* (special variable)
• *the-random-state* (special variable)
• next-csrf-token (function)
• random-string (function)

4 Packages

Packages are listed by definition order.

4.1 hunchentools

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• abort-with-bad-request (function)
• abort-with-forbidden (function)
• abort-with-internal-server-error (function)
• abort-with-not-found (function)
• abort-with-return-code (function)
• create-prefix-methods-dispatcher (function)
• create-regex-methods-dispatcher (function)
• create-uri-methods-dispatcher (function)
• delete-session-csrf-token (function)
• delete-session-user (function)
• escape-string-custom (function)
• escape-string-js (function)
• harden-session-cookie (function)
• require-session-csrf-token (function)
• require-session-user (function)
• session-csrf-token (function)
• session-user (function)
• (setf session-user) (function)

Internal Definitions

• *csrf-secret* (special variable)
• *the-random-state* (special variable)
• next-csrf-token (function)
• random-string (function)

5 Definitions

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

5.1 Exported definitions

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)

5.2 Internal definitions

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)

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)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types