"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/mwg/Linux-PAM_MWG.txt" between
Linux-PAM-1.3.1-docs.tar.xz and Linux-PAM-1.4.0-docs.tar.xz

About: Linux-PAM is the Pluggable Authentication Modules for Linux. Documentation.

Linux-PAM_MWG.txt  (Linux-PAM-1.3.1-docs.tar.xz)	:	Linux-PAM_MWG.txt  (Linux-PAM-1.4.0-docs.tar.xz)
skipping to change at line 257		skipping to change at line 257
item);		item);
pam_handle_t *pamh;		pam_handle_t *pamh;
int item_type;		int item_type;
const void *item;		const void *item;
2.1.3.1. DESCRIPTION		2.1.3.1. DESCRIPTION
The pam_set_item function allows applications and PAM service modules to access		The pam_set_item function allows applications and PAM service modules to access
and to update PAM informations of item_type. For this a copy of the object		and to update PAM information of item_type. For this a copy of the object
pointed to by the item argument is created. The following item_types are		pointed to by the item argument is created. The following item_types are
supported:		supported:
PAM_SERVICE		PAM_SERVICE
The service name (which identifies that PAM stack that the PAM functions		The service name (which identifies that PAM stack that the PAM functions
will use to authenticate the program).		will use to authenticate the program).
PAM_USER		PAM_USER
skipping to change at line 360		skipping to change at line 360
requesting passwords: "New UNIX password: " and "Retype UNIX password: ".		requesting passwords: "New UNIX password: " and "Retype UNIX password: ".
The example word UNIX can be replaced with this item, by default it is		The example word UNIX can be replaced with this item, by default it is
empty. This item is used by pam_get_authtok(3).		empty. This item is used by pam_get_authtok(3).
For all item_types, other than PAM_CONV and PAM_FAIL_DELAY, item is a pointer		For all item_types, other than PAM_CONV and PAM_FAIL_DELAY, item is a pointer
to a <NUL> terminated character string. In the case of PAM_CONV, item points to		to a <NUL> terminated character string. In the case of PAM_CONV, item points to
an initialized pam_conv structure. In the case of PAM_FAIL_DELAY, item is a		an initialized pam_conv structure. In the case of PAM_FAIL_DELAY, item is a
function pointer: void (*delay_fn)(int retval, unsigned usec_delay, void		function pointer: void (*delay_fn)(int retval, unsigned usec_delay, void
*appdata_ptr)		*appdata_ptr)
Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reseted before returning to the		Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reset before returning to the
application. Which means an application is not able to access the		application. Which means an application is not able to access the
authentication tokens.		authentication tokens.
2.1.3.2. RETURN VALUES		2.1.3.2. RETURN VALUES
PAM_BAD_ITEM		PAM_BAD_ITEM
The application attempted to set an undefined or inaccessible item.		The application attempted to set an undefined or inaccessible item.
PAM_BUF_ERR		PAM_BUF_ERR
skipping to change at line 398		skipping to change at line 398
item);		item);
const pam_handle_t *pamh;		const pam_handle_t *pamh;
int item_type;		int item_type;
const void **item;		const void **item;
2.1.4.1. DESCRIPTION		2.1.4.1. DESCRIPTION
The pam_get_item function allows applications and PAM service modules to access		The pam_get_item function allows applications and PAM service modules to access
and retrieve PAM informations of item_type. Upon successful return, item		and retrieve PAM information of item_type. Upon successful return, item
contains a pointer to the value of the corresponding item. Note, this is a		contains a pointer to the value of the corresponding item. Note, this is a
pointer to the actual data and should not be free()'ed or over-written! The		pointer to the actual data and should not be free()'ed or over-written! The
following values are supported for item_type:		following values are supported for item_type:
PAM_SERVICE		PAM_SERVICE
The service name (which identifies that PAM stack that the PAM functions		The service name (which identifies that PAM stack that the PAM functions
will use to authenticate the program).		will use to authenticate the program).
PAM_USER		PAM_USER
skipping to change at line 573		skipping to change at line 573
PAM_SYSTEM_ERR		PAM_SYSTEM_ERR
A NULL pointer was submitted.		A NULL pointer was submitted.
PAM_CONV_ERR		PAM_CONV_ERR
The conversation method supplied by the application failed to obtain the		The conversation method supplied by the application failed to obtain the
username.		username.
		PAM_BUF_ERR
		Memory buffer error.
		PAM_ABORT
		Error resuming an old conversation.
		PAM_CONV_AGAIN
		The conversation method supplied by the application is waiting for an
		event.
