---
name: "pam"
section: "3"
platform: "macos"
package: "OpenPAM"
version: "35"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/pam/3"
---

# pam(3)

Pluggable Authentication Modules Library

## NAME

**pam\_acct\_mgmt**, **pam\_authenticate**, **pam\_chauthtok**, **pam\_close\_session**, **pam\_end**, **pam\_get\_data**, **pam\_get\_item**, **pam\_get\_user**, **pam\_getenv**, **pam\_getenvlist**, **pam\_open\_session**, **pam\_putenv**, **pam\_set\_data**, **pam\_set\_item**, **pam\_setcred**, **pam\_start**, **pam\_strerror** – Pluggable Authentication Modules Library

## LIBRARY

library “libpam”

## SYNOPSIS

**#include \<security/pam\_appl.h\>**

*int*\

**pam\_acct\_mgmt**(*pam\_handle\_t \*pamh*, *int flags*);

*int*\

**pam\_authenticate**(*pam\_handle\_t \*pamh*, *int flags*);

*int*\

**pam\_chauthtok**(*pam\_handle\_t \*pamh*, *int flags*);

*int*\

**pam\_close\_session**(*pam\_handle\_t \*pamh*, *int flags*);

*int*\

**pam\_end**(*pam\_handle\_t \*pamh*, *int status*);

*int*\

**pam\_get\_data**(*const pam\_handle\_t \*pamh*, *const char \*module\_data\_name*, *const void \*\*data*);

*int*\

**pam\_get\_item**(*const pam\_handle\_t \*pamh*, *int item\_type*, *const void \*\*item*);

*int*\

**pam\_get\_user**(*pam\_handle\_t \*pamh*, *const char \*\*user*, *const char \*prompt*);

*const char \**\

**pam\_getenv**(*pam\_handle\_t \*pamh*, *const char \*name*);

*char \*\**\

**pam\_getenvlist**(*pam\_handle\_t \*pamh*);

*int*\

**pam\_open\_session**(*pam\_handle\_t \*pamh*, *int flags*);

*int*\

**pam\_putenv**(*pam\_handle\_t \*pamh*, *const char \*namevalue*);

*int*\

**pam\_set\_data**(*pam\_handle\_t \*pamh*, *const char \*module\_data\_name*, *void \*data*, *void (\*cleanup)(pam\_handle\_t \*pamh, void \*data, int pam\_end\_status)*);

*int*\

**pam\_set\_item**(*pam\_handle\_t \*pamh*, *int item\_type*, *const void \*item*);

*int*\

**pam\_setcred**(*pam\_handle\_t \*pamh*, *int flags*);

*int*\

**pam\_start**(*const char \*service*, *const char \*user*, *const struct pam\_conv \*pam\_conv*, *pam\_handle\_t \*\*pamh*);

*const char \**\

**pam\_strerror**(*const pam\_handle\_t \*pamh*, *int error\_number*);

## DESCRIPTION

The Pluggable Authentication Modules (PAM) library abstracts a number of common authentication-related operations and provides a framework for dynamically loaded modules that implement these operations in various ways.

### Terminology

In PAM parlance, the application that uses PAM to authenticate a user is the server, and is identified for configuration purposes by a service name, which is often (but not necessarily) the program name.

The user requesting authentication is called the applicant, while the user (usually, root) charged with verifying his identity and granting him the requested credentials is called the arbitrator.

The sequence of operations the server goes through to authenticate a user and perform whatever task he requested is a PAM transaction; the context within which the server performs the requested task is called a session.

The functionality embodied by PAM is divided into six primitives grouped into four facilities: authentication, account management, session management and password management.

### Conversation

The PAM library expects the application to provide a conversation callback which it can use to communicate with the user. Some modules may use specialized conversation functions to communicate with special hardware such as cryptographic dongles or biometric devices. See [pam\_conv(3)](/pam_conv/3.md) for details.

### Initialization and Cleanup

The **pam\_start**() function initializes the PAM library and returns a handle which must be provided in all subsequent function calls. The transaction state is contained entirely within the structure identified by this handle, so it is possible to conduct multiple transactions in parallel.

The **pam\_end**() function releases all resources associated with the specified context, and can be called at any time to terminate a PAM transaction.

### Storage

The **pam\_set\_item**() and **pam\_get\_item**() functions set and retrieve a number of predefined items, including the service name, the names of the requesting and target users, the conversation function, and prompts.

The **pam\_set\_data**() and **pam\_get\_data**() functions manage named chunks of free-form data, generally used by modules to store state from one invocation to another.

### Authentication

There are two authentication primitives: **pam\_authenticate**() and **pam\_setcred**(). The former authenticates the user, while the latter manages his credentials.

### Account Management

