bsd-auth: Do a lot more function documenting

1 files changed, 30 insertions, 11 deletions

diff --git a/content/posts/WIP-how-bsd-authentication-works/index.org b/content/posts/WIP-how-bsd-authentication-works/index.org
index e1a3f33..ec601ce 100644
--- a/content/posts/WIP-how-bsd-authentication-works/index.org
+++ b/content/posts/WIP-how-bsd-authentication-works/index.org
@@ -196,9 +196,9 @@
       challenge-response methods.
     - If =password= is specified, then it's non-interactively tested
 
-  =auth_userokay= is just a wrapper around [[#auth_usercheck][=auth_usercheck=]] that
-  takes care of closing the session using [[#auth_close][=auth_close=]] for you,
-  returning the resulting value.
+  =auth_userokay= is just a wrapper around [[#auth_usercheck][=auth_usercheck=]] that takes
+  care of closing the session using [[#auth_close][=auth_close=]], and returning the
+  resulting value.
 
 * auth_session_t
   :PROPERTIES:
@@ -579,6 +579,12 @@
    =auth_setpwd= is used to retrieve and set the [[https://man.openbsd.org/man3/getpwnam.3][password database]]
    entry in =as= if one isn't already set.
 
+   If a passwd entry is passed in through =pwd=, it uses that to set
+   =as->pwd=. If =pwd= is =NULL=, it tries to find the passwd entry
+   associated with =as->name=. If it finds one, it sets =as->pwd= and
+   returns =0=. If there is no entry with that username, it returns
+   =1=.
+
 ** auth_set_va_list
    :PROPERTIES:
    :CUSTOM_ID: auth_set_va_list
@@ -903,8 +909,8 @@
   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/man3/getpwnam.3#getpwnam_r][=getpwman_r(3)=]], which operates on the [[https://man.openbsd.org/passwd.5][=passwd(5)=]] database. After
+  it 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.
 
@@ -932,8 +938,7 @@
 
   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.
+  [[#auth_verify][=auth_verify=]]. Finally it returns the auth session pointer.
 
   #+begin_src c
   as = auth_verify(as, style, name, lc->lc_class, (char *)NULL);
@@ -2095,9 +2100,20 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_check_expire= is used to check whether an authentication
-  request is expired. This is used in the mainly context of
-  challenge-response authentication.
+  =auth_check_expire= is used to check if the account used for a
+  session is expired. This is used in the mainly context of
+  challenge-response authentication. If an account is valid, it
+  returns zero. Otherwise it returns a negative number, representing
+  the number of seconds elapsed since the account expired. If there's
+  no account associated with the session, it will return =-1=.
+
+  It first checks if =as->pwd= is set, and if it isn't it tries to set
+  it using [[#auth_setpwd][=auth_setpwd=]]. If both of those fail, then it returns =-1=
+  and removes the =AUTH_ALLOW= bitmask from =as->state=, and adds the
+  bitmask for =AUTH_EXPIRED=.
+
+  Interestingly, this function will return =0= if an account doesn't
+  exist, instead of =-1=.
 
   <<here>>
 
@@ -2126,7 +2142,7 @@
   =_auth_validuser= is a small helper function used to check if a
   username passes some very basic validity criteria. Those being that
   it must not be an empty sting, and that it doesn't start with a
-  dash.
+  hyphen.
 
   If a username is invalid, it is logged in the syslog.
 
@@ -2145,6 +2161,9 @@
  The manpage also says the path is limited to =/bin/= and =/usr/bin=,
  which is also not the case.
 
+ The man page describes the interface for =auth_getitem= is in the
+ format of =AUTH_<item>=, but in reality it is =AUTHV_<item>=.
+
  Ask jcs about the file descriptor situation, I don't understand it
  after reading both the man page and source.
  ---