bsd-auth: wording of several headings

1 files changed, 13 insertions, 8 deletions

diff --git a/content/posts/WIP-how-bsd-authentication-works/index.org b/content/posts/WIP-how-bsd-authentication-works/index.org
index 35316d7..46a6bf6 100644
--- a/content/posts/WIP-how-bsd-authentication-works/index.org
+++ b/content/posts/WIP-how-bsd-authentication-works/index.org
@@ -142,12 +142,13 @@
       challenge-response methods.
     - If =password= is specified, then it's non-interactively tested
 
-  =auth_userokay= is just a wrapper around =auth_usercheck=, which
-  returns a finished auth session of type =auth_session_t=. It closes
-  the auth session using =auth_close= and returns the value returned
-  from closing.
+  =auth_userokay= is just a wrapper around =auth_usercheck=. It takes
+  care of closing the session for you, and returns =0= instead of
+  =NULL= on failure.
 
 * auth_session_t
+  =auth_session_t= is the main data structure used to represent the
+  authentication session. It gets used by all other functions.
 
   #+BEGIN_SRC c
   struct auth_session_t {
@@ -196,6 +197,8 @@
   };
   #+END_SRC
 
+  There are several functions which get used to operate on
+  =auth_session_t= to keep it opaque.
 ** auth_setdata
    #+begin_src c
    int auth_setdata(auth_session_t *as, void *ptr, size_t len)
@@ -211,10 +214,12 @@
    int auth_setitem(auth_session_t *as, auth_item_t item, char *value)
    #+end_src
 
-   =auth_setitem= is used to set =challenge=, =class=, =name=,
-   =service=, =style=, and =interactive= of =*as=. If =*value= is
-   =NULL=, it clears that item. If =item= is =AUTHV_ALL= and =*value=
-   is =NULL=, all fields are cleared. It returns =0= on success.
+   =auth_setitem= is used to set one of several different fields of
+   =*as= to =*value=. Depending on the value of =item=, it can be the
+   =challenge=, =class=, =name=, =service=, =style=, or =interactive=
+   field. If =*value= is =NULL=, it clears that field. If =item= is
+   =AUTHV_ALL= and =*value= is =NULL=, all fields are cleared. It
+   returns =0= on success.
 
 *** auth_item_t
     =auth_item_t= is an enum defined in =/include/bsd_auth.h=.