path: root/content/posts/how-bsd-authentication-works/index.org

#+TITLE: How BSD Authentication Works
#+DATE: 2020-06-26T18:31:36-04:00
#+DRAFT: true
#+DESCRIPTION:
#+TAGS[]:
#+KEYWORDS[]:
#+SLUG:
#+SUMMARY:

[[https://web.archive.org/web/20170327150148/http://www.penzin.net/bsdauth/]]

This one is pretty difficult, since there seems to be very little
information about how BSD Auth works apart from the source code
itself. This is my best attempt to understand the flow of BSD Auth
from what I've read.

All of the high level authentication functions are described in
=authenticate(3)=.

~#include <bsd_auth.h>~

The highest level function, and easiest to use is =auth_userokay=
which takes four character arrays as arguments, =name=, =style=,
=type=, and =password=. It returns either a =0= for failure, of a
non-zero value for success.

This function lives inside =/lib/libc/gen/authenticate.c=

#+BEGIN_SRC c
int auth_userokay(char *name, char *style, char *type, char *password);
#+END_SRC

The return codes are defined inside of =login_cap.h= as

#+BEGIN_SRC c
/*
* bits which can be returned by authenticate()/auth_scan()
*/
#define  AUTH_OKAY       0x01            /* user authenticated */
#define  AUTH_ROOTOKAY   0x02            /* authenticated as root */
#define  AUTH_SECURE     0x04            /* secure login */
#define  AUTH_SILENT     0x08            /* silent rejection */
#define  AUTH_CHALLENGE  0x10            /* a challenge was given */
#define  AUTH_EXPIRED    0x20            /* account expired */
#define  AUTH_PWEXPIRED  0x40            /* password expired */
#+END_SRC

- =name= is the name of the user to be authenticated
- =style= is the login method to be used
  - If =style= is =NULL=, the user's default login style will be
    used. By default this is =passwd= on normal accounts.
  - The style can be one of the installed authentication methods,
    like =radius=, =skey=, =yubikey=, etc.
  - There's more information about available styles in =login.conf(5)=
  - Styles can also be installed through BSD Auth module packages
- =type= is the authentication type
  - Types are defined in =login.conf= and define a group of allowed
    auth styles
  - If =type= is =NULL=, use the auth type for the user's login
    class. The default type is =auth-default=, which allows
    =psaswd= and =skey= auth methods.
  - There's more information about how to add methods in =login.conf(5)=
- =password= is the password to test
  - If =password= is =NULL=, then the user is interactively
    prompted. This is required for auth styles using
    challenge-response methods.
  - If =password= is specified, then it's non-interactively tested

=auth_userokay= is just a wrapper around =auth_usercheck=, which
returns a finished auth session of type =auth_session_t=. It closes
the auth session using =auth_close= and returns the value returned
from closing.

#+BEGIN_SRC c
struct auth_session_t {
    char    *name;                 /* name of use being authenticated */
    char    *style;                /* style of authentication used */
    char    *class;                /* class of user */
    char    *service;              /* type of service being performed */
    char    *challenge;            /* last challenge issued */
    int     flags;                 /* see below */
    struct  passwd *pwd;           /* password entry for user */
    struct  timeval now;           /* time of authentication */

    int     state;                 /* authenticated state */

    struct  rmfiles *rmlist;       /* list of files to remove on failure */
    struct  authopts *optlist;     /* list of options to scripts */
    struct  authdata *data;        /* additional data to send to scripts */

    char    spool[MAXSPOOLSIZE];   /* data returned from login script */
    int     index;                 /* how much returned thus far */

    int     fd;                    /* connection to authenticator */

    va_list ap0;                   /* argument list to auth_call */
    va_list ap;                    /* additional arguments to auth_call */
};
#+END_SRC

Where =authdata=, =authopts=, and =rmfiles= are defined as

#+BEGIN_SRC c
struct rmfiles {
    struct rmfiles  *next;
    char            *file;
};

struct authopts {
    struct authopts *next;
    char            *opt;
};

struct authdata {
    struct  authdata *next;
    void    *ptr;
    size_t   len;
};
#+END_SRC

#+BEGIN_SRC c
auth_session_t *auth_usercheck(char *name, char *style, char *type, char *password)
#+END_SRC

=auth_usercheck= checks the user name against the passwd db. It also
checks the login class against the =login.conf= db, along with
confirming the login styles available.

If the password is non-=NULL=, then an =auth_session_t= struct is
created by calling =auth_open()=, then it calls

#+BEGIN_SRC c
auth_setitem(as, AUTHV_SERVICE, "response");
auth_setdata(as, "", 1);
auth_setdata(as, password, strlen(password) + 1);
#+END_SRC

setting the service protocol to =response=, adding an empty line to
the session data, then adding the password as data. If the password is
=NULL=, it sets the =auth_session_t= pointer to =NULL=. It then passes
the user name, style, and login class to =auth_verify=, and returns
the the auth session pointer the call returns.




After that it constructs the path of the authentication module by
combining =_PATH_AUTHPROG=, which is defined in =login_cap.h= as
=/usr/libexec/auth/login_=, and the authentication style. For the
case of auth style =passwd=, it would result in the path
=/usr/libexec/auth/login_passwd=.

Then =auth_call= is called with the struct, the path to the auth
module, the auth style, the "-s" flag followed by the service
(login, challenge, response), a double dash, and the user name.

#+BEGIN_SRC c
auth_call(as, path, auth_getitem(as, AUTHV_STYLE), "-s",
    auth_getitem(as, AUTHV_SERVICE), "--", name, (char *)NULL);
#+END_SRC

Inside of =auth_call=, a socket pair of type =PF_LOCAL,
SOCK_STREAM= is created. This is called the "back channel", and is
used to communicate between with the authentication module. The
process then forks, calling ~execve(path, argv, auth_environ)~,
where the =argv= is everything after =path= in the =auth_call=
arguments. Any =authopts= set in the auth session are also passed
as arguments in the format =-v opt1 -v opt2 -v opt3=,
etc. =auth_environ= is defined at the top of the file as

#+BEGIN_SRC c
static char *auth_environ[] = {
    "PATH=" _PATH_DEFPATH,
    "SHELL=" _PATH_BSHELL,
    NULL,
};
#+END_SRC

Where both constants are defined in =paths.h= as

#+BEGIN_SRC c
#define	_PATH_DEFPATH	"/usr/bin:/bin:/usr/sbin:/sbin:/usr/X11R6/bin:/usr/local/bin:/usr/local/sbin"
#define	_PATH_BSHELL	"/bin/sh"
#+END_SRC


The =exec='d process then listens on FD 3, which is one half of the
=sockpair= that was created earlier.

In the non-exec'd process, first the contents of the auth session's
=*data= are read in one at a time.

The data received through the back channel is then put into the
=spool= of the auth session using =_auth_spool(as, pfd[0])=. After
that the spooled data is scanned for key words defined in
=login_cap.h=.

#+BEGIN_SRC c
#define BI_AUTH         "authorize"         /* Accepted authentication */
#define BI_REJECT       "reject"            /* Rejected authentication */
#define BI_CHALLENGE    "reject challenge"  /* Reject with a challenge */
#define BI_SILENT       "reject silent"     /* Reject silently */
#define BI_REMOVE       "remove"            /* remove file on error */
#define BI_ROOTOKAY     "authorize root"    /* root authenticated */
#define BI_SECURE       "authorize secure"  /* okay on non-secure line */
#define BI_SETENV       "setenv"            /* set environment variable */
#define BI_UNSETENV     "unsetenv"          /* unset environment variable */
#define BI_VALUE        "value"             /* set local variable */
#define BI_EXPIRED      "reject expired"    /* account expired */
#define BI_PWEXPIRED    "reject pwexpired"  /* password expired */
#define BI_FDPASS       "fd"                /* child is passing an fd */
#+END_SRC

It is looking for lines that start with either =BI_AUTH=
(=authorize=), or =BI_REJECT= (=reject=). If the line is still longer,
it continues to scan for any other qualifiers such as =pwexpired= or
=silent=. The struct's =state= is set to one using the =AUTH_= values
from =login_cap.h= accordingly.

This is the integer returned by
=auth_userokay=.

# Setting env on auth_close(as)
# partual rewrite below

The call graph for =auth_userokay= looks something like this:

#+BEGIN_SRC c
int auth_userokay(char *name, char *style, char *type, char *password)
#+END_SRC

calls ~auth_usercheck~ and then calls ~auth_close~ on the returned
~auth_session_t~. The value returned from ~auth_close~ is then
returned.

#+BEGIN_SRC c
auth_session_t *auth_usercheck(char *name, char *style, char *type, char *password)
#+END_SRC

Validates the checks that the user exists, gets the user's login
class, verifies the auth type, and that the auth style can be used.

It creates an auth session struct.

If the password is provided it sets the service type to =response=,
and adds the adds the password to the auth data. Otherwise it
leaves it empty.