xref: /illumos-gate/usr/src/head/nss_common.h (revision bbf21555)
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(5):
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(5))
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 */
471