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 2006 Sun Microsystems, Inc. All rights reserved.
23 * Use is subject to license terms.
24 */
25
26 /*
27 *
28 * NOTE: The interfaces documented in this file may change in a minor
29 * release. It is intended that in the future a stronger committment
30 * will be made to these interface definitions which will guarantee
31 * them across minor releases.
32 */
33
34 #ifndef _NSS_COMMON_H
35 #define _NSS_COMMON_H
36
37 #pragma ident "%Z%%M% %I% %E% SMI"
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 #if defined(__STDC__)
252 typedef nss_status_t (*nss_backend_op_t)(struct nss_backend *, void *args);
253 #else
254 typedef nss_status_t (*nss_backend_op_t)();
255 #endif
256
257 struct nss_backend {
258 nss_backend_op_t *ops;
259 int n_ops;
260 };
261 typedef struct nss_backend nss_backend_t;
262 typedef int nss_dbop_t;
263
264 #define NSS_DBOP_DESTRUCTOR 0
265 #define NSS_DBOP_ENDENT 1
266 #define NSS_DBOP_SETENT 2
267 #define NSS_DBOP_GETENT 3
268 #define NSS_DBOP_next_iter (NSS_DBOP_GETENT + 1)
269 #define NSS_DBOP_next_noiter (NSS_DBOP_DESTRUCTOR + 1)
270 #define NSS_DBOP_next_ipv6_iter (NSS_DBOP_GETENT + 3)
271
272 #define NSS_LOOKUP_DBOP(instp, n) \
273 (((n) >= 0 && (n) < (instp)->n_ops) ? (instp)->ops[n] : 0)
274
275 #define NSS_INVOKE_DBOP(instp, n, argp) (\
276 ((n) >= 0 && (n) < (instp)->n_ops && (instp)->ops[n] != 0) \
277 ? (*(instp)->ops[n])(instp, argp) \
278 : NSS_UNAVAIL)
279
280 /*
281 * Locating and instantiating backends
282 * -----------------------------------
283 *
284 * To perform step (a), the switch consults a list of backend-finder routines,
285 * passing a <database, source> pair.
286 *
287 * There is a standard backend-finder; frontends may augment or replace this
288 * in order to, say, indicate that some backends are "compiled in" with the
289 * frontend.
290 *
291 * Backend-finders return a pointer to a constructor function for the backend.
292 * (or NULL if they can't find the backend). The switch engine caches these
293 * function pointers; when it needs to perform step (b), it calls the
294 * constructor function, which returns a pointer to a new instance of the
295 * backend, properly initialized (or returns NULL).
296 */
297
298 #if defined(__STDC__)
299 typedef nss_backend_t *(*nss_backend_constr_t)(const char *db_name,
300 const char *src_name,
301 /* Hook for (unimplemented) args in nsswitch.conf */ const char *cfg_args);
302 #else
303 typedef nss_backend_t *(*nss_backend_constr_t)();
304 #endif
305
306 struct nss_backend_finder {
307 #if defined(__STDC__)
308 nss_backend_constr_t (*lookup)
309 (void *lkp_priv, const char *, const char *, void **del_privp);
310 void (*delete)
311 (void *del_priv, nss_backend_constr_t);
312 #else
313 nss_backend_constr_t (*lookup)();
314 void (*delete)();
315 #endif
316 struct nss_backend_finder *next;
317 void *lookup_priv;
318 };
319
320 typedef struct nss_backend_finder nss_backend_finder_t;
321
322 extern nss_backend_finder_t *nss_default_finders;
323
324 /*
325 * Frontend parameters
326 * -------------------
327 *
328 * The frontend must tell the switch engine:
329 * - the database name,
330 * - the compiled-in default configuration entry.
331 * It may also override default values for:
332 * - the database name to use when looking up the configuration
333 * information (e.g. "shadow" uses the config entry for "passwd"),
334 * - a limit on the number of instances of each backend that are
335 * simultaneously active,
336 * - a limit on the number of instances of each backend that are
337 * simultaneously dormant (waiting for new requests),
338 * - a flag that tells the switch engine to use the default configuration
339 * entry and ignore any other config entry for this database,
340 * - backend-finders (see above)
341 * - a cleanup routine that should be called when these parameters are
342 * about to be deleted.
343 *
344 * In order to do this, the frontend includes a pointer to an initialization
345 * function (nss_db_initf_t) in every nss_*() call. When necessary (normally
346 * just on the first invocation), the switch engine allocates a parameter
347 * structure (nss_db_params_t), fills in the default values, then calls
348 * the initialization function, which should update the parameter structure
349 * as necessary.
350 *
351 * (This might look more natural if we put nss_db_initf_t in nss_db_root_t,
352 * or abolished nss_db_initf_t and put nss_db_params_t in nss_db_root_t.
353 * It's done the way it is for shared-library efficiency, namely:
354 * - keep the unshared data (nss_db_root_t) to a minimum,
355 * - keep the symbol lookups and relocations to a minimum.
356 * In particular this means that non-null pointers, e.g. strings and
357 * function pointers, in global data are a bad thing).
358 */
359
360 enum nss_dbp_flags {
361 NSS_USE_DEFAULT_CONFIG = 0x1
362 };
363
364 struct nss_db_params {
365 const char *name; /* Mandatory: database name */
366 const char *config_name; /* config-file database name */
367 const char *default_config; /* Mandatory: default config */
368 unsigned max_active_per_src;
369 unsigned max_dormant_per_src;
370 enum nss_dbp_flags flags;
371 nss_backend_finder_t *finders;
372 void *private; /* Not used by switch */
373 void (*cleanup)(struct nss_db_params *);
374 };
375
376 typedef struct nss_db_params nss_db_params_t;
377
378 #if defined(__STDC__)
379 typedef void (*nss_db_initf_t)(nss_db_params_t *);
380 #else
381 typedef void (*nss_db_initf_t)();
382 #endif
383
384 /*
385 * DBD param offsets in NSS2 nscd header.
386 * Offsets are relative to beginning of dbd section.
387 * 32 bit offsets should be sufficient, forever.
388 * 0 offset == NULL
389 * flags == nss_dbp_flags
390 */
391 typedef struct nss_dbd {
392 uint32_t o_name;
393 uint32_t o_config_name;
394 uint32_t o_default_config;
395 uint32_t flags;
396 } nss_dbd_t;
397
398 /*
399 * These structures are defined inside the implementation of the switch
400 * engine; the interface just holds pointers to them.
401 */
402 struct nss_db_state;
403 struct nss_getent_context;
404
405 /*
406 * Finally, the two handles that frontends hold:
407 */
408
409 struct nss_db_root {
410 struct nss_db_state *s;
411 mutex_t lock;
412 };
413 typedef struct nss_db_root nss_db_root_t;
414 #define NSS_DB_ROOT_INIT { 0, DEFAULTMUTEX }
415 #define DEFINE_NSS_DB_ROOT(name) nss_db_root_t name = NSS_DB_ROOT_INIT
416
417
418 typedef struct {
419 struct nss_getent_context *ctx;
420 mutex_t lock;
421 } nss_getent_t;
422
423 #define NSS_GETENT_INIT { 0, DEFAULTMUTEX }
424 #define DEFINE_NSS_GETENT(name) nss_getent_t name = NSS_GETENT_INIT
425
426 /*
427 * Policy Engine Configuration
428 * ---------------------------
429 *
430 * When nscd is running it can reconfigure it's internal policy engine
431 * as well as advise an application's front-end and policy engine on how
432 * respond optimally to results being returned from nscd. This is done
433 * through the policy engine configuration interface.
434 */
435
436 typedef enum {
437 NSS_CONFIG_GET,
438 NSS_CONFIG_PUT,
439 NSS_CONFIG_ADD,
440 NSS_CONFIG_DELETE,
441 NSS_CONFIG_LIST
442 } nss_config_op_t;
443
444 struct nss_config {
445 char *name;
446 nss_config_op_t cop;
447 mutex_t *lock;
448 void *buffer;
449 size_t length;
450 };
451 typedef struct nss_config nss_config_t;
452
453
454 #if defined(__STDC__)
455 extern nss_status_t nss_config(nss_config_t **, int);
456
457 extern nss_status_t nss_search(nss_db_root_t *, nss_db_initf_t,
458 int search_fnum, void *search_args);
459 extern nss_status_t nss_getent(nss_db_root_t *, nss_db_initf_t, nss_getent_t *,
460 void *getent_args);
461 extern void nss_setent(nss_db_root_t *, nss_db_initf_t, nss_getent_t *);
462 extern void nss_endent(nss_db_root_t *, nss_db_initf_t, nss_getent_t *);
463 extern void nss_delete(nss_db_root_t *);
464
465 extern nss_status_t nss_pack(void *, size_t, nss_db_root_t *,
466 nss_db_initf_t, int, void *);
467 extern nss_status_t nss_pack_ent(void *, size_t, nss_db_root_t *,
468 nss_db_initf_t, nss_getent_t *);
469 extern nss_status_t nss_unpack(void *, size_t, nss_db_root_t *,
470 nss_db_initf_t, int, void *);
471 extern nss_status_t nss_unpack_ent(void *, size_t, nss_db_root_t *,
472 nss_db_initf_t, nss_getent_t *, void *);
473
474 extern nss_status_t _nsc_search(nss_db_root_t *, nss_db_initf_t,
475 int search_fnum, void *search_args);
476 extern nss_status_t _nsc_getent_u(nss_db_root_t *, nss_db_initf_t,
477 nss_getent_t *, void *getent_args);
478 extern nss_status_t _nsc_setent_u(nss_db_root_t *, nss_db_initf_t,
479 nss_getent_t *);
480 extern nss_status_t _nsc_endent_u(nss_db_root_t *, nss_db_initf_t,
481 nss_getent_t *);
482
483 #else
484 extern nss_status_t nss_config();
485
486 extern nss_status_t nss_search();
487 extern nss_status_t nss_getent();
488 extern void nss_setent();
489 extern void nss_endent();
490 extern void nss_delete();
491
492 extern int nss_pack();
493 extern int nss_pack_ent();
494 extern int nss_unpack();
495 extern int nss_unpack_ent();
496
497 extern nss_status_t _nsc_search();
498 extern nss_status_t _nsc_getent_u();
499 extern nss_status_t _nsc_setent_u();
500 extern nss_status_t _nsc_endent_u();
501 #endif
502
503 #ifdef __cplusplus
504 }
505 #endif
506
507 #endif /* _NSS_COMMON_H */