pam

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 22, 2023 License: BSD-2-Clause Imports: 6 Imported by: 34

README

GoDoc Go Report Card

Go PAM

This is a Go wrapper for the PAM application API.

Testing

To run the full suite, the tests must be run as the root user. To setup your system for testing, create a user named "test" with the password "secret". For example:

$ sudo useradd test \
    -d /tmp/test \
    -p '$1$Qd8H95T5$RYSZQeoFbEB.gS19zS99A0' \
    -s /bin/false

Then execute the tests:

$ sudo GOPATH=$GOPATH $(which go) test -v

Documentation

Overview

Package pam provides a wrapper for the PAM application API.

Example

This example uses the default PAM service to authenticate any users. This should cause PAM to ask its conversation handler for a username and password in sequence.

package main

import (
	"bufio"
	"errors"
	"fmt"
	"os"

	"github.com/msteinert/pam"
	"golang.org/x/term"
)

func main() {
	t, err := pam.StartFunc("", "", func(s pam.Style, msg string) (string, error) {
		switch s {
		case pam.PromptEchoOff:
			fmt.Print(msg)
			pw, err := term.ReadPassword(int(os.Stdin.Fd()))
			if err != nil {
				return "", err
			}
			fmt.Println()
			return string(pw), nil
		case pam.PromptEchoOn:
			fmt.Print(msg)
			s := bufio.NewScanner(os.Stdin)
			s.Scan()
			return s.Text(), nil
		case pam.ErrorMsg:
			fmt.Fprintf(os.Stderr, "%s\n", msg)
			return "", nil
		case pam.TextInfo:
			fmt.Println(msg)
			return "", nil
		default:
			return "", errors.New("unrecognized message style")
		}
	})
	if err != nil {
		fmt.Fprintf(os.Stderr, "start: %s\n", err.Error())
		os.Exit(1)
	}
	err = t.Authenticate(0)
	if err != nil {
		fmt.Fprintf(os.Stderr, "authenticate: %s\n", err.Error())
		os.Exit(1)
	}
	fmt.Println("authentication succeeded!")
}
Output:

Index

Examples

Constants

View Source
const (
	// PromptEchoOff indicates the conversation handler should obtain a
	// string without echoing any text.
	PromptEchoOff Style = C.PAM_PROMPT_ECHO_OFF
	// PromptEchoOn indicates the conversation handler should obtain a
	// string while echoing text.
	PromptEchoOn = C.PAM_PROMPT_ECHO_ON
	// ErrorMsg indicates the conversation handler should display an
	// error message.
	ErrorMsg = C.PAM_ERROR_MSG
	// TextInfo indicates the conversation handler should display some
	// text.
	TextInfo = C.PAM_TEXT_INFO
	// BinaryPrompt indicates the conversation handler that should implement
	// the private binary protocol
	BinaryPrompt = C.PAM_BINARY_PROMPT
)

Coversation handler style types.

View Source
const (
	// Service is the name which identifies the PAM stack.
	Service Item = C.PAM_SERVICE
	// User identifies the username identity used by a service.
	User = C.PAM_USER
	// Tty is the terminal name.
	Tty = C.PAM_TTY
	// Rhost is the requesting host name.
	Rhost = C.PAM_RHOST
	// Authtok is the currently active authentication token.
	Authtok = C.PAM_AUTHTOK
	// Oldauthtok is the old authentication token.
	Oldauthtok = C.PAM_OLDAUTHTOK
	// Ruser is the requesting user name.
	Ruser = C.PAM_RUSER
	// UserPrompt is the string use to prompt for a username.
	UserPrompt = C.PAM_USER_PROMPT
)

PAM Item types.

View Source
const (
	// Silent indicates that no messages should be emitted.
	Silent Flags = C.PAM_SILENT
	// DisallowNullAuthtok indicates that authorization should fail
	// if the user does not have a registered authentication token.
	DisallowNullAuthtok = C.PAM_DISALLOW_NULL_AUTHTOK
	// EstablishCred indicates that credentials should be established
	// for the user.
	EstablishCred = C.PAM_ESTABLISH_CRED
	// DeleteCred inidicates that credentials should be deleted.
	DeleteCred = C.PAM_DELETE_CRED
	// ReinitializeCred indicates that credentials should be fully
	// reinitialized.
	ReinitializeCred = C.PAM_REINITIALIZE_CRED
	// RefreshCred indicates that the lifetime of existing credentials
	// should be extended.
	RefreshCred = C.PAM_REFRESH_CRED
	// ChangeExpiredAuthtok indicates that the authentication token
	// should be changed if it has expired.
	ChangeExpiredAuthtok = C.PAM_CHANGE_EXPIRED_AUTHTOK
)

PAM Flag types.

Variables

This section is empty.

Functions

func CheckPamHasBinaryProtocol added in v1.2.0

func CheckPamHasBinaryProtocol() bool

