usr/src/man/man3pam/pam_set_item.3pam

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.   All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PAM_SET_ITEM 3PAM "Oct 31, 2006"
   7 .SH NAME
   8 pam_set_item, pam_get_item \- authentication information routines for PAM
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
  13 #include <security/pam_appl.h>
  14
  15 \fBint\fR \fBpam_set_item\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBint\fR \fIitem_type\fR,
  16      \fBconst void *\fR\fIitem\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBpam_get_item\fR(\fBconst pam_handle_t *\fR\fIpamh\fR, \fBint\fR \fIitem_type\fR,
  22      \fBvoid **\fR\fIitem\fR);
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 The \fBpam_get_item()\fR and \fBpam_set_item()\fR functions allow applications
  29 and \fBPAM\fR service modules to access and to update \fBPAM\fR information as
  30 needed.  The information is specified by \fIitem_type\fR, and can be one of the
  31 following:
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fBPAM_AUSER\fR\fR
  36 .ad
  37 .RS 19n
  38 The authenticated user name.  Applications that are trusted to correctly
  39 identify the authenticated user should set this item to the authenticated user
  40 name. See NOTES and \fBpam_unix_cred\fR(5).
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fBPAM_AUTHTOK\fR\fR
  47 .ad
  48 .RS 19n
  49 The user authentication token.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fBPAM_CONV\fR\fR
  56 .ad
  57 .RS 19n
  58 The  \fBpam_conv\fR structure.
  59 .RE
  60
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fBPAM_OLDAUTHTOK\fR\fR
  65 .ad
  66 .RS 19n
  67 The old user authentication token.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBPAM_RESOURCE\fR\fR
  74 .ad
  75 .RS 19n
  76 A semicolon-separated list of \fIkey\fR=\fIvalue\fR pairs that represent the
  77 set of resource controls for application by \fBpam_setcred\fR(3PAM) or
  78 \fBpam_open_session\fR(3PAM). See the individual service module definitions,
  79 such as \fBpam_unix_cred\fR(5), for interpretations of the keys and values.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBPAM_RHOST\fR\fR
  86 .ad
  87 .RS 19n
  88 The remote host name.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBPAM_RUSER\fR\fR
  95 .ad
  96 .RS 19n
  97 The \fBrlogin\fR/\fBrsh\fR untrusted remote user name.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBPAM_SERVICE\fR\fR
 104 .ad
 105 .RS 19n
 106 The service name.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBPAM_TTY\fR\fR
 113 .ad
 114 .RS 19n
 115 The tty name.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBPAM_USER\fR\fR
 122 .ad
 123 .RS 19n
 124 The user name.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBPAM_USER_PROMPT\fR\fR
 131 .ad
 132 .RS 19n
 133 The default prompt used by  \fBpam_get_user()\fR.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fBPAM_REPOSITORY\fR
 140 .ad
 141 .RS 19n
 142 The repository that contains the authentication token information.
 143 .RE
 144
 145 .sp
 146 .LP
 147 The pam_repository structure is defined as:
 148 .sp
 149 .in +2
 150 .nf
 151 struct pam_repository {
 152     char   *type;       /* Repository type, e.g., files, */
 153                         /* nis, ldap */
 154     void   *scope;      /* Optional scope information */
 155     size_t  scope_len;  /* length of scope information */
 156 };
 157 .fi
 158 .in -2
 159
 160 .sp
 161 .LP
 162 The \fIitem_type\fR \fBPAM_SERVICE\fR can be set only by \fBpam_start()\fR and
 163 is read-only to both applications and service modules.
 164 .sp
 165 .LP
 166 For security reasons, the \fIitem_type\fR \fBPAM_AUTHTOK\fR and
 167 \fBPAM_OLDAUTHTOK\fR are available only to the module providers. The
 168 authentication module, account module, and session management module should
 169 treat \fBPAM_AUTHTOK\fR as the current authentication token and ignore
 170 \fBPAM_OLDAUTHTOK\fR. The password management module should treat
 171 \fBPAM_OLDAUTHTOK\fR as the current authentication token and \fBPAM_AUTHTOK\fR
 172 as the new authentication token.
 173 .sp
 174 .LP
 175 The \fBpam_set_item()\fR function is passed the authentication handle,
 176 \fIpamh\fR, returned by \fBpam_start()\fR, a pointer to the object, \fIitem\fR,
 177 and its type, \fIitem_type\fR. If successful, \fBpam_set_item()\fR copies the
 178 item to an internal storage area allocated by the  authentication module and
 179 returns  \fBPAM_SUCCESS\fR. An item that had been previously set will be
 180 overwritten by the new value.
 181 .sp
 182 .LP
 183 The \fBpam_get_item()\fR function is passed the authentication handle,
 184 \fIpamh\fR, returned by \fBpam_start()\fR, an \fIitem_type\fR, and the address
 185 of the pointer, \fIitem\fR, which is assigned the address of the requested
 186 object. The object data is valid until modified by a subsequent call to
 187 \fBpam_set_item()\fR for the same \fIitem_type\fR, or unless it is modified by
 188 any of the underlying service modules. If the item has not been previously set,
 189 \fBpam_get_item()\fR returns a null pointer.  An \fIitem\fR retrieved by
 190 \fBpam_get_item()\fR should not be modified or freed.  The item will be
 191 released by \fBpam_end()\fR.
 192 .SH RETURN VALUES
 193 .sp
 194 .LP
 195 Upon success, \fBpam_get_item()\fR returns  \fBPAM_SUCCESS\fR; otherwise it
 196 returns an error code. Refer to \fBpam\fR(3PAM) for information on error
 197 related return values.
 198 .SH ATTRIBUTES
 199 .sp
 200 .LP
 201 See \fBattributes\fR(5) for description of the following attributes:
 202 .sp
 203
 204 .sp
 205 .TS
 206 box;
 207 c | c
 208 l | l .
 209 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 210 _
 211 Interface Stability      Stable
 212 _
 213 MT-Level        MT-Safe with exceptions
 214 .TE
 215
 216 .sp
 217 .LP
 218 The functions in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
 219 multithreaded application uses its own \fBPAM\fR handle.
 220 .SH SEE ALSO
 221 .sp
 222 .LP
 223 \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), \fBpam_acct_mgmt\fR(3PAM),
 224 \fBpam_authenticate\fR(3PAM), \fBpam_chauthtok\fR(3PAM),
 225 \fBpam_get_user\fR(3PAM), \fBpam_open_session\fR(3PAM),
 226 \fBpam_setcred\fR(3PAM), \fBpam_start\fR(3PAM), \fBattributes\fR(5),
 227 \fBpam_unix_cred\fR(5)
 228 .SH NOTES
 229 .sp
 230 .LP
 231 If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is set and a service module does
 232 not recognize the type, the service module does not process any information,
 233 and returns \fBPAM_IGNORE\fR. If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is
 234 not set, a service module performs its default action.
 235 .sp
 236 .LP
 237 PAM_AUSER is not intended as a replacement for PAM_USER.  It is expected to be
 238 used to supplement PAM_USER when there is an authenticated user from a source
 239 other than \fBpam_authenticate\fR(3PAM). Such sources could be \fBsshd\fR
 240 host-based authentication, kerberized \fBrlogin\fR, and \fBsu\fR(1M).