This module provides a Python-style interface to PAM’s C API; all functionality is exposed through the handle class and its instances.
Due to the Python GC, there is no need to explicitly close handles – simply allow the GC to reclaim them, or use the del statement to immediately clean up. For this reason, there is no direct analog to pam_end(3).
Represents a PAM handle.
Parameters: |
|
---|---|
Raises: |
|
All of the parameters have reasonable defaults – for authenticating the user running the program interactively.
Other uses will require either supplying values in the constructor call or populating the instance attributes afterwards.
Authenticates the user associated with this handle.
Parameters: |
|
---|
>>> from draxoft.auth import pam
>>> import random
>>> h = pam.handle()
>>> h.user = ''.join(random.sample('abcdefghijklmnopqrstuvwxyz', 7))
>>> h.user
fbvqrpo
>>> h.conv = lambda style,msg,data: 'password'
>>> h.authenticate()
Traceback (most recent call last):
...
pam.PamError: [Errno 13] unknown user
>>> try:
... h.authenticate()
... except pam.PamError, e:
... e.errno == pam.PAM_USER_UNKNOWN
True
Signature : | callback(style, message, data) |
---|
Conversation callback. Provides a conversation callback for retrieving user IDs and authentication tokens.
The style parameter specifies the prompt style, which implies the type of data being collected or displayed – PAM_PROMPT_ECHO_OFF for passwords, PAM_PROMPT_ECHO_ON for user names, PAM_ERROR_MSG for error messages, and PAM_TEXT_INFO for informational messages. The message parameter is the text to be displayed, if applicable, and data is the data attribute.
Defaults to _conv_callback().
Opaque data passed into callback functions.
Display a prompt and accept the user’s response without echoing it to the terminal. This is commonly used for passwords.
Display a prompt and accept the user’s response, echoing it to the terminal. This is commonly used for user names and one-time passphrases.
Display an error message.
Display an informational message.
Verifies and enforces account restrictions after the user has been authenticated.
Establish the credentials of the target user.
Revoke all established credentials.
Fully reinitialize credentials.
Refresh credentials.
Sets up a user session for a previously authenticated user.
Tears down a previously-established user session.
Mapping from environment variable names to values, both strings.
Warning
Direct references to this object are unsafe! Do not assign it to a variable or in any other way store its value without a copy operation.
The implementation of this object is closely linked with that of the parent handle in a way that creates circular references. As a result, no reference is stored for the parent object – which means a reference to an environment attribute could well access reclaimed memory when used or garbage collected, potentially causing a crash.
This should be considered a bug and will be fixed “Real Soon Now.”
If the 'unsetenv' extension is provided, variables may be removed using the del operator.
>>> h = pam.handle()
>>> h.environment['answer'] = 42 # the input can be a Python object...
>>> h.environment['answer'] # ...but the output will be a string.
'42'
>>> if 'unsetenv' in pam.extensions:
... del h.environment['answer']
... 'answer' not in h.environment
... else:
... 'answer' in h.environment
...
True
The environment attribute may contain sensitive information, particularly after a call to authenticate(). By default, this information will be removed. If this module is being run effective-user-ID 0, this attribute can be set to True to prevent this scrubbing.
>>> h = pam.handle()
>>> h.elevated
False
>>> h.elevated = True
Traceback (most recent call last):
...
OSError: [Errno 13] Permission denied
Only supported/defined if 'fail_delay' in extensions.
Warning
The fail delay API is experimental and poorly tested.
Due to development environment, there is little occasion to test the Linux-PAM-specific features. Any bug reports or further testing will be welcomed.
See also
Provides a mechanism by which an application can suggest a minimum delay of usec microseconds.
The handle records the longest time requested; should authenticate() fail, the return to the application is delayed by an amount of time randomly distributed (by up to 25%) about this longest value.
Signature : | callback(rc, usec, data) |
---|
This callback allows an application to control the mechanism by which the PAM fail delay is implemented.
For some applications, a blocking delay between failure and return may be unacceptable. Single-threaded server applications, for example, might prefer to block just the client’s queued requests instead of the server itself.
The rc argument is the last return code; usec is the requested delay (in microseconds) and data is the opaque data.
The default is None, in which case fail delay (if any) is entirely controlled by the fail_delay() method.
Base class: EnvironmentError
Wrapper class for errors occurring in the PAM library. Nearly every handle method or property may raise these in event of an internal error.
Describes the error “in plain English” suitable for display.
One of the error codes listed below. Unfortunately, this value is an integer and therefore may carry little meaning for the recipient.
Error | Description |
---|---|
|
General failure. |
|
User account has expired. |
|
Authentication information is unavailable. |
|
Authentication token aging disabled. |
|
Authentication token failure. |
|
Password has expired. |
|
Authentication token lock busy. |
|
Failed to recover old authentication token. |
|
Authentication error. |
|
Memory buffer error. |
|
Conversation error. |
|
Failed to set user credentials. |
|
User credentials have expired. |
|
Insufficient credentials. |
|
Failed to retrieve user credentials. |
|
Unknown authentication domain. |
|
Ignore this module. |
|
Maximum number of tries exceeded. |
|
Unknown module type. |
|
New authentication token required. |
|
Module data not found. |
|
Failed to load module. |
|
Permission denied. |
|
Error in service module. |
|
Session failure. |
|
Success. |
|
Invalid symbol. |
|
System error. |
|
Try again. |
|
Unknown user. |
Specifies the PAM implementation, if known.
Platform | Implementation |
---|---|
AIX 4.3 (patched) | 'Linux-PAM' |
AIX 5.1 (ML01+) | '?' |
AIX 5.2+ | '?' |
Darwin (Mac OS X) | 'OpenPAM' |
DragonflyBSD | 'OpenPAM' |
FreeBSD | 'OpenPAM' |
HP-UX | '?' |
Linux | 'Linux-PAM' (some distros support 'OpenPAM') |
NetBSD | 'OpenPAM' |
PC-BSD | 'OpenPAM' |
Solaris | 'OpenPAM' |
Set of strings describing the API extensions supported by this module. Potential extensions include:
- 'fail_delay'
- This module supports the PAM fail delay API. Currently only provided by Linux-PAM implementations.
- 'unsetenv'
- Environment variables can be deleted in this implementation. Currently only supported by OpenPAM.