1 ENCRYPTION - CUPS v1.1.20 - 11/24/2003
2 --------------------------------------
4 This file describes the encryption support provided by CUPS.
6 WARNING: CLIENTS CURRENTLY TRUST ALL CERTIFICATES FROM SERVERS.
7 This makes the CUPS client applications vulnerable to "man in
8 the middle" attacks, so we don't recommend using this to do
9 remote administration over WANs at this time.
11 Future versions of CUPS will keep track of server certificates
12 and provide a callback/confirmation interface for accepting new
13 certificates and warning when a certificate has changed.
18 BEFORE USING THE ENCRYPTION SUPPORT, PLEASE VERIFY THAT IT IS
19 LEGAL TO DO SO IN YOUR COUNTRY. CUPS by itself doesn't include
20 any encryption code, but it can link against the OpenSSL, GNU
21 TLS, or CDSA libraries which do.
24 OVERVIEW OF ENCRYPTION SUPPORT IN CUPS
26 CUPS supports SSL/2.0, SSL/3.0, and TLS/1.0 encryption using
27 keys as large as 128-bits. Encryption support is provided via
28 the OpenSSL, GNU TLS, or CDSA libraries and some new hooks in
31 CUPS provides support for dedicated (https) and "upgrade" (TLS)
32 encryption of sessions. The "HTTP Upgrade" method is described
33 in RFC 2817; basically, the client can be secure or unsecure,
34 and the client or server initiates an upgrade to a secure
35 connection via some new HTTP fields and status codes. The HTTP
36 Upgrade method is new and no browsers we know of support it yet.
37 Stick with "https" for web browsers.
39 The current implementation is very basic. The CUPS client
40 software (lp, lpr, etc.) uses encryption as requested by the
43 The user can specify the "-E" option with the printing commands
44 to force encryption of the connection. Encryption can also be
45 specified using the Encryption directive in the client.conf file
46 or in the CUPS_ENCRYPTION environment variable:
54 Always do SSL/TLS encryption using the https scheme.
58 Upgrade to TLS encryption if the server asks for it.
59 This is the default setting.
63 Always upgrade to TLS encryption as soon as the
64 connection is made. This is different than the "Always"
65 mode above since the connection is initially unsecure
66 and the client initiates the upgrade to TLS encryption.
67 (same as using the "-E" option)
69 These keywords are also used in the cupsd.conf file to secure
70 particular locations. To secure all traffic on the server, listen
71 on port 443 (https port) instead of port 631 and change the "ipp"
72 service listing (or add it if you don't have one) in /etc/services
73 to 443. To provide both secure and normal methods, add a line
78 to /etc/cups/cupsd.conf.
83 You'll need the OpenSSL, GNU TLS, or CDSA libraries from:
85 http://www.openssl.org/
86 http://www.gnutls.org/
87 http://www.intel.com/labs/archive/cdsa.htm
90 CONFIGURING WITH ENCRYPTION SUPPORT
92 Once you have the OpenSSL, GNU TLS, or CDSA libraries installed,
93 you'll need to configure CUPS to use it with the "--enable-ssl"
96 ./configure --enable-ssl
98 If the library stuff is not in a standard location, make sure to
99 define the CFLAGS, CXXFLAGS, and LDFLAGS environment variables
100 with the appropriate compiler and linker options first.
103 GENERATING A SERVER CERTIFICATE AND KEY
105 The following OpenSSL command will generate a server certificate
106 and key that you can play with. Since the certificate is not
107 properly signed it will generate all kinds of warnings in
110 openssl req -new -x509 -keyout /etc/cups/ssl/server.key \
111 -out /etc/cups/ssl/server.crt -days 365 -nodes
113 chmod 600 /etc/cups/ssl/server.*
115 The "-nodes" option prevents the certificate and key from being
116 encrypted. The cupsd process runs in the background, detached
117 from any input source; if you encrypt these files then cupsd
118 will not be able to load them!
120 Send all rants about non-encrypted certificate and key files to
121 /dev/null. It makes sense to encrypt user files, but not for
122 files used by system processes/daemons...
127 If you have problems, READ THE DOCUMENTATION FIRST! If the
128 documentation does not solve your problems please send an email
129 to "cups-support@cups.org". Include your operating system and
130 version, compiler and version, and any errors or problems you've
131 run into. The "/var/log/cups/error_log" file should also be sent,
132 as it often helps to determine the cause of your problem.
134 If you are running a version of Linux, be sure to provide the
135 Linux distribution you have, too.
137 Please note that the "cups-support@cups.org" email address goes
138 to the CUPS developers; they are busy people, so your email may
139 go unanswered for days or weeks. In general, only general build
140 or distribution problems will actually get answered - for
141 end-user support see the "README.txt" for a summary of the