From f5581b25d0476ec02c87e89b1211e8fd7659a57a Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Tue, 25 Jan 2022 18:09:21 -0500 Subject: 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 7a7a07700..3740c5f7b 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 3466cf345..bba09b155 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. -- cgit v1.2.1