2.1.6. The conversation function		2.1.6. The conversation function
#include <security/pam_appl.h>		#include <security/pam_appl.h>
struct pam_message {		struct pam_message {
int msg_style;		int msg_style;
const char *msg;		const char *msg;
};		};
struct pam_response {		struct pam_response {
skipping to change at line 645		skipping to change at line 658
PAM_TEXT_INFO		PAM_TEXT_INFO
Display some text.		Display some text.
The point of having an array of messages is that it becomes possible to pass a		The point of having an array of messages is that it becomes possible to pass a
number of things to the application in a single call from the module. It can		number of things to the application in a single call from the module. It can
also be convenient for the application that related things come at once: a		also be convenient for the application that related things come at once: a
windows based application can then present a single form with many messages/		windows based application can then present a single form with many messages/
prompts on at once.		prompts on at once.
In passing, it is worth noting that there is a descrepency between the way		In passing, it is worth noting that there is a discrepancy between the way
Linux-PAM handles the const struct pam_message **msg conversation function		Linux-PAM handles the const struct pam_message **msg conversation function
argument from the way that Solaris' PAM (and derivitives, known to include HP/		argument and the way that Solaris' PAM (and derivatives, known to include HP/
UX, are there others?) does. Linux-PAM interprets the msg argument as entirely		UX, are there others?) does. Linux-PAM interprets the msg argument as entirely
equivalent to the following prototype const struct pam_message *msg[] (which,		equivalent to the following prototype const struct pam_message *msg[] (which,
in spirit, is consistent with the commonly used prototypes for argv argument to		in spirit, is consistent with the commonly used prototypes for argv argument to
the familiar main() function: char **argv; and char *argv[]). Said another way		the familiar main() function: char **argv; and char *argv[]). Said another way
Linux-PAM interprets the msg argument as a pointer to an array of num_msg read		Linux-PAM interprets the msg argument as a pointer to an array of num_msg read
only 'struct pam_message' pointers. Solaris' PAM implementation interprets this		only 'struct pam_message' pointers. Solaris' PAM implementation interprets this
argument as a pointer to a pointer to an array of num_msg pam_message		argument as a pointer to a pointer to an array of num_msg pam_message
structures. Fortunately, perhaps, for most module/application developers when		structures. Fortunately, perhaps, for most module/application developers when
num_msg has a value of one these two definitions are entirely equivalent.		num_msg has a value of one these two definitions are entirely equivalent.
Unfortunately, casually raising this number to two has led to unanticipated		Unfortunately, casually raising this number to two has led to unanticipated
skipping to change at line 721		skipping to change at line 734
This function sets the variable to an empty value. It is listed separately		This function sets the variable to an empty value. It is listed separately
to indicate that this is the correct way to achieve such a setting.		to indicate that this is the correct way to achieve such a setting.
NAME		NAME
Without an '=' the pam_putenv() function will delete the corresponding		Without an '=' the pam_putenv() function will delete the corresponding
variable from the PAM environment.		variable from the PAM environment.
pam_putenv() operates on a copy of name_value, which means in contrast to		pam_putenv() operates on a copy of name_value, which means in contrast to
putenv(3), the application is responsible to free the data.		putenv(3), the application is responsible for freeing the data.
2.1.7.2. RETURN VALUES		2.1.7.2. RETURN VALUES
PAM_PERM_DENIED		PAM_PERM_DENIED
Argument name_value given is a NULL pointer.		Argument name_value given is a NULL pointer.
PAM_BAD_ITEM		PAM_BAD_ITEM
Variable requested (for deletion) is not currently set.		Variable requested (for deletion) is not currently set.
skipping to change at line 860		skipping to change at line 873
....		....
#endif /* HAVE_PAM_FAIL_DELAY */		#endif /* HAVE_PAM_FAIL_DELAY */
For applications written with a single thread that are event driven in nature,		For applications written with a single thread that are event driven in nature,
generating this delay may be undesirable. Instead, the application may want to		generating this delay may be undesirable. Instead, the application may want to
register the delay in some other way. For example, in a single threaded server		register the delay in some other way. For example, in a single threaded server
that serves multiple authentication requests from a single event loop, the		that serves multiple authentication requests from a single event loop, the
application might want to simply mark a given connection as blocked until an		application might want to simply mark a given connection as blocked until an
application timer expires. For this reason the delay function can be changed		application timer expires. For this reason the delay function can be changed
with the PAM_FAIL_DELAY item. It can be queried and set with pam_get_item(3)		with the PAM_FAIL_DELAY item. It can be queried and set with pam_get_item(3)
and pam_set_item (3) respectively. The value used to set it should be a		and pam_set_item(3) respectively. The value used to set it should be a function
function pointer of the following prototype:		pointer of the following prototype:
void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);		void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);
The arguments being the retval return code of the module stack, the usec_delay		The arguments being the retval return code of the module stack, the usec_delay
micro-second delay that libpam is requesting and the appdata_ptr that the		micro-second delay that libpam is requesting and the appdata_ptr that the
application has associated with the current pamh. This last value was set by		application has associated with the current pamh. This last value was set by
the application when it called pam_start(3) or explicitly with pam_set_item(3).		the application when it called pam_start(3) or explicitly with pam_set_item(3).
Note, if PAM_FAIL_DELAY item is unset (or set to NULL), then no delay will be
performed.		Note that the PAM_FAIL_DELAY item is set to NULL by default. This indicates
		that PAM should perform a random delay as described above when authentication
		fails and a delay has been suggested. If an application does not want the PAM
		library to perform any delay on authentication failure, then the application
		must define a custom delay function that executes no statements and set the
		PAM_FAIL_DELAY item to point to this function.
