update comments and documentation

diff --git a/doc/antora/modules/raddb/pages/sites-available/tacacs.adoc b/doc/antora/modules/raddb/pages/sites-available/tacacs.adoc
index d57f3dc8b01ede90085737baf0482b279e773097..09cfd0e3fd0927394f5e5766de76d6a898afafe1 100644 (file)
--- a/doc/antora/modules/raddb/pages/sites-available/tacacs.adoc
+++ b/doc/antora/modules/raddb/pages/sites-available/tacacs.adoc
@@ -187,18 +187,24 @@ not recommended.
 ### Recv
 
 
-
-In general, it is not necessary to set `Auth-Type` here.  The packet header
+In general, it is not necessary to set `Auth-Type` in this section.  The packet header
 contains a TACACS `Authentication-Type` with value `PAP`, `CHAP`, etc.  That value will
-be used automatically.
+be used automatically by the server to set `Auth-Type`.
 
 The only reason to set `Auth-Type` here is when you want to use a custom
-authentication method, such as `ldap`.
+authentication method, such as `ldap`.  You should ONLY set `Auth-Type := ldap` when
+the packet contains `Authentication-Type = PAP` _and_ the passwords in LDAP are stored
+in "crypt" or hashed form.
+
+
 
 
 
 
 
+LDAP authentication will only work with PAP authentication
+
+
 
 
 The automatic state machine will ensure that both User-Name
@@ -214,6 +220,8 @@ the next packet (if the client provides it)
 
 ### Send
 
+Note that "follow" is officially deprecated, and is not supported.
+
 
 
 Call an instance of `linelog` to log the authentication success
@@ -237,12 +245,29 @@ for the client to present to the user.
 
 ## Authentication-Continue
 
-This should handle ASCII methods as PAP with challenge-response.
+This section handles responses to challenges for `Authentication-Type = ASCII`
+
+i.e. The server receives an `Authentication-Start` packet
+with `Authentication-Type = ASCII`, and replies with a
+challenge.  The client returns the username or password in
+an `Authentication-Continue` packet.  The server should
+then check the username or password.
+
+The TACACS+ protocol puts the response username or password
+into the "data" field.  For simplicity, the server copies
+that field into the User-Name or User-Password attribute as
+appropriate.  This automatic copyinh means that it is a lot
+easier to understand and configure TACACS+.
 
 
 
 ### Recv
 
+Receive `Authentication-Continue` packet.  When this
+section is done and has a User-Password, the server will
+run an `authenticate ... { }` section.  It will then call
+one of the `send` sections to send the reply.
+
 
 https://tools.ietf.org/id/draft-ietf-opsawg-07.html#rfc.section.4.3
 
@@ -258,6 +283,16 @@ https://tools.ietf.org/id/draft-ietf-opsawg-07.html#rfc.section.4.3
 
 ### Send
 
+Add the arguments to whatever the user entered.
+
+
+
+Replace whatever the user entered with the following arguments
+
+
+
+Reject the request
+
 
 
 ## Accounting
@@ -342,6 +377,12 @@ server tacacs {
        authenticate MSCHAPv2 {
                mschap
        }
+#      authenticate ldap {
+#              if (Authentication-Type != PAP) {
+#                      %log.warn("The packet is not PAP.  LDAP authentication is likely to fail!")
+#              }
+#              ldap
+#      }
        authenticate ASCII {
                pap
        }
@@ -380,6 +421,15 @@ server tacacs {
                &reply.Data := "authorization-response-data"
                &reply.Argument-List := "key1=var1"
        }
+       send Authorization-Pass-Reply {
+               &reply.Authorization-Status := Pass-Repl
+               &reply.Server-Message := "authorization-response-server"
+               &reply.Data := "authorization-response-data"
+               &reply.Argument-List := "key1=var1"
+       }
+       send Authorization-Fail {
+               &reply.Authorization-Status := Fail
+       }
        recv Accounting-Request {
                detail
        }

diff --git a/raddb/sites-available/tacacs b/raddb/sites-available/tacacs
index 5c14f4ddcaca38f3e524b9d061cd70667c6584f1..035988ccd2688ad10dfe438b0664a42ee4b01afe 100644 (file)
--- a/raddb/sites-available/tacacs
+++ b/raddb/sites-available/tacacs
@@ -228,17 +228,18 @@ server tacacs {
        #
        #  ### Recv
        #
+       #
+       #  In general, it is not necessary to set `Auth-Type` in this section.  The packet header
+       #  contains a TACACS `Authentication-Type` with value `PAP`, `CHAP`, etc.  That value will
+       #  be used automatically by the server to set `Auth-Type`.
+       #
+       #  The only reason to set `Auth-Type` here is when you want to use a custom
+       #  authentication method, such as `ldap`.  You should ONLY set `Auth-Type := ldap` when
+       #  the packet contains `Authentication-Type = PAP` _and_ the passwords in LDAP are stored
+       #  in "crypt" or hashed form.
+       #
        recv Authentication-Start {
                -sql
-
-               #
-               #  In general, it is not necessary to set `Auth-Type` here.  The packet header
-               #  contains a TACACS `Authentication-Type` with value `PAP`, `CHAP`, etc.  That value will
-               #  be used automatically.
-               #
-               #  The only reason to set `Auth-Type` here is when you want to use a custom
-               #  authentication method, such as `ldap`.
-               #
        }
 
        authenticate PAP {
@@ -257,6 +258,17 @@ server tacacs {
                mschap
        }
 
+       #
+       #  LDAP authentication will only work with PAP authentication
+       #
+#      authenticate ldap {
+#              if (Authentication-Type != PAP) {
+#                      %log.warn("The packet is not PAP.  LDAP authentication is likely to fail!")
+#              }
+#
+#              ldap
+#      }
+
        #
        #  The automatic state machine will ensure that both User-Name
        #  and User-Password have been provided by this point making
@@ -313,12 +325,29 @@ server tacacs {
        #
        #  ## Authentication-Continue
        #
-       #  This should handle ASCII methods as PAP with challenge-response.
+       #  This section handles responses to challenges for `Authentication-Type = ASCII`
+       #
+       #  i.e. The server receives an `Authentication-Start` packet
+       #  with `Authentication-Type = ASCII`, and replies with a
+       #  challenge.  The client returns the username or password in
+       #  an `Authentication-Continue` packet.  The server should
+       #  then check the username or password.
+       #
+       #  The TACACS+ protocol puts the response username or password
+       #  into the "data" field.  For simplicity, the server copies
+       #  that field into the User-Name or User-Password attribute as
+       #  appropriate.  This automatic copyinh means that it is a lot
+       #  easier to understand and configure TACACS+.
        #
 
        #
        #  ### Recv
        #
+       #  Receive `Authentication-Continue` packet.  When this
+       #  section is done and has a User-Password, the server will
+       #  run an `authenticate ... { }` section.  It will then call
+       #  one of the `send` sections to send the reply.
+       #
        recv Authentication-Continue {
                #
                #       https://tools.ietf.org/id/draft-ietf-opsawg-07.html#rfc.section.4.3