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.  (If log_error()
  61                         is called to do this, the NO_EXIT flag must be used.)
  62                         When verify_user() gets AUTH_FATAL from an auth
  63                         function it does an exit(1).
  64
  65 The functions in the struct are as follows:
  66
  67     int init(struct passwd *pw, sudo_auth *auth)
  68         Function to do any one-time initialization for the auth
  69         method.  All of the "init" functions are run before anything
  70         else.
  71
  72     int setup(struct passwd *pw, char **prompt, sudo_auth *auth)
  73         Function to do method-specific setup.  All the "setup"
  74         routines are run before any of the "verify" routines.  A
  75         pointer to the prompt string may be used to add method-specific
  76         info to the prompt.
  77
  78     int verify(struct passwd *pw, char *p, sudo_auth *auth)
  79         Function to do user verification for this auth method.  For
  80         standalone auth methods ``p'' is the prompt string.  For
  81         normal auth methods, ``p'' is the password the user entered.
  82         Note that standalone auth methods are responsible for
  83         rerading the password themselves.
  84
  85     int cleanup(struct passwd *pw, sudo_auth *auth)
  86         Function to do per-auth method cleanup.  This is only run
  87         at the end of the authentication process, after the user
  88         has completely failed or succeeded to authenticate.
  89         The ``auth->status'' variable contains the result of the
  90         last authentication attempt which may be interesting.
  91
  92 A note about standalone methods.  Some authentication methods can't
  93 coexist with any others.  This may be because they encapsulate other
  94 methods (pam, sia) or because they have a special way of interacting
  95 with the user (securid).
  96
  97 Adding a new authentication method:
  98
  99 Each method should live in its own file.  Add prototypes for the functions
 100 in sudo_auth.h.
 101
 102 Add the method to the ``auth_switch'' in sudo_auth.c.  Note that
 103 standalone methods must go first.  If ``fooauth'' is a normal auth
 104 method, its entry would look like:
 105
 106 #ifdef HAVE_FOOAUTH
 107 AUTH_ENTRY("foo", 0, foo_init, foo_setup, foo_verify,
 108     foo_cleanup, foo_begin_session, foo_end_session)
 109 #endif
 110
 111 If this is a standalone method, it would be:
 112
 113 #ifdef HAVE_FOOAUTH
 114 AUTH_ENTRY("foo", FLAG_STANDALONE, foo_init, foo_setup, foo_verify,
 115     foo_cleanup, foo_begin_session, foo_end_session)
 116 #endif
 117
 118 If the method needs to run as the user, not root, add FLAG_USER to
 119 the second argument in the  AUTH_ENTRY line.  If you don't have an
 120 init/setup/cleanup/begin/end routine, just use a NULL for that
 121 field.