The glass Reference Manual

Table of Contents

The glass Reference Manual

This is the glass Reference Manual, version 1.0.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 18:10:11 2020 GMT+0.

1 Introduction

glass

General Lisp Authentication Security Services (glass) is a Common Lisp GSS-compatible API. It provides a set of generic functions which systems providing authentication services should specialize. Users wishing to consume these services should use these rather than functions exported directly from the providing packages.

The supported authentication systems are Kerberos, NTLM and SPNEGO (Negotiate).

1. Introduction

The GSSAPI specifies a generalized mechanism for defining security service APIs. It is the most common way to consume Kerberos authentication.

2. Usage

This package provides a set of generic functions. Systems which provide security systems should provide methods for these generics.

2.1 Kerberos

Kerberos support is provided by cerberus.

;; client
CL-USER> (cerberus:logon-user "username@realm" "password" :kdc-address "10.1.1.1")
CL-USER> (defvar *credentials* 
                 (gss:acquire-credentials :kerberos 
                                         "host/host.name.com@realm"))
*CREDENTIALS*
CL-USER> (multiple-value-bind (context buffer) (gss:initialize-security-context *context* :mutual t)
           (defvar *client-context* context)
           (defvar *buffer* buffer))

;; send the buffer to the application server
CL-USER> (cerberus:logon-service "host/host.name.com@realm" "password")
CL-USER> (defvar *server-credentials* (gss:acquire-credentials :kerberos nil))
*SERVER-CREDENTIALS*
CL-USER> (multiple-value-bind (context response-buffer) (gss:accept-security-context *server-credentials* *buffer*)
            (defvar *server-context* context)
            (defvar *response-buffer* response-buffer))

;; send the response buffer back to the client and pass to INITIALIZE-SECURITY-CONTEXT so the 
;; client can authenticate the server
CL-USER> (gss:initialize-security-context *client-context* :buffer *response-buffer*)

