git.gag.com Git - debian/sudo/blob - 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     short flags;                /* various flags, see below */
  11     short 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) __P((struct passwd *pw, char **prompt, sudo_auth *auth));
  16     int (*setup) __P((struct passwd *pw, char **prompt, sudo_auth *auth));
  17     int (*verify) __P((struct passwd *pw, char *p, sudo_auth *auth));
  18     int (*cleanup) __P((struct passwd *pw, sudo_auth *auth));
  19 } sudo_auth;
  20
  21 The variables in the struct are as follows:
  22     flags       Bitwise binary flags, see below.
  23
  24     status      Contains the return value from the last run of
  25                 the "verify" function.  Starts out as AUTH_FAILURE.
  26
  27     name        The name of the authentication method as a C string.
  28
  29     data        A pointer to method-specific data.  This is passed to
  30                 all the functions of an auth method and is usually
  31                 initialized in the "init" or "setup" routines.
  32
  33 Possible values of sudo_auth.flags:
  34     FLAG_USER           Whether or not the auth functions should run with
  35                         the euid of the invoking user instead of 0.
  36
  37     FLAG_CONFIGURED     If set then the auth method is assumed to have been
  38                         configured successfully.  All auth methods start out
  39                         with this set.  If an "init" or "setup" function
  40                         fails, this bit is cleared.
  41
  42     FLAG_ONEANDONLY     If set, this indicates that the method is the
  43                         only one in use.  Can be used by auth functions
  44                         to determine whether to return a fatal or nonfatal
  45                         error.
  46
  47 The member functions can return the following values:
  48     AUTH_SUCCESS        Function succeeded.  For a ``verify'' function
  49                         this means the user correctly authenticated.
  50
  51     AUTH_FAILURE        Function failed.  If this is an ``init'' or
  52                         ``setup'' routine, the auth method will be
  53                         marked as !configured.
  54
  55     AUTH_FATAL          A fatal error occurred.  The routine should have
  56                         written an error message to stderr and optionally
  57                         sent mail to the administrator.  (If log_error()
  58                         is called to do this, the NO_EXIT flag must be used.)
  59                         When verify_user() gets AUTH_FATAL from an auth
  60                         function it does an exit(1).
  61
  62 The functions in the struct are as follows:
  63
  64     int init(struct passwd *pw, char **prompt, sudo_auth *auth)
  65         Function to do any one-time initialization for the auth
  66         method.  All of the "init" functions are run before anything
  67         else.  A pointer to the prompt string may be used to add
  68         method-specific info to the prompt.
  69
  70     int setup(struct passwd *pw, char **prompt, sudo_auth *auth)
  71         Function to do method-specific setup.  All the "setup"
  72         routines are run before any of the "verify" routines.  A
  73         pointer to the prompt string may be used to add method-specific
  74         info to the prompt.
  75
  76     int verify(struct passwd *pw, char *p, sudo_auth *auth)
  77         Function to do user verification for this auth method.  For
  78         standalone auth methods ``p'' is the prompt string.  For
  79         normal auth methods, ``p'' is the password the user entered.
  80         Note that standalone auth methods are responsible for
  81         rerading the password themselves.
  82
  83     int cleanup(struct passwd *pw, sudo_auth *auth)
  84         Function to do per-auth method cleanup.  This is only run
  85         at the end of the authentication process, after the user
  86         has completely failed or succeeded to authenticate.
  87         The ``auth->status'' variable contains the result of the
  88         last authentication attempt which may be interesting.
  89
  90 A note about standalone methods.  Some authentication methods can't
  91 coexist with any others.  This may be because they encapsulate other
  92 methods (pam, sia) or because they have a special way of interacting
  93 with the user (securid).
  94
  95 Adding a new authentication method:
  96
  97 Each method should live in its own file.  Add prototypes for the functions
  98 in sudo_auth.h.
  99
 100 If this is a standalone method, add it to the standalone #if cascade
 101 in sudo_auth.h.  For instance, for a method, ``fooauth'', add:
 102
 103 #elif defined(HAVE_FOOAUTH)
 104 #  define AUTH_STANDALONE \
 105         AUTH_ENTRY(0, "foo", \
 106             foo_init, foo_setup, foo_verify, foo_cleanup)
 107
 108 If the method needs to run as the user, not root, replace the first
 109 parameter to AUTH_ENTRY (0) with FLAG_USER.  If you don't have a
 110 init/setup/cleanup routine, just use a NULL for that field.
 111
 112 For a normal authentication method, add it to the ``auth_switch'' in
 113 sudo_auth.c.  If ``fooauth'' is a normal auth method, its entry
 114 would look like:
 115
 116 #  ifdef HAVE_FOOAUTH
 117     AUTH_ENTRY(0, "foo", foo_init, foo_setup, foo_verify, foo_cleanup)
 118 #  endif
 119
 120 Again, if the method doesn't need to run as root, replace the 0 with
 121 FLAG_USER.  Likewise, if you don't have a init/setup/cleanup routine,
 122 just use a NULL for that field.
 123
 124 NOTE:  You should not make a method both ``standalone'' and
 125        ``normal''.  Just use the --without-passwd configure argument
 126        to disable passwd/shadow file checking and then have your
 127        auth routines check the FLAG_ONEANDONLY flag to see if
 128        they are running standalone and act accordingly.