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[]: openbsd
#+KEYWORDS[]: openbsd
#+SLUG:
#+SUMMARY:
#+SHOWTOC: true

[[https://web.archive.org/web/20170327150148/http://www.penzin.net/bsdauth/]]
* History
OpenBSD is quite different from many other Unix-like operating systems
in many ways, but one way which I find interesting is the
authentication system. Most systems from AIX, Solaris, and Linux to
most BSDs including MacOS use some form of a system called Pluggable
Authentication Module (PAM). The two main implementations of PAM are
[[http://www.linux-pam.org/][Linux PAM]] and [[https://www.openpam.org/][OpenPAM]]. PAM modules are created a dynamically loaded
shared objects, which communicate using a set of standard
interfaces ([[https://linux.die.net/man/3/pam][Linux-PAM]]) ([[https://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html][OpenPAM]]). PAM is configured using the [[https://linux.die.net/man/5/pam.d][pam.d]]
directory and [[https://www.freebsd.org/cgi/man.cgi?query=pam.conf&sektion=5&apropos=0&manpath=FreeBSD+12.1-RELEASE+and+Ports][pam.conf]].

OpenBSD on the other hand uses a mechanism called BSD
Authentication. It was originally developed for a proprietary
operating system called [[https://en.wikipedia.org/wiki/BSD/OS][BSD/OS]] by [[https://en.wikipedia.org/wiki/Berkeley_Software_Design][Berkeley Software Design Inc.]], who
later donated the system. It was adopted by OpenBSD in release
2.9. BSD Auth is comparatively much simpler than PAM. Modules or,
authentication "styles", are instead stand alone applications or
scripts that communicate over IPC (=PF_LOCAL, SOCK_STREAM=,
specifically). The program or script has no ability to interfere with
the parent and can very easily revoke permissions using =pledge(3)= or
=unveil(3)=.

* Why
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.


* BSD Auth Modules
These programs or scripts are located in =/usr/libexec/auth/= with the
naming convention =login_<style>=. They take arguments in the form of

#+BEGIN_SRC shell
login_<style> [-s service] [-v key=value] user [class]
#+END_SRC

- =<style>= is the authentication method. This could be =passwd=,
  =radius=, =skey=, =yubikey=, etc.
  - There's more information about available styles in =login.conf(5)=
- =service= is the service type. Typically authentication methods will
  accept three values here, =login=, =challenge=, or =response=. Some
  styles take different service arguments, read the style's man page
  for details.
  - =login= is typically the default method
- =-v key=value= is an optional argument. This is used to pass extra
  data to the program under certain circumstances.
- =user= is the name of the user to be authenticated.
- =class= is optional and specifies the class of the user to be
  authenticated.

* Documentation
All of the high level authentication functions are described in
=authenticate(3)=, with the lower level functions being described in
=auth_subr(3)=.

* auth_userokay
The highest level function, and easiest to use is =auth_userokay=. It
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

- =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
    =passwd=, =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.

* auth_session_t

#+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

* auth_usercheck
#+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 it calls =auth_open=, which
allocates and returns the pointer to an =auth_session_t=, and sets its
default =service= to =login=, and it's =fd= to =-1=. After that's
returned, =auth_usercheck= calls (with =as= as the session struct)

#+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, login class, and =NULL= char pointer to
=auth_verify=. The last two variables are received as variable
arguments. It then returns the auth session pointer the call
returns.

* auth_verify

#+BEGIN_SRC c
auth_session_t *auth_verify(auth_session_t *as, char *style, char *name, ...)
#+END_SRC

=auth_verify= creates an auth session if =as= is =NULL=. It then sets
the user name and style of the session, if the respective arguments
are non-=NULL=. It then copies its variable arguments to the auth
session's =va_list ap=, which is used inside of =auth_call=.

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, the user name, and a =NULL=
character pointer. The return value of =auth_call= is ignored and a
pointer to the auth session is returned immediately afterwards.

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

* auth_call

#+BEGIN_SRC c
int auth_call(auth_session_t *as, char *path, ...)
#+END_SRC

<<here>>

---
note: In the man page auth_subr it says
#+begin_quote
path    The full path name of the login script to run.  The call will
             fail if path does not pass the requirements of the secure_path(3)
             function.
#+end_quote
However I don't see this enforced anywhere, I even wrote a small test
script to prove that's the case on =vfwall ~/authtest=.

The manpage also says the path is limited to =/bin/= and =/usr/bin=,
which is also not the case.

Ask jcs about the file descriptor situation, I don't understand it
after reading both the man page and source.
---

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 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.

#+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


This is the integer returned by
=auth_userokay=.

* grapgh?
# 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.