1 /*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21 /*
22 * Copyright 2014 Garrett D'Amore <garrett@damore.org>
23 *
24 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
25 * Use is subject to license terms.
26 */
27
28 /*
29 *
30 * NOTE: The interfaces documented in this file may change in a minor
31 * release. It is intended that in the future a stronger committment
32 * will be made to these interface definitions which will guarantee
33 * them across minor releases.
34 */
35
36 #ifndef _NSS_COMMON_H
37 #define _NSS_COMMON_H
38
39 #include <synch.h>
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 /*
46 * The name-service switch
47 * -----------------------
48 *
49 * From nsswitch.conf(4):
50 *
51 * The operating system uses a number of "databases" of information
52 * about hosts, users (passwd/shadow), groups and so forth. Data for
53 * these can come from a variety of "sources": host-names and
54 * -addresses, for example, may be found in /etc/hosts, NIS, NIS+ or
55 * DNS. One or more sources may be used for each database; the
56 * sources and their lookup order are specified in the
57 * /etc/nsswitch.conf file.
58 *
59 * The implementation of this consists of:
60 *
61 * - a "frontend" for each database, which provides a programming
62 * interface for that database [for example, the "passwd" frontend
63 * consists of getpwnam_r(), getpwuid_r(), getpwent_r(), setpwent(),
64 * endpwent(), and the old MT-unsafe routines getpwnam() and getpwuid()]
65 * and is implemented by calls to...
66 *
67 * - the common core of the switch (called the "switch" or "policy" engine);
68 * that determines what sources to use and when to invoke them. This
69 * component works in conjunction with the name service switch (nscd).
70 * Usually nscd is the policy engine for an application lookup.
71 *
72 * - Old style backend interfaces follow this pointer to function interface:
73 *
74 * A "backend" exists for useful <database, source> pairs. Each backend
75 * consists of whatever private data it needs and a set of functions
76 * that the switch engine may invoke on behalf of the frontend
77 * [e.g. the "nis" backend for "passwd" provides routines to lookup
78 * by name and by uid, as well as set/get/end iterator routines].
79 * The set of functions, and their expected arguments and results,
80 * constitutes a (database-specific) interface between a frontend and
81 * all its backends. The switch engine knows as little as possible
82 * about these interfaces.
83 *
84 * (The term "backend" is used ambiguously; it may also refer to a
85 * particular instantiation of a backend, or to the set of all backends
86 * for a particular source, e.g. "the nis backend").
87 *
88 * This header file defines the interface between the switch engine and the
89 * frontends and backends. Interfaces between specific frontends and
90 * backends are defined elsewhere; many are in <nss_dbdefs.h>.
91 * Most of these definitions are in the form of pointer to function
92 * indicies used to call specific backend APIs.
93 *
94 *
95 * Switch-engine outline
96 * ---------------------
97 *
98 * Frontends may call the following routines in the switch engine:
99 *
100 * nss_search() does getXXXbyYYY, e.g. getpwnam_r(), getpwuid_r()
101 * nss_getent() does getXXXent, e.g. getpwent_r()
102 * nss_setent() does setXXXent, e.g. setpwent()
103 * nss_endent() does endXXXent, e.g. endpwent()
104 * nss_delete() releases resources, in the style of endpwent().
105 *
106 * A getpwnam_r() call might proceed thus (with many details omitted):
107 *
108 * (1) getpwnam_r fills in (getpwnam-specific) argument/result struct,
109 * calls nss_search(),
110 * (2) nss_search queries the name service cache for an existing
111 * result via a call to _nsc_search(). if the cache
112 * (nscd) has a definitive answer skip to step 7
113 * (3) nss_search looks up configuration info, gets "passwd: files nis",
114 * (4) nss_search decides to try first source ("files"),
115 * (a) nss_search locates code for <"passwd", "files"> backend,
116 * (b) nss_search creates instance of backend,
117 * (c) nss_search calls get-by-name routine in backend,
118 * through a function pointer interface,
119 * (d) backend searches /etc/passwd, doesn't find the name,
120 * returns "not found" status to nss_search,
121 * (5) nss_search examines status and config info, decides to try
122 * next source ("nis"),
123 * (a) nss_search locates code for <"passwd", "nis"> backend,
124 * (b) nss_search creates instance of backend,
125 * (c) nss_search calls get-by-name routine in backend,
126 * through a function pointer interface,
127 * (d) backend searches passwd.byname, finds the desired entry,
128 * fills in the result part of the getpwnam-specific
129 * struct, returns "success" status to nss_search,
130 * (6) nss_search examines status and config info, decides to return
131 * to caller,
132 * (7) getpwnam_r extracts result from getpwnam-specific struct,
133 * returns to caller.
134 *
135 *
136 * Data structures
137 * ---------------
138 *
139 * Both databases and sources are represented by case-sensitive strings
140 * (the same strings that appear in the configuration file).
141 *
142 * The switch engine maintains a per-frontend data structure so that the
143 * results of steps (2), (a) and (b) can be cached. The frontend holds a
144 * handle (nss_db_root_t) to this structure and passes it in to the
145 * nss_*() routines.
146 *
147 * The nss_setent(), nss_getent() and nss_endent() routines introduce another
148 * variety of state (the current position in the enumeration process).
149 * Within a single source, this information is maintained by private data
150 * in the backend instance -- but, in the presence of multiple sources, the
151 * switch engine must keep track of the current backend instance [e.g either
152 * <"passwd", "files"> or <"passwd", "nis"> instances]. The switch engine
153 * has a separate per-enumeration data structure for this; again, the
154 * frontend holds a handle (nss_getent_t) and passes it in, along with the
155 * nss_db_root_t handle, to nss_setent(), nss_getent() and nss_endent().
156 *
157 *
158 * Multithreading
159 * --------------
160 *
161 * The switch engine takes care of locking; frontends should be written to
162 * be reentrant, and a backend instance may assume that all calls to it are
163 * serialized.
164 *
165 * If multiple threads simultaneously want to use a particular backend, the
166 * switch engine creates multiple backend instances (up to some limit
167 * specified by the frontend). Backends must of course lock any state that
168 * is shared between instances, and must serialize calls to any MT-unsafe
169 * code.
170 *
171 * The switch engine has no notion of per-thread state.
172 *
173 * Frontends can use the nss_getent_t handle to define the scope of the
174 * enumeration (set/get/endXXXent) state: a static handle gives global state
175 * (which is what Posix has specified for the getXXXent_r routines), handles
176 * in Thread-Specific Data give per-thread state, and handles on the stack
177 * give per-invocation state.
178 */
179
180 /*
181 * Backend instances
182 * -----------------
183 *
184 * As far as the switch engine is concerned, an instance of a backend is a
185 * struct whose first two members are:
186 * - A pointer to a vector of function pointers, one for each
187 * database-specific function,
188 * - The length of the vector (an int), used for bounds-checking.
189 * There are four well-known function slots in the vector:
190 * [0] is a destructor for the backend instance,
191 * [1] is the endXXXent routine,
192 * [2] is the setXXXent routine,
193 * [3] is the getXXXent routine.
194 * Any other slots are database-specific getXXXbyYYY routines; the frontend
195 * specifies a slot-number to nss_search().
196 *
197 * The functions take two arguments:
198 * - a pointer to the backend instance (like a C++ "this" pointer)
199 * - a single (void *) pointer to the database-specific argument/result
200 * structure (the contents are opaque to the switch engine).
201 * The four well-known functions ignore the (void *) pointer.
202 *
203 * Backend routines return the following status codes to the switch engine:
204 *
205 * SUCCESS, UNAVAIL, NOTFOUND, TRYAGAIN (these are the same codes that may
206 * be specified in the config information; see nsswitch.conf(4))
207 *
208 * The remaining conditions/errors are internally generated and if
209 * necessary are translated, as to one of the above external errors,
210 * usually NOTFOUND or UNAVAIL.
211 *
212 * NSS_NISSERVDNS_TRYAGAIN (should only be used by the NIS backend for
213 * NIS server in DNS forwarding mode to indicate DNS server non-response).
214 *
215 * The policy component may return NSS_TRYLOCAL which signifies that nscd
216 * is not going to process the request, and it should be performed locally.
217 *
218 * NSS_ERROR is a catchall for internal error conditions, errno will be set
219 * to a system <errno.h> error that can help track down the problem if
220 * it is persistent. This error is the result of some internal error
221 * condition and should not be seen during or exposed to aan application.
222 * The error may be from the application side switch component or from the
223 * nscd side switch component.
224 *
225 * NSS_ALTRETRY and NSS_ALTRESET are internal codes used by the application
226 * side policy component and nscd to direct the policy component to
227 * communicate to a per-user nscd if/when per-user authentication is enabled.
228 *
229 * NSS_NSCD_PRIV is a catchall for internal nscd errors or status
230 * conditions. This return code is not visible to applications. nscd
231 * may use this as a status flag and maintain additional error or status
232 * information elsewhere in other private nscd data. This status value
233 * is for nscd private/internal use only.
234 */
235
236 typedef enum {
237 NSS_SUCCESS = 0,
238 NSS_NOTFOUND = 1,
239 NSS_UNAVAIL = 2,
240 NSS_TRYAGAIN = 3,
241 NSS_NISSERVDNS_TRYAGAIN = 4,
242 NSS_TRYLOCAL = 5,
243 NSS_ERROR = 6,
244 NSS_ALTRETRY = 7,
245 NSS_ALTRESET = 8,
246 NSS_NSCD_PRIV = 9
247 } nss_status_t;
248
249 struct nss_backend;
250
251 typedef nss_status_t (*nss_backend_op_t)(struct nss_backend *, void *args);
252
253 struct nss_backend {
254 nss_backend_op_t *ops;
255 int n_ops;
256 };
257 typedef struct nss_backend nss_backend_t;
258 typedef int nss_dbop_t;
259
260 #define NSS_DBOP_DESTRUCTOR 0
261 #define NSS_DBOP_ENDENT 1
262 #define NSS_DBOP_SETENT 2
263 #define NSS_DBOP_GETENT 3
264 #define NSS_DBOP_next_iter (NSS_DBOP_GETENT + 1)
265 #define NSS_DBOP_next_noiter (NSS_DBOP_DESTRUCTOR + 1)
266 #define NSS_DBOP_next_ipv6_iter (NSS_DBOP_GETENT + 3)
267
268 #define NSS_LOOKUP_DBOP(instp, n) \
269 (((n) >= 0 && (n) < (instp)->n_ops) ? (instp)->ops[n] : 0)
270
271 #define NSS_INVOKE_DBOP(instp, n, argp) (\
272 ((n) >= 0 && (n) < (instp)->n_ops && (instp)->ops[n] != 0) \
273 ? (*(instp)->ops[n])(instp, argp) \
274 : NSS_UNAVAIL)
275
276 /*
277 * Locating and instantiating backends
278 * -----------------------------------
279 *
280 * To perform step (a), the switch consults a list of backend-finder routines,
281 * passing a <database, source> pair.
282 *
283 * There is a standard backend-finder; frontends may augment or replace this
284 * in order to, say, indicate that some backends are "compiled in" with the
285 * frontend.
286 *
287 * Backend-finders return a pointer to a constructor function for the backend.
288 * (or NULL if they can't find the backend). The switch engine caches these
289 * function pointers; when it needs to perform step (b), it calls the
290 * constructor function, which returns a pointer to a new instance of the
291 * backend, properly initialized (or returns NULL).
292 */
293
294 typedef nss_backend_t *(*nss_backend_constr_t)(const char *db_name,
295 const char *src_name,
296 /* Hook for (unimplemented) args in nsswitch.conf */ const char *cfg_args);
297
298 struct nss_backend_finder {
299 nss_backend_constr_t (*lookup)
300 (void *lkp_priv, const char *, const char *, void **del_privp);
301 void (*delete)
302 (void *del_priv, nss_backend_constr_t);
303 struct nss_backend_finder *next;
304 void *lookup_priv;
305 };
306
307 typedef struct nss_backend_finder nss_backend_finder_t;
308
309 extern nss_backend_finder_t *nss_default_finders;
310
311 /*
312 * Frontend parameters
313 * -------------------
314 *
315 * The frontend must tell the switch engine:
316 * - the database name,
317 * - the compiled-in default configuration entry.
318 * It may also override default values for:
319 * - the database name to use when looking up the configuration
320 * information (e.g. "shadow" uses the config entry for "passwd"),
321 * - a limit on the number of instances of each backend that are
322 * simultaneously active,
323 * - a limit on the number of instances of each backend that are
324 * simultaneously dormant (waiting for new requests),
325 * - a flag that tells the switch engine to use the default configuration
326 * entry and ignore any other config entry for this database,
327 * - backend-finders (see above)
328 * - a cleanup routine that should be called when these parameters are
329 * about to be deleted.
330 *
331 * In order to do this, the frontend includes a pointer to an initialization
332 * function (nss_db_initf_t) in every nss_*() call. When necessary (normally
333 * just on the first invocation), the switch engine allocates a parameter
334 * structure (nss_db_params_t), fills in the default values, then calls
335 * the initialization function, which should update the parameter structure
336 * as necessary.
337 *
338 * (This might look more natural if we put nss_db_initf_t in nss_db_root_t,
339 * or abolished nss_db_initf_t and put nss_db_params_t in nss_db_root_t.
340 * It's done the way it is for shared-library efficiency, namely:
341 * - keep the unshared data (nss_db_root_t) to a minimum,
342 * - keep the symbol lookups and relocations to a minimum.
343 * In particular this means that non-null pointers, e.g. strings and
344 * function pointers, in global data are a bad thing).
345 */
346
347 enum nss_dbp_flags {
348 NSS_USE_DEFAULT_CONFIG = 0x1
349 };
350
351 struct nss_db_params {
352 const char *name; /* Mandatory: database name */
353 const char *config_name; /* config-file database name */
354 const char *default_config; /* Mandatory: default config */
355 unsigned max_active_per_src;
356 unsigned max_dormant_per_src;
357 enum nss_dbp_flags flags;
358 nss_backend_finder_t *finders;
359 void *private; /* Not used by switch */
360 void (*cleanup)(struct nss_db_params *);
361 };
362
363 typedef struct nss_db_params nss_db_params_t;
364
365 typedef void (*nss_db_initf_t)(nss_db_params_t *);
366
367 /*
368 * DBD param offsets in NSS2 nscd header.
369 * Offsets are relative to beginning of dbd section.
370 * 32 bit offsets should be sufficient, forever.
371 * 0 offset == NULL
372 * flags == nss_dbp_flags
373 */
374 typedef struct nss_dbd {
375 uint32_t o_name;
376 uint32_t o_config_name;
377 uint32_t o_default_config;
378 uint32_t flags;
379 } nss_dbd_t;
380
381 /*
382 * These structures are defined inside the implementation of the switch
383 * engine; the interface just holds pointers to them.
384 */
385 struct nss_db_state;
386 struct nss_getent_context;
387
388 /*
389 * Finally, the two handles that frontends hold:
390 */
391
392 struct nss_db_root {
393 struct nss_db_state *s;
394 mutex_t lock;
395 };
396 typedef struct nss_db_root nss_db_root_t;
397 #define NSS_DB_ROOT_INIT { 0, DEFAULTMUTEX }
398 #define DEFINE_NSS_DB_ROOT(name) nss_db_root_t name = NSS_DB_ROOT_INIT
399
400
401 typedef struct {
402 struct nss_getent_context *ctx;
403 mutex_t lock;
404 } nss_getent_t;
405
406 #define NSS_GETENT_INIT { 0, DEFAULTMUTEX }
407 #define DEFINE_NSS_GETENT(name) nss_getent_t name = NSS_GETENT_INIT
408
409 /*
410 * Policy Engine Configuration
411 * ---------------------------
412 *
413 * When nscd is running it can reconfigure it's internal policy engine
414 * as well as advise an application's front-end and policy engine on how
415 * respond optimally to results being returned from nscd. This is done
416 * through the policy engine configuration interface.
417 */
418
419 typedef enum {
420 NSS_CONFIG_GET,
421 NSS_CONFIG_PUT,
422 NSS_CONFIG_ADD,
423 NSS_CONFIG_DELETE,
424 NSS_CONFIG_LIST
425 } nss_config_op_t;
426
427 struct nss_config {
428 char *name;
429 nss_config_op_t cop;
430 mutex_t *lock;
431 void *buffer;
432 size_t length;
433 };
434 typedef struct nss_config nss_config_t;
435
436
437 extern nss_status_t nss_config(nss_config_t **, int);
438
439 extern nss_status_t nss_search(nss_db_root_t *, nss_db_initf_t,
440 int search_fnum, void *search_args);
441 extern nss_status_t nss_getent(nss_db_root_t *, nss_db_initf_t, nss_getent_t *,
442 void *getent_args);
443 extern void nss_setent(nss_db_root_t *, nss_db_initf_t, nss_getent_t *);
444 extern void nss_endent(nss_db_root_t *, nss_db_initf_t, nss_getent_t *);
445 extern void nss_delete(nss_db_root_t *);
446
447 extern nss_status_t nss_pack(void *, size_t, nss_db_root_t *,
448 nss_db_initf_t, int, void *);
449 extern nss_status_t nss_pack_ent(void *, size_t, nss_db_root_t *,
450 nss_db_initf_t, nss_getent_t *);
451 extern nss_status_t nss_unpack(void *, size_t, nss_db_root_t *,
452 nss_db_initf_t, int, void *);
453 extern nss_status_t nss_unpack_ent(void *, size_t, nss_db_root_t *,
454 nss_db_initf_t, nss_getent_t *, void *);
455
456 extern nss_status_t _nsc_search(nss_db_root_t *, nss_db_initf_t,
457 int search_fnum, void *search_args);
458 extern nss_status_t _nsc_getent_u(nss_db_root_t *, nss_db_initf_t,
459 nss_getent_t *, void *getent_args);
460 extern nss_status_t _nsc_setent_u(nss_db_root_t *, nss_db_initf_t,
461 nss_getent_t *);
462 extern nss_status_t _nsc_endent_u(nss_db_root_t *, nss_db_initf_t,
463 nss_getent_t *);
464
465
466 #ifdef __cplusplus
467 }
468 #endif
469
470 #endif /* _NSS_COMMON_H */