4 The PamHandle Class
An instance of this class is automatically created
for a Python PAM module when it is first referenced,
(ie when it is execfile
'ed).
It is the first argument to every Python method called by PAM.
It is destroyed automatically when pam_end(3) is called,
right after the execfile
'ed module is destroyed.
If any method fails, or any access to a member fails
a PamHandle.exception exception will be thrown.
It contains the following members:
- PAM_???
-
All the PAM_??? constants
defined in the PAM include files are available.
They are all read-only int's.
- authtok
-
The PAM_AUTHTOK PAM item.
Reading this results in a call pam_get_item(PAM_AUTHTOK),
writing it results in a call pam_set_item(PAM_AUTHTOK, value).
Its value will be either a string
or None for the C value NULL.
- env
-
This is a mapping representing the PAM environment.
pam_python implements accesses and changes to it
via the PAM methods pam_getenv(), pam_putenv()
and pam_getenvlist().
The PAM environment only supports string keys and values,
and the keys may not be blank or contain '='.
- exception
-
The exception raised by methods defined here if they fail.
It is a subclass of StandardError.
Instances contain the member pam_result,
which is the error code returned by PAM.
The description is the PAM error message.
- libpam_version
-
The version of PAM pam_python was compiled with.
This is a string.
In version 0.1.0 of pam_python and prior
this was an int holding the version of PAM library loaded.
Newer versions of PAM no longer export that value.
- pamh
-
The PAM handle, as read-only int.
Possibly useful during debugging.
- oldauthtok
-
The PAM_OLDAUTHTOK PAM item.
Reading this results in a call pam_get_item(PAM_OLDAUTHTOK),
writing it results in a call pam_set_item(PAM_OLDAUTHTOK, value).
Its value will be either a string
or None for the C value NULL.
- rhost
-
The PAM_RHOST PAM item.
Reading this results in a call pam_get_item(PAM_RHOST),
writing it results in a call pam_set_item(PAM_RHOST, value).
Its value will be either a string
or None for the C value NULL.
- ruser
-
The PAM_RUSER PAM item.
Reading this results in a call pam_get_item(PAM_RUSER),
writing it results in a call pam_set_item(PAM_RUSER, value).
Its value will be either a string
or None for the C value NULL.
- service
-
The PAM_SERVICE PAM item.
Reading this results in a call pam_get_item(PAM_SERVICE),
writing it results in a call pam_set_item(PAM_SERVICE, value).
Its value will be either a string
or None for the C value NULL.
- tty
-
The PAM_TTY PAM item.
Reading this results in a call pam_get_item(PAM_TTY),
writing it results in a call pam_set_item(PAM_TTY, value).
Its value will be either a string
or None for the C value NULL.
- user
-
The PAM_USER PAM item.
Reading this results in a call pam_get_item(PAM_USER),
writing it results in a call pam_set_item(PAM_USER, value).
Its value will be either a string
or None for the C value NULL.
- user_prompt
-
The PAM_USER_PROMPT PAM item.
Reading this results in a call pam_get_item(PAM_USER_PROMPT),
writing it results in a call pam_set_item(PAM_USER_PROMPT, value).
Its value will be either a string
or None for the C value NULL.
The following methods are available:
-
Creates an instance of the PamMessage class.
Instances of this class can be passed to the conversation() method.
They are the equivalent of the C API's
struct pam_message
type,
and have the same members.
The arguments become the instance members of the same name.
Instances are immutable.
-
Creates an instance of the PamResponse class.
Instances of this class are returned by the conversation() method.
They are the equivalent of the C API's
struct pam_response
type,
and have the same members.
The arguments become the instance members of the same name.
Instances are immutable.
-
Calls the function defined by the PAM_CONV item.
The prompts argument is a Message object
or a list them.
You don't have to pass an actual Message object,
any class that defines a string member msg
and a int member msg_style will do.
These members are used to initialise the
struct pam_message
members of the same name.
It returns either a single Response object if a single
Message was passed,
or a list of them of the same length as the list passed.
These Response objects contain the data the user entered.
-
This results in a call to pam_fail_delay(),
which sets the maximum random delay after an authentication failure
to delay milliseconds.
-
This results in a call to pam_get_user(),
which returns the current user name (a string)
or None if pam_get_user() return NULL.
If not known it asks the PAM application for the user name,
giving it the string prompt parameter
to prompt the user to enter it.
-
This results in a call to pam_strerror(),
which returns a string description
of the int PAM reurn value errnum.
There is no interface provided for PAM's
pam_get_data() and pam_set_data() methods.
There are two reasons for this.
Firstly those two methods are provided so C code can have private storage
local to the PAM handle.
A Python PAM Module can use own module name space to do the same job,
and its easier to do so.
But more importantly its safer because there is no type-safe way
of providing access to the facility from Python.