bsd-auth: Add a lot of links to the online man pages, add missing funcs

1 files changed, 89 insertions, 32 deletions

diff --git a/content/posts/WIP-how-bsd-authentication-works/index.org b/content/posts/WIP-how-bsd-authentication-works/index.org
index e0828b0..dcc6520 100644
--- a/content/posts/WIP-how-bsd-authentication-works/index.org
+++ b/content/posts/WIP-how-bsd-authentication-works/index.org
@@ -545,7 +545,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_setoption= initializes a new =authopts= struct, and sets the
+   [[https://man.openbsd.org/auth_subr.3#auth_setoption][=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.
@@ -564,7 +564,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_setstate= sets the =state= of =*as= to =s=.
+   [[https://man.openbsd.org/auth_subr.3#auth_setstate][=auth_setstate=]] sets the =state= of =*as= to =s=.
 
    @@html: <details> <summary> @@
    #+begin_src c
@@ -576,7 +576,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_getstate= return the =state= of =*as=.
+   [[https://man.openbsd.org/auth_subr.3#auth_getstate][=auth_getstate=]] return the =state= of =*as=.
 
 ** auth_setpwd / auth_getpwd
    :PROPERTIES:
@@ -632,7 +632,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_setpwd= is used to retrieve and set the [[https://man.openbsd.org/man3/getpwnam.3][password database]]
+   [[https://man.openbsd.org/auth_subr.3#auth_setpwd][=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
@@ -651,7 +651,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_getpwd= returns =as->pwd=.
+   [[https://man.openbsd.org/auth_subr.3#auth_getpwd][=auth_getpwd=]] returns =as->pwd=.
 
 ** auth_set_va_list
    :PROPERTIES:
@@ -660,7 +660,7 @@
 
    @@html: <details> <summary> @@
    #+begin_src c
-   void	auth_set_va_list(auth_session_t *as, va_list ap)
+   void auth_set_va_list(auth_session_t *as, va_list ap)
    #+end_src
    @@html: </summary> @@
    #+begin_src c
@@ -668,7 +668,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_set_va_list= copies =ap= to the =ap= field in =*as=
+   [[https://man.openbsd.org/auth_subr.3#auth_set_va_list][=auth_set_va_list=]] copies =ap= to the =ap= field in =*as=
 
 ** auth_clrenv
    :PROPERTIES:
@@ -701,9 +701,9 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_clrenv= removes all lines containing =BI_SETENV= and
+   [[https://man.openbsd.org/auth_subr.3#auth_clrenv][=auth_clrenv=]] removes all lines containing =BI_SETENV= and
    =BI_UNSETENV= from =as->spool=. This is explained under the
-   =auth_call= section.
+   [[#auth_call][=auth_call=]] section.
 
 ** auth_clroption
    :PROPERTIES:
@@ -745,7 +745,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_clroption= removes the option named =option= from =as=.
+   [[https://man.openbsd.org/auth_subr.3#auth_clroption][=auth_clroption=]] removes the option named =option= from =as=.
 
 ** auth_clroptions
    :PROPERTIES:
@@ -769,7 +769,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_clroptions= clears all options from =as=.
+   [[https://man.openbsd.org/auth_subr.3#auth_clroptions][=auth_clroptions=]] clears all options from =as=.
 
 ** auth_setenv
    :PROPERTIES:
@@ -832,7 +832,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_setenv= scans through =as->spool=, modifying the environment
+   [[https://man.openbsd.org/auth_subr.3#auth_setenv][=auth_setenv=]] scans through =as->spool=, modifying the environment
    according to =BI_SETENV= and =BI_UNSETENV= instructions.
 
 ** auth_getvalue
@@ -921,7 +921,7 @@
    #+end_src
    @@html: </details> @@
 
-   =auth_getvalue= scans =as->spool= looking for lines beginning with
+   [[https://man.openbsd.org/auth_subr.3#auth_getvalue~2][=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
@@ -932,6 +932,15 @@
    of the authentication module to create and return appropriately
    escaped value strings.
 
+** auth_getchallenge
+   :PROPERTIES:
+   :CUSTOM_ID: auth_getchallenge
+   :END:
+
+   The [[https://man.openbsd.org/auth_subr.3#auth_getchallenge][=auth_subr(3)=]] man page claims this function exists, but I
+   can't find it anywhere in the source code. I suspect this is an
+   error.
+
 * auth_open
   :PROPERTIES:
   :CUSTOM_ID: auth_open
@@ -955,7 +964,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_open= is used by several functions to create a new auth
+  [[https://man.openbsd.org/auth_subr.3#auth_open][=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"=.
@@ -1036,7 +1045,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_usercheck= first checks that =*name= is a valid username. This
+  [[https://man.openbsd.org/man3/authenticate.3#auth_usercheck][=auth_usercheck=]] first checks that =*name= is a valid username. This
   means that it doesn't begin with a hyphen, had a non-zero length.
 
   If =*style= is =NULL=, it checks if =*name= is in the =user:style=
@@ -1123,7 +1132,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_verify= is used as a frontend for [[#auth_call][=auth_call=]].
+  [[https://man.openbsd.org/man3/authenticate.3#auth_verify][=auth_verify=]] is used as a frontend for [[#auth_call][=auth_call=]].
 
   It creates an auth session using =auth_open= if =*as= is =NULL=.
 
@@ -1365,7 +1374,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_call= is responsible for setting up the environment,
+  [[https://man.openbsd.org/auth_subr.3#auth_call~2][=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
@@ -1859,7 +1868,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_close= is responsible for setting the environment variables,
+  [[https://man.openbsd.org/auth_subr.3#auth_close][=auth_close=]] is responsible for setting the environment variables,
   removing any files requested by the authentication module, and
   freeing =as=.
 
@@ -1960,7 +1969,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_userchallenge= is used when the authentication style requires
+  [[https://man.openbsd.org/man3/authenticate.3#auth_userchallenge][=auth_userchallenge=]] is used when the authentication style requires
   that the user be presented with a challenge, but the user cannot be
   directly interacted with over the terminal. As an example, this
   might be used in cases where the user is using S/KEY authentication
@@ -2045,7 +2054,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_challenge=, much like [[#auth_verify][=auth_verify=]] is a function that acts as
+  [[https://man.openbsd.org/auth_subr.3#auth_challenge][=auth_challenge=]], much like [[#auth_verify][=auth_verify=]] is a function that acts as
   a front-end for [[#auth_call][=auth_call=]], except used specifically for
   challenges.
 
@@ -2146,7 +2155,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_userresponse= is used to pass the user's response from
+  [[https://man.openbsd.org/man3/authenticate.3#auth_userresponse][=auth_userresponse=]] is used to pass the user's response from
   [[#auth_userchallenge][=auth_userchallenge=]] back to the authentication module. Similar to
   =auth_userchallenge=, it is also a front-end for [[#auth_call][=auth_call=]].
 
@@ -2232,20 +2241,65 @@
   #+end_src
   @@html: </details> @@
 
-  =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=.
+  [[https://man.openbsd.org/auth_subr.3#auth_check_expire][=auth_check_expire=]] is used to check if the account used for a
+  session is expired. If an account is valid, it returns =0=.
+  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=.
+  Interestingly, if there's an account name associated with the
+  session but it doesn't exist on the system, this function will still
+  return =0= instead of =-1=.
+
+* auth_check_change
+  :PROPERTIES:
+  :CUSTOM_ID: auth_check_change
+  :END:
+
+  @@html: <details> <summary> @@
+  #+begin_src c
+  quad_t auth_check_change(auth_session_t *as)
+  #+end_src
+  @@html: </summary> @@
+  #+begin_src c
+  {
+      if (as->pwd == NULL && auth_setpwd(as, NULL) < 0) {
+          as->state &= ~AUTH_ALLOW;
+          as->state |= AUTH_PWEXPIRED;	/* XXX */
+          return (-1);
+      }
+
+      if (as->pwd == NULL)
+          return (0);
+
+      if (as->pwd && (quad_t)as->pwd->pw_change) {
+          if (as->now.tv_sec == 0)
+              WRAP(gettimeofday)(&as->now, NULL);
+          if (as->now.tv_sec >= (quad_t)as->pwd->pw_change) {
+              as->state &= ~AUTH_ALLOW;
+              as->state |= AUTH_PWEXPIRED;
+          }
+          if ((quad_t)as->now.tv_sec == (quad_t)as->pwd->pw_change)
+              return (-1);
+          return ((quad_t)as->pwd->pw_change - (quad_t)as->now.tv_sec);
+      }
+      return (0);
+  }
+  #+end_src
+  @@html: </details> @@
+
+  [[https://man.openbsd.org/auth_subr.3#auth_check_change][=auth_check_change=]] is used to check if the password associated with
+  an account is expired. If the password isn't expired, it returns
+  =0=. Otherwise it returns a negative number representing the number
+  of seconds elapsed since the password expired. If there's no account
+  associated with the session, it will return =-1=.
+
+  It operates very similarly to [[#auth_check_expire][=auth_check_expire=]].
 
 * auth_approval
   :PROPERTIES:
@@ -2392,7 +2446,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_approval= is used to check a user against the [[#approval][approval script]]
+  [[https://man.openbsd.org/man3/authenticate.3#auth_approval][=auth_approval=]] is used to check a user against the [[#approval][approval script]]
   for service =type=. It is a front end for [[#auth_call][=auth_call=]]. Approval
   script types all begin with =approval-=.
 
@@ -2436,7 +2490,7 @@
   @@html: </details> @@
 
   [[https://man.openbsd.org/authenticate.3#auth_checknologin][=auth_checknologin=]] is a simple wrapper around the internal
-  =_auth_checknologin=. If the user is now allowed to login, it prints
+  [[#_auth_checknologin][=_auth_checknologin=]]. If the user is now allowed to login, it prints
   the reason and calls =exit(1)=.
 
 * auth_cat
@@ -2464,7 +2518,7 @@
   #+end_src
   @@html: </details> @@
 
-  =auth_cat= is a helper function that will write the contents of a
+  [[https://man.openbsd.org/man3/authenticate.3#auth_cat][=auth_cat=]] is a helper function that will write the contents of a
   =file= to =stdout=. It returns =0= on failure or =1= on success.
 
 * _auth_validuser
@@ -2582,4 +2636,7 @@
 
  Ask jcs about the file descriptor situation, I don't understand it
  after reading both the man page and source.
+
+ The =auth_getchallenge= function us in the =auth_subr(3)= man page
+ doesn't seem to exist in the source code.
  ---