;; compute checksums
CL-USER> (gss:get-mic *client-context* #(1 2 3 4))
CL-USER> (gss:verify-mic *server-context* (gss:get-mic *client-context* #(1 2 3 4)))

;; encrypt message
CL-USER> (gss:wrap *client-context* #(1 2 3 4))
CL-USER> (gss:unwrap *server-context* (gss:wrap *client-context* #(1 2 3 4)))

2.2 NTLM

NTLM support is provided by ntlm. NTLM is a legacy protocol and is not recommended for use over unsecure networks, nevertheless it is often required for use with various Microsoft tools.

2.3 SPNEGO (Negotiate)

Negotiate support is provided by spnego. This system is essentially a wrapper around NTLM and Kerberos, with an initial negotiation stage to determine a mutually agreeable system.

3. License

Licensed under the terms of the MIT license.

Frank James May 2015.

2 Systems

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

2.1 glass

Author

Frank James <frank.a.james@gmail.com>

License

MIT

Description

General Lisp Authentication and Security System API.

Version

1.0.2

Source

glass.asd (file)

Components

• glass.lisp (file)
• errors.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 glass.asd

Location

glass.asd

Systems

glass (system)

3.1.2 glass/glass.lisp

Parent

glass (system)

Location

glass.lisp

Packages

glass

Exported Definitions

• accept-security-context (generic function)
• acquire-credentials (generic function)
• context-principal-name (generic function)
• get-mic (generic function)
• initialize-security-context (generic function)
• unwrap (generic function)
• verify-mic (generic function)
• wrap (generic function)

3.1.3 glass/errors.lisp

Dependency

glass.lisp (file)

Parent

glass (system)

Location

errors.lisp

Exported Definitions

gss-error (condition)

Internal Definitions

• *gss-status-codes* (special variable)
• gss-error-major (method)
• gss-error-minor (method)

4 Packages

Packages are listed by definition order.

4.1 glass

Source

glass.lisp (file)

Nickname

gss

Use List

common-lisp

Exported Definitions

• accept-security-context (generic function)
• acquire-credentials (generic function)
• context-principal-name (generic function)
• get-mic (generic function)
• gss-error (condition)
• initialize-security-context (generic function)
• unwrap (generic function)
• verify-mic (generic function)
• wrap (generic function)

Internal Definitions

• *gss-status-codes* (special variable)
• gss-error-major (generic function)
• gss-error-major (method)
• gss-error-minor (generic function)
• gss-error-minor (method)

5 Definitions

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

5.1 Exported definitions

5.1.1 Generic functions

Generic Function: accept-security-context CONTEXT-OR-CREDENTIALS BUFFER &key

For the server to accept a security context from the client.

On the first call to this function, CONTEXT-OR-CREDENTIALS should be a credential object as returned from the initial
call to ACQUIRE-CREDENTIALS. Subsequent calls CONTEXT-OR-CREDENTIALS should be the context returned from the previous call
to this function.

BUFFER is the opaque octet vector sent from the client.

Returns (values context response-buffer continue-needed) where CONTEXT is the context to be used in subsequent calls to this function or other glass functions. RESPONSE-BUFFER is either an opaque octet vector to be sent back to the client, or nil if the context has been completed. CONTINUE-NEEDED is a boolean indicating whether further calls to this function are required before authentication has completed.

May signal GSS-ERROR if authentication fails.

Package

glass

Source

glass.lisp (file)

Generic Function: acquire-credentials MECH-TYPE PRINCIPAL &key

Acquire credentials for the principal named. Returns CREDENTIALS, for input into INITIALIZE-SECURITY-CONTEXT and ACCEPT-SECURITY-CONTEXT. c.f. GSS_Acquire_cred.

MECH-TYPE ::= symbol naming the authentication mechamism.

PRINCIPAL ::= the name of the principal you are requesting credentials for. NIL assumes default.

Returns an opaque credential object to be used in subsequent calls.

Package

glass

Source

glass.lisp (file)

Generic Function: context-principal-name CONTEXT &key

Returns a string which represents the name of the principal to which is authenticated by this context. This function should be used by servers wishing to get some information on the identity of the client.

Package

glass

Source

glass.lisp (file)

Generic Function: get-mic CONTEXT MESSAGE &key

Compute a checksum over the message. C.f. GSS_GetMIC.
MESSAGE ::= octet array containing the plaintext.
Returns an octet array.

Package

glass

Source

glass.lisp (file)

Generic Function: initialize-security-context CONTEXT-OR-CREDENTIALS &key

Returns a security context to be sent to the application server. c.f. GSS_Init_sec_context.

On the first call CONTEXT-OR-CREDENTIALS should be the result of the initial call to ACQUIRE-CREDENTIALS.

On subsequent calls, CONTEXT-OR-CREDENTIALS should be the context returned from the previous call to INITIALIZE-SECURITY-CONTEXT.

Returns (values context buffer continue-needed) where context is an opaque object to be used in subsequent calls to this or other functions. Buffer is either an opaque octet-vector, which should be sent to the server, or nil if the context has been completed. Continue needed is
a boolean indicating whether further calls to this function need to made before the authentication is complete.

May signal conditions of type GSS-ERROR.

Package

glass

Source

glass.lisp (file)

Generic Function: unwrap CONTEXT-HANDLE BUFFER &key

Decrypt the message. c.f. GSS_Unwrap

BUFFER ::= the wrapped message, as returned by WRAP.
Returns the decrypted plaintext.

Package

glass

Source

glass.lisp (file)

Generic Function: verify-mic CONTEXT MESSAGE MESSAGE-TOKEN &key

Verify the checksum. c.f. GSS_VerifyMIC

MESSAGE ::= octet array containing the original message that was checksum’ed. MESSAGE-TOKEN ::= the checksum, i.e. result of calling GET-MIC.

Returns T if verified.

Package

glass

Source

glass.lisp (file)

Generic Function: wrap CONTEXT MESSAGE &key

Encrypt the message. c.f. GSS_Wrap
MESSAGE ::= octet array containing the plaintext message
Returns an octet array contining the encrypted message.

Package

glass

Source

glass.lisp (file)

5.1.2 Conditions

Condition: gss-error ()

Package

glass

Source

errors.lisp (file)

Direct superclasses

error (condition)

Direct methods

• gss-error-minor (method)
• gss-error-major (method)

Direct slots

Slot: major

Initargs

:major

Initform

(quote nil)

Readers

gss-error-major (generic function)

Slot: minor

Initargs

:minor

Initform

(quote nil)

Readers

gss-error-minor (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *gss-status-codes*

Package

glass

Source

errors.lisp (file)

5.2.2 Generic functions

Generic Function: gss-error-major CONDITION

Package

glass

Methods

Method: gss-error-major (CONDITION gss-error)

Source

errors.lisp (file)

Generic Function: gss-error-minor CONDITION

Package

glass

Methods

Method: gss-error-minor (CONDITION gss-error)

Source

errors.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types