From: Michael Sweet Date: Tue, 20 Sep 2016 02:09:55 +0000 (-0400) Subject: Document how encryption works (Issue #4876) X-Git-Tag: v2.2.1~10^2~4 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=0ebe8e7c41c0c0792c9e32e5f0f30e9247408c5f;p=thirdparty%2Fcups.git Document how encryption works (Issue #4876) --- diff --git a/doc/Makefile b/doc/Makefile index dc5add425d..de4a9f6b60 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -54,6 +54,7 @@ HELPFILES = \ help/api-ppd.html \ help/api-raster.html \ help/cgi.html \ + help/encryption.html \ help/glossary.html \ help/kerberos.html \ help/license.html \ diff --git a/doc/help/encryption.html b/doc/help/encryption.html new file mode 100644 index 0000000000..3dfa87e8a5 --- /dev/null +++ b/doc/help/encryption.html @@ -0,0 +1,55 @@ + + + + + Managing Encryption + + + +

Managing Encryption

CUPS supports TLS encryption in two ways:

Using HTTPS (always on) as soon as a connection is established, and
Using HTTP Upgrade to TLS (opportunistic) after the connection is established.

CUPS supports self-signed, CA-signed, and enterprise certificates, with configurable certificate validation, cipher suite, and SSL/TLS version policies.

Out of the box, CUPS uses a Trust On First Use ("TOFU") certificate validation policy like the popular Secure Shell (ssh) software, requires TLS/1.0 or higher, only allows secure cipher suites, and automatically creates a "self-signed" certificate and private key for the scheduler so that remote administration operations and printer sharing are encrypted by default.

+ +

Configuring Client TLS Policies

The client.conf file controls the client TLS policies. The default policy is:

+AllowAnyRoot Yes
+AllowExpiredCerts No
+Encryption IfRequested
+SSLOptions None
+TrustOnFirstUse Yes
+ValidateCerts No
+

A client can be configured to only communicate with trusted TLS/1.1+ servers and printers by copying the corresponding certificates to the client (see below) and using the following policy in the client.conf file or macOS^® printing preferences:

+AllowAnyRoot No
+AllowExpiredCerts No
+Encryption Required
+SSLOptions DenyTLS1.0
+TrustOnFirstUse No
+ValidateCerts Yes
+

Similarly, if a client needs to support an older server that only supports SSL/3.0 and RC4 cipher suites you can use the following policy option:

+SSLOptions AllowRC4 AllowSSL3
+

+ +

Configuring Server TLS Policies

Two directives in the cups-files.conf file control the server (scheduler) TLS policies - CreateSelfSignedCerts and ServerKeychain. The default policy creates self-signed certificates as needed.

The DefaultEncryption and Encryption directives in the cupsd.conf file control whether encryption is used. The default configuration requires encryption for remote access whenever authentication is required.

+ +

Platform Differences

macOS^®

On macOS, client configuration settings for ordinary users are stored in the ~/Library/Preferences/org.cups.PrintingPrefs.plist file. System-wide and user certificates are stored in the system and login keychains, with private CUPS keychains being used for self-signed and CUPS-managed certificates.

Windows^®

On Windows, client configuration settings are controlled by the SSL/TLS Group Policy settings and certificate stores.

Other Platforms

Other platforms only use the client.conf file and PEM-encoded certificates (hostname.crt) and private keys (hostname.key) in the /etc/cups/ssl and ~/.cups/ssl directories. If present, the /etc/cups/ssl/site.crt file defines a site-wide CA certificate that is used to validate server and printer certificates. Certificates for known servers and printers are stored by CUPS in the corresponding ssl directory so they can be validated for subsequent connections.

CUPS also supports certificates created and managed by the popular Let's Encrypt certificate service, which are stored in the /etc/letsencrypt/live directory.

+ + diff --git a/packaging/cups.list.in b/packaging/cups.list.in index 16ba1d6bc3..91c57b4feb 100644 --- a/packaging/cups.list.in +++ b/packaging/cups.list.in @@ -569,6 +569,7 @@ f 0444 root sys $DOCDIR/apple-touch-icon.png doc/apple-touch-icon.png d 0755 root sys $DOCDIR/help - f 0444 root sys $DOCDIR/help/accounting.html doc/help/accounting.html f 0444 root sys $DOCDIR/help/cgi.html doc/help/cgi.html +f 0444 root sys $DOCDIR/help/encryption.html doc/help/encryption.html f 0444 root sys $DOCDIR/help/glossary.html doc/help/glossary.html f 0444 root sys $DOCDIR/help/kerberos.html doc/help/kerberos.html f 0444 root sys $DOCDIR/help/license.html doc/help/license.html diff --git a/packaging/cups.spec.in b/packaging/cups.spec.in index 6606635daf..02908331ea 100644 --- a/packaging/cups.spec.in +++ b/packaging/cups.spec.in @@ -251,6 +251,7 @@ rm -rf $RPM_BUILD_ROOT %dir /usr/share/doc/cups/help /usr/share/doc/cups/help/accounting.html /usr/share/doc/cups/help/cgi.html +/usr/share/doc/cups/help/encryption.html /usr/share/doc/cups/help/glossary.html /usr/share/doc/cups/help/kerberos.html /usr/share/doc/cups/help/license.html