From: Michael R Sweet Date: Tue, 4 Mar 2025 23:00:07 +0000 (-0500) Subject: Update X.509 documentation (Issue #1182) X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=745f21c5ff9a25c3412dcd1ea5975f8ea1326559;p=thirdparty%2Fcups.git Update X.509 documentation (Issue #1182) --- diff --git a/CHANGES.md b/CHANGES.md index 8fe45e6983..abebe5dec9 100644 --- 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 7ab8bf1bf2..ba021f3b34 100644 --- a/doc/help/man-client.conf.html +++ b/doc/help/man-client.conf.html @@ -138,6 +138,31 @@ The default is "Minimal".

ValidateCerts No
Specifies whether to only allow TLS with certificates whose common name matches the hostname. The default is "No". +

+

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. +

+

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. +

+

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 +client.conf +file, for example OAuth authorization requires a CA-signed certificate. +

+

The +AllowAnyRoot +directive controls whether unpinned self-signed certificates are acceptable. +The +TrustOnFirstUse +directive controls whether self-certificates are automatically pinned in the per-user certificate store for subsequent host validations. +When +AllowAnyRoot +is disabled, +TrustOnFirstUse +is also disabled.

Notes

Because of sandboxing, the client.conf file is not generally accessible to applications on macOS. diff --git a/man/client.conf.5 b/man/client.conf.5 index ce52d22d31..650ed8927a 100644 --- 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