#+TITLE: How BSD Authentication Works
#+DATE: 2020-11-02T16:49:46-05:00
#+DRAFT: true
#+DESCRIPTION:
#+TAGS[]: openbsd
#+KEYWORDS[]: openbsd
#+SLUG:
#+SUMMARY:
#+SHOWTOC: true
[[https://web.archive.org/web/20170327150148/http://www.penzin.net/bsdauth/]]
* History
:PROPERTIES:
:CUSTOM_ID: history
:END:
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 [[https://en.wikipedia.org/wiki/Pluggable_authentication_module][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 as dynamically loaded
shared objects, which communicate using a set of somewhat
standardized interfaces ([[https://linux.die.net/man/3/pam][Linux-PAM]] and [[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]]. PAM can best be described as
[[https://www.youtube.com/watch?v=-CXp3byvI1g][unstandardized black magic]].
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. The program or script has no
ability to interfere with the parent and can very easily revoke
permissions using [[https://man.openbsd.org/pledge][=pledge(2)=]] or [[https://man.openbsd.org/unveil][=unveil(2)=]]. The BSD Authentication
system of configured through [[https://man.openbsd.org/login.conf][=login.conf(5)=]].
* Why
:PROPERTIES:
:CUSTOM_ID: why
:END:
This one is pretty difficult, since there seems to be very little
information about how BSD Auth works apart from the source code
itself and the man pages, which intentionally keep the internals
opaque. This is my best attempt to understand and describe the flow
of BSD Auth.
* BSD Auth Modules
:PROPERTIES:
:CUSTOM_ID: modules
:END:
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 [[https://man.openbsd.org/login.conf][=login.conf(5)=]] under the [[https://man.openbsd.org/login.conf#AUTHENTICATION][=AUTHENTICATION=]]
header.
- =service= is the service type. Typically authentication methods
will accept one of three values here, =login=, =challenge=, or
=response=. =login= is the default if it's not specified, and is
used to let the module know to interact with the user directly
through =stdin= and =stdout=, while =challenge= and =response= are
used to pass messages back and forth through the BSD Auth API.
Each style's man page will have more details on these.
- =-v key=value= is an optional argument. There can be more than one
arguments in this style. 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.
=login= and =su= pass in extra data as =-v= flags.
#+CAPTION: Taken from [[https://man.openbsd.org/login.conf][=login.conf(5)=]]
#+BEGIN_SRC
The login(1) program provides the following through the -v option:
auth_type The type of authentication to use.
fqdn The hostname provided to login by the -h option.
hostname The name login(1) will place in the utmp file for the
remote hostname.
local_addr The local IP address given to login(1) by the -L option.
lastchance Set to "yes" when a user's password has expired but the
user is being given one last chance to login and update
the password.
login This is a new login session (as opposed to a simple
identity check).
remote_addr The remote IP address given to login(1) by the -R option.
style The style of authentication used for this user (see
approval scripts below).
The su(1) program provides the following through the -v option:
wheel Set to either "yes" or "no" to indicate if the user is in
group wheel when they are trying to become root. Some
authentication types require the user to be in group
wheel when using the su(1) program to become super user.
#+END_SRC
The auth module communicates with its caller through file
descriptor 3.
Some modules require an extra file descriptor to be passed in for
challenge/response authentication. In these cases, an extra =-v
fd=4= argument will be passed. Theoretically this =fd= can be any
number, but in practice =fd=4= is hard-coded.
Most modules also have a hidden flag =-d=, which sets the back
channel do =stdio=, presumably for debugging purposes.
* Documentation
:PROPERTIES:
:CUSTOM_ID: documentation
:END:
All of the high level authentication functions are described in
[[https://man.openbsd.org/authenticate][=authenticate(3)=]], with the lower level functions being described in
[[https://man.openbsd.org/auth_subr][=auth_subr(3)=]].
* auth_userokay
:PROPERTIES:
:CUSTOM_ID: auth_userokay
:END:
=auth_userokay= is the highest level function, and easiest to use.
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][=auth_usercheck=]], which
takes care of closing the session using =auth_close= for you,
returning the resulting value.
* auth_session_t
:PROPERTIES:
:CUSTOM_ID: auth_session_t
:END:
=auth_session_t= is the main data structure used to represent the
authentication session. It gets used by all other functions.
#+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 =MAXSPOOLSIZE=, =authdata=, =authopts=, and =rmfiles= are defined as
#+BEGIN_SRC c
#define MAXSPOOLSIZE (8*1024) /* Spool up to 8K of back info */
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
There are several functions which get used to operate on
=auth_session_t= to keep it opaque.
** auth_setdata
:PROPERTIES:
:CUSTOM_ID: auth_setdata
:END:
#+begin_src c
int auth_setdata(auth_session_t *as, void *ptr, size_t len)
#+end_src
=auth_setdata= allocates and initializes a new =authdata= struct,
storing a copy of the data from =*ptr= and =len=. It then point the
=next= field on the last =authdata= struct in =*as= to its
location. It returns =0= on success.
** auth_setitem / auth_getitem
:PROPERTIES:
:CUSTOM_ID: auth_setitem
:END:
#+begin_src c
int auth_setitem(auth_session_t *as, auth_item_t item, char *value)
#+end_src
=auth_setitem= is used to set one of several different fields of
=*as= to =*value=. Depending on the value of =item=, it can be the
=challenge=, =class=, =name=, =service=, =style=, or =interactive=
field. If =*value= is =NULL=, it clears that field. If =item= is
=AUTHV_ALL= and =*value= is =NULL=, all fields are cleared. It
returns =0= on success.
#+begin_src c
char *auth_getitem(auth_session_t *as, auth_item_t item)
#+end_src
=auth_getitem= is used to return the value of the fields listed above.
*** auth_item_t
:PROPERTIES:
:CUSTOM_ID: auth_item_t
:END:
=auth_item_t= is an enum defined in =/include/bsd_auth.h=.
#+begin_src c
typedef enum {
AUTHV_ALL,
AUTHV_CHALLENGE,
AUTHV_CLASS,
AUTHV_NAME,
AUTHV_SERVICE,
AUTHV_STYLE,
AUTHV_INTERACTIVE
} auth_item_t;
#+end_src
** auth_setoption
:PROPERTIES:
:CUSTOM_ID: auth_setoption
:END:
#+begin_src c
int auth_setoption(auth_session_t *as, char *n, char *v)
#+end_src
=auth_setoption= initializes a new =authopts= struct, and sets the
=*opt= field to a string formatted as =sprintf(%s=%s, n, v)=. It
then point the =*next= field on the last =authopts= struct in =*as=
to its location. It returns =0= on success.
** auth_setstate / auth_getstate
:PROPERTIES:
:CUSTOM_ID: auth_setstate
:END:
#+begin_src c
void auth_setstate(auth_session_t *as, int s)
#+end_src
=auth_setstate= sets the =state= of =*as= to =s=.
#+begin_src c
int auth_getstate(auth_session_t *as)
#+end_src
=auth_getstate= return the =state= of =*as=.
** auth_set_va_list
:PROPERTIES:
:CUSTOM_ID: auth_set_va_list
:END:
#+begin_src c
void auth_set_va_list(auth_session_t *as, va_list ap)
#+end_src
=auth_set_va_list= copies =ap= to the =ap= field in =*as=
** auth_clrenv
:PROPERTIES:
:CUSTOM_ID: auth_clrenv
:END:
#+begin_src c
void auth_clrenv(auth_session_t *as)
#+end_src
=auth_clrenv= removes all lines containing =BI_SETENV= and
=BI_UNSETENV= from =as->spool=. This is explained under the
=auth_call= section.
** auth_setenv
:PROPERTIES:
:CUSTOM_ID: auth_setenv
:END:
#+begin_src c
void auth_setenv(auth_session_t *as)
#+end_src
=auth_setenv= scans through =as->spool=, modifying the environment
according to =BI_SETENV= and =BI_UNSETENV= instructions.
** auth_getvalue
:PROPERTIES:
:CUSTOM_ID: auth_getvalue
:END:
#+BEGIN_SRC c
char *auth_getvalue(auth_session_t *as, char *what)
#+END_SRC
=auth_getvalue= scans =as->spool= looking for lines beginning with
=BI_VALUE=. It then checks if the next word is equal to =what=.
When it finds the desired line, it duplicates the string, converts
escape sequences in the value, and returns the newly created
string.
For convenience, the function =auth_mkvalue= can be used inside of
the authentication module to create and return appropriately
escaped value strings.
* auth_open
:PROPERTIES:
:CUSTOM_ID: auth_open
:END:
#+begin_src c
auth_session_t *auth_open(void)
#+end_src
=auth_open= is used by several functions to create a new auth
session. It allocates an [[#auth_session_t][=auth_session_t=]] struct on the heap, sets
its default =service= to that defined by =LOGIN_DEFSERVICE= in
=/include/login_cap.h=, which is currently ="login"=.
#+begin_src c
#define LOGIN_DEFSERVICE "login"
#+end_src
It then sets the =fd= field to =-1=, and returns the pointer.
* auth_usercheck
:PROPERTIES:
:CUSTOM_ID: auth_usercheck
:END:
#+BEGIN_SRC c
auth_session_t *auth_usercheck(char *name, char *style, char *type, char *password)
#+END_SRC
=auth_usercheck= first checks that =*name= doesn't begin with a
hyphen, and that it's not too long.
If =*style= is =NULL=, it checks if =*name= is in the =user:style=
format, and splits it accordingly.
It then gets the user's password database entry through
[[https://man.openbsd.org/man3/getpwnam.3#getpwnam_r][=getpwman_r(3)=]], which operates on the [[https://man.openbsd.org/passwd.5][=passwd(5)=]] database. It then
uses that to retrieve the user's login class using
[[https://man.openbsd.org/login_getclass#login_getclass][=login_getclass(3)=]], which returns a =login_cap_t=. Login classes
are stored in the [[https://man.openbsd.org/man5/login.conf.5][=login.conf(5)=]] database.
That struct is then passed into [[https://man.openbsd.org/login_getclass#login_getstyle][=login_getstyle(3)=]], which also
received the =*style= and =*type=. If =*type= is =NULL=, it returns
the first available login style for that class. If =*style= is
specified, it is returned if available, otherwise =NULL= is
returned, which causes =auch_usercheck= to return =NULL= as well.
It then creates a pointer =as= of type [[#auth_session_t][=auth_session_t=]], and handles
it differently based on whether =*password= is =NULL=.
- If the password is a string, it creates a new session using
[[#auth_open][=auth_open=]] and assigns it to =as=. It then sets the session
=service= to ="response"=, and adds the =password= string to the
session's =data=.
#+BEGIN_SRC c
auth_setitem(as, AUTHV_SERVICE, "response");
auth_setdata(as, "", 1);
auth_setdata(as, password, strlen(password) + 1);
#+END_SRC
- If =*password= is =NULL=, it sets =as= to =NULL=.
It then passes the =auth_session_t= pointer (=as=), =*name=,
=*style=, login class (=lc->lc_class=), and a =NULL= char pointer to
=auth_verify=. It then returns the auth session pointer the call
returns.
#+begin_src c
as = auth_verify(as, style, name, lc->lc_class, (char *)NULL);
// [...] some cleanup
return (as);
#+end_src
* auth_verify
:PROPERTIES:
:CUSTOM_ID: auth_verify
:END:
#+BEGIN_SRC c
auth_session_t *auth_verify(auth_session_t *as, char *style, char *name, ...)
#+END_SRC
=auth_verify= is used as a frontend for [[#auth_call][=auth_call=]].
It creates an auth session using =auth_open= if =*as= is =NULL=.
The =state= of the session is set to =0=.
It sets the =name= and =style= of the session, if the
=*style= and/or =*name= are non-=NULL=.
After that it constructs the path of the authentication module,
placing it in the variable =path=. It is constructed 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=.
#+begin_src c
snprintf(path, sizeof(path), _PATH_AUTHPROG "%s", style);
#+end_src
It then copies its variable arguments to the auth session using
[[#auth_set_va_list][=auth_set_va_list=]].
Then =auth_call= is called with the session struct, the path to the
auth module, the auth style, the "-s" flag followed by the service
(=login=, =challenge=, or =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
va_start(ap, name);
auth_set_va_list(as, ap);
auth_call(as, path, auth_getitem(as, AUTHV_STYLE), "-s",
auth_getitem(as, AUTHV_SERVICE), "--", name, (char *)NULL);
va_end(ap);
return (as);
#+END_SRC
* auth_call
:PROPERTIES:
:CUSTOM_ID: auth_call
:END:
#+BEGIN_SRC c
int auth_call(auth_session_t *as, char *path, ...)
#+END_SRC
=auth_call= is responsible for setting up the environment,
calling the modules, and communicating with them.
An array of char pointers called =argv= is allocated to hold the arguments for the
auth module.
#+BEGIN_SRC c
char *argv[64]; /* 64 args should be more than enough */
#+END_SRC
First, the variable arguments are placed in =as->ap0=.
[[#_auth_next_arg][=_auth_next_arg=]] is called once, with the result being set as the
first element in =argv=. If =as->fd= is set, add =-v= and =fd=4= to
=argv=.
Then it loops through the =optlist= and appends =-v= followed the
option for each of them.
After that the rest of the arguments are retrieved from
=_auth_next_arg= and added to the end of =argv=. Finally a =NULL= is
added to the end of =argv=.
Next 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 now calls [[https://man.openbsd.org/man2/fork.2][=fork(2)=]].
Here two constants are set for the back channel and optional
authentication file descriptors.
#+begin_src c
#define COMM_FD 3
#define AUTH_FD 4
#+end_src
In the child process, the back channel is set to file descriptor 3,
or =COMM_FD= using =dup2(3)=. If =as->fd=, is not =-1=, it is set to
file descriptor 4, or =AUTH_FD=, also using [[https://man.openbsd.org/man2/dup.2#dup2][=dup2(3)=]]. The remainder
of the file descriptors are closed using [[https://man.openbsd.org/man2/closefrom.2][=closefrom(2)=]] by calling
either =closefrom(COMM_FD + 1)= or =closefrom(AUTH_FD + 1)=,
depending on whether or not =AUTH_FD= is used.
The child process then executes the module.
#+begin_src c
execve(path, argv, auth_environ);
#+end_src
=auth_environ= is defined at the top of the file as a very minimal
environment.
#+BEGIN_SRC c
static char *auth_environ[] = {
"PATH=" _PATH_DEFPATH,
"SHELL=" _PATH_BSHELL,
NULL,
};
#+END_SRC
Where both constants are defined in =/include/paths.h=.
#+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
In the parent process, the child's end of the back channel is
closed, and so is the parent's copy of =as->fd= if it exists.
The data from =as->data= is then written to the back channel
sequentially, zeroed, and freed.
Next =as->index= is set to =0=.
The response from the authentication module is then read from the
back channel and put into =as->spool= with an optional received file
descriptor placed in =as->fd=, using [[#_auth_spool][=_auth_spool=]].
#+begin_src c
_auth_spool(as, pfd[0]);
#+end_src
Once the back channel data has finished spooling, it 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
The [[https://man.openbsd.org/login.conf][=login.conf(5)=]] man page once again goes into greater detail on
these values.
#+BEGIN_SRC
authorize The user has been authorized.
authorize secure
The user has been authorized and root should be allowed to
login even if this is not a secure terminal. This should only
be sent by authentication styles that are secure over insecure
lines.
reject Authorization is rejected. This overrides any indication that
the user was authorized (though one would question the wisdom
in sending both a reject and an authorize command).
reject challenge
Authorization was rejected and a challenge has been made
available via the value challenge.
reject silent
Authorization is rejected, but no error messages should be
generated.
remove file
If the login session fails for any reason, remove file before
termination.
setenv name value
If the login session succeeds, the environment variable name
should be set to the specified value.
unsetenv name
If the login session succeeds, the environment variable name
should be removed.
value name value
Set the internal variable name to the specified value. The
value should only contain printable characters. Several \
sequences may be used to introduce non printing characters.
These are:
\n A newline.
\r A carriage return.
\t A tab.
\xxx The character represented by the octal value xxx. The
value may be one, two, or three octal digits.
\c The string is replaced by the value of c. This allows
quoting an initial space or the \ character itself.
The following values are currently defined:
challenge
See section on challenges below.
errormsg
If set, the value is the reason authentication failed.
The calling program may choose to display this when
rejecting the user, but display is not required.
#+END_SRC
The scanner is looking for lines that begin with =BI_AUTH=,
=BI_REJECT=, or =BI_REMOVE=.
Here =as->state= is set according to the values defined on
=login_cap.h=.
#+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
If an authorization is received (any line starting with =BI_AUTH=),
the appropriate state is bitwise =or=-ed onto =as->state=, allowing
multiple authorizations, such as a case where both =BI_ROOTOKAY=,
resulting in a state of =AUTH_ROOTOKAY=, and =BI_SECURE=, resulting
in a state of =AUTH_SECURE= are both sent.
If a rejection is received (any line starting with =BI_REJECT=),
=as->state= is set according to the rejection, and the scanning is
stopped. Rejections are final and take precedence over any
authorizations.
For any lines beginning with =BI_REMOVE=, the file names after the
key word are sent to [[#_add_rmlist][=_add_rmlist=]].
#+begin_src c
_add_rmlist(as, line);
#+end_src
After scanning is complete, the resulting status is checked against
a bitmask to ensure the result is either only accept or only reject.
An =okay= value is then defined by masking the state with the value
=AUTH_ALLOW=.
#+begin_src c
okay = as->state & AUTH_ALLOW;
#+end_src
=AUTH_ALLOW= is defined in =login_cap.h=.
#+begin_src c
#define AUTH_ALLOW (AUTH_OKAY | AUTH_ROOTOKAY | AUTH_SECURE)
#+end_src
If the status results in a rejection, [[#auth_clrenv][=auth_clrenv=]] is called with
=as=. This removes any requests the login script has made to set
environment variables from =as->spool=.
=okay= is then returned to the caller.
** _auth_next_arg
:PROPERTIES:
:CUSTOM_ID: _auth_next_arg
:END:
#+BEGIN_SRC c
static char *_auth_next_arg(auth_session_t *as)
#+END_SRC
First goes through =as->ap0=, returning one argument at a time
until it hits the =NULL= character pointer. At which point it
calls =va_end(as->ap0)= and [[https://man.openbsd.org/man3/bzero.3#explicit_bzero][=explicit_bzero(3)=]]'s it.
Moves on to do the same thing for =as->ap=.
Finally when it's gone through both lists, returns =NULL=
** _auth_spool
:PROPERTIES:
:CUSTOM_ID: _auth_spool
:END:
#+begin_src c
static void _auth_spool(auth_session_t *as, int fd)
#+end_src
=_auth_spool='s job is to read data from =fd= and place it in
=as->spool=, and to update =as->index= with the length of the data
on the spool. While spooling it converts newlines to =NUL='s in
order to parse the output more easily. It also handles any file
descriptors passed through the back channel by sending them to
[[#_recv_fd][=_recv_fd=]].
#+begin_src c
// [...]
if (strcasecmp(s, BI_FDPASS) == 0)
_recv_fd(as, fd);
#+end_src
** _recv_fd
:PROPERTIES:
:CUSTOM_ID: _recv_fd
:END:
#+begin_src c
static void _recv_fd(auth_session_t *as, int fd)
#+end_src
=_recv_fd= reads control messages, also called ancillary data, from
=fd= and tries to receive a file descriptor. It does this using the
[[https://man.openbsd.org/CMSG_DATA.3][control message API]].
If it receives one and =as->fd= is equal to =-1=, it sets it to the
received file descriptor. Otherwise it closes the received file
descriptor.
** _add_rmlist
:PROPERTIES:
:CUSTOM_ID: _add_rmlist
:END:
#+begin_src c
static void _add_rmlist(auth_session_t *as, char *file)
#+end_src
=_add_rmlist= is used to add to the list of files to be removed
after authentication is complete
A =rmfiles= struct is allocated and appended to the end of the
=as->rmlist= linked list.
* auth_close
:PROPERTIES:
:CUSTOM_ID: auth_close
:END:
#+begin_src c
int auth_close(auth_session_t *as)
#+end_src
=auth_close= is responsible for setting the environment variables,
removing any files requested by the authentication module, and
freeing =as=.
First it saves the allow state of =as->state= in a variable =s=.
#+begin_src c
s = as->state & AUTH_ALLOW;
#+end_src
If =s= is equal to =0=, =as->index= is set to =0=, truncating
=as->spool= so that no further functions will be able to read from
it.
It then modifies the environment using =auth_setenv=
#+begin_src c
auth_setenv(as);
#+end_src
All =as->rmlist= structs are checked. If =s= is equal to =0=, the
files are deleted. All =rmlist= structs are then freed.
All =as->optlist= structs are freed.
All =as->data= structs are [[https://man.openbsd.org/man3/bzero.3#explicit_bzero][=explicit_bzero(3)=]]'d and then freed.
=as->pwd= is =explicit_bzero='d and freed.
All remaining structs referenced by =as= are freed.
=as= is freed.
=s= is returned.
* COMMENT note :noexport:
---
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.
---