The **pam\_acct\_mgmt**() function enforces policies such as password expiry, account expiry, time-of-day restrictions, and so forth.

### Session Management

The **pam\_open\_session**() and **pam\_close\_session**() functions handle session setup and teardown.

### Password Management

The **pam\_chauthtok**() function allows the server to change the user's password, either at the user's request or because the password has expired.

### Miscellaneous

The **pam\_putenv**(), **pam\_getenv**() and **pam\_getenvlist**() functions manage a private environment list in which modules can set environment variables they want the server to export during the session.

The **pam\_strerror**() function returns a pointer to a string describing the specified PAM error code.

## RETURN VALUES

The following return codes are defined by ⟨security/pam\_constants.h⟩:

- \[PAM\_ABORT\]

  General failure.

- \[PAM\_ACCT\_EXPIRED\]

  User account has expired.

- \[PAM\_APPLE\_ACCT\_TEMP\_LOCK\]

  Account is temporarily locked.

- \[PAM\_APPLE\_ACCT\_LOCKED\]

  Account is locked.

- \[PAM\_AUTHINFO\_UNAVAIL\]

  Authentication information is unavailable.

- \[PAM\_AUTHTOK\_DISABLE\_AGING\]

  Authentication token aging disabled.

- \[PAM\_AUTHTOK\_ERR\]

  Authentication token failure.

- \[PAM\_AUTHTOK\_EXPIRED\]

  Password has expired.

- \[PAM\_AUTHTOK\_LOCK\_BUSY\]

  Authentication token lock busy.

- \[PAM\_AUTHTOK\_RECOVERY\_ERR\]

  Failed to recover old authentication token.

- \[PAM\_AUTH\_ERR\]

  Authentication error.

- \[PAM\_BUF\_ERR\]

  Memory buffer error.

- \[PAM\_CONV\_ERR\]

  Conversation failure.

- \[PAM\_CRED\_ERR\]

  Failed to set user credentials.

- \[PAM\_CRED\_EXPIRED\]

  User credentials have expired.

- \[PAM\_CRED\_INSUFFICIENT\]

  Insufficient credentials.

- \[PAM\_CRED\_UNAVAIL\]

  Failed to retrieve user credentials.

- \[PAM\_DOMAIN\_UNKNOWN\]

  Unknown authentication domain.

- \[PAM\_IGNORE\]

  Ignore this module.

- \[PAM\_MAXTRIES\]

  Maximum number of tries exceeded.

- \[PAM\_MODULE\_UNKNOWN\]

  Unknown module type.

- \[PAM\_NEW\_AUTHTOK\_REQD\]

  New authentication token required.

- \[PAM\_NO\_MODULE\_DATA\]

  Module data not found.

- \[PAM\_OPEN\_ERR\]

  Failed to load module.

- \[PAM\_PERM\_DENIED\]

  Permission denied.

- \[PAM\_SERVICE\_ERR\]

  Error in service module.

- \[PAM\_SESSION\_ERR\]

  Session failure.

- \[PAM\_SUCCESS\]

  Success.

- \[PAM\_SYMBOL\_ERR\]

  Invalid symbol.

- \[PAM\_SYSTEM\_ERR\]

  System error.

- \[PAM\_TRY\_AGAIN\]

  Try again.

- \[PAM\_USER\_UNKNOWN\]

  Unknown user.

## SEE ALSO

[openpam(3)](/openpam/3.md), [pam\_acct\_mgmt(3)](/pam_acct_mgmt/3.md), [pam\_authenticate(3)](/pam_authenticate/3.md), [pam\_chauthtok(3)](/pam_chauthtok/3.md), [pam\_close\_session(3)](/pam_close_session/3.md), [pam\_conv(3)](/pam_conv/3.md), [pam\_end(3)](/pam_end/3.md), [pam\_get\_data(3)](/pam_get_data/3.md), [pam\_getenv(3)](/pam_getenv/3.md), [pam\_getenvlist(3)](/pam_getenvlist/3.md), [pam\_get\_item(3)](/pam_get_item/3.md), [pam\_get\_user(3)](/pam_get_user/3.md), [pam\_open\_session(3)](/pam_open_session/3.md), [pam\_putenv(3)](/pam_putenv/3.md), [pam\_setcred(3)](/pam_setcred/3.md), [pam\_set\_data(3)](/pam_set_data/3.md), [pam\_set\_item(3)](/pam_set_item/3.md), [pam\_start(3)](/pam_start/3.md), [pam\_strerror(3)](/pam_strerror/3.md)

## STANDARDS

*X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules*, June 1997.

## AUTHORS

The OpenPAM library and this manual page were developed for the FreeBSD Project by ThinkSec AS and Network Associates Laboratories, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 (“CBOSS”), as part of the DARPA CHATS research program.