bsd-auth: much new info

1 files changed, 41 insertions, 19 deletions

diff --git a/content/posts/WIP-how-bsd-authentication-works/index.org b/content/posts/WIP-how-bsd-authentication-works/index.org
index 46a6bf6..1a77bee 100644
--- a/content/posts/WIP-how-bsd-authentication-works/index.org
+++ b/content/posts/WIP-how-bsd-authentication-works/index.org
@@ -54,10 +54,13 @@
     =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
-    usually the right choice. Read the style's man page for details.
+  - =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. =login=
+    is used to let the module know to interact with the user directly,
+    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 is no limit to the
     number of =-v= arguments. This is used to pass extra data to the
     program under certain circumstances.
@@ -260,8 +263,14 @@
 
   =auth_open= is used by several functions to create a new auth
   session. It allocates an =auth_session_t= struct on the heap, sets
-  its default =service= to =login=, it's =fd= to =-1=, and returns the
-  pointer.
+  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
 
@@ -269,13 +278,28 @@
   auth_session_t *auth_usercheck(char *name, char *style, char *type, char *password)
   #+END_SRC
 
-  =auth_usercheck= checks the user name against the passwd db. It also
-  checks the login class against the =login.conf= db, along with
-  confirming the login styles available.
+  =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=]], 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=]],
+  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=]], 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.
 
-  If the password is non-=NULL=, then it creates a new session using
-  =auth_open=. With the new session, =auth_usercheck= calls (with =as=
-  as the session struct)
+  If the password is a string, then it creates a new session using
+  =auth_open=. It then sets the session =service= to ="response"=, and
+  adds the =password= string to the session's =data=. Here the newly
+  created session is called =as=.
 
   #+BEGIN_SRC c
   auth_setitem(as, AUTHV_SERVICE, "response");
@@ -283,13 +307,11 @@
   auth_setdata(as, password, strlen(password) + 1);
   #+END_SRC
 
-  setting the service protocol to =response=, adding an empty line to
-  the session data, then adding the password as data. If the password is
-  =NULL=, it sets the =auth_session_t= pointer to =NULL=. It then passes
-  the user name, style, login class, and =NULL= char pointer to
-  =auth_verify=. The last two variables are received as variable
-  arguments. It then returns the auth session pointer the call
-  returns.
+  If the password is =NULL=, it sets the =auth_session_t= pointer to
+  =NULL=. It then passes the user name, style, login class, and =NULL=
+  char pointer to =auth_verify=. The last two variables are received
+  as variable arguments. It then returns the auth session pointer the
+  call returns.
 
 * auth_verify