#+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 ~ 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 and returns the value returned from =auth_close=. =auth_usercheck= From there it calls a couple other functions, constructing and filling out an =auth_session_t= struct using the =auth_set*= functions from =auth_subr(3)=. It contains things like the user name, login class, along with other details required to authenticate the user. # FILL THIS PART OUT MORE! #+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 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) 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.