CheckPamHasBinaryProtocol return if pam on system supports PAM_BINARY_PROMPT

func CheckPamHasStartConfdir added in v1.1.0

func CheckPamHasStartConfdir() bool

CheckPamHasStartConfdir return if pam on system supports pam_system_confdir

Types

type BinaryConversationHandler added in v1.2.0

type BinaryConversationHandler interface {
	ConversationHandler
	// RespondPAMBinary receives a pointer to the binary message. It's up to
	// the receiver to parse it according to the protocol specifications.
	// The function can return a byte array that will passed as pointer back
	// to the module.
	RespondPAMBinary(BinaryPointer) ([]byte, error)
}

BinaryConversationHandler is an interface for objects that can be used as conversation callbacks during PAM authentication if binary protocol is going to be supported.

type BinaryPointer added in v1.2.0

type BinaryPointer unsafe.Pointer

BinaryPointer exposes the type used for the data in a binary conversation it represents a pointer to data that is produced by the module and that must be parsed depending on the protocol in use

type ConversationFunc

type ConversationFunc func(Style, string) (string, error)

ConversationFunc is an adapter to allow the use of ordinary functions as conversation callbacks.

func (ConversationFunc) RespondPAM

func (f ConversationFunc) RespondPAM(s Style, msg string) (string, error)

RespondPAM is a conversation callback adapter.

type ConversationHandler

type ConversationHandler interface {
	// RespondPAM receives a message style and a message string. If the
	// message Style is PromptEchoOff or PromptEchoOn then the function
	// should return a response string.
	RespondPAM(Style, string) (string, error)
}

ConversationHandler is an interface for objects that can be used as conversation callbacks during PAM authentication.

type Flags

type Flags int

Flags are inputs to various PAM functions than be combined with a bitwise or. Refer to the official PAM documentation for which flags are accepted by which functions.

type Item

type Item int

Item is a an PAM information type.

type Style

type Style int

Style is the type of message that the conversation handler should display.

type Transaction

type Transaction struct {
	// contains filtered or unexported fields
}

Transaction is the application's handle for a PAM transaction.

func Start

func Start(service, user string, handler ConversationHandler) (*Transaction, error)

Start initiates a new PAM transaction. Service is treated identically to how pam_start treats it internally.

All application calls to PAM begin with Start*. The returned transaction provides an interface to the remainder of the API.

func StartConfDir added in v1.1.0

func StartConfDir(service, user string, handler ConversationHandler, confDir string) (*Transaction, error)

StartConfDir initiates a new PAM transaction. Service is treated identically to how pam_start treats it internally. confdir allows to define where all pam services are defined. This is used to provide custom paths for tests.

All application calls to PAM begin with Start*. The returned transaction provides an interface to the remainder of the API.

func StartFunc

func StartFunc(service, user string, handler func(Style, string) (string, error)) (*Transaction, error)

StartFunc registers the handler func as a conversation handler.

func (*Transaction) AcctMgmt

func (t *Transaction) AcctMgmt(f Flags) error

AcctMgmt is used to determine if the user's account is valid.

Valid flags: Silent, DisallowNullAuthtok

func (*Transaction) Authenticate

func (t *Transaction) Authenticate(f Flags) error

Authenticate is used to authenticate the user.

Valid flags: Silent, DisallowNullAuthtok

func (*Transaction) ChangeAuthTok

func (t *Transaction) ChangeAuthTok(f Flags) error

ChangeAuthTok is used to change the authentication token.

Valid flags: Silent, ChangeExpiredAuthtok

func (*Transaction) CloseSession

func (t *Transaction) CloseSession(f Flags) error

CloseSession closes a previously opened session.

Valid flags: Silent

func (*Transaction) Error

func (t *Transaction) Error() string

func (*Transaction) GetEnv

func (t *Transaction) GetEnv(name string) string

GetEnv is used to retrieve a PAM environment variable.

func (*Transaction) GetEnvList

func (t *Transaction) GetEnvList() (map[string]string, error)

GetEnvList returns a copy of the PAM environment as a map.

func (*Transaction) GetItem

func (t *Transaction) GetItem(i Item) (string, error)

GetItem retrieves a PAM information item.

func (*Transaction) OpenSession

func (t *Transaction) OpenSession(f Flags) error

OpenSession sets up a user session for an authenticated user.

Valid flags: Slient

func (*Transaction) PutEnv

func (t *Transaction) PutEnv(nameval string) error

PutEnv adds or changes the value of PAM environment variables.

NAME=value will set a variable to a value. NAME= will set a variable to an empty value. NAME (without an "=") will delete a variable.

func (*Transaction) SetCred

func (t *Transaction) SetCred(f Flags) error

SetCred is used to establish, maintain and delete the credentials of a user.

Valid flags: EstablishCred, DeleteCred, ReinitializeCred, RefreshCred

func (*Transaction) SetItem

func (t *Transaction) SetItem(i Item, item string) error

SetItem sets a PAM information item.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL