The south Reference Manual

Table of Contents

The south Reference Manual

This is the south Reference Manual, version 0.3.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:36:45 2018 GMT+0.

1 Introduction

Please Use North Instead

This library has been superseded by North. Please use that instead, as its code based is an improvement from South in almost every respect and it includes the ability to provide the server side of the oAuth system as well.

How To

Load South through Quicklisp or ASDF:

(ql:quickload :south)

First you need to tell South about the service you want to interact with. For this you will need at least the following three URLs oauth/request-token, oauth/authorize, oauth/access-token as well as the api-key and api-secret of your oAuth application that you want to use to connect. To set up South you can either set the according special variables directly or use the prepare function:

(south:prepare
  :oauth/request-token "https://api.twitter.com/oauth/request_token"
  :oauth/authenticate "https://api.twitter.com/oauth/authenticate"
  :oauth/authorize "https://api.twitter.com/oauth/authorize"
  :oauth/access-token "https://api.twitter.com/oauth/access_token"
  :api-key key
  :api-secret secret)

Twitter requires an additional authenticate URL, which is otherwise set to the same as the authorize address. To start the authentication process simply call initiate-authentication. If your addresses and api codes are correct, it should return an URL that the user has to visit in their browser.

(south:initiate-authentication)

By default this will use the SERVER method, which loads and starts a hunchentoot instance on *SERVER-PORT*. After the remote authentication has been accepted it redirects to this local server. If you want to handle the server yourself, you should instead pass a callback URL as the :method to initiate-authentication. Depending on the service it might provide additional non-standard authentication methods, like twitter's PIN. The PIN method is already integrated into South, but anything beyond that you will have to add yourself. If you choose to use your own server or a different method, you will need to call complete-authentication with the verifier and optionally the access-token.

(south:complete-authentication verifier :token access-token)

The SERVER method will automatically call complete-authentication once it receives the request and shuts itself down. If complete-authentication returns successfully you should now be all set to perform oAuth requests. To request with oAuth signatures, you can use the signed-request function.

(south:signed-request "https://api.twitter.com/1.1/account/verify_credentials.json")

Depending on how your service requires it, posting form data may require special treatment. South provides a signed-data-request function that is geared towards how twitter requires it, but it may also work for other services.

If you need to handle multiple oAuth accounts at the same time you may want to use the with-oauth-environment macro to establish dynamic bindings around the internal special variables. The macro accepts parameters for all the environment variables so you may directly set them without needing to call prepare.

Applications

If your application uses South, please let me know so I can list it here!

• Humbler, a Tumblr API interface library.

2 Systems

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

2.1 south

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shinmera/south

License

Artistic

Description

Simple OaUTH library for oAuth1.0

Version

0.3.0

Dependencies

• drakma
• uuid
• ironclad
• cl-ppcre

Source

south.asd (file)

Components

• package.lisp (file)
• toolkit.lisp (file)
• oauth.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 south.asd

Location

south.asd

Systems

south (system)

3.1.2 south/package.lisp

Parent

south (system)

Location

package.lisp

Packages

south

3.1.3 south/toolkit.lisp

Dependency

package.lisp (file)

Parent

south (system)

Location

toolkit.lisp

Exported Definitions

• *external-format* (special variable)
• generate-nonce (function)
• url-decode (function)
• url-encode (function)

Internal Definitions

• +unix-epoch-difference+ (constant)
• get-unix-time (function)
• hmac (function)
• parse-boolean (function)
• to-keyword (function)

3.1.4 south/oauth.lisp

Dependency

toolkit.lisp (file)

Parent

south (system)

Location

oauth.lisp

Exported Definitions

• *authentication-callback* (special variable)
• *oauth-access-secret* (special variable)
• *oauth-access-token* (special variable)
• *oauth-api-key* (special variable)
• *oauth-api-secret* (special variable)
• *oauth-signature-method* (special variable)
• *oauth-verifier-location* (special variable)
• *oauth-version* (special variable)
• *oauth/access-token* (special variable)
• *oauth/authenticate* (special variable)
• *oauth/authorize* (special variable)
• *oauth/request-token* (special variable)
• *server-port* (special variable)
• complete-authentication (function)
• http-body (method)
• (setf http-body) (method)
• http-headers (method)
• (setf http-headers) (method)
• http-status (method)
• (setf http-status) (method)
• initiate-authentication (function)
• initiate-server-authentication (function)
• oauth-error (condition)
• oauth-parameter-missing (condition)
• oauth-request-error (condition)
• oauth/access-token (function)
• oauth/authenticate (function)
• oauth/authorize (function)
• oauth/request-token (function)
• parameter (method)
• (setf parameter) (method)
• pin-request-token (function)
• prepare (function)
• reset (function)
• signed-data-parameters-request (function)
• signed-data-request (function)
• signed-request (function)
• signed-stream-request (function)
• target-headers (method)
• (setf target-headers) (method)
• target-method (method)
• (setf target-method) (method)
• target-parameters (method)
• (setf target-parameters) (method)
• target-url (method)
• (setf target-url) (method)
• with-oauth-environment (macro)

