Update X.509 documentation (Issue #1182)

diff --git a/CHANGES.md b/CHANGES.md
index 8fe45e6983060f2fc72810ccd8954dd183c978fe..abebe5dec9e2bfc16de62889b1aa086fd599623b 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -35,7 +35,7 @@ Changes in CUPS v2.5b1 (YYYY-MM-DD)
 - Added new `cupsGetClock` API.
 - Added new `cupsParseOptions2` API with "end" argument.
 - Added `cups-oauth` and `cups-x509` utilities (Issue #1184)
-- Updated documentation (Issue #984, Issue #1086)
+- Updated documentation (Issue #984, Issue #1086, Issue #1182)
 - Updated the configure script to default to installing to /usr/local.
 - Updated CUPS to require TLS support - OpenSSL, GNUTLS and LibreSSL are
   supported.

diff --git a/doc/help/man-client.conf.html b/doc/help/man-client.conf.html
index 7ab8bf1bf249b09a5e1bce6c95993cb63ab5a704..ba021f3b34834afc4ef79ceef4bfdc74a2253edf 100644 (file)
--- a/doc/help/man-client.conf.html
+++ b/doc/help/man-client.conf.html
@@ -138,6 +138,31 @@ The default is "Minimal".
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ValidateCerts No</strong><br>
 Specifies whether to only allow TLS with certificates whose common name matches the hostname.
 The default is &quot;No&quot;.
+</p>
+    <h2 id="client.conf-5.x.509-certificate-store">X.509 Certificate Store</h2>
+<p>CUPS uses the system root CA certificate store and per-user certificate stores managed by CUPS.
+The per-user certificate stores are found in &quot;/etc/cups/ssl&quot; for the root user and &quot;$XDG_CONFIG_HOME/cups/ssl&quot; (Linux/*BSD), &quot;$HOME/Library/Application Support/cups/ssl&quot; (macOS), &quot;%USERPROFILE%/AppData/Local/cups&quot; (Windows), and/or &quot;$HOME/.cups/ssl&quot; for other user accounts.
+</p>
+    <p>Certificates, certificate signing requests, and private keys are stored as PEM-encoded files with the naming convention &quot;COMMON-NAME.crt&quot; for certificates, &quot;COMMON-NAME.csr&quot; for certificate signing requests, and &quot;COMMON-NAME.key&quot; for private keys. The special common name &quot;_site_&quot; is used for a site-specific root certificate that can be used for trust evaluations.
+</p>
+    <h2 id="client.conf-5.x.509-certificate-validation">X.509 Certificate Validation</h2>
+<p>CUPS supports validation of the certificate's commonName and subjectAltName field values, the certificate expiration date, and the certificate's root certificate(s), if any.
+Self-signed certificates are &quot;pinned&quot; (stored) to the host in order to do validation.
+Validation for certain non-printing servers may add additional restrictions to the policy defined in the
+<strong>client.conf</strong>
+file, for example OAuth authorization requires a CA-signed certificate.
+</p>
+    <p>The
+<strong>AllowAnyRoot</strong>
+directive controls whether unpinned self-signed certificates are acceptable.
+The
+<strong>TrustOnFirstUse</strong>
+directive controls whether self-certificates are automatically pinned in the per-user certificate store for subsequent host validations.
+When
+<strong>AllowAnyRoot</strong>
+is disabled,
+<strong>TrustOnFirstUse</strong>
+is also disabled.
 </p>
     <h2 id="client.conf-5.notes">Notes</h2>
 <p>Because of sandboxing, the <strong>client.conf</strong> file is not generally accessible to applications on macOS.

diff --git a/man/client.conf.5 b/man/client.conf.5
index ce52d22d311ee2ed93720bf9e5d5cab2fe03ece3..650ed8927a32cb35691b37f11f0420ef4bb2998f 100644 (file)
--- a/man/client.conf.5
+++ b/man/client.conf.5
@@ -8,7 +8,7 @@
 .\" Licensed under Apache License v2.0.  See the file "LICENSE" for more
 .\" information.
 .\"
-.TH client.conf 5 "CUPS" "2025-02-28" "OpenPrinting"
+.TH client.conf 5 "CUPS" "2025-03-04" "OpenPrinting"
 .SH NAME
 client.conf \- client configuration file for cups (deprecated on macos)
 .SH DESCRIPTION
@@ -153,6 +153,29 @@ The default is "Minimal".
 \fBValidateCerts No\fR
 Specifies whether to only allow TLS with certificates whose common name matches the hostname.
 The default is "No".
+.SH X.509 CERTIFICATE STORE
+CUPS uses the system root CA certificate store and per-user certificate stores managed by CUPS.
+The per-user certificate stores are found in "/etc/cups/ssl" for the root user and "$XDG_CONFIG_HOME/cups/ssl" (Linux/*BSD), "$HOME/Library/Application Support/cups/ssl" (macOS), "%USERPROFILE%/AppData/Local/cups" (Windows), and/or "$HOME/.cups/ssl" for other user accounts.
+.PP
+Certificates, certificate signing requests, and private keys are stored as PEM-encoded files with the naming convention "COMMON-NAME.crt" for certificates, "COMMON-NAME.csr" for certificate signing requests, and "COMMON-NAME.key" for private keys. The special common name "_site_" is used for a site-specific root certificate that can be used for trust evaluations.
+.SH X.509 CERTIFICATE VALIDATION
+CUPS supports validation of the certificate's commonName and subjectAltName field values, the certificate expiration date, and the certificate's root certificate(s), if any.
+Self-signed certificates are "pinned" (stored) to the host in order to do validation.
+Validation for certain non-printing servers may add additional restrictions to the policy defined in the
+.B client.conf
+file, for example OAuth authorization requires a CA-signed certificate.
+.PP
+The
+.B AllowAnyRoot
+directive controls whether unpinned self-signed certificates are acceptable.
+The
+.B TrustOnFirstUse
+directive controls whether self-certificates are automatically pinned in the per-user certificate store for subsequent host validations.
+When
+.B AllowAnyRoot
+is disabled,
+.B TrustOnFirstUse
+is also disabled.
 .SH NOTES
 Because of sandboxing, the \fBclient.conf\fR file is not generally accessible to applications on macOS.
 Configuration settings can instead be viewed or changed using the