(sagittarius pam) - Privileged Access Module

This library provides a wrapper layer of, Linux PAM, Open PAM, Windows LogonUser and BSD Auth.

This example shows how to authenticate a user.

(import (rnrs)
        (sagittarius pam)
        (sagittarius stty))

(define (prompts-handler prompts)
  (define (prompt-handler prompt)
    (display (cdr prompt)) (flush-output-port (current-output-port))
    (if (eq? (car prompt) 'echo-off)
        (with-stty '((not echo) echonl) 
         (lambda () (get-line (current-input-port))))
        (get-line (current-input-port))))
  (vector-map prompt-handler prompts))

(cond ((pam-authenticate "login" "username" prompts-handler) =>
       (lambda (token)
         ;; do whatever with the token
         (pam-invalidate-token! token)))
      (else 
        ;; handle authentication error
       ))

CAVEAT

This module interacts with platform specific authentication mechanis. It doesn't change the required configuration. Below are known limitation per platform.

Linux PAM / Open PAM

Authenticating the logged on user may not invoke prompt, but simply return the authenticate token, depending on the PAM (Pluggable Authentication Module) configuration.

Also, authenticating other users on behalf may require root / sudo permission.

Windows

The service argument is used only if UPN format is used for username, i.e. username@domain. And the value is passed to LogonUser as domain argument. Otherwise, the domain argument is extracted from the passwd name, which is constructed domain\name format.

BSD Auth

BSD Auth requires access to /usr/libexec/auth directory to execute authentication. The directory is usually not accessible other than root. So, to run the authentication, the process must be executed by root permission.

Provising platform user authentication mechanism.

Returns #t if the given obj is passwd object, otherwise #f.

The passwd object represents struct passwd in C.

Retrieves information of user, if the user doesn't exists, then returns #f.

Returns associated user name of the pw.

Returns associated full user name of the pw.

Returns associated home directory of the pw.

Returns associated shell of the pw.

Return #t if the given obj is auth token, otherwise #f.

Return passwd object associated to this auth token.

Invokes the underlying platform authentication mechanism.

For Linux / Open PAM, the service argument must be one of the names configured under /etc/pam.d directory. e.g. login or passwd.

For BSD Auth, the service argument must be one of the names configured in /etc/login.conf. e.g. passwd.

For Windows, the service argument must be domain or empty string when the user is UPN format. For local machine login, this argument can be ".".

The user argument is the username or passwd to authenticate.
If the user is string, and the user is not found, then the procedure returns #f without trying to do authentication.

The conversation argument must accept one argument, a vector and must return a vector of string, the size of the vector must be the size of the input vector.

The argument of conversation procedure contains a pair of prompt. A prompt format is below

(type . message)

type is a symbol of one of the followings

echo-off

Show the message and recieve user input without echoing, then return the value

echo-on

Show the message and recieve user input, then return the value

error

Show the message on error output

text

Show the message

If the authentication succeeds, then the procedure returns auth token, otherwise #f.

Invalidates the given token.

Error handler when conversation argument of the pam-authenticate raises an error. The result of the handler procedure will be ignored, this is only for diagnosis purpose.

A error handler must be a procedure which accepts exactly one argument, which is the raised condition.