doc/help/encryption.html

   1 <!doctype html>
   2 <html>
   3 <!-- SECTION: Getting Started -->
   4   <head>
   5     <title>Managing Encryption</title>
   6     <link rel="STYLESHEET" type="text/css" href="../cups-printable.css">
   7   </head>
   8   <body>
   9     <h1 class="title">Managing Encryption</h1>
  10     <p>CUPS supports TLS encryption in two ways:</p>
  11     <ol>
  12       <li>Using HTTPS (always on) as soon as a connection is established, and</li>
  13       <li>Using HTTP Upgrade to TLS (opportunistic) after the connection is established.</li>
  14     </ol>
  15     <p>CUPS supports self-signed, CA-signed, and enterprise certificates, with configurable certificate validation, cipher suite, and SSL/TLS version policies.</p>
  16     <p>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.</p>
  17
  18     <h2 class="title" id="CLIENT">Configuring Client TLS Policies</h2>
  19     <p>The <a href="man-client.conf.html"><var>client.conf</var></a> file controls the client TLS policies. The default policy is:</p>
  20     <pre class="command">
  21 AllowAnyRoot Yes
  22 AllowExpiredCerts No
  23 Encryption IfRequested
  24 SSLOptions None
  25 TrustOnFirstUse Yes
  26 ValidateCerts No
  27 </pre>
  28     <p>A client can be configured to only communicate with trusted TLS/1.1+ servers and printers by copying the corresponding certificates to the client (<a href="#PLATFORM">see below</a>) and using the following policy in the <var>client.conf</var> file or macOS<sup>&reg;</sup> printing preferences:</p>
  29     <pre class="command">
  30 AllowAnyRoot No
  31 AllowExpiredCerts No
  32 Encryption Required
  33 SSLOptions DenyTLS1.0
  34 TrustOnFirstUse No
  35 ValidateCerts Yes
  36 </pre>
  37     <p>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:</p>
  38     <pre class="command">
  39 SSLOptions AllowRC4 AllowSSL3
  40 </pre>
  41
  42     <h2 class="title" id="SERVER">Configuring Server TLS Policies</h2>
  43     <p>Two directives in the <a href="man-cups-files.conf.html"><var>cups-files.conf</var></a> file control the server (scheduler) TLS policies - <a href="man-cups-files.conf.html#CreateSelfSignedCerts"><code>CreateSelfSignedCerts</code></a> and <a href="man-cups-files.conf.html#ServerKeychain"><code>ServerKeychain</code></a>. The default policy creates self-signed certificates as needed.</p>
  44     <p>The <a href="man-cupsd.conf.html#DefaultEncryption"><code>DefaultEncryption</code></a> and <a href="man-cupsd.conf.html#Encryption"><code>Encryption</code></a> directives in the <a href="man-cupsd.conf.html"><var>cupsd.conf</var></a> file control whether encryption is used. The default configuration requires encryption for remote access whenever authentication is required.</p>
  45
  46     <h2 class="title" id="PLATFORM">Platform Differences</h2>
  47     <h3>macOS<sup>&reg;</sup></h3>
  48     <p>On macOS, client configuration settings for ordinary users are stored in the <var>~/Library/Preferences/org.cups.PrintingPrefs.plist</var> 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.</p>
  49     <h3>Windows<sup>&reg;</sup></h3>
  50     <p>On Windows, client configuration settings are controlled by the SSL/TLS Group Policy settings and certificate stores.</p>
  51     <h3>Other Platforms</h3>
  52     <p>Other platforms only use the <var>client.conf</var> file and PEM-encoded certificates (<i>hostname</i>.crt) and private keys (<i>hostname</i>.key) in the <var>/etc/cups/ssl</var> and <var>~/.cups/ssl</var> directories. If present, the <var>/etc/cups/ssl/site.crt</var> 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 <var>ssl</var> directory so they can be validated for subsequent connections.</p>
  53     <p>CUPS also supports certificates created and managed by the popular <a href="https://letsencrypt.org/">Let's Encrypt</a> certificate service, which are stored in the <var>/etc/letsencrypt/live</var> directory.</p>
  54   </body>
  55 </html>