pam_end(3pam)

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

NAME

6       pam_start, pam_end - PAM authentication transaction functions
7

SYNOPSIS

9       cc [ flag ... ] file ... -lpam [ library ... ]
10       #include <security/pam_appl.h>
11
12       int pam_start(const char *service, const char *user,
13            const struct pam_conv *pam_conv, pam_handle_t **pamh);
14
15
16       int pam_end(pam_handle_t *pamh, int status);
17
18

DESCRIPTION

20       The pam_start() function is called to initiate an authentication trans‐
21       action. It takes as arguments the name of the current service, service,
22       the name of the user to be authenticated, user, the address of the con‐
23       versation structure, pam_conv, and the address  of  a  variable  to  be
24       assigned  the  authentication  handle pamh. Upon successful completion,
25       pamh refers to a PAM handle  for  use  with  subsequent  calls  to  the
26       authentication library.
27
28
29       The   pam_conv structure contains the address of the conversation func‐
30       tion provided by the application.  The underlying  PAM  service  module
31       invokes  this function to output information to and retrieve input from
32       the user. The pam_conv structure has the following entries:
33
34         struct pam_conv {
35             int   (*conv)();     /* Conversation function */
36             void  *appdata_ptr;  /* Application data */
37         };
38
39
40         int conv(int num_msg, const struct pam_message **msg,
41                  struct pam_response **resp, void *appdata_ptr);
42
43
44
45       The conv() function is called by a service module to hold a PAM conver‐
46       sation  with  the  application  or  user.  For window applications, the
47       application can create a new pop-up window to be used by  the  interac‐
48       tion.
49
50
51       The  num_msg   parameter  is the number of messages associated with the
52       call. The parameter msg is a pointer to an array of length  num_msg  of
53       the pam_message structure.
54
55
56       The pam_message structure is used to pass prompt, error message, or any
57       text information from the authentication service to the application  or
58       user.  It  is the responsibility of the PAM service modules to localize
59       the messages. The memory used by pam_message has to  be  allocated  and
60       freed by the  PAM modules.  The pam_message structure has the following
61       entries:
62
63         struct pam_message{
64             int     msg_style;
65             char    *msg;
66         };
67
68
69
70       The message style, msg_style, can be set to one of the  following  val‐
71       ues:
72
73       PAM_PROMPT_ECHO_OFF    Prompt user, disabling echoing of response.
74
75
76       PAM_PROMPT_ECHO_ON     Prompt user, enabling echoing of response.
77
78
79       PAM_ERROR_MSG          Print error message.
80
81
82       PAM_TEXT_INFO          Print general text information.
83
84
85
86       The   maximum   size   of  the  message  and  the  response  string  is
87       PAM_MAX_MSG_SIZE as defined in <security/pam.appl.h>.
88
89
90       The structure pam_response is used by the authentication service to get
91       the user's response back from the application or user. The storage used
92       by pam_response has to be allocated by the application and freed by the
93       PAM modules. The pam_response structure has the following entries:
94
95         struct pam_response{
96             char *resp;
97             int  resp_retcode;  /* currently not used, */
98                                 /* should be set to 0 */
99          };
100
101
102
103       It  is  the  responsibility  of  the conversation function to strip off
104       NEWLINE characters for PAM_PROMPT_ECHO_OFF and PAM_PROMPT_ECHO_ON  mes‐
105       sage  styles,  and  to  add  NEWLINE  characters  (if  appropriate) for
106       PAM_ERROR_MSG and PAM_TEXT_INFO message styles.
107
108
109       The appdata_ptr argument is an application data pointer which is passed
110       by  the application to the  PAM service modules. Since the  PAM modules
111       pass it back through the conversation function,  the  applications  can
112       use this pointer to point to any application-specific data.
113
114
115       The pam_end() function is called to terminate the authentication trans‐
116       action identified by  pamh and to free any storage  area  allocated  by
117       the  authentication  module.  The  argument,  status,  is passed to the
118       cleanup(|) function stored within the   pam  handle,  and  is  used  to
119       determine  what  module-specific state must be purged.  A cleanup func‐
120       tion is attached to the handle by the underlying PAM modules through  a
121       call to pam_set_data(3PAM) to free module-specific data.
122
123
124       Refer  to  Solaris  Security for Developers Guide for information about
125       providing authentication, account management, session  management,  and
126       password management through PAM modules.
127

RETURN VALUES

129       Refer to the RETURN VALUES section on pam(3PAM).
130

ATTRIBUTES

132       See attributes(5) for description of the following attributes:
133
134
135
136
137       ┌─────────────────────────────┬─────────────────────────────┐
138       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
139       ├─────────────────────────────┼─────────────────────────────┤
140       │Interface Stability          │ Stable                      │
141       ├─────────────────────────────┼─────────────────────────────┤
142       │MT-Level                     │MT-Safe with exceptions      │
143       └─────────────────────────────┴─────────────────────────────┘
144

NOTES

154       The  interfaces  in  libpam  are MT-Safe only if each thread within the
155       multithreaded application uses its own PAM handle.
156
157
158
159SunOS 5.11                        22 Feb 2005                  pam_start(3PAM)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ATTRIBUTES

SEE ALSO

NOTES