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