"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/adg/Linux-PAM_ADG.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_ADG.txt  (Linux-PAM-1.3.1-docs.tar.xz)	:	Linux-PAM_ADG.txt  (Linux-PAM-1.4.0-docs.tar.xz)
skipping to change at line 229		skipping to change at line 229
user,		user,
pam_conversation,		pam_conversation,
pamh);		pamh);
const char *service_name;		const char *service_name;
const char *user;		const char *user;
const struct pam_conv *pam_conversation;		const struct pam_conv *pam_conversation;
pam_handle_t **pamh;		pam_handle_t **pamh;
		int pam_start_confdir( service_name,
		user,
		pam_conversation,
		confdir,
		pamh);
		const char *service_name;
		const char *user;
		const struct pam_conv *pam_conversation;
		const char *confdir;
		pam_handle_t **pamh;
3.1.1.1. DESCRIPTION		3.1.1.1. DESCRIPTION
The pam_start function creates the PAM context and initiates the PAM		The pam_start function creates the PAM context and initiates the PAM
transaction. It is the first of the PAM functions that needs to be called by an		transaction. It is the first of the PAM functions that needs to be called by an
application. The transaction state is contained entirely within the structure		application. The transaction state is contained entirely within the structure
identified by this handle, so it is possible to have multiple transactions in		identified by this handle, so it is possible to have multiple transactions in
parallel. But it is not possible to use the same handle for different		parallel. But it is not possible to use the same handle for different
transactions, a new one is needed for every new context.		transactions, a new one is needed for every new context.
The service_name argument specifies the name of the service to apply and will		The service_name argument specifies the name of the service to apply and will
skipping to change at line 258		skipping to change at line 271
conversation function to use. An application must provide this for direct		conversation function to use. An application must provide this for direct
communication between a loaded module and the application.		communication between a loaded module and the application.
Following a successful return (PAM_SUCCESS) the contents of pamh is a handle		Following a successful return (PAM_SUCCESS) the contents of pamh is a handle
that contains the PAM context for successive calls to the PAM functions. In an		that contains the PAM context for successive calls to the PAM functions. In an
error case is the content of pamh undefined.		error case is the content of pamh undefined.
The pam_handle_t is a blind structure and the application should not attempt to		The pam_handle_t is a blind structure and the application should not attempt to
probe it directly for information. Instead the PAM library provides the		probe it directly for information. Instead the PAM library provides the
functions pam_set_item(3) and pam_get_item(3). The PAM handle cannot be used		functions pam_set_item(3) and pam_get_item(3). The PAM handle cannot be used
for mulitiple authentications at the same time as long as pam_end was not		for multiple authentications at the same time as long as pam_end was not called
called on it before.		on it before.
		The pam_start_confdir function behaves like the pam_start function but it also
		allows setting confdir argument with a path to a directory to override the
		default (/etc/pam.d) path for service policy files. If the confdir is NULL, the
		function works exactly the same as pam_start.
