From e19fa767be9e398213bc8cee1181724bf930dd96 Mon Sep 17 00:00:00 2001
From: Dante Catalfamo
Date: Sun, 28 Jun 2020 21:25:55 -0400
Subject: Add clarity to a couple explanations

---
 .../posts/how-bsd-authentication-works/index.org   | 26 ++++++++++++----------
 1 file changed, 14 insertions(+), 12 deletions(-)

(limited to 'content')

diff --git a/content/posts/how-bsd-authentication-works/index.org b/content/posts/how-bsd-authentication-works/index.org
index a886395..f6c46af 100644
--- a/content/posts/how-bsd-authentication-works/index.org
+++ b/content/posts/how-bsd-authentication-works/index.org
@@ -25,12 +25,11 @@ operating system called [[https://en.wikipedia.org/wiki/BSD/OS][BSD/OS]] by [[ht
 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 (=PF_LOCAL, SOCK_STREAM=, more
+scripts that communicate over IPC (=PF_LOCAL, SOCK_STREAM=,
 specifically). The program or script has no ability to interfere with
-the parent and can very easily isolate itself using =pledge(3)= or
+the parent and can very easily revoke permissions using =pledge(3)= or
 =unveil(3)=.
 
-
 This one is pretty difficult, since there seems to be very little
 information about how BSD Auth works apart from the source code
 itself. This is my best attempt to understand the flow of BSD Auth
@@ -40,10 +39,10 @@ All of the high level authentication functions are described in
 =authenticate(3)=, with the lower level functions being described in
 =auth_subr(3)=.
 
-The highest level function, and easiest to use is =auth_userokay=
-which 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.
+The highest level function, and easiest to use is =auth_userokay=. 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=
 
@@ -70,8 +69,8 @@ The return codes are defined inside of =login_cap.h= as
 - =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 =radius=, =skey=, =yubikey=, etc.
+  - 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
@@ -147,9 +146,11 @@ auth_session_t *auth_usercheck(char *name, char *style, char *type, char *passwo
 checks the login class against the =login.conf= db, along with
 confirming the login styles available.
 
-If the password is non-=NULL=, then an =auth_session_t= struct is
-created by calling =auth_open()=, then it calls (with the session
-struct as the variable =as=)
+
+If the password is non-=NULL=, then it calls =auth_open=, which
+allocates and returns the pointer to an =auth_session_t=, and sets its
+default =service= to =login=, and it's =fd= to =-1=. After that's
+returned, =auth_usercheck= calls (with =as= as the session struct)
 
 #+BEGIN_SRC c
 auth_setitem(as, AUTHV_SERVICE, "response");
@@ -191,6 +192,7 @@ auth_call(as, path, auth_getitem(as, AUTHV_STYLE), "-s",
     auth_getitem(as, AUTHV_SERVICE), "--", name, (char *)NULL);
 #+END_SRC
 
+
 #+BEGIN_SRC c
 int auth_call(auth_session_t *as, char *path, ...)
 #+END_SRC
-- 
cgit v1.2.3