krb5 commit: Clarify certauth interface documentation

[Greg Hudson]

https://github.com/krb5/krb5/commit/f5581b25d0476ec02c87e89b1211e8fd7659a57a
commit f5581b25d0476ec02c87e89b1211e8fd7659a57a
Author: Greg Hudson <ghudson at mit.edu>
Date:   Tue Jan 25 18:09:21 2022 -0500

    Clarify certauth interface documentation
    
    Try to make it clearer that princ is the requested client principal,
    not a principal extracted from the certificate, and that the module
    must decode the certificate and inspect its attributes.  Document
    KRB5_CERTAUTH_HWAUTH_PASS in certauth_plugin.h.
    
    ticket: 9051 (new)

 doc/plugindev/certauth.rst         |   21 ++++++++++++---------
 src/include/krb5/certauth_plugin.h |   18 ++++++++++++------
 2 files changed, 24 insertions(+), 15 deletions(-)

diff --git a/doc/plugindev/certauth.rst b/doc/plugindev/certauth.rst
index 7a7a077..3740c5f 100644
--- a/doc/plugindev/certauth.rst
+++ b/doc/plugindev/certauth.rst
@@ -13,16 +13,19 @@ A certauth module implements the **authorize** method to determine
 whether a client's certificate is authorized to authenticate a client
 principal.  **authorize** receives the DER-encoded certificate, the
 requested client principal, and a pointer to the client's
-krb5_db_entry (for modules that link against libkdb5).  It returns the
+krb5_db_entry (for modules that link against libkdb5).  The method
+must decode the certificate and inspect its attributes to determine if
+it should authorize PKINIT authentication.  It returns the
 authorization status and optionally outputs a list of authentication
-indicator strings to be added to the ticket.  Beginning in release
-1.19, the authorize method can request that the hardware
-authentication bit be set in the ticket by returning
-**KRB5_CERTAUTH_HWAUTH**.  Beginning in release 1.20, the authorize method
-can return **KRB5_CERTAUTH_HWAUTH_PASS** to request that the hardware
-authentication bit be set in the ticket but otherwise defer authorization
-to another certauth module.  A module must use its own internal or
-library-provided ASN.1 certificate decoder.
+indicator strings to be added to the ticket.
+
+Beginning in release 1.19, the authorize method can request that the
+hardware authentication bit be set in the ticket by returning
+**KRB5_CERTAUTH_HWAUTH**.  Beginning in release 1.20, the authorize
+method can return **KRB5_CERTAUTH_HWAUTH_PASS** to request that the
+hardware authentication bit be set in the ticket but otherwise defer
+authorization to another certauth module.  A module must use its own
+internal or library-provided ASN.1 certificate decoder.
 
 A module can optionally create and destroy module data with the
 **init** and **fini** methods.  Module data objects last for the
diff --git a/src/include/krb5/certauth_plugin.h b/src/include/krb5/certauth_plugin.h
index 3466cf3..bba09b1 100644
--- a/src/include/krb5/certauth_plugin.h
+++ b/src/include/krb5/certauth_plugin.h
@@ -85,16 +85,22 @@ typedef void
 (*krb5_certauth_fini_fn)(krb5_context context, krb5_certauth_moddata moddata);
 
 /*
- * Mandatory: return 0 or KRB5_CERTAUTH_HWAUTH if the DER-encoded cert is
- * authorized for PKINIT authentication by princ; otherwise return one of the
- * following error codes:
+ * Mandatory: decode cert as an X.509 certificate and determine whether it is
+ * authorized to authenticate as the requested client principal princ using
+ * PKINIT.  Return 0 or KRB5_CERTAUTH_HWAUTH if the certificate is authorized.
+ * Otherwise return one of the following error codes:
+ *
  * - KRB5KDC_ERR_CLIENT_NAME_MISMATCH - incorrect SAN value
  * - KRB5KDC_ERR_INCONSISTENT_KEY_PURPOSE - incorrect EKU
  * - KRB5KDC_ERR_CERTIFICATE_MISMATCH - other extension error
- * - KRB5_PLUGIN_NO_HANDLE - the module has no opinion about cert
+ * - KRB5_PLUGIN_NO_HANDLE or KRB5_CERTAUTH_HWAUTH_PASS - the module has no
+ *   opinion about whether cert is authorized
  *
- * Returning KRB5_CERTAUTH_HWAUTH will cause the hw-authent flag to be set in
- * the issued ticket (new in release 1.19).
+ * Returning KRB5_CERTAUTH_HWAUTH will authorize the PKINIT authentication and
+ * cause the hw-authent flag to be set in the issued ticket (new in release
+ * 1.19).  Returning KRB5_CERTAUTH_HWAUTH_PASS does not authorize the PKINIT
+ * authentication, but causes the hw-authent flag to be set if another module
+ * authorizes it (new in release 1.20)
  *
  * - opts is used by built-in modules to receive internal data, and must be
  *   ignored by other modules.