Common Lisp Package: CL-OPENID

README:

FUNCTION

Public

AUTH-REQUEST-REALM (AUTH-REQUEST-MESSAGE)

Returns the realm of the OpenID authentication request AUTH-REQUEST-MESSAGE.

CANCEL-RESPONSE-URI (OP AUTH-REQUEST-MESSAGE)

Returns the URI of the Relying Party to redirect the user's browser to. The URI parameters tell the Relying Party that the authentication failed. AUTH-REQUEST-MESSAGE should be the oritinal OpenID authentication request message that was received from the Relying Party previously and passed to the HANDLE-CHECKID-SETUP.

CLAIMED-ID (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

COPY-MESSAGE (MESSAGE &REST PARAMETERS)

Create a copy of MESSAGE, updating PARAMETERS provided as keyword parameters. If MESSAGE already includes provided key, new value is used in the result; if a key is new, the field will be appended to result message. PARAMETERS are interpreted as by MAKE-MESSAGE function.

HANDLE-INDIRECT-RESPONSE (RP MESSAGE REQUEST-URI &OPTIONAL AUTHPROC)

Handle indirect response MESSAGE for RP, coming at REQUEST-URI, concerning AUTHPROC. AUTHPROC can be a literal AUTH-PROCESS object, or a string (unique authproc handle, sent earlier by RP). When AUTHPROC is NIL or not supplied, its handle is taken from MESSAGE. Returns claimed ID URI on success, NIL on failure. As second value, always returns AUTH-PROCESS object.

HANDLE-OPENID-PROVIDER-REQUEST (OP MESSAGE &KEY ALLOW-UNENCRYPTED-ASSOCIATION-P &AUX (V1-COMPAT (NOT (MESSAGE-V2-P MESSAGE))))

Handle request MESSAGE for OpenID Provider instance OP. ALLOW-UNENCRYPTED-ASSOCIATION-P specifies whether it is allowable to use unencrypted association method. Set it to NIL unless your OP endopoint uses HTTPS. See OpenID Authentication 2.0 - Final, section 8.4.1. No-Encryption Association Sessions (http://openid.net/specs/openid-authentication-2_0.html#assoc_sess_types). Returns two values: the first is body, and the second is an HTTP status code. On HTTP redirections (the second value between 300 and 399 inclusive), the primary returned value will be an URI to redirect the user to.

IMMEDIATE-P (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

INITIATE-AUTHENTICATION (RP GIVEN-ID &KEY IMMEDIATE-P EXTRA-PARAMETERS &AUX (AUTHPROC (DISCOVER GIVEN-ID)) (HANDLE (NEW-AUTHPROC-HANDLE)))

Initiate authentication process by relying party RP for identifier GIVEN-ID received from user. If IMMEDIATE-P is true, initiates immediate authentication process. The EXTRA-PARAMETERS is an optional key-value list to be added to the authentication request message. The list format is the same as for the MAKE-MESSAGE function. This parameter is needed for OpenID extensions, for example OAuth or Attribute Exchange. Returns multiple values: - the URI to redirect the user's browser to; - Unique handle (string) identifying the started authentication process; - the AUTH-PROCESS structure identified by the handle. The latter two values are useful if the client code needs to track the process.

MAKE-MESSAGE (&REST PARAMETERS)

Make new message from arbitrary keyword parameters. Keyword specifies a message field key (actual key is lowercased symbol name), and value following the keyword specifies associated value. Value can be a string (which will be literal field value), symbol (symbol's name will be used as a value), vector of (UNSIGNED-BYTE 8) (which will be Base64-encoded), URI object or integer (which both will be PRINC-TO-STRING-ed). If value is NIL, field won't be included in the message at all.

MESSAGE-FIELD (MESSAGE FIELD-NAME)

get value of FIELD-NAME field from MESSAGE.

MESSAGE-V2-P (MESSAGE)

True if MESSAGE is an OpenID v2 message (namespace check).

OP-LOCAL-ID (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

PROTOCOL-VERSION (AUTH-PROCESS)

Protocol version of an authentication process, as a cons (MAJOR . MINOR).

PROTOCOL-VERSION-MAJOR (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

PROTOCOL-VERSION-MINOR (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

PROVIDER-ENDPOINT-URI (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

RETURN-TO (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

SUCCESSFUL-RESPONSE-URI (OP AUTH-REQUEST-MESSAGE)

Returns the URI of the Relying Party to redirect the user's browser to. The URI parameters tell the Relying Party that the authentication was successful. AUTH-REQUEST-MESSAGE should be the oritinal OpenID authentication request message that was received from the Relying Party previously and passed to the HANDLE-CHECKID-SETUP.

TIMESTAMP (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

XRDS-LOCATION (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

Undocumented

AUTH-PROCESS-P (OBJECT)

SETFCLAIMED-ID (NEW-VALUE INSTANCE)

SETFIMMEDIATE-P (NEW-VALUE INSTANCE)

SETFOP-LOCAL-ID (NEW-VALUE INSTANCE)

SETFPROTOCOL-VERSION (NEW-VALUE AUTH-PROCESS)

SETFPROTOCOL-VERSION-MAJOR (NEW-VALUE INSTANCE)

SETFPROTOCOL-VERSION-MINOR (NEW-VALUE INSTANCE)

SETFPROVIDER-ENDPOINT-URI (NEW-VALUE INSTANCE)

SETFRETURN-TO (NEW-VALUE INSTANCE)

SETFTIMESTAMP (NEW-VALUE INSTANCE)

SETFXRDS-LOCATION (NEW-VALUE INSTANCE)

Private

AGET (KEY ALIST)

Get a CDR of an (ASSOC KEY ALIST). Sequence (e.g. string) keys are searched with :TEST #'EQUAL.

ALIST-TO-URL-ENCODED-STRING (ALIST EXTERNAL-FORMAT)

ALIST is supposed to be an alist of name/value pairs where both names and values are strings (or, for values, NIL). This function returns a string where this list is represented as for the content type `application/x-www-form-urlencoded', i.e. the values are URL-encoded using the external format EXTERNAL-FORMAT, the pairs are joined with a #\& character, and each name is separated from its value with a #\= character. If the value is NIL, no #\= is used.

ASSOCIATION-EXPIRES (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

ASSOCIATION-HANDLE (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

ASSOCIATION-HMAC-DIGEST (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

ASSOCIATION-MAC (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

BASE64-BTWOC (I)

Return two's complement binary string representing integer I, as Base64-encoded string.

BTWOC (I &AUX (OCTETS (INTEGER-TO-OCTETS I)))

Return two's complement binary string representing integer I, as an octet vector.

CHECK-REALM (REALM URI)

Check URI against REALM.

DH-ENCRYPT/DECRYPT-KEY (DIGEST GENERATOR PRIME PUBLIC PRIVATE KEY)

Perform Diffie-Hellman key exchange.

DIRECT-ERROR-RESPONSE (ERR &KEY CONTACT REFERENCE MESSAGE)

Return error direct response (key-value-encoded error message as body, 400 Error code as second value).

DIRECT-REQUEST (URI MESSAGE)

Send a direct request to URI, sending MESSAGE alist.

DIRECT-RESPONSE (MESSAGE)

Return direct response (key-value-encoded MESSAGE as body, no second value).

DISCOVER (ID &AUX (AUTHPROC (ETYPECASE ID (AUTH-PROCESS ID) (STRING (MAKE-AUTH-PROCESS ID)))) (REQUEST-URI (OR (XRDS-LOCATION AUTHPROC) (CLAIMED-ID AUTHPROC))) (*TEXT-CONTENT-TYPES* (APPEND '((application . xhtml+xml) (application . xrds+xml)) *TEXT-CONTENT-TYPES*)))

Perform discovery on ID. ID may be either an already initialized AUTH-PROCESS structure, or user-given ID string. Signals an OPENID-DISCOVERY-ERROR if the discovery was unsuccessful, i.e. when the discovery URI specified by ID does not contain the needed OpenID discovery information. May also signal other errors, in case of network problems, or if the URI is not available, etc.

ENCODE-KV (MESSAGE)

Encode MESSAGE alist as key-value form octet vector

ENSURE-INTEGER (VAL)

For VAL being an integer, a Base64-encoded string representing integer, or an octet vector representing integer, return its integer value.

ENSURE-TRAILING-SLASH (PATH)

Add trailing slash to PATH if it's not already there.

ENSURE-VECTOR (VAL)

For VAL being an integer, a Base64-encoded string representing integer, or an octet vector representing integer, return it as an octet vector.

ENSURE-VECTOR-LENGTH (VEC LEN)

Shorten or enlarge vector VEC so that it has length LEN. If (= (LENGTH VEC) LEN), returns VEC. Otherwise, either pads with zeroes on the left, or removes a number of leftmost elements.

GC-ASSOCIATIONS (SERVER &OPTIONAL INVALIDATE-HANDLE &AUX (TIME (GET-UNIVERSAL-TIME)))

Garbage-collect timed out associations from SERVER. INVALIDATE-HANDLE is a handle of association that needs to be collected regardless of validity. SERVER may be a RELYING-PARTY or OPENID-PROVIDER instance.

GC-AUTHPROCS (RP &AUX (TIME-LIMIT (- (GET-UNIVERSAL-TIME) (AUTHPROC-TIMEOUT RP))))

Collect old auth-process objects from relying party RP.

INDIRECT-MESSAGE-URI (ENDPOINT MESSAGE &AUX (URI (NEW-URI ENDPOINT)))

Return URI to send indirect message MESSAGE to endpoint URI ENDPOINT. Usable for both indirect requests and responses.

INDIRECT-RESPONSE (RETURN-TO MESSAGE)

Return indirect response (URI as body +INDIRECT-RESPONSE-CODE+ as the second value).

MAKE-ASSOCIATION (&KEY (HANDLE (NEW-ASSOCIATION-HANDLE)) (EXPIRES-IN *DEFAULT-ASSOCIATION-TIMEOUT*) (EXPIRES-AT (+ (GET-UNIVERSAL-TIME) EXPIRES-IN)) ASSOCIATION-TYPE (HMAC-DIGEST (OR (AGET ASSOCIATION-TYPE '((HMAC-SHA1 . SHA1) (HMAC-SHA256 . SHA256))) (OPENID-ASSOCIATION-ERROR Unknown association type ~A. ASSOCIATION-TYPE))) (MAC (NUMBER 115792089237316195423570985008687907853269984665640564039457584007913129639936)))

Make new association structure, DWIM included. - HANDLE should be the new association handle; if none is provided, new one is generated. - EXPIRES-IN is the timeout of the handle; alternatively, EXPIRES-AT is the universal-time when association times out. - ASSOCIATION-TYPE is the OpenID association type (string); alternatively, HMAC-DIGEST is an Ironclad digest name (a keyword) used for signature HMAC checks. - MAC is the literal, unencrypted MAC key.

MAKE-AUTH-PROCESS (GIVEN-ID)

Initialize new AUTH-PROCESS structure from a user-given identifier GIVEN-ID (string). An XRDS location for Yadis discovery discovered by a HEAD request may be included in returned structure.

MAYBE-URI (U)

Return (URI U), unless U is NIL.

MESSAGE-FIELD-STRING (VALUE)

Format VALUE as a string for protocol message.

N-REMOVE-ENTITIES (STR &OPTIONAL (ENTITIES +ENTITIES+))

Remove HTML entities from STR, destructively.

NEW-ASSOCIATION-HANDLE

Return new unique association handle as string

NEW-AUTHPROC-HANDLE

Return new unique authentication handle as string

NEW-URI (U)

Return U as new URI object. If U is already an URI object, return a copy; otherwise, return (URI U).

NULL (OBJECT)

Return true if OBJECT is a NULL, and NIL otherwise.

PARSE-KV (ARRAY)

Parse key-value form message passed as an octet vector into parameter alist.

REMOVE-DOT-SEGMENTS (PARSED-PATH)

Remove . and .. from parsed URI path, to correctly identify same paths and prevent URI traversal attacks.

REQUEST-AUTHENTICATION-URI (AUTHPROC &KEY REALM IMMEDIATE-P ASSOCIATION EXTRA-PARAMETERS)

URI for an authentication request for AUTHPROC

SETUP-NEEDED-RESPONSE (OP MESSAGE)

Send setup_needed (immediate authentication failure) response to MESSAGE from OP.

SIGNAL-INDIRECT-ERROR (MESSAGE REASON &REST ARGS)

Signal INDIRECT-ERROR condition for MESSAGE, effectively returning indirect error reply from WITH-INDIRECT-ERROR-HANDLER. REASON is textual error message format string, with ARGS being its arguments.

SIGNATURE (ASSOCIATION MESSAGE &OPTIONAL SIGNED)

Calculate signature from MESSAGE using ASSOCIATION, return signature string. Optional SIGNED parameter is a list of fields to sign, as strings, with "openid" prefix stripped.

SIGNED (ASSOCIATION MESSAGE &OPTIONAL SIGNED)

Sign MESSAGE, using ASSOCIATION, return signed message. Optional SIGNED parameter is a list of fields to sign, as strings, with "openid" prefix stripped.

USER-SETUP-URL (OP MESSAGE)

Returns the value to be passed in the openid.user_setup_url parameter of a response to a failed immediate authentication request. OP is the OpenID Provider. MESSAGE is the original authentication request. In case the MESSAGE is a request of OpenID version 2, returns NIL.

Undocumented

%MAKE-ASSOCIATION (&KEY ((EXPIRES DUM0) NIL) ((HANDLE DUM1) NIL) ((MAC DUM2) NIL) ((HMAC-DIGEST DUM3) NIL))

%MAKE-AUTH-PROCESS (&KEY ((PROTOCOL-VERSION-MAJOR DUM0) 2) ((PROTOCOL-VERSION-MINOR DUM1) 0) ((CLAIMED-ID DUM2) NIL) ((OP-LOCAL-ID DUM3) NIL) ((IMMEDIATE-P DUM4) NIL) ((RETURN-TO DUM5) NIL) ((XRDS-LOCATION DUM6) NIL) ((PROVIDER-ENDPOINT-URI DUM7) NIL) ((TIMESTAMP DUM8) NIL))

AP-ASSOCIATION (RP AUTHPROC)

ASSOCIATE (ENDPOINT &KEY V1 ASSOC-TYPE SESSION-TYPE &AUX XA)

ASSOCIATION (RP ENDPOINT &OPTIONAL V1)

ASSOCIATION-BY-HANDLE (RP HANDLE)

SETFASSOCIATION-EXPIRES (NEW-VALUE INSTANCE)

SETFASSOCIATION-HANDLE (NEW-VALUE INSTANCE)

SETFASSOCIATION-HMAC-DIGEST (NEW-VALUE INSTANCE)

SETFASSOCIATION-MAC (NEW-VALUE INSTANCE)

ASSOCIATION-P (OBJECT)

AUTHPROC-BY-HANDLE (RP HANDLE)

CHECK-DISCOVERY-POSTCONDITION (AUTHPROC)

CHECK-SIGNATURE (ASSOCIATION MESSAGE)

COPY-ASSOCIATION (INSTANCE)

COPY-AUTH-PROCESS (INSTANCE)

ERROR-RESPONSE-MESSAGE (ERR &KEY CONTACT REFERENCE MESSAGE)

GC-NONCES (RP &AUX (TIME-LIMIT (- (GET-UNIVERSAL-TIME) (NONCE-TIMEOUT RP))))

NONCE

NONCE-UNIVERSAL-TIME (NONCE)

OPENID-ASSOCIATION-ERROR (FORMAT-CONTROL &REST FORMAT-ARGUMENTS)

OPENID-DISCOVERY-ERROR (FORMAT-CONTROL &REST FORMAT-ARGUMENTS)

PERFORM-HTML-DISCOVERY (AUTHPROC BODY &AUX EP OPLOC EP.1 OPLOC.1 XRDS)

PERFORM-XRDS-DISCOVERY (AUTHPROC BODY &AUX (PARSED (PARSE BODY)) PRIO ENDPOINT OPLOCAL V1PRIO V1ENDPOINT V1OPLOCAL V1TYPE)

SESSION-DIGEST-TYPE (SESSION-TYPE)

SETUP-NEEDED-RESPONSE-MESSAGE (OP MESSAGE)

SUCCESSFUL-RESPONSE-MESSAGE (OP MESSAGE)

MACRO

Public

IN-NS (MESSAGE &OPTIONAL (NAMESPACE '+OPENID2-NAMESPACE+))

Add openid.namespace NAMESPACE to MESSAGE.

Private

DEFINE-CONSTANT (NAME VALUE &REST OPTIONS)

Do a DEFCONSTANT, but do not attempt to redefine if already bound.

STRING-CASE (KEYFORM &BODY CLAUSES)

Like CASE, but for a string KEYFORM.

WITH-INDIRECT-ERROR-HANDLER (&BODY BODY)

Handle INDIRECT-ERROR in BODY. When INDIRECT-ERROR is signaled, immediately return indirect error response.

GENERIC-FUNCTION

Public

HANDLE-CHECKID-IMMEDIATE (OP MESSAGE)

Handles checkid_immediate requests. This generic should be specialized on concrete Provider classes to perform immediate login checks on MESSAGE. It should return at once, either true value (to indicate successful login), or NIL (to indicate immediate login failure).

HANDLE-CHECKID-SETUP (OP MESSAGE)

Handles checkid_setup requests. This generic should be specialized on concrete Provider classes to perform login checks with user dialogue, that would (possibly after some HTTP request-response cycles) end by redirecting the user's browser either to SUCCESSFUL-RESPONSE-URI, or to CANCEL-RESPONSE-URI. This generic is called by HANDLE-OPENID-PROVIDER-REQUEST, and the values returned by this function are then returned by HANDLE-OPENID-PROVIDER-REQUEST. I.e. it must return two values: response "body" and HTTP status code. That way HANDLE-CHECKID-SETUP can either redirect user's browser somewhere, or just show him something. (With hunchentoot, HUNCHNTOOT:REDIRECT may also be used, which is a non-local transfer control). Default method just returns (VALUES (CANSEL-RESPONSE-URI ...) +INDIRECT-RESPONSE-CODE+).

Undocumented

AUTHPROC (CONDITION)

CODE (CONDITION)

MESSAGE (CONDITION)

REASON (CONDITION)

Private

Undocumented

RETURN-TO-URI (CONDITION)

SLOT-ACCESSOR

Public

ENDPOINT-URI (OBJECT)

Provider endpoint URI

SETFENDPOINT-URI (NEW-VALUE OBJECT)

Provider endpoint URI

REALM (OBJECT)

Relying Party realm.

SETFREALM (NEW-VALUE OBJECT)

Relying Party realm.

ROOT-URI (OBJECT)

Root URI address of the Relying Party instance. Used to generate return_to redirections.

SETFROOT-URI (NEW-VALUE OBJECT)

Root URI address of the Relying Party instance. Used to generate return_to redirections.

Private

ASSOCIATIONS (OBJECT)

OP's associations.

SETFASSOCIATIONS (NEW-VALUE OBJECT)

OP's associations.

AUTHPROC-TIMEOUT (OBJECT)

Number of seconds after which an AUTH-PROCESS is considered timed out and is deleted from AUTHPROCS.

SETFAUTHPROC-TIMEOUT (NEW-VALUE OBJECT)

Number of seconds after which an AUTH-PROCESS is considered timed out and is deleted from AUTHPROCS.

AUTHPROCS (OBJECT)

Authenticaction processes currently handled by RP.

SETFAUTHPROCS (NEW-VALUE OBJECT)

Authenticaction processes currently handled by RP.

NONCE-TIMEOUT (OBJECT)

Number of seconds after which nonce is considered timed out.

SETFNONCE-TIMEOUT (NEW-VALUE OBJECT)

Number of seconds after which nonce is considered timed out.

NONCES (OBJECT)

A list of openid.nonce response parameters to avoid duplicates.

SETFNONCES (NEW-VALUE OBJECT)

A list of openid.nonce response parameters to avoid duplicates.

Undocumented

ASSOCIATIONS-LOCK (OBJECT)

SETFASSOCIATIONS-LOCK (NEW-VALUE OBJECT)

AUTHPROCS-LOCK (OBJECT)

SETFAUTHPROCS-LOCK (NEW-VALUE OBJECT)

NONCES-LOCK (OBJECT)

SETFNONCES-LOCK (NEW-VALUE OBJECT)

VARIABLE

Private

*ASSOCIATION-HANDLE-COUNTER*

Counter for unique association handle generation

*AUTH-HANDLE-COUNTER*

Counter for unique association handle generation

*DEFAULT-ASSOCIATION-TIMEOUT*

Default association timeout, in seconds

*NONCE-COUNTER*

Counter for nonce generation

CLASS

Public

AUTH-PROCESS

Data structure gathering information about an ongoing authentication process.

OPENID-PROVIDER

OpenID Provider server abstract class. This class should be subclassed, and specialized methods should be provided at least for HANDLE-CHECKID-SETUP (preferably also for HANDLE-CHECKID-IMMEDIATE).

RELYING-PARTY

Relying Party server class.

Private

ASSOCIATION (RP ENDPOINT &OPTIONAL V1)

An association between OP and RP.

Undocumented

NULL (OBJECT)

CONDITION

Public

OPENID-ASSERTION-ERROR

Error signaled by RP when indirect response cannot be verified correctly.

Private

INDIRECT-ERROR

Error occured during OpenID chekid_setup or checkid_immediate handling. This condition is handled by HANDLE-OPENID-PROVIDER-REQUEST and, if it occurs, indirect error response is directed to user.

Undocumented

OPENID-ASSOCIATION-ERROR (FORMAT-CONTROL &REST FORMAT-ARGUMENTS)

OPENID-DISCOVERY-ERROR (FORMAT-CONTROL &REST FORMAT-ARGUMENTS)

OPENID-REQUEST-ERROR

CONSTANT

Public

+AUTHPROC-HANDLE-PARAMETER+

Name of HTTP GET parameter, sent in return_to URI, which contains AUTH-PROCESS object unique handle.

+INDIRECT-RESPONSE-CODE+

HTTP code recommented to use for indirect responses sent via HTTP redirect.

Private

+DH-GENERATOR+

Default generator value for Diffie-Hellman key exchange.

+DH-PRIME+

This is a confirmed-prime number, used as the default modulus for Diffie-Hellman Key Exchange.

+ENTITIES+

Alist of HTML entities to be unquoted.

+OPENID2-NAMESPACE+

Namespace URI for OpenID 2.0 messages.

+OPENID2-NS-CONS+

Helper constant pair for constructing messages.

+PROTOCOL-VERSIONS+

OpenID protocol versions for XRDS service type URIs

Undocumented

+CANCEL-RESPONSE-MESSAGE+

+SETUP-NEEDED-RESPONSE-MESSAGE+