3.1.1.2. RETURN VALUES		3.1.1.2. RETURN VALUES
PAM_ABORT		PAM_ABORT
General failure.		General failure.
PAM_BUF_ERR		PAM_BUF_ERR
Memory buffer error.		Memory buffer error.
PAM_SUCCESS		PAM_SUCCESS
Transaction was successful created.		Transaction was successfully started.
PAM_SYSTEM_ERR		PAM_SYSTEM_ERR
System error, for example a NULL pointer was submitted instead of a pointer		System error, for example a NULL pointer was submitted instead of a pointer
to data.		to data.
3.1.2. Termination of PAM transaction		3.1.2. Termination of PAM transaction
#include <security/pam_appl.h>		#include <security/pam_appl.h>
skipping to change at line 342		skipping to change at line 360
item);		item);
pam_handle_t *pamh;		pam_handle_t *pamh;
int item_type;		int item_type;
const void *item;		const void *item;
3.1.3.1. DESCRIPTION		3.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 445		skipping to change at line 463
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.
3.1.3.2. RETURN VALUES		3.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 483		skipping to change at line 501
item);		item);
const pam_handle_t *pamh;		const pam_handle_t *pamh;
int item_type;		int item_type;
const void **item;		const void **item;
3.1.4.1. DESCRIPTION		3.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 668		skipping to change at line 686
....		....
#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.
3.1.6.2. RETURN VALUES		3.1.6.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 829		skipping to change at line 852
Failed to retrieve user credentials.		Failed to retrieve user credentials.
PAM_SUCCESS		PAM_SUCCESS
Data was successful stored.		Data was successful stored.
PAM_SYSTEM_ERR		PAM_SYSTEM_ERR
A NULL pointer was submitted as PAM handle, the function was called by a		A NULL pointer was submitted as PAM handle, the function was called by a
module or another system error occured.		module or another system error occurred.
PAM_USER_UNKNOWN		PAM_USER_UNKNOWN
User is not known to an authentication module.		User is not known to an authentication module.
3.1.9. Account validation management		3.1.9. Account validation management
#include <security/pam_appl.h>		#include <security/pam_appl.h>
int pam_acct_mgmt( pamh,		int pam_acct_mgmt( pamh,
skipping to change at line 1091		skipping to change at line 1114
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.
3.1.13.2. RETURN VALUES		3.1.13.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 1243		skipping to change at line 1266
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 1454		skipping to change at line 1477
5.1.1.1. DESCRIPTION		5.1.1.1. DESCRIPTION
The misc_conv function is part of libpam_misc and not of the standard libpam		The misc_conv function is part of libpam_misc and not of the standard libpam
library. This function will prompt the user with the appropriate comments and		library. This function will prompt the user with the appropriate comments and
obtain the appropriate inputs as directed by authentication modules.		obtain the appropriate inputs as directed by authentication modules.
In addition to simply slotting into the appropriate pam_conv(3), this function		In addition to simply slotting into the appropriate pam_conv(3), this function
provides some time-out facilities. The function exports five variables that can		provides some time-out facilities. The function exports five variables that can
be used by an application programmer to limit the amount of time this		be used by an application programmer to limit the amount of time this
conversation function will spend waiting for the user to type something. The		conversation function will spend waiting for the user to type something. The
five variabls are as follows:		five variables are as follows:
time_t pam_misc_conv_warn_time;		time_t pam_misc_conv_warn_time;
This variable contains the time (as returned by time(2)) that the user		This variable contains the time (as returned by time(2)) that the user
should be first warned that the clock is ticking. By default it has the		should be first warned that the clock is ticking. By default it has the
value 0, which indicates that no such warning will be given. The		value 0, which indicates that no such warning will be given. The
application may set its value to sometime in the future, but this should be		application may set its value to sometime in the future, but this should be
done prior to passing control to the Linux-PAM library.		done prior to passing control to the Linux-PAM library.
const char *pam_misc_conv_warn_line;		const char *pam_misc_conv_warn_line;
Used in conjuction with pam_misc_conv_warn_time, this variable is a pointer		Used in conjunction with pam_misc_conv_warn_time, this variable is a
to the string that will be displayed when it becomes time to warn the user		pointer to the string that will be displayed when it becomes time to warn
that the timeout is approaching. Its default value is a translated version		the user that the timeout is approaching. Its default value is a translated
of “...Time is running out...”, but this can be changed by the application		version of “...Time is running out...”, but this can be changed by the
prior to passing control to Linux-PAM.		application prior to passing control to Linux-PAM.
time_t pam_misc_conv_die_time;		time_t pam_misc_conv_die_time;
This variable contains the time (as returned by time(2)) that the will time		This variable contains the time (as returned by time(2)) that the will time
out. By default it has the value 0, which indicates that the conversation		out. By default it has the value 0, which indicates that the conversation
function will not timeout. The application may set its value to sometime in		function will not timeout. The application may set its value to sometime in
the future, but this should be done prior to passing control to the		the future, but this should be done prior to passing control to the
Linux-PAM library.		Linux-PAM library.
const char *pam_misc_conv_die_line;		const char *pam_misc_conv_die_line;
Used in conjuction with pam_misc_conv_die_time, this variable is a pointer		Used in conjunction with pam_misc_conv_die_time, this variable is a pointer
to the string that will be displayed when the conversation times out. Its		to the string that will be displayed when the conversation times out. Its
default value is a translated version of “...Sorry, your time is up!”, but		default value is a translated version of “...Sorry, your time is up!”, but
this can be changed by the application prior to passing control to		this can be changed by the application prior to passing control to
Linux-PAM.		Linux-PAM.
int pam_misc_conv_died;		int pam_misc_conv_died;
Following a return from the Linux-PAM libraray, the value of this variable		Following a return from the Linux-PAM library, the value of this variable
indicates whether the conversation has timed out. A value of 1 indicates		indicates whether the conversation has timed out. A value of 1 indicates
the time-out occurred.		the time-out occurred.
The following two function pointers are available for supporting binary prompts		The following two function pointers are available for supporting binary prompts
in the conversation function. They are optimized for the current incarnation of		in the conversation function. They are optimized for the current incarnation of
the libpamc library and are subject to change.		the libpamc library and are subject to change.
int (*pam_binary_handler_fn)(void *appdata, pamc_bp_t *prompt_p);		int (*pam_binary_handler_fn)(void *appdata, pamc_bp_t *prompt_p);
This function pointer is initialized to NULL but can be filled with a		This function pointer is initialized to NULL but can be filled with a
End of changes. 16 change blocks.
22 lines changed or deleted		45 lines changed or added

---