linux pam开发手册

The Linux-PAM Application

Developers' Guide

Andrew G. Morgan <morgan@kernel.org>

Thorsten Kukuk <kukuk@thkukuk.de>

The Linux-PAM Application Developers' Guide

by Andrew G. Morgan and Thorsten Kukuk

Version 1.1.2, 31. August 2010

Abstract

This manual documents what an application developer needs to know about the Linux-PAM library. It describes how an

1.2. Synopsis .............................................................................................................. 1

2. Overview ....................................................................................................................... 2

3. The public interface to Linux-PAM ..................................................................................... 4

3.1. What can be expected by the application ................................................................... 4

3.1.1. Initialization of PAM transaction ................................................................... 4

3.1.2. Termination of PAM transaction ................................................................... 5

3.1.3. Setting PAM items ..................................................................................... 5

3.1.4. Getting PAM items ..................................................................................... 7

3.1.5. Strings describing PAM error codes ............................................................... 9

3.1.6. Request a delay on failure ............................................................................ 9

3.1.13. Set or change PAM environment variable .................................................... 14

3.1.14. Get a PAM environment variable ............................................................... 15

3.1.15. Getting the PAM environment ................................................................... 15

3.2. What is expected of an application ......................................................................... 16

3.2.1. The conversation function .......................................................................... 16

3.3. Programming notes .............................................................................................. 18

4. Security issues of Linux-PAM .......................................................................................... 19

4.1. Care about standard library calls ............................................................................ 19

4.2. Choice of a service name ...................................................................................... 19

4.3. The conversation function ..................................................................................... 20

5.1.3. Liberating a locally saved environment ......................................................... 22

5.1.4. BSD like PAM environment variable setting .................................................. 23

6. Porting legacy applications .............................................................................................. 24

7. Glossary of PAM related terms ........................................................................................ 25

8. An example application .................................................................................................. 26

9. Files ............................................................................................................................ 28

10. See also ...................................................................................................................... 29

11. Author/acknowledgments ............................................................................................... 30

12. Copyright information for this document .......................................................................... 31

Chapter 1. Introduction

1.1. Description

ment. This library dynamically loads locally configured authentication modules that actually perform the

authentication tasks.

From the perspective of an application developer the information contained in the local configuration of

the PAM library should not be important. Indeed it is intended that an application treat the functions docu-

mented here as a 'black box' that will deal with all aspects of user authentication. 'All aspects' includes user

verification, account management, session initialization/termination and also the resetting of passwords

(authentication tokens).

1.2. Synopsis

For general applications that wish to use the services provided by Linux-PAM the following is a summary

of the relevant linking information:

#include <security/pam_appl.h>

#include <security/pam_misc.h>

cc -o application .... -lpam -lpam_misc

Chapter 2. Overview

Most service-giving applications are restricted. In other words, their service is not available to all and

every prospective client. Instead, the applying client must jump through a number of hoops to convince

the serving application that they are authorized to obtain service.

The process of authenticating a client is what PAM is designed to manage. In addition to authentication,

PAM provides account management, credential management, session management and authentication-to-

ken (password changing) management services. It is important to realize when writing a PAM based ap-

this too. (This latter case might be via some hardware interface for example.)

It is important to note that the application must leave all decisions about when to prompt the user at the

discretion of the PAM library.

The PAM library, however, must work equally well for different styles of application. Some applications,

like the familiar login and passwd are terminal based applications, exchanges of information with the client

in these cases is as plain text messages. Graphically based applications, however, have a more sophisticated

interface. They generally interact with the user via specially constructed dialogue boxes. Additionally,

network based services require that text messages exchanged with the client are specially formatted for

automated processing: one such example is ftpd which prefixes each exchanged message with a numeric

identifier.

from the user for processing by the PAM library. The details of this function are provided in a later section.

For example, the conversation function may be called by the PAM library with a request to prompt the

user for a password. Its job is to reformat the prompt request into a form that the client will understand.

In the case of ftpd, this might involve prefixing the string with the number 331 and sending the request

over the network to a connected client. The conversation function will then obtain any reply and, after

extracting the typed password, will return this string of text to the PAM library. Similar concerns need to

be addressed in the case of an X-based graphical server.

There are a number of issues that need to be addressed when one is porting an existing application to

become PAM compliant. A section below has been devoted to this: Porting legacy applications.

Besides authentication, PAM provides other forms of management. Session management is provided with