bsd-auth: Touch ups and reviews

1 files changed, 29 insertions, 27 deletions

diff --git a/content/posts/WIP-how-bsd-authentication-works/index.org b/content/posts/WIP-how-bsd-authentication-works/index.org
index 9fd5fdd..c33a1c2 100644
--- a/content/posts/WIP-how-bsd-authentication-works/index.org
+++ b/content/posts/WIP-how-bsd-authentication-works/index.org
@@ -286,7 +286,6 @@
    :PROPERTIES:
    :CUSTOM_ID: auth_setdata
    :END:
-  <<review>>
 
    @@html: <details> <summary> @@
    #+begin_src c
@@ -1052,8 +1051,11 @@
   #+end_src
   @@html: </details> @@
 
-  [[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.
+  [[https://man.openbsd.org/man3/authenticate.3#auth_usercheck][=auth_usercheck=]] is very similar to [[#auth_userokay][=auth_userokay=]]. It takes the
+  same arguments, except it returns the [[#auth_session_t][=auth_session_t=]] struct
+  instead of just the status.
+
+  It first checks that =name= is valid according to [[#_auth_validuser][=_auth_validuser=]].
 
   If =style= is =NULL=, it checks if =name= is in the =user:style=
   format, and splits it accordingly.
@@ -1163,7 +1165,7 @@
   [[#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
+  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
@@ -1419,8 +1421,8 @@
   #+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
+  or =COMM_FD= using [[https://man.openbsd.org/man2/dup.2#dup2][=dup2(3)=]]. If =as->fd=, is not =-1=, it is set to
+  file descriptor 4, or =AUTH_FD=, also using =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.
@@ -1570,17 +1572,17 @@
   #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.
 
+  If an authorization is received (any line starting with =BI_AUTH=),
+  the appropriate state is bitwise =or=-ed onto =as->state=. This
+  allows multiple authorizations, such as a case where both
+  =BI_ROOTOKAY= and =BI_SECURE= are sent. This would result in a state
+  of =AUTH_OKAY || AUTH_ROOTOKAY || AUTH_SECURE=.
+
   For any lines beginning with =BI_REMOVE=, the file names after the
   key word are sent to [[#_add_rmlist][=_add_rmlist=]].
   #+begin_src c
@@ -1987,8 +1989,7 @@
   has a pointer to string, which is used to return the challenge to
   the calling function.
 
-  It first checks that =name= is a valid username. This means that it
-  doesn't begin with a hyphen, had a non-zero length.
+  It first checks that =name= is a valid username using [[#_auth_validuser][=_auth_validuser=]].
 
   If =style= is =NULL=, it checks if =name= is in the =user:style=
   format, and splits it accordingly.
@@ -2084,9 +2085,10 @@
   auth_call(as, path, as->style, "-s", "challenge", "--", as->name, as->class, (char *)NULL);
   #+end_src
 
-  =as->state= is checked for the =AUTH_CHALLENGE= bit, and if it's
-  present, the challenge is extracted from the back channel output,
-  and used to set =as->challenge=.
+  =as->state= is checked for the =AUTH_CHALLENGE= bit, indicating the
+  auth module has returned a challenge. If it's present, the challenge
+  is extracted from the back channel output, and used to set
+  =as->challenge=.
 
   #+begin_src c
   if (as->state & AUTH_CHALLENGE)
@@ -2173,14 +2175,15 @@
   auth_setstate(as, 0);
   #+end_src
 
-  =as= is then checked to ensure all the required items are set. Then
-  it checks if =as->style= or =as->name= are =NULL=, or if the
-  username is invalid using [[#_auth_validuser][=auth_validuser=]]. If any of those checks
-  fail, and =more= is equal to =0=, then the session is closed using
+  =as= is then checked to ensure all the required items are set. It
+  checks if =as->style= or =as->name= are =NULL=, or if the username
+  is invalid using [[#_auth_validuser][=_auth_validuser=]]. If any of those checks fail, and
+  =more= is equal to =0=, then the session is closed using
   [[#auth_close][=auth_close=]], and the return value of that returned. Otherwise =0=
   is returned.
 
-  Then the path to the [[#modules][auth module]] is created.
+  Then the path to the [[#modules][auth module]] is created similarly to how it is
+  created in [[#auth_verify][auth_verify]].
 
   The challenge and class of the session are extracted and stored in
   variables =challenge= and =class= respectively.
@@ -2203,7 +2206,8 @@
   If the request is allowed, it's checked to make sure it's not
   expired using [[#auth_check_expire][=auth_check_expire=]].
 
-  If =more= is equal to =0=, the session is closed using [[#auth_close][=auth_close=]].
+  If =more= is equal to =0=, the session is closed using [[#auth_close][=auth_close=]]
+  and the return value from it is returned.
 
   The allow state of the session is then returned.
 
@@ -2429,10 +2433,6 @@
   and removes the =AUTH_ALLOW= bitmask from =as->state=, and adds the
   bitmask for =AUTH_EXPIRED=.
 
-  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
@@ -2618,6 +2618,8 @@
 
   If a username is invalid, it is logged in the syslog.
 
+  It returns =1= if the username is valid, otherwise it returns =0=.
+
 * _auth_checknologin
   :PROPERTIES:
   :CUSTOM_ID: _auth_checknologin