From 05d2dc417f808c242702ec5a02047707a51bc435 Mon Sep 17 00:00:00 2001
From: Dante Catalfamo
Date: Fri, 4 Jun 2021 14:25:48 -0400
Subject: bsd-auth: find places that need more work, begin proof reading

---
 .../WIP-how-bsd-authentication-works/index.org     | 44 ++++++++++++----------
 1 file changed, 24 insertions(+), 20 deletions(-)

diff --git a/content/posts/WIP-how-bsd-authentication-works/index.org b/content/posts/WIP-how-bsd-authentication-works/index.org
index dcc8054..a22c9e0 100644
--- a/content/posts/WIP-how-bsd-authentication-works/index.org
+++ b/content/posts/WIP-how-bsd-authentication-works/index.org
@@ -14,15 +14,15 @@
   :END:
 
   OpenBSD is quite different from many other Unix-like operating
-  systems in several ways. One which I find interesting is the
-  authentication system. Most systems from AIX, Solaris, and Linux to
-  other BSDs including MacOS use some form of a system called
-  [[https://en.wikipedia.org/wiki/Pluggable_authentication_module][Pluggable Authentication Module]] (PAM). The two main implementations
-  are [[http://www.linux-pam.org/][Linux PAM]] and [[https://www.openpam.org/][OpenPAM]]. PAM modules are created as dynamically
-  loaded shared objects, which communicate using a set of somewhat
-  standardized interfaces ([[https://linux.die.net/man/3/pam][Linux-PAM]] and [[https://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html][OpenPAM]]). It's configured
-  using the [[https://linux.die.net/man/5/pam.d][pam.d]] directory for Linux PAM and [[https://www.freebsd.org/cgi/man.cgi?query=pam.conf&sektion=5&apropos=0&manpath=FreeBSD+12.1-RELEASE+and+Ports][pam.conf]] for OpenPAM.
-  PAM can best be described as [[https://www.youtube.com/watch?v=-CXp3byvI1g][unstandardized black magic]].
+  systems. One which I find interesting is the authentication system.
+  Most systems from AIX, Solaris, and Linux to other BSDs including
+  MacOS, use a framework called [[https://en.wikipedia.org/wiki/Pluggable_authentication_module][Pluggable Authentication Module]] (PAM).
+  The two main implementations are [[http://www.linux-pam.org/][Linux PAM]] and [[https://www.openpam.org/][OpenPAM]]. PAM modules
+  are created as dynamically loaded shared objects, which communicate
+  using a combination of common and implementation specific interfaces
+  ([[https://linux.die.net/man/3/pam][Linux-PAM]] and [[https://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html][OpenPAM]]). It's configured using the [[https://linux.die.net/man/5/pam.d][pam.d]] directory
+  and [[https://www.freebsd.org/cgi/man.cgi?query=pam.conf&sektion=5&apropos=0&manpath=FreeBSD+12.1-RELEASE+and+Ports][pam.conf]] file. PAM can best be described as [[https://www.youtube.com/watch?v=-CXp3byvI1g][unstandardized black
+  magic]].
 
   OpenBSD on the other hand uses a mechanism called BSD
   Authentication. It was originally developed for a now-defunct
@@ -42,7 +42,7 @@
 
   There isn't much on the internet about how to use BSD
   Authentication. I was curious about how the internals worked, and I
-  figured someone else might be too :-).
+  figured someone else might be too :-)
 
 * Documentation
   :PROPERTIES:
@@ -63,8 +63,9 @@
   :CUSTOM_ID: modules
   :END:
 
-  These programs or scripts are located in =/usr/libexec/auth/= with the
-  naming convention =login_<style>=. They take arguments in the form of
+  Modules are located in =/usr/libexec/auth/= with the naming
+  convention =login_<style>=. They accept arguments in the following
+  form.
 
   #+BEGIN_SRC shell
   login_<style> [-s service] [-v key=value] user [class]
@@ -75,7 +76,7 @@
     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
+    will accept one of three values here: =login=, =challenge=, or
     =response=. =login= is the default if it's not specified, and is
     used to let the module know to interact with the user directly
     through =stdin= and =stdout=, while =challenge= and =response= are
@@ -135,18 +136,20 @@
   Most modules also have a hidden flag =-d=, which sets the back
   channel do =stdio=, presumably for debugging purposes.
 
+  The simplest way to authenticate a user with BSD Auth is by using
+  [[#auth_userokay][=auth_userokay=]].
+
+** TODO How are these configured in login.conf?
 * Approval Scripts
   :PROPERTIES:
   :CUSTOM_ID: approval
   :END:
 
   Approval scripts can be much simpler than the full login modules
-  used by the other functions. They may run with limited information
-  and instead of explicitly allowing or denying users with specific
-  conditions. They are given the same back-channel as auth modules,
-  but do not have to explicitly authenticate or revoke users. They
-  should exit with a zero status for approval, or non-zero status to
-  signal disapproval.
+  used by the other functions. They are given the same back-channel as
+  auth modules, but should not explicitly authenticate or revoke
+  users. They should exit with a zero status for approval, or non-zero
+  status to signal disapproval.
 
   Approval scrips receive arguments in the following form.
   #+begin_src shell
@@ -157,7 +160,8 @@
   [[#modules][auth modules]]. More information is available in the [[https://man.openbsd.org/login.conf#APPROVAL][=APPROVAL=]]
   section of the =login.conf= man page.
 
-  Approval scripts are checked using [[#auth_approval][=auth_approval=]].
+  Approval scripts are run using [[#auth_approval][=auth_approval=]].
+** TODO How are these configured in login.conf?
 
 * auth_userokay
   :PROPERTIES:
-- 
cgit v1.2.3