2 nslcd.h - file describing client/server protocol
4 Copyright (C) 2006 West Consulting
5 Copyright (C) 2006, 2007, 2009, 2010, 2011, 2012, 2013 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-terminated) 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 length of address
62 RAW the address itself
63 With the ADDRESSLIST using the same construct as with STRINGLIST.
65 The protocol uses network byte order for all types.
68 /* The current version of the protocol. This protocol should only be
69 updated with major backwards-incompatible changes. */
70 #define NSLCD_VERSION 0x00000002
72 /* Get a NSLCD configuration option. There is one request parameter:
75 STRING value, interpretation depending on request */
76 #define NSLCD_ACTION_CONFIG_GET 0x00010001
78 /* return the message, if any, that is presented to the user when password
79 modification through PAM is prohibited */
80 #define NSLCD_CONFIG_PAM_PASSWORD_PROHIBIT_MESSAGE 1
82 /* Email alias (/etc/aliases) NSS requests. The result values for a
85 STRINGLIST alias rcpts */
86 #define NSLCD_ACTION_ALIAS_BYNAME 0x00020001
87 #define NSLCD_ACTION_ALIAS_ALL 0x00020008
89 /* Ethernet address/name mapping NSS requests. The result values for a
92 TYPE(uint8_t[6]) ether address */
93 #define NSLCD_ACTION_ETHER_BYNAME 0x00030001
94 #define NSLCD_ACTION_ETHER_BYETHER 0x00030002
95 #define NSLCD_ACTION_ETHER_ALL 0x00030008
97 /* Group and group membership related NSS requests. The result values
98 for a single entry are:
100 STRING group password
102 STRINGLIST members (usernames) of the group
103 (not that the BYMEMER call returns an empty members list) */
104 #define NSLCD_ACTION_GROUP_BYNAME 0x00040001
105 #define NSLCD_ACTION_GROUP_BYGID 0x00040002
106 #define NSLCD_ACTION_GROUP_BYMEMBER 0x00040006
107 #define NSLCD_ACTION_GROUP_ALL 0x00040008
109 /* Hostname (/etc/hosts) lookup NSS requests. The result values
112 STRINGLIST host aliases
113 ADDRESSLIST host addresses */
114 #define NSLCD_ACTION_HOST_BYNAME 0x00050001
115 #define NSLCD_ACTION_HOST_BYADDR 0x00050002
116 #define NSLCD_ACTION_HOST_ALL 0x00050008
118 /* Netgroup NSS result entries contain a number of parts. A result entry
121 followed by zero or more references to other netgroups or netgroup
122 triples. A reference to another netgroup looks like:
123 INT32 NSLCD_NETGROUP_TYPE_NETGROUP
124 STRING other netgroup name
125 A a netgroup triple looks like:
126 INT32 NSLCD_NETGROUP_TYPE_TRIPLE
130 A netgroup result entry is terminated by:
131 INT32 NSLCD_NETGROUP_TYPE_END
133 #define NSLCD_ACTION_NETGROUP_BYNAME 0x00060001
134 #define NSLCD_ACTION_NETGROUP_ALL 0x00060008
135 #define NSLCD_NETGROUP_TYPE_NETGROUP 1
136 #define NSLCD_NETGROUP_TYPE_TRIPLE 2
137 #define NSLCD_NETGROUP_TYPE_END 3
139 /* Network name (/etc/networks) NSS requests. Result values for a single
142 STRINGLIST network aliases
143 ADDRESSLIST network addresses */
144 #define NSLCD_ACTION_NETWORK_BYNAME 0x00070001
145 #define NSLCD_ACTION_NETWORK_BYADDR 0x00070002
146 #define NSLCD_ACTION_NETWORK_ALL 0x00070008
148 /* User account (/etc/passwd) NSS requests. Result values are:
153 STRING gecos information
154 STRING home directory
155 STRING login shell */
156 #define NSLCD_ACTION_PASSWD_BYNAME 0x00080001
157 #define NSLCD_ACTION_PASSWD_BYUID 0x00080002
158 #define NSLCD_ACTION_PASSWD_ALL 0x00080008
160 /* Protocol information requests. Result values are:
162 STRINGLIST protocol aliases
163 INT32 protocol number */
164 #define NSLCD_ACTION_PROTOCOL_BYNAME 0x00090001
165 #define NSLCD_ACTION_PROTOCOL_BYNUMBER 0x00090002
166 #define NSLCD_ACTION_PROTOCOL_ALL 0x00090008
168 /* RPC information requests. Result values are:
170 STRINGLIST rpc aliases
172 #define NSLCD_ACTION_RPC_BYNAME 0x000a0001
173 #define NSLCD_ACTION_RPC_BYNUMBER 0x000a0002
174 #define NSLCD_ACTION_RPC_ALL 0x000a0008
176 /* Service (/etc/services) information requests. The BYNAME and BYNUMBER
177 requests contain an extra protocol string in the request which, if not
178 blank, will filter the services by this protocol. Result values are:
180 STRINGLIST service aliases
181 INT32 service (port) number
182 STRING service protocol */
183 #define NSLCD_ACTION_SERVICE_BYNAME 0x000b0001
184 #define NSLCD_ACTION_SERVICE_BYNUMBER 0x000b0002
185 #define NSLCD_ACTION_SERVICE_ALL 0x000b0008
187 /* Extended user account (/etc/shadow) information requests. Result
188 values for a single entry are:
191 INT32 last password change
198 #define NSLCD_ACTION_SHADOW_BYNAME 0x000c0001
199 #define NSLCD_ACTION_SHADOW_ALL 0x000c0008
201 /* PAM-related requests. The request parameters for all these requests
208 If the user is not known in LDAP no result may be returned (immediately
209 return NSLCD_RESULT_END instead of a PAM error code). */
211 /* PAM authentication check request. The extra request values are:
213 and the result value consists of:
214 INT32 authc NSLCD_PAM_* result code
215 STRING user name (the canonical user name)
216 INT32 authz NSLCD_PAM_* result code
217 STRING authorisation error message
218 If the username is empty in this request an attempt is made to
219 authenticate as the administrator (set using rootpwmoddn).
220 Some authorisation checks are already done during authentication so the
221 response also includes authorisation information. */
222 #define NSLCD_ACTION_PAM_AUTHC 0x000d0001
224 /* PAM authorisation check request. The result value consists of:
225 INT32 authz NSLCD_PAM_* result code
226 STRING authorisation error message
227 The authentication check may have already returned some authorisation
228 information. The authorisation error message, if supplied, will be used
229 by the PAM module instead of a message that is generated by the PAM
231 #define NSLCD_ACTION_PAM_AUTHZ 0x000d0002
233 /* PAM session open request. The result value consists of:
235 This session id may be used to close this session with. */
236 #define NSLCD_ACTION_PAM_SESS_O 0x000d0003
238 /* PAM session close request. This request has the following
241 and this calls only returns an empty response value. */
242 #define NSLCD_ACTION_PAM_SESS_C 0x000d0004
244 /* PAM password modification request. This requests has the following extra
246 INT32 asroot: 0=oldpasswd is user passwd, 1=oldpasswd is root passwd
249 and returns there extra result values:
250 INT32 NSLCD_PAM_* result code
251 STRING error message */
252 #define NSLCD_ACTION_PAM_PWMOD 0x000d0005
254 /* User information change request. This request allows one to change
255 their full name and other information. The request parameters for this
258 INT32 asroot: 0=passwd is user passwd, 1=passwd is root passwd
260 followed by one or more of the below, terminated by NSLCD_USERMOD_END
261 INT32 NSLCD_USERMOD_*
263 the response consists of one or more of the entries below, terminated
264 by NSLCD_USERMOD_END:
265 INT32 NSLCD_USERMOD_*
267 (if the response is blank, the change went OK, otherwise the string
268 contains an error message)
270 #define NSLCD_ACTION_USERMOD 0x000e0001
272 /* These are the possible values for the NSLCD_ACTION_USERMOD operation
274 #define NSLCD_USERMOD_END 0 /* end of change values */
275 #define NSLCD_USERMOD_RESULT 1 /* global result value */
276 #define NSLCD_USERMOD_FULLNAME 2 /* full name */
277 #define NSLCD_USERMOD_ROOMNUMBER 3 /* room number */
278 #define NSLCD_USERMOD_WORKPHONE 4 /* office phone number */
279 #define NSLCD_USERMOD_HOMEPHONE 5 /* home phone number */
280 #define NSLCD_USERMOD_OTHER 6 /* other info */
281 #define NSLCD_USERMOD_HOMEDIR 7 /* home directory */
282 #define NSLCD_USERMOD_SHELL 8 /* login shell */
284 /* Request result codes. */
285 #define NSLCD_RESULT_BEGIN 1
286 #define NSLCD_RESULT_END 2
288 /* Partial list of PAM result codes. */
289 #define NSLCD_PAM_SUCCESS 0 /* everything ok */
290 #define NSLCD_PAM_PERM_DENIED 6 /* Permission denied */
291 #define NSLCD_PAM_AUTH_ERR 7 /* Authc failure */
292 #define NSLCD_PAM_CRED_INSUFFICIENT 8 /* Cannot access authc data */
293 #define NSLCD_PAM_AUTHINFO_UNAVAIL 9 /* Cannot retrieve authc info */
294 #define NSLCD_PAM_USER_UNKNOWN 10 /* User not known */
295 #define NSLCD_PAM_MAXTRIES 11 /* Retry limit reached */
296 #define NSLCD_PAM_NEW_AUTHTOK_REQD 12 /* Password expired */
297 #define NSLCD_PAM_ACCT_EXPIRED 13 /* Account expired */
298 #define NSLCD_PAM_SESSION_ERR 14 /* Cannot make/remove session record */
299 #define NSLCD_PAM_AUTHTOK_ERR 20 /* Authentication token manipulation error */
300 #define NSLCD_PAM_AUTHTOK_DISABLE_AGING 23 /* Password aging disabled */
301 #define NSLCD_PAM_IGNORE 25 /* Ignore module */
302 #define NSLCD_PAM_ABORT 26 /* Fatal error */
303 #define NSLCD_PAM_AUTHTOK_EXPIRED 27 /* authentication token has expired */
305 #endif /* not _NSLCD_H */