summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/man/pam_get_item.3154
-rw-r--r--doc/man/pam_item_types_ext.inc.xml4
-rw-r--r--doc/man/pam_set_data.368
-rw-r--r--doc/man/pam_set_item.3148
4 files changed, 239 insertions, 135 deletions
diff --git a/doc/man/pam_get_item.3 b/doc/man/pam_get_item.3
index ae63d298..27ea6cf3 100644
--- a/doc/man/pam_get_item.3
+++ b/doc/man/pam_get_item.3
@@ -1,22 +1,22 @@
.\" Title: pam_get_item
.\" Author:
-.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
-.\" Date: 06/27/2006
-.\" Manual: Linux\-PAM Manual
-.\" Source: Linux\-PAM Manual
+.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
+.\" Date: 12/06/2007
+.\" Manual: Linux-PAM Manual
+.\" Source: Linux-PAM Manual
.\"
-.TH "PAM_GET_ITEM" "3" "06/27/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.TH "PAM_GET_ITEM" "3" "12/06/2007" "Linux-PAM Manual" "Linux-PAM Manual"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
-pam_get_item \- getting PAM informations
+pam_get_item - getting PAM informations
.SH "SYNOPSIS"
.sp
.ft B
.nf
-#include <security/pam_modules.h>
+#include <security/pam_modules\.h>
.fi
.ft
.HP 17
@@ -26,98 +26,146 @@ pam_get_item \- getting PAM informations
The
\fBpam_get_item\fR
function allows applications and PAM service modules to access and retrieve PAM informations of
-\fIitem_type\fR. Upon successful return,
+\fIitem_type\fR\. Upon successful return,
\fIitem\fR
-contains a pointer to the value of the corresponding item. Note, this is a pointer to the
+contains a pointer to the value of the corresponding item\. Note, this is a pointer to the
\fIactual\fR
data and should
\fBnot\fR
be
-\fIfree()\fR'ed or over\-written! The following values are supported for
+\fIfree()\fR\'ed or over\-written! The following values are supported for
\fIitem_type\fR:
-.TP 3n
+.PP
PAM_SERVICE
-The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program).
-.TP 3n
+.RS 4
+The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program)\.
+.RE
+.PP
PAM_USER
-The username of the entity under whose identity service will be given. That is, following authentication,
+.RS 4
+The username of the entity under whose identity service will be given\. That is, following authentication,
\fIPAM_USER\fR
-identifies the local entity that gets to use the service. Note, this value can be mapped from something (eg., "anonymous") to something else (eg. "guest119") by any module in the PAM stack. As such an application should consult the value of
+identifies the local entity that gets to use the service\. Note, this value can be mapped from something (eg\., "anonymous") to something else (eg\. "guest119") by any module in the PAM stack\. As such an application should consult the value of
\fIPAM_USER\fR
-after each call to a PAM function.
-.TP 3n
+after each call to a PAM function\.
+.RE
+.PP
PAM_USER_PROMPT
-The string used when prompting for a user's name. The default value for this string is a localized version of "login: ".
-.TP 3n
+.RS 4
+The string used when prompting for a user\'s name\. The default value for this string is a localized version of "login: "\.
+.RE
+.PP
PAM_TTY
+.RS 4
The terminal name: prefixed by
\fI/dev/\fR
if it is a device file; for graphical, X\-based, applications the value for this item should be the
\fI$DISPLAY\fR
-variable.
-.TP 3n
+variable\.
+.RE
+.PP
PAM_RUSER
-The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user.
+.RS 4
+The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user\.
.sp
-Generally an application or module will attempt to supply the value that is most strongly authenticated (a local account before a remote one. The level of trust in this value is embodied in the actual authentication stack associated with the application, so it is ultimately at the discretion of the system administrator.
+Generally an application or module will attempt to supply the value that is most strongly authenticated (a local account before a remote one\. The level of trust in this value is embodied in the actual authentication stack associated with the application, so it is ultimately at the discretion of the system administrator\.
.sp
\fIPAM_RUSER@PAM_RHOST\fR
-should always identify the requesting user. In some cases,
+should always identify the requesting user\. In some cases,
\fIPAM_RUSER\fR
-may be NULL. In such situations, it is unclear who the requesting entity is.
-.TP 3n
+may be NULL\. In such situations, it is unclear who the requesting entity is\.
+.RE
+.PP
PAM_RHOST
+.RS 4
The requesting hostname (the hostname of the machine from which the
\fIPAM_RUSER\fR
-entity is requesting service). That is
+entity is requesting service)\. That is
\fIPAM_RUSER@PAM_RHOST\fR
-does identify the requesting user. In some applications,
+does identify the requesting user\. In some applications,
\fIPAM_RHOST\fR
-may be NULL. In such situations, it is unclear where the authentication request is originating from.
-.TP 3n
+may be NULL\. In such situations, it is unclear where the authentication request is originating from\.
+.RE
+.PP
PAM_AUTHTOK
-The authentication token (often a password). This token should be ignored by all module functions besides
+.RS 4
+The authentication token (often a password)\. This token should be ignored by all module functions besides
\fBpam_sm_authenticate\fR(3)
and
-\fBpam_sm_chauthtok\fR(3). In the former function it is used to pass the most recent authentication token from one stacked module to another. In the latter function the token is used for another purpose. It contains the currently active authentication token.
-.TP 3n
+\fBpam_sm_chauthtok\fR(3)\. In the former function it is used to pass the most recent authentication token from one stacked module to another\. In the latter function the token is used for another purpose\. It contains the currently active authentication token\.
+.RE
+.PP
PAM_OLDAUTHTOK
-The old authentication token. This token should be ignored by all module functions except
-\fBpam_sm_chauthtok\fR(3).
-.TP 3n
+.RS 4
+The old authentication token\. This token should be ignored by all module functions except
+\fBpam_sm_chauthtok\fR(3)\.
+.RE
+.PP
PAM_CONV
-The pam_conv structure. See
-\fBpam_conv\fR(3).
-.TP 3n
+.RS 4
+The pam_conv structure\. See
+\fBpam_conv\fR(3)\.
+.RE
+.PP
+The following additional items are specific to Linux\-PAM and should not be used in portable applications:
+.PP
PAM_FAIL_DELAY
-A function pointer to redirect centrally managed failure delays. See
-\fBpam_fail_delay\fR(3).
+.RS 4
+A function pointer to redirect centrally managed failure delays\. See
+\fBpam_fail_delay\fR(3)\.
+.RE
+.PP
+PAM_XDISPLAY
+.RS 4
+The name of the X display\. For graphical, X\-based applications the value for this item should be the
+\fI$DISPLAY\fR
+variable\. This value should be used instead of
+\fIPAM_TTY\fR
+for passing the name of the display where possible\.
+.RE
+.PP
+PAM_XAUTHDATA
+.RS 4
+A pointer to a structure containing the X authentication data required to make a connection to the display specified by
+\fIPAM_XDISPLAY\fR, if such information is necessary\. See
+\fBpam_xauth_data\fR(3)\.
+.RE
.PP
If a service module wishes to obtain the name of the user, it should not use this function, but instead perform a call to
-\fBpam_get_user\fR(3).
+\fBpam_get_user\fR(3)\.
.PP
-Only a service module is privileged to read the authentication tokens, PAM_AUTHTOK and PAM_OLDAUTHTOK.
+Only a service module is privileged to read the authentication tokens, PAM_AUTHTOK and PAM_OLDAUTHTOK\.
.SH "RETURN VALUES"
-.TP 3n
+.PP
PAM_BAD_ITEM
-The application attempted to set an undefined or inaccessible item.
-.TP 3n
+.RS 4
+The application attempted to set an undefined or inaccessible item\.
+.RE
+.PP
PAM_BUF_ERR
-Memory buffer error.
-.TP 3n
+.RS 4
+Memory buffer error\.
+.RE
+.PP
PAM_PERM_DENIED
+.RS 4
The value of
\fIitem\fR
-was NULL.
-.TP 3n
+was NULL\.
+.RE
+.PP
PAM_SUCCESS
-Data was successful updated.
-.TP 3n
+.RS 4
+Data was successful updated\.
+.RE
+.PP
PAM_SYSTEM_ERR
+.RS 4
The
\fIpam_handle_t\fR
-passed as first argument was invalid.
+passed as first argument was invalid\.
+.RE
.SH "SEE ALSO"
.PP
diff --git a/doc/man/pam_item_types_ext.inc.xml b/doc/man/pam_item_types_ext.inc.xml
index 0c72f699..89f19875 100644
--- a/doc/man/pam_item_types_ext.inc.xml
+++ b/doc/man/pam_item_types_ext.inc.xml
@@ -20,9 +20,9 @@
<para>
The name of the X display. For graphical, X-based applications the
value for this item should be the <emphasis>$DISPLAY</emphasis>
- variable. This value should be used instead of
+ variable. This value may be used independently of
<emphasis>PAM_TTY</emphasis> for passing the
- name of the display where possible.
+ name of the display.
</para>
</listitem>
</varlistentry>
diff --git a/doc/man/pam_set_data.3 b/doc/man/pam_set_data.3
index c3a2a689..1991b92a 100644
--- a/doc/man/pam_set_data.3
+++ b/doc/man/pam_set_data.3
@@ -1,22 +1,22 @@
.\" Title: pam_set_data
.\" Author:
-.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
-.\" Date: 06/27/2006
-.\" Manual: Linux\-PAM Manual
-.\" Source: Linux\-PAM Manual
+.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
+.\" Date: 12/06/2007
+.\" Manual: Linux-PAM Manual
+.\" Source: Linux-PAM Manual
.\"
-.TH "PAM_SET_DATA" "3" "06/27/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.TH "PAM_SET_DATA" "3" "12/06/2007" "Linux-PAM Manual" "Linux-PAM Manual"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
-pam_set_data \- set module internal data
+pam_set_data - set module internal data
.SH "SYNOPSIS"
.sp
.ft B
.nf
-#include <security/pam_modules.h>
+#include <security/pam_modules\.h>
.fi
.ft
.HP 17
@@ -29,30 +29,30 @@ function associates a pointer to an object with the (hopefully) unique string
\fImodule_data_name\fR
in the PAM context specified by the
\fIpamh\fR
-argument.
+argument\.
.PP
-PAM modules may be dynamically loadable objects. In general such files should not contain
+PAM modules may be dynamically loadable objects\. In general such files should not contain
\fIstatic\fR
-variables. This function and its counterpart
+variables\. This function and its counterpart
\fBpam_get_data\fR(3), provide a mechanism for a module to associate some data with the handle
-\fIpamh\fR. Typically a module will call the
+\fIpamh\fR\. Typically a module will call the
\fBpam_set_data\fR
function to register some data under a (hopefully) unique
-\fImodule_data_name\fR. The data is available for use by other modules too but
+\fImodule_data_name\fR\. The data is available for use by other modules too but
\fInot\fR
-by an application. Since this functions stores only a pointer to the
-\fIdata\fR, the module should not modify or free the content of it.
+by an application\. Since this functions stores only a pointer to the
+\fIdata\fR, the module should not modify or free the content of it\.
.PP
The function
\fBcleanup()\fR
is associated with the
\fIdata\fR
and, if non\-NULL, it is called when this data is over\-written or following a call to
-\fBpam_end\fR(3).
+\fBpam_end\fR(3)\.
.PP
The
\fIerror_status\fR
-argument is used to indicate to the module the sort of action it is to take in cleaning this data item. As an example, Kerberos creates a ticket file during the authentication phase, this file might be associated with a data item. When
+argument is used to indicate to the module the sort of action it is to take in cleaning this data item\. As an example, Kerberos creates a ticket file during the authentication phase, this file might be associated with a data item\. When
\fBpam_end\fR(3)
is called by the module, the
\fIerror_status\fR
@@ -60,31 +60,41 @@ carries the return value of the
\fBpam_authenticate\fR(3)
or other
\fIlibpam\fR
-function as appropriate. Based on this value the Kerberos module may choose to delete the ticket file (\fIauthentication failure\fR) or leave it in place.
+function as appropriate\. Based on this value the Kerberos module may choose to delete the ticket file (\fIauthentication failure\fR) or leave it in place\.
.PP
The
\fIerror_status\fR
-may have been logically OR'd with either of the following two values:
-.TP 3n
+may have been logically OR\'d with either of the following two values:
+.PP
PAM_DATA_REPLACE
+.RS 4
When a data item is being replaced (through a second call to
-\fBpam_set_data\fR) this mask is used. Otherwise, the call is assumed to be from
-\fBpam_end\fR(3).
-.TP 3n
+\fBpam_set_data\fR) this mask is used\. Otherwise, the call is assumed to be from
+\fBpam_end\fR(3)\.
+.RE
+.PP
PAM_DATA_SILENT
+.RS 4
Which indicates that the process would prefer to perform the
\fBcleanup()\fR
-quietly. That is, discourages logging/messages to the user.
+quietly\. That is, discourages logging/messages to the user\.
+.RE
.SH "RETURN VALUES"
-.TP 3n
+.PP
PAM_BUF_ERR
-Memory buffer error.
-.TP 3n
+.RS 4
+Memory buffer error\.
+.RE
+.PP
PAM_SUCCESS
-Data was successful stored.
-.TP 3n
+.RS 4
+Data was successful stored\.
+.RE
+.PP
PAM_SYSTEM_ERR
-A NULL pointer was submitted as PAM handle or the function was called by an application.
+.RS 4
+A NULL pointer was submitted as PAM handle or the function was called by an application\.
+.RE
.SH "SEE ALSO"
.PP
diff --git a/doc/man/pam_set_item.3 b/doc/man/pam_set_item.3
index fa802747..a152cbbf 100644
--- a/doc/man/pam_set_item.3
+++ b/doc/man/pam_set_item.3
@@ -1,22 +1,22 @@
.\" Title: pam_set_item
.\" Author:
-.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
-.\" Date: 06/27/2006
-.\" Manual: Linux\-PAM Manual
-.\" Source: Linux\-PAM Manual
+.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
+.\" Date: 12/06/2007
+.\" Manual: Linux-PAM Manual
+.\" Source: Linux-PAM Manual
.\"
-.TH "PAM_SET_ITEM" "3" "06/27/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.TH "PAM_SET_ITEM" "3" "12/06/2007" "Linux-PAM Manual" "Linux-PAM Manual"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
-pam_set_item \- set and update PAM informations
+pam_set_item - set and update PAM informations
.SH "SYNOPSIS"
.sp
.ft B
.nf
-#include <security/pam_modules.h>
+#include <security/pam_modules\.h>
.fi
.ft
.HP 17
@@ -26,97 +26,143 @@ pam_set_item \- set and update PAM informations
The
\fBpam_set_item\fR
function allows applications and PAM service modules to access and to update PAM informations of
-\fIitem_type\fR. For this a copy of the object pointed to by the
+\fIitem_type\fR\. For this a copy of the object pointed to by the
\fIitem\fR
-argument is created. The following
+argument is created\. The following
\fIitem_type\fRs are supported:
-.TP 3n
+.PP
PAM_SERVICE
-The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program).
-.TP 3n
+.RS 4
+The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program)\.
+.RE
+.PP
PAM_USER
-The username of the entity under whose identity service will be given. That is, following authentication,
+.RS 4
+The username of the entity under whose identity service will be given\. That is, following authentication,
\fIPAM_USER\fR
-identifies the local entity that gets to use the service. Note, this value can be mapped from something (eg., "anonymous") to something else (eg. "guest119") by any module in the PAM stack. As such an application should consult the value of
+identifies the local entity that gets to use the service\. Note, this value can be mapped from something (eg\., "anonymous") to something else (eg\. "guest119") by any module in the PAM stack\. As such an application should consult the value of
\fIPAM_USER\fR
-after each call to a PAM function.
-.TP 3n
+after each call to a PAM function\.
+.RE
+.PP
PAM_USER_PROMPT
-The string used when prompting for a user's name. The default value for this string is a localized version of "login: ".
-.TP 3n
+.RS 4
+The string used when prompting for a user\'s name\. The default value for this string is a localized version of "login: "\.
+.RE
+.PP
PAM_TTY
+.RS 4
The terminal name: prefixed by
\fI/dev/\fR
if it is a device file; for graphical, X\-based, applications the value for this item should be the
\fI$DISPLAY\fR
-variable.
-.TP 3n
+variable\.
+.RE
+.PP
PAM_RUSER
-The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user.
+.RS 4
+The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user\.
.sp
-Generally an application or module will attempt to supply the value that is most strongly authenticated (a local account before a remote one. The level of trust in this value is embodied in the actual authentication stack associated with the application, so it is ultimately at the discretion of the system administrator.
+Generally an application or module will attempt to supply the value that is most strongly authenticated (a local account before a remote one\. The level of trust in this value is embodied in the actual authentication stack associated with the application, so it is ultimately at the discretion of the system administrator\.
.sp
\fIPAM_RUSER@PAM_RHOST\fR
-should always identify the requesting user. In some cases,
+should always identify the requesting user\. In some cases,
\fIPAM_RUSER\fR
-may be NULL. In such situations, it is unclear who the requesting entity is.
-.TP 3n
+may be NULL\. In such situations, it is unclear who the requesting entity is\.
+.RE
+.PP
PAM_RHOST
+.RS 4
The requesting hostname (the hostname of the machine from which the
\fIPAM_RUSER\fR
-entity is requesting service). That is
+entity is requesting service)\. That is
\fIPAM_RUSER@PAM_RHOST\fR
-does identify the requesting user. In some applications,
+does identify the requesting user\. In some applications,
\fIPAM_RHOST\fR
-may be NULL. In such situations, it is unclear where the authentication request is originating from.
-.TP 3n
+may be NULL\. In such situations, it is unclear where the authentication request is originating from\.
+.RE
+.PP
PAM_AUTHTOK
-The authentication token (often a password). This token should be ignored by all module functions besides
+.RS 4
+The authentication token (often a password)\. This token should be ignored by all module functions besides
\fBpam_sm_authenticate\fR(3)
and
-\fBpam_sm_chauthtok\fR(3). In the former function it is used to pass the most recent authentication token from one stacked module to another. In the latter function the token is used for another purpose. It contains the currently active authentication token.
-.TP 3n
+\fBpam_sm_chauthtok\fR(3)\. In the former function it is used to pass the most recent authentication token from one stacked module to another\. In the latter function the token is used for another purpose\. It contains the currently active authentication token\.
+.RE
+.PP
PAM_OLDAUTHTOK
-The old authentication token. This token should be ignored by all module functions except
-\fBpam_sm_chauthtok\fR(3).
-.TP 3n
+.RS 4
+The old authentication token\. This token should be ignored by all module functions except
+\fBpam_sm_chauthtok\fR(3)\.
+.RE
+.PP
PAM_CONV
-The pam_conv structure. See
-\fBpam_conv\fR(3).
-.TP 3n
+.RS 4
+The pam_conv structure\. See
+\fBpam_conv\fR(3)\.
+.RE
+.PP
+The following additional items are specific to Linux\-PAM and should not be used in portable applications:
+.PP
PAM_FAIL_DELAY
-A function pointer to redirect centrally managed failure delays. See
-\fBpam_fail_delay\fR(3).
+.RS 4
+A function pointer to redirect centrally managed failure delays\. See
+\fBpam_fail_delay\fR(3)\.
+.RE
+.PP
+PAM_XDISPLAY
+.RS 4
+The name of the X display\. For graphical, X\-based applications the value for this item should be the
+\fI$DISPLAY\fR
+variable\. This value should be used instead of
+\fIPAM_TTY\fR
+for passing the name of the display where possible\.
+.RE
+.PP
+PAM_XAUTHDATA
+.RS 4
+A pointer to a structure containing the X authentication data required to make a connection to the display specified by
+\fIPAM_XDISPLAY\fR, if such information is necessary\. See
+\fBpam_xauth_data\fR(3)\.
+.RE
.PP
For all
\fIitem_type\fRs, other than PAM_CONV and PAM_FAIL_DELAY,
\fIitem\fR
-is a pointer to a <NUL> terminated character string. In the case of PAM_CONV,
+is a pointer to a <NUL> terminated character string\. In the case of PAM_CONV,
\fIitem\fR
points to an initialized
\fIpam_conv\fR
-structure. In the case of PAM_FAIL_DELAY,
+structure\. In the case of PAM_FAIL_DELAY,
\fIitem\fR
is a function pointer:
\fBvoid (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)\fR
.PP
-Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reseted before returning to the application. Which means an application is not able to access the authentication tokens.
+Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reseted before returning to the application\. Which means an application is not able to access the authentication tokens\.
.SH "RETURN VALUES"
-.TP 3n
+.PP
PAM_BAD_ITEM
-The application attempted to set an undefined or inaccessible item.
-.TP 3n
+.RS 4
+The application attempted to set an undefined or inaccessible item\.
+.RE
+.PP
PAM_BUF_ERR
-Memory buffer error.
-.TP 3n
+.RS 4
+Memory buffer error\.
+.RE
+.PP
PAM_SUCCESS
-Data was successful updated.
-.TP 3n
+.RS 4
+Data was successful updated\.
+.RE
+.PP
PAM_SYSTEM_ERR
+.RS 4
The
\fIpam_handle_t\fR
-passed as first argument was invalid.
+passed as first argument was invalid\.
+.RE
.SH "SEE ALSO"
.PP