git.gag.com Git - debian/sudo/blob - plugins/sudoers/auth/API

   1 NOTE: the Sudo auth API is subject to change
   2
   3 Purpose: to provide a simple API for authentication methods that
   4          encapsulates things nicely without turning into a maze
   5          of #ifdef's
   6
   7 The sudo_auth struct looks like this:
   8
   9 typedef struct sudo_auth {
  10     int flags;                  /* various flags, see below */
  11     int status;                 /* status from verify routine */
  12     char *name;                 /* name of the method in string form */
  13     void *data;                 /* method-specific data pointer */
  14
  15     int (*init)(struct passwd *pw, sudo_auth *auth);
  16     int (*setup)(struct passwd *pw, char **prompt, sudo_auth *auth);
  17     int (*verify)(struct passwd *pw, char *p, sudo_auth *auth);
  18     int (*cleanup)(struct passwd *pw, sudo_auth *auth);
  19     int (*begin_session)(struct passwd *pw, sudo_auth *auth);
  20     int (*end_session)(sudo_auth *auth);
  21 } sudo_auth;
  22
  23 The variables in the struct are as follows:
  24     flags       Bitwise binary flags, see below.
  25
  26     status      Contains the return value from the last run of
  27                 the "verify" function.  Starts out as AUTH_FAILURE.
  28
  29     name        The name of the authentication method as a C string.
  30
  31     data        A pointer to method-specific data.  This is passed to
  32                 all the functions of an auth method and is usually
  33                 initialized in the "init" or "setup" routines.
  34
  35 Possible values of sudo_auth.flags:
  36     FLAG_USER           Whether or not the auth functions should run with
  37                         the euid of the invoking user instead of 0.
  38
  39     FLAG_DISABLED       Set if an "init" or "setup" function fails.
  40
  41     FLAG_STANDALONE     If set, this indicates that the method must
  42                         be the only auth method configured, and that
  43                         it will prompt for the password itself.
  44
  45     FLAG_ONEANDONLY     If set, this indicates that the method is the
  46                         only one in use.  Can be used by auth functions
  47                         to determine whether to return a fatal or nonfatal
  48                         error.
  49
  50 The member functions can return the following values:
  51     AUTH_SUCCESS        Function succeeded.  For a ``verify'' function
  52                         this means the user correctly authenticated.
  53
  54     AUTH_FAILURE        Function failed.  If this is an ``init'' or
  55                         ``setup'' routine, the auth method will be
  56                         marked as !configured.
  57
  58     AUTH_FATAL          A fatal error occurred.  The routine should have
  59                         written an error message to stderr and optionally
  60                         sent mail to the administrator.
  61                         When verify_user() gets AUTH_FATAL from an auth
  62                         function it does an exit(1).
  63
  64 The functions in the struct are as follows:
  65
  66     int init(struct passwd *pw, sudo_auth *auth)
  67         Function to do any one-time initialization for the auth
  68         method.  All of the "init" functions are run before anything
  69         else.
  70
  71     int setup(struct passwd *pw, char **prompt, sudo_auth *auth)
  72         Function to do method-specific setup.  All the "setup"
  73         routines are run before any of the "verify" routines.  A
  74         pointer to the prompt string may be used to add method-specific
  75         info to the prompt.
  76
  77     int verify(struct passwd *pw, char *p, sudo_auth *auth)
  78         Function to do user verification for this auth method.  For
  79         standalone auth methods ``p'' is the prompt string.  For
  80         normal auth methods, ``p'' is the password the user entered.
  81         Note that standalone auth methods are responsible for
  82         rerading the password themselves.
  83
  84     int cleanup(struct passwd *pw, sudo_auth *auth)
  85         Function to do per-auth method cleanup.  This is only run
  86         at the end of the authentication process, after the user
  87         has completely failed or succeeded to authenticate.
  88         The ``auth->status'' variable contains the result of the
  89         last authentication attempt which may be interesting.
  90
  91 A note about standalone methods.  Some authentication methods can't
  92 coexist with any others.  This may be because they encapsulate other
  93 methods (pam, sia) or because they have a special way of interacting
  94 with the user (securid).
  95
  96 Adding a new authentication method:
  97
  98 Each method should live in its own file.  Add prototypes for the functions
  99 in sudo_auth.h.
 100
 101 Add the method to the ``auth_switch'' in sudo_auth.c.  Note that
 102 standalone methods must go first.  If ``fooauth'' is a normal auth
 103 method, its entry would look like:
 104
 105 #ifdef HAVE_FOOAUTH
 106 AUTH_ENTRY("foo", 0, foo_init, foo_setup, foo_verify,
 107     foo_cleanup, foo_begin_session, foo_end_session)
 108 #endif
 109
 110 If this is a standalone method, it would be:
 111
 112 #ifdef HAVE_FOOAUTH
 113 AUTH_ENTRY("foo", FLAG_STANDALONE, foo_init, foo_setup, foo_verify,
 114     foo_cleanup, foo_begin_session, foo_end_session)
 115 #endif
 116
 117 If the method needs to run as the user, not root, add FLAG_USER to
 118 the second argument in the  AUTH_ENTRY line.  If you don't have an
 119 init/setup/cleanup/begin/end routine, just use a NULL for that
 120 field.