The glass Reference Manual

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

The glass Reference Manual

This is the glass Reference Manual, version 1.0.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:42:03 2022 GMT+0.

Table of Contents


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.


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

2.1 glass

General Lisp Authentication and Security System API.

Author

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

License

MIT

Version

1.0.2

Source

glass.asd.

Child Components

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   [Contents][Index]

3.1.1 glass/glass.asd

Source

glass.asd.

Parent Component

glass (system).

ASDF Systems

glass.


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

3.1.2 glass/glass.lisp

Source

glass.asd.

Parent Component

glass (system).

Packages

glass.

Public Interface

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

3.1.3 glass/errors.lisp

Dependency

glass.lisp (file).

Source

glass.asd.

Parent Component

glass (system).

Public Interface

gss-error (condition).

Internals

4 Packages

Packages are listed by definition order.


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

4.1 glass

Source

glass.lisp.

Nickname

gss

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


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.

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.

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.

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.

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.

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.

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.

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.


5.1.2 Conditions

Condition: gss-error
Package

glass.

Source

errors.lisp.

Direct superclasses

error.

Direct methods
Direct slots
Slot: major
Initform

(quote nil)

Initargs

:major

Readers

gss-error-major.

Writers

This slot is read-only.

Slot: minor
Initform

(quote nil)

Initargs

:minor

Readers

gss-error-minor.

Writers

This slot is read-only.


5.2 Internals


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

5.2.1 Special variables

Special Variable: *gss-status-codes*
Package

glass.

Source

errors.lisp.


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

5.2.2 Generic functions

Generic Reader: gss-error-major (condition)
Package

glass.

Methods
Reader Method: gss-error-major ((condition gss-error))
Source

errors.lisp.

Target Slot

major.

Generic Reader: gss-error-minor (condition)
Package

glass.

Methods
Reader Method: gss-error-minor ((condition gss-error))
Source

errors.lisp.

Target Slot

minor.


Appendix A Indexes


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

A.1 Concepts