include/nss_common.h

   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(), and the old MT-unsafe routines
  64  *      setpwent(), getpwent(), endpwent(), 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()
 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 */