pam_get_item(3pam)

1pam_set_item(3PAM)           PAM Library Functions          pam_set_item(3PAM)
2
3
4

NAME

6       pam_set_item,  pam_get_item  -  authentication information routines for
7       PAM
8

SYNOPSIS

10       cc [ flag ... ] file ... -lpam [ library ... ]
11       #include <security/pam_appl.h>
12
13       int pam_set_item(pam_handle_t *pamh, int item_type,
14            const void *item);
15
16
17       int pam_get_item(const pam_handle_t *pamh, int item_type,
18            void **item);
19
20

DESCRIPTION

22       The pam_get_item() and pam_set_item() functions allow applications  and
23       PAM  service modules to access and to update PAM information as needed.
24       The information is specified by item_type, and can be one of  the  fol‐
25       lowing:
26
27       PAM_AUSER          The  authenticated user name.  Applications that are
28                          trusted to correctly identify the authenticated user
29                          should set this item to the authenticated user name.
30                          See NOTES and pam_unix_cred(5).
31
32
33       PAM_AUTHTOK        The user authentication token.
34
35
36       PAM_CONV           The  pam_conv structure.
37
38
39       PAM_OLDAUTHTOK     The old user authentication token.
40
41
42       PAM_RESOURCE       A semicolon-separated list of key=value  pairs  that
43                          represent  the set of resource controls for applica‐
44                          tion by pam_setcred(3PAM) or pam_open_session(3PAM).
45                          See  the individual service module definitions, such
46                          as pam_unix_cred(5), for interpretations of the keys
47                          and values.
48
49
50       PAM_RHOST          The remote host name.
51
52
53       PAM_RUSER          The rlogin/rsh untrusted remote user name.
54
55
56       PAM_SERVICE        The service name.
57
58
59       PAM_TTY            The tty name.
60
61
62       PAM_USER           The user name.
63
64
65       PAM_USER_PROMPT    The default prompt used by  pam_get_user().
66
67
68       PAM_REPOSITORY     The  repository  that  contains  the  authentication
69                          token information.
70
71
72
73       The pam_repository structure is defined as:
74
75         struct pam_repository {
76             char   *type;       /* Repository type, e.g., files, */
77                                 /* nis, ldap */
78             void   *scope;      /* Optional scope information */
79             size_t  scope_len;  /* length of scope information */
80         };
81
82
83
84       The item_type PAM_SERVICE can be set only by pam_start() and  is  read-
85       only to both applications and service modules.
86
87
88       For  security reasons, the item_type PAM_AUTHTOK and PAM_OLDAUTHTOK are
89       available only to the  module  providers.  The  authentication  module,
90       account  module, and session management module should treat PAM_AUTHTOK
91       as the current authentication  token  and  ignore  PAM_OLDAUTHTOK.  The
92       password  management  module should treat PAM_OLDAUTHTOK as the current
93       authentication token and PAM_AUTHTOK as the new authentication token.
94
95
96       The pam_set_item() function is passed the authentication handle,  pamh,
97       returned  by  pam_start(), a pointer to the object, item, and its type,
98       item_type. If successful, pam_set_item() copies the item to an internal
99       storage  area  allocated  by  the   authentication  module  and returns
100       PAM_SUCCESS. An item that had been previously set will  be  overwritten
101       by the new value.
102
103
104       The  pam_get_item() function is passed the authentication handle, pamh,
105       returned by pam_start(), an item_type, and the address of the  pointer,
106       item, which is assigned the address of the requested object. The object
107       data is valid until modified by a subsequent call to pam_set_item() for
108       the  same  item_type, or unless it is modified by any of the underlying
109       service  modules.  If  the  item   has   not   been   previously   set,
110       pam_get_item()   returns   a   null  pointer.   An  item  retrieved  by
111       pam_get_item() should not be modified  or  freed.   The  item  will  be
112       released by pam_end().
113

RETURN VALUES

115       Upon success, pam_get_item() returns  PAM_SUCCESS; otherwise it returns
116       an error code. Refer to pam(3PAM)  for  information  on  error  related
117       return values.
118

ATTRIBUTES

120       See attributes(5) for description of the following attributes:
121
122
123
124
125       ┌─────────────────────────────┬─────────────────────────────┐
126       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
127       ├─────────────────────────────┼─────────────────────────────┤
128       │Interface Stability          │ Stable                      │
129       ├─────────────────────────────┼─────────────────────────────┤
130       │MT-Level                     │MT-Safe with exceptions      │
131       └─────────────────────────────┴─────────────────────────────┘
132
133
134       The  functions  in  libpam(3LIB) are MT-Safe only if each thread within
135       the multithreaded application uses its own PAM handle.
136

NOTES

143       If the PAM_REPOSITORY item_type is set and a service  module  does  not
144       recognize  the  type,  the service module does not process any informa‐
145       tion, and returns PAM_IGNORE. If the PAM_REPOSITORY  item_type  is  not
146       set, a service module performs its default action.
147
148
149       PAM_AUSER  is  not  intended  as  a  replacement  for  PAM_USER.  It is
150       expected to be used to supplement PAM_USER when there is  an  authenti‐
151       cated  user  from  a  source  other  than  pam_authenticate(3PAM). Such
152       sources could be sshd host-based authentication, kerberized rlogin, and
153       su(1M).
154
155
156
157SunOS 5.11                        31 Oct 2006               pam_set_item(3PAM)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ATTRIBUTES

SEE ALSO

NOTES