Internal Definitions

• authorization-format-parameter (function)
• create-authorization-header (function)
• create-authorization-header-value (function)
• create-signature (function)
• make-signed (function)
• oauth-response->alist (function)
• prepare-data-parameters (function)
• request-wrapper (function)
• signature-format-parameter (function)

4 Packages

Packages are listed by definition order.

4.1 south

Source

package.lisp (file)

Nickname

org.tymoonnext.south

Use List

common-lisp

Exported Definitions

• *authentication-callback* (special variable)
• *external-format* (special variable)
• *oauth-access-secret* (special variable)
• *oauth-access-token* (special variable)
• *oauth-api-key* (special variable)
• *oauth-api-secret* (special variable)
• *oauth-signature-method* (special variable)
• *oauth-verifier-location* (special variable)
• *oauth-version* (special variable)
• *oauth/access-token* (special variable)
• *oauth/authenticate* (special variable)
• *oauth/authorize* (special variable)
• *oauth/request-token* (special variable)
• *server-port* (special variable)
• complete-authentication (function)
• generate-nonce (function)
• http-body (generic function)
• http-body (method)
• (setf http-body) (method)
• (setf http-body) (generic function)
• http-headers (generic function)
• http-headers (method)
• (setf http-headers) (method)
• (setf http-headers) (generic function)
• http-status (generic function)
• http-status (method)
• (setf http-status) (method)
• (setf http-status) (generic function)
• initiate-authentication (function)
• initiate-server-authentication (function)
• oauth-error (condition)
• oauth-parameter-missing (condition)
• oauth-request-error (condition)
• oauth/access-token (function)
• oauth/authenticate (function)
• oauth/authorize (function)
• oauth/request-token (function)
• parameter (generic function)
• parameter (method)
• (setf parameter) (method)
• (setf parameter) (generic function)
• pin-request-token (function)
• prepare (function)
• reset (function)
• signed-data-parameters-request (function)
• signed-data-request (function)
• signed-request (function)
• signed-stream-request (function)
• target-headers (generic function)
• target-headers (method)
• (setf target-headers) (method)
• (setf target-headers) (generic function)
• target-method (generic function)
• target-method (method)
• (setf target-method) (method)
• (setf target-method) (generic function)
• target-parameters (generic function)
• target-parameters (method)
• (setf target-parameters) (method)
• (setf target-parameters) (generic function)
• target-url (generic function)
• target-url (method)
• (setf target-url) (method)
• (setf target-url) (generic function)
• url-decode (function)
• url-encode (function)
• with-oauth-environment (macro)

Internal Definitions