2.2.2.2. RETURN VALUES		2.2.2.2. RETURN VALUES
PAM_SUCCESS		PAM_SUCCESS
Delay was successful adjusted.		Delay was successful adjusted.
PAM_SYSTEM_ERR		PAM_SYSTEM_ERR
A NULL pointer was submitted as PAM handle.		A NULL pointer was submitted as PAM handle.
skipping to change at line 940		skipping to change at line 958
module---that is, with the service_name matching that of the application---in		module---that is, with the service_name matching that of the application---in
the configuration file (see the Linux-PAM System Administrators' Guide).		the configuration file (see the Linux-PAM System Administrators' Guide).
Together these two parameters provide the number of arguments and an array of		Together these two parameters provide the number of arguments and an array of
pointers to the individual argument tokens. This will be familiar to C		pointers to the individual argument tokens. This will be familiar to C
programmers as the ubiquitous method of passing command arguments to the		programmers as the ubiquitous method of passing command arguments to the
function main(). Note, however, that the first argument (argv[0]) is a true		function main(). Note, however, that the first argument (argv[0]) is a true
argument and not the name of the module.		argument and not the name of the module.
3.2. Authentication management		3.2. Authentication management
To be correctly initialized, PAM_SM_AUTH must be #define'd prior to including
<security/pam_modules.h>. This will ensure that the prototypes for static
modules are properly declared.
3.2.1. Service function for user authentication		3.2.1. Service function for user authentication
#define PAM_SM_AUTH
#include <security/pam_modules.h>		#include <security/pam_modules.h>
int pam_sm_authenticate( pamh,		int pam_sm_authenticate( pamh,
flags,		flags,
argc,		argc,
argv);		argv);
pam_handle_t *pamh;		pam_handle_t *pamh;
int flags;		int flags;
int argc;		int argc;
skipping to change at line 1011		skipping to change at line 1023
The supplied username is not known to the authentication service.		The supplied username is not known to the authentication service.
PAM_MAXTRIES		PAM_MAXTRIES
One or more of the authentication modules has reached its limit of tries		One or more of the authentication modules has reached its limit of tries
authenticating the user. Do not try again.		authenticating the user. Do not try again.
3.2.2. Service function to alter credentials		3.2.2. Service function to alter credentials
#define PAM_SM_AUTH
#include <security/pam_modules.h>		#include <security/pam_modules.h>
int pam_sm_setcred( pamh,		int pam_sm_setcred( pamh,
flags,		flags,
argc,		argc,
argv);		argv);
pam_handle_t *pamh;		pam_handle_t *pamh;
int flags;		int flags;
int argc;		int argc;
skipping to change at line 1096		skipping to change at line 1106
PAM_USER_UNKNOWN		PAM_USER_UNKNOWN
The user is not known to this authentication module.		The user is not known to this authentication module.
These, non-PAM_SUCCESS, return values will typically lead to the credential		These, non-PAM_SUCCESS, return values will typically lead to the credential
stack failing. The first such error will dominate in the return value of		stack failing. The first such error will dominate in the return value of
pam_setcred().		pam_setcred().
3.3. Account management		3.3. Account management
To be correctly initialized, PAM_SM_ACCOUNT must be #define'd prior to
including <security/pam_modules.h>. This will ensure that the prototypes for
static modules are properly declared.
3.3.1. Service function for account management		3.3.1. Service function for account management
#define PAM_SM_ACCOUNT
#include <security/pam_modules.h>		#include <security/pam_modules.h>
int pam_sm_acct_mgmt( pamh,		int pam_sm_acct_mgmt( pamh,
flags,		flags,
argc,		argc,
argv);		argv);
pam_handle_t *pamh;		pam_handle_t *pamh;
int flags;		int flags;
int argc;		int argc;
skipping to change at line 1170		skipping to change at line 1174
PAM_SUCCESS		PAM_SUCCESS
The authentication token was successfully updated.		The authentication token was successfully updated.
PAM_USER_UNKNOWN		PAM_USER_UNKNOWN
User unknown to password service.		User unknown to password service.
3.4. Session management		3.4. Session management
To be correctly initialized, PAM_SM_SESSION must be #define'd prior to
including <security/pam_modules.h>. This will ensure that the prototypes for
static modules are properly declared.
3.4.1. Service function to start session management		3.4.1. Service function to start session management
#define PAM_SM_SESSION
#include <security/pam_modules.h>		#include <security/pam_modules.h>
int pam_sm_open_session( pamh,		int pam_sm_open_session( pamh,
flags,		flags,
argc,		argc,
argv);		argv);
pam_handle_t *pamh;		pam_handle_t *pamh;
int flags;		int flags;
int argc;		int argc;
skipping to change at line 1215		skipping to change at line 1213
PAM_SESSION_ERR		PAM_SESSION_ERR
Cannot make/remove an entry for the specified session.		Cannot make/remove an entry for the specified session.
PAM_SUCCESS		PAM_SUCCESS
The session was successfully started.		The session was successfully started.
3.4.2. Service function to terminate session management		3.4.2. Service function to terminate session management
#define PAM_SM_SESSION
#include <security/pam_modules.h>		#include <security/pam_modules.h>
int pam_sm_close_session( pamh,		int pam_sm_close_session( pamh,
flags,		flags,
argc,		argc,
argv);		argv);
pam_handle_t *pamh;		pam_handle_t *pamh;
int flags;		int flags;
int argc;		int argc;
skipping to change at line 1254		skipping to change at line 1250
PAM_SESSION_ERR		PAM_SESSION_ERR
Cannot make/remove an entry for the specified session.		Cannot make/remove an entry for the specified session.
PAM_SUCCESS		PAM_SUCCESS
The session was successfully terminated.		The session was successfully terminated.
3.5. Authentication token management		3.5. Authentication token management
To be correctly initialized, PAM_SM_PASSWORD must be #define'd prior to
including <security/pam_modules.h>. This will ensure that the prototypes for
static modules are properly declared.
3.5.1. Service function to alter authentication token		3.5.1. Service function to alter authentication token
#define PAM_SM_PASSWORD
#include <security/pam_modules.h>		#include <security/pam_modules.h>
int pam_sm_chauthtok( pamh,		int pam_sm_chauthtok( pamh,
flags,		flags,
argc,		argc,
argv);		argv);
pam_handle_t *pamh;		pam_handle_t *pamh;
int flags;		int flags;
int argc;		int argc;
End of changes. 19 change blocks.
38 lines changed or deleted		28 lines changed or added

---