2 nslcd.h - file describing client/server protocol
4 Copyright (C) 2006 West Consulting
5 Copyright (C) 2006, 2007, 2009, 2010, 2011, 2012 Arthur de Jong
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 2.1 of the License, or (at your option) any later version.
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.
17 You should have received a copy of the GNU Lesser General Public
18 License along with this library; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
27 The protocol used between the nslcd client and server is a simple binary
28 protocol. It is request/response based where the client initiates a
29 connection, does a single request and closes the connection again. Any
30 mangled or not understood messages will be silently ignored by the server.
35 [request parameters if any]
36 A response looks like:
38 INT32 NSLCD_ACTION_* (the original request type)
40 INT32 NSLCD_RESULT_END
41 A single result entry looks like:
42 INT32 NSLCD_RESULT_BEGIN
44 If a response would return multiple values (e.g. for NSLCD_ACTION_*_ALL
45 functions) each return value will be preceded by a NSLCD_RESULT_BEGIN
46 value. After the last returned result the server sends
47 NSLCD_RESULT_END. If some error occurs (e.g. LDAP server unavailable,
48 error in the request, etc) the server terminates the connection to signal
49 an error condition (breaking the protocol).
51 These are the available basic data types:
52 INT32 - 32-bit integer value
53 TYPE - a typed field that is transferred using sizeof()
54 STRING - a string length (32bit) followed by the string value (not
55 null-terminted) the string itself is assumed to be UTF-8
56 STRINGLIST - a 32-bit number noting the number of strings followed by
57 the strings one at a time
59 Furthermore the ADDRESS compound data type is defined as:
60 INT32 type of address: e.g. AF_INET or AF_INET6
61 INT32 lenght of address
62 RAW the address itself in network byte order
63 With the ADDRESSLIST using the same construct as with STRINGLIST.
65 The protocol uses host-byte order for all types (except in the raw
69 /* The current version of the protocol. Note that version 1
70 is experimental and this version will be used until a
71 1.0 release of nss-pam-ldapd is made. */
72 #define NSLCD_VERSION 1
74 /* Get a NSLCD configuration option. There is one request parameter:
77 STRING value, interpretation depending on request */
78 #define NSLCD_ACTION_CONFIG_GET 20006
80 /* return the message, if any, that is presented to the user when password
81 modification through PAM is prohibited */
82 #define NSLCD_CONFIG_PAM_PASSWORD_PROHIBIT_MESSAGE 852
84 /* Email alias (/etc/aliases) NSS requests. The result values for a
87 STRINGLIST alias rcpts */
88 #define NSLCD_ACTION_ALIAS_BYNAME 4001
89 #define NSLCD_ACTION_ALIAS_ALL 4002
91 /* Ethernet address/name mapping NSS requests. The result values for a
94 TYPE(uint8_t[6]) ether address */
95 #define NSLCD_ACTION_ETHER_BYNAME 3001
96 #define NSLCD_ACTION_ETHER_BYETHER 3002
97 #define NSLCD_ACTION_ETHER_ALL 3005
99 /* Group and group membership related NSS requests. The result values
100 for a single entry are:
102 STRING group password
104 STRINGLIST members (usernames) of the group
105 (not that the BYMEMER call returns an emtpy members list) */
106 #define NSLCD_ACTION_GROUP_BYNAME 5001
107 #define NSLCD_ACTION_GROUP_BYGID 5002
108 #define NSLCD_ACTION_GROUP_BYMEMBER 5003
109 #define NSLCD_ACTION_GROUP_ALL 5004
111 /* Hostname (/etc/hosts) lookup NSS requests. The result values
114 STRINGLIST host aliases
115 ADDRESSLIST host addresses */
116 #define NSLCD_ACTION_HOST_BYNAME 6001
117 #define NSLCD_ACTION_HOST_BYADDR 6002
118 #define NSLCD_ACTION_HOST_ALL 6005
120 /* Netgroup NSS request return a number of results. Result values
121 can be either a reference to another netgroup:
122 INT32 NSLCD_NETGROUP_TYPE_NETGROUP
123 STRING other netgroup name
124 or a netgroup triple:
125 INT32 NSLCD_NETGROUP_TYPE_TRIPLE
129 #define NSLCD_ACTION_NETGROUP_BYNAME 12001
130 #define NSLCD_NETGROUP_TYPE_NETGROUP 123
131 #define NSLCD_NETGROUP_TYPE_TRIPLE 456
133 /* Network name (/etc/networks) NSS requests. Result values for a single
136 STRINGLIST network aliases
137 ADDRESSLIST network addresses */
138 #define NSLCD_ACTION_NETWORK_BYNAME 8001
139 #define NSLCD_ACTION_NETWORK_BYADDR 8002
140 #define NSLCD_ACTION_NETWORK_ALL 8005
142 /* User account (/etc/passwd) NSS requests. Result values are:
147 STRING gecos information
148 STRING home directory
149 STRING login shell */
150 #define NSLCD_ACTION_PASSWD_BYNAME 1001
151 #define NSLCD_ACTION_PASSWD_BYUID 1002
152 #define NSLCD_ACTION_PASSWD_ALL 1004
154 /* Protocol information requests. Result values are:
156 STRINGLIST protocol aliases
157 INT32 protocol number */
158 #define NSLCD_ACTION_PROTOCOL_BYNAME 9001
159 #define NSLCD_ACTION_PROTOCOL_BYNUMBER 9002
160 #define NSLCD_ACTION_PROTOCOL_ALL 9003
162 /* RPC information requests. Result values are:
164 STRINGLIST rpc aliases
166 #define NSLCD_ACTION_RPC_BYNAME 10001
167 #define NSLCD_ACTION_RPC_BYNUMBER 10002
168 #define NSLCD_ACTION_RPC_ALL 10003
170 /* Service (/etc/services) information requests. Result values are:
172 STRINGLIST service aliases
173 INT32 service (port) number
174 STRING service protocol */
175 #define NSLCD_ACTION_SERVICE_BYNAME 11001
176 #define NSLCD_ACTION_SERVICE_BYNUMBER 11002
177 #define NSLCD_ACTION_SERVICE_ALL 11005
179 /* Extended user account (/etc/shadow) information requests. Result
180 values for a single entry are:
183 INT32 last password change
190 #define NSLCD_ACTION_SHADOW_BYNAME 2001
191 #define NSLCD_ACTION_SHADOW_ALL 2005
193 /* PAM-related requests. The request parameters for all these requests
196 STRING DN (if value is known already, otherwise empty)
198 all requests, except the SESSION requests start the result value with:
199 STRING user name (cannonical name)
200 STRING DN (can be used to speed up requests)
201 Some functions may return an authorisation message. This message, if
202 supplied will be used by the PAM module instead of a message that is
203 generated by the PAM module itself. */
205 /* PAM authentication check request. The extra request values are:
207 and the result value ends with:
208 INT32 authc NSLCD_PAM_* result code
209 INT32 authz NSLCD_PAM_* result code
210 STRING authorisation error message
211 If the username is empty in this request an attempt is made to
212 authenticate as the administrator (set using rootpwmoddn). The returned DN
213 is that of the administrator. */
214 #define NSLCD_ACTION_PAM_AUTHC 20001
216 /* PAM authorisation check request. The extra request values are:
220 and the result value ends with:
221 INT32 authz NSLCD_PAM_* result code
222 STRING authorisation error message */
223 #define NSLCD_ACTION_PAM_AUTHZ 20002
225 /* PAM session open and close requests. These requests have the following
226 extra request values:
230 INT32 session id (ignored for SESS_O)
231 and these calls only return the session ID:
233 The SESS_C must contain the ID that is retured by SESS_O to close the
235 #define NSLCD_ACTION_PAM_SESS_O 20003
236 #define NSLCD_ACTION_PAM_SESS_C 20004
238 /* PAM password modification request. This requests has the following extra
242 and returns there extra result values:
243 INT32 authz NSLCD_PAM_* result code
244 STRING authorisation error message
245 In this request the DN may be set to the administrator's DN. In this
246 case old password should be the administrator's password. This allows
247 the administrator to change any user's password. */
248 #define NSLCD_ACTION_PAM_PWMOD 20005
250 /* Request result codes. */
251 #define NSLCD_RESULT_BEGIN 0
252 #define NSLCD_RESULT_END 3
254 /* Partial list of PAM result codes. */
255 #define NSLCD_PAM_SUCCESS 0 /* everything ok */
256 #define NSLCD_PAM_PERM_DENIED 6 /* Permission denied */
257 #define NSLCD_PAM_AUTH_ERR 7 /* Authc failure */
258 #define NSLCD_PAM_CRED_INSUFFICIENT 8 /* Cannot access authc data */
259 #define NSLCD_PAM_AUTHINFO_UNAVAIL 9 /* Cannot retrieve authc info */
260 #define NSLCD_PAM_USER_UNKNOWN 10 /* User not known */
261 #define NSLCD_PAM_MAXTRIES 11 /* Retry limit reached */
262 #define NSLCD_PAM_NEW_AUTHTOK_REQD 12 /* Password expired */
263 #define NSLCD_PAM_ACCT_EXPIRED 13 /* Account expired */
264 #define NSLCD_PAM_SESSION_ERR 14 /* Cannot make/remove session record */
265 #define NSLCD_PAM_AUTHTOK_ERR 20 /* Authentication token manipulation error */
266 #define NSLCD_PAM_AUTHTOK_DISABLE_AGING 23 /* Password aging disabled */
267 #define NSLCD_PAM_IGNORE 25 /* Ignore module */
268 #define NSLCD_PAM_ABORT 26 /* Fatal error */
269 #define NSLCD_PAM_AUTHTOK_EXPIRED 27 /* authentication token has expired */
271 #endif /* not _NSLCD_H */