• +unix-epoch-difference+ (constant)
• authorization-format-parameter (function)
• create-authorization-header (function)
• create-authorization-header-value (function)
• create-signature (function)
• get-unix-time (function)
• hmac (function)
• make-signed (function)
• oauth-response->alist (function)
• parse-boolean (function)
• prepare-data-parameters (function)
• request-wrapper (function)
• signature-format-parameter (function)
• to-keyword (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *authentication-callback*

Function called when COMPLETE-AUTHENTICATION is called.
Two arguments are passed, the ACCESS-TOKEN and the ACCESS-SECRET.

Package

south

Source

oauth.lisp (file)

Special Variable: *external-format*

The external format used for encoding/decoding.

Package

south

Source

toolkit.lisp (file)

Special Variable: *oauth-access-secret*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth-access-token*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth-api-key*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth-api-secret*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth-signature-method*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth-verifier-location*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth-version*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth/access-token*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth/authenticate*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth/authorize*

Package

south

Source

oauth.lisp (file)

Special Variable: *oauth/request-token*

Package

south

Source

oauth.lisp (file)

Special Variable: *server-port*

Package

south

Source

oauth.lisp (file)

5.1.2 Macros

Macro: with-oauth-environment (&key OAUTH/REQUEST-TOKEN OAUTH/AUTHORIZE OAUTH/AUTHENTICATE OAUTH/ACCESS-TOKEN SIGNATURE-METHOD VERSION API-KEY API-SECRET ACCESS-TOKEN ACCESS-SECRET) &body BODY

Establishes an environment for all oauth related special variables.
Unless a non-NIL value is provided for a parameter it is bound to the current value of the according special variable.

Package

south

Source

oauth.lisp (file)

5.1.3 Functions

Function: complete-authentication VERIFIER &optional TOKEN

Finishes the authentication procedure by retrieving the access token. Sets the *OAUTH-TOKEN* and *OAUTH-TOKEN-SECRET* to their respective values.

Package

south

Source

oauth.lisp (file)

Function: generate-nonce ()

Generate a NONCE to use for requests. Currently this simply uses a v4-UUID.

Package

south

Source

toolkit.lisp (file)

Function: initiate-authentication &key METHOD API-KEY API-SECRET

Starts the authentication process and returns an URL that the user has to visit.
METHOD can be one of :PIN :SERVER or a string designating a callback URL.
Note that the :PIN method is NOT STANDARD and thus might not be available for your service. See OAUTH/AUTHORIZE, INITIATE-SERVER-AUTHENTICATION and OAUTH/AUTHENTICATE respectively.

Package

south

Source

oauth.lisp (file)

Function: initiate-server-authentication ()

Initiate the authentication through the server mechanism. This is the same as the redirect mechanism, except it starts up a Hunchentoot server automatically and handles the callback for you. The server will be started on *SERVER-PORT* and will be shut down automatically after a single request.

Package

south

Source

oauth.lisp (file)

Function: oauth/access-token VERIFIER

Turn the tokens received through the authentication into an access token.

According to spec https://dev.twitter.com/docs/auth/implementing-sign-twitter

Package

south

Source

oauth.lisp (file)

Function: oauth/authenticate CALLBACK-URL

Initiate the authentication through the redirect mechanism.
Returns an URL that the user has to open in the browser.
Upon successful authentication, the page should redirect back
to the specified callback url. This callback endpoint should then
pass the proper parameters to COMPLETE-AUTHENTICATION.

According to spec https://dev.twitter.com/docs/auth/implementing-sign-twitter

Package

south

Source

oauth.lisp (file)

Function: oauth/authorize ()

Initiate the authentication through the PIN mechanism.
Returns an URL that the user has to open in the browser.
This page should, upon successful authentication, return a PIN
that has to be initialized by passing it to COMPLETE-AUTHENTICATION.

According to spec https://dev.twitter.com/docs/auth/pin-based-authorization

Package

south

Source

oauth.lisp (file)

Function: oauth/request-token CALLBACK

Query for a request token using the specified callback.
Returns an ALIST containing :OAUTH-TOKEN, :OAUTH-TOKEN-SECRET and :OAUTH-CALLBACK-CONFIRMED, the first two being strings and the last a boolean.

According to spec https://dev.twitter.com/docs/auth/implementing-sign-twitter

Package

south

Source

oauth.lisp (file)

Function: pin-request-token ()

Query for a PIN based request token.
Seee CALLBACK-REQUEST-TOKEN.

According to spec https://dev.twitter.com/docs/auth/pin-based-authorization

Package

south

Source

oauth.lisp (file)

Function: prepare &key OAUTH/REQUEST-TOKEN OAUTH/AUTHORIZE OAUTH/AUTHENTICATE OAUTH/ACCESS-TOKEN API-KEY API-SECRET

Cosmetic function to set the oauth request URLs and api-key and -secret. This only sets the internal value of the parameter if it is non-NIL.

Package

south

Source

oauth.lisp (file)

Function: reset ()

Resets the internal API-KEY, API-SECRET, ACCESS-TOKEN and ACCESS-SECRET to NIL. This does not change the oauth request URLs.

Package

south

Source

oauth.lisp (file)

Function: signed-data-parameters-request REQUEST-URL &key DATA-PARAMETERS PARAMETERS OAUTH-PARAMETERS ADDITIONAL-HEADERS METHOD DRAKMA-PARAMS

Issue a signed data request against the API.
See SIGNED-REQUEST. The difference to SIGNED-DATA-REQUEST is that the default PARAMETERS are used to calculate the authorization header, whereas the DATA-PARAMETERS are not. In SINGED-DATA-REQUEST, neither of the parameters are used for the header.

Package

south

Source

oauth.lisp (file)

Function: signed-data-request REQUEST-URL &key DATA-PARAMETERS PARAMETERS OAUTH-PARAMETERS ADDITIONAL-HEADERS METHOD DRAKMA-PARAMS

Issue a signed data request against the API.
See SIGNED-REQUEST.

According to spec https://dev.twitter.com/docs/uploading-media

Package

south

Source

oauth.lisp (file)

Function: signed-request REQUEST-URL &key PARAMETERS OAUTH-PARAMETERS ADDITIONAL-HEADERS METHOD DRAKMA-PARAMS

Issue a signed request against the API.
This requires the *oauth-api-key*, *oauth-signature-method*, *oauth-version* and at least *oauth-api-secret* to be set.
See CREATE-SIGNATURE.
For return values see DRAKMA:HTTP-REQUEST

According to spec https://dev.twitter.com/docs/auth/authorizing-request

Package

south

Source

oauth.lisp (file)

Function: signed-stream-request REQUEST-URL &key PARAMETERS OAUTH-PARAMETERS ADDITIONAL-HEADERS METHOD DRAKMA-PARAMS

Issue a signed data request against the API.
See SIGNED-REQUEST. Returns values according to DRAKMA:HTTP-REQUEST with :WANT-STREAM T

Package

south

Source

oauth.lisp (file)

Function: url-decode STRING &optional EXTERNAL-FORMAT

Returns a URL-decoded version of the string STRING external format EXTERNAL-FORMAT.

According to spec https://dev.twitter.com/docs/auth/percent-encoding-parameters

Package

south

Source

toolkit.lisp (file)

Function: url-encode THING &optional EXTERNAL-FORMAT

Returns a URL-encoded version of the string STRING or OCTET-SEQUENCE using the external format EXTERNAL-FORMAT.

According to spec https://dev.twitter.com/docs/auth/percent-encoding-parameters

Package

south

Source

toolkit.lisp (file)

5.1.4 Generic functions

Generic Function: http-body CONDITION

Generic Function: (setf http-body) NEW-VALUE CONDITION

Package

south

Methods

Method: http-body (CONDITION oauth-request-error)

Method: (setf http-body) NEW-VALUE (CONDITION oauth-request-error)

Source

oauth.lisp (file)

Generic Function: http-headers CONDITION

Generic Function: (setf http-headers) NEW-VALUE CONDITION

Package

south

Methods

Method: http-headers (CONDITION oauth-request-error)

Method: (setf http-headers) NEW-VALUE (CONDITION oauth-request-error)

Source

oauth.lisp (file)

Generic Function: http-status CONDITION

Generic Function: (setf http-status) NEW-VALUE CONDITION

Package

south

Methods

Method: http-status (CONDITION oauth-request-error)

Method: (setf http-status) NEW-VALUE (CONDITION oauth-request-error)

Source

oauth.lisp (file)

Generic Function: parameter CONDITION

Generic Function: (setf parameter) NEW-VALUE CONDITION

Package

south

Methods

Method: parameter (CONDITION oauth-parameter-missing)

Method: (setf parameter) NEW-VALUE (CONDITION oauth-parameter-missing)

Source

oauth.lisp (file)

Generic Function: target-headers CONDITION

Generic Function: (setf target-headers) NEW-VALUE CONDITION

Package

south

Methods

Method: target-headers (CONDITION oauth-request-error)

Method: (setf target-headers) NEW-VALUE (CONDITION oauth-request-error)

Source

oauth.lisp (file)

Generic Function: target-method CONDITION

Generic Function: (setf target-method) NEW-VALUE CONDITION

Package

south

Methods

Method: target-method (CONDITION oauth-request-error)

Method: (setf target-method) NEW-VALUE (CONDITION oauth-request-error)

Source

oauth.lisp (file)

Generic Function: target-parameters CONDITION

Generic Function: (setf target-parameters) NEW-VALUE CONDITION

Package

south

Methods

Method: target-parameters (CONDITION oauth-request-error)

Method: (setf target-parameters) NEW-VALUE (CONDITION oauth-request-error)

Source

oauth.lisp (file)

Generic Function: target-url CONDITION

Generic Function: (setf target-url) NEW-VALUE CONDITION

Package

south

Methods

Method: target-url (CONDITION oauth-request-error)

Method: (setf target-url) NEW-VALUE (CONDITION oauth-request-error)

Source

oauth.lisp (file)

5.1.5 Conditions

Condition: oauth-error ()

Package

south

Source

oauth.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• oauth-parameter-missing (condition)
• oauth-request-error (condition)

Condition: oauth-parameter-missing ()

Package

south

Source

oauth.lisp (file)

Direct superclasses

oauth-error (condition)

Direct methods

• parameter (method)
• parameter (method)

Direct slots

Slot: %parameter

Initargs

:parameter

Readers

parameter (generic function)

Writers

(setf parameter) (generic function)

Condition: oauth-request-error ()

Package

south

Source

oauth.lisp (file)

Direct superclasses

oauth-error (condition)

Direct methods

• target-headers (method)
• target-headers (method)
• target-parameters (method)
• target-parameters (method)
• target-method (method)
• target-method (method)
• target-url (method)
• target-url (method)
• http-headers (method)
• http-headers (method)
• http-body (method)
• http-body (method)
• http-status (method)
• http-status (method)

Direct slots

Slot: %http-status

Initargs

:status

Readers

http-status (generic function)

Writers

(setf http-status) (generic function)

Slot: %http-body

Initargs

:body

Readers

http-body (generic function)

Writers

(setf http-body) (generic function)

Slot: %http-headers

Initargs

:headers

Readers

http-headers (generic function)

Writers

(setf http-headers) (generic function)

Slot: %target-url

Initargs

:url

Readers

target-url (generic function)

Writers

(setf target-url) (generic function)

Slot: %target-method

Initargs

:method

Readers

target-method (generic function)

Writers

(setf target-method) (generic function)

Slot: %target-parameters

Initargs

:parameters

Readers

target-parameters (generic function)

Writers

(setf target-parameters) (generic function)

Slot: %target-headers

Initargs

:sent-headers

Readers

target-headers (generic function)

Writers

(setf target-headers) (generic function)

5.2 Internal definitions

5.2.1 Constants

Constant: +unix-epoch-difference+

The universal to unix time difference in seconds.

Package

south

Source

toolkit.lisp (file)

5.2.2 Functions

Function: authorization-format-parameter S PARAM &rest REST

Package

south

Source

oauth.lisp (file)

Function: create-authorization-header METHOD REQUEST-URL OAUTH-PARAMETERS PARAMETERS

Package

south

Source

oauth.lisp (file)

Function: create-authorization-header-value PARAMETERS

Turns the OAuth parameters into the correct header value.

Package

south

Source

oauth.lisp (file)

Function: create-signature METHOD URL PARAMETERS

Create an OAuth signature for a request.
This requires at least the *oauth-api-secret* to be bound properly, and usually the *oauth-access-secret* as well.

According to spec https://dev.twitter.com/docs/auth/creating-signature

Package

south

Source

oauth.lisp (file)

Function: get-unix-time ()

Return the unix timestamp for GMT, as required by OAuth.

Package

south

Source

toolkit.lisp (file)

Function: hmac STRING KEYSTRING

Returns a base-64 encoded string of the HMAC digest of the given STRING using the KEYSTRING as HMAC key. The encoding of *external-format* is used throughout.

Package

south

Source

toolkit.lisp (file)

Function: make-signed METHOD URL OAUTH-PARAMETERS &optional OTHER-PARAMETERS

Returns the signed version of the oauth-parameters.
Simply generates a signature and appends the proper parameter.

Package

south

Source

oauth.lisp (file)

Function: oauth-response->alist BODY &optional SPEC

Turn an oauth-response into an ALIST.

Package

south

Source

oauth.lisp (file)

Function: parse-boolean VALUE

Parses a string boolean. If the string is one of (T, true, 1), then T is returned, otherwise NIL. The check is case-insensitive.

Package

south

Source

toolkit.lisp (file)

Function: prepare-data-parameters PARAMETERS

Package

south

Source

oauth.lisp (file)

Function: request-wrapper URI &rest DRAKMA-PARAMS

Package

south

Source

oauth.lisp (file)

Function: signature-format-parameter S PARAM &rest REST

Package

south

Source

oauth.lisp (file)

Function: to-keyword STRING

Turns a key into a keyword.
Replaces _ with - and uppercases the string, then interns it into the keyword package. This is useful to parse the request responses into an alist.

Package

south

Source

toolkit.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types