#+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/]] 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)=. 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)=, with the lower level functions being described in =auth_subr(3)=. 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 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 =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. #+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 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. #+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 #+BEGIN_SRC c int auth_call(auth_session_t *as, char *path, ...) #+END_SRC <> --- 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. 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.