]>
Commit | Line | Data |
---|---|---|
59b3b437 | 1 | ENCRYPTION - CUPS v1.1.20 - 11/24/2003 |
4466102a | 2 | -------------------------------------- |
7428af94 | 3 | |
4 | This file describes the encryption support provided by CUPS. | |
5 | ||
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. | |
10 | ||
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. | |
14 | ||
15 | ||
16 | LEGAL STUFF | |
17 | ||
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 | |
4466102a | 20 | any encryption code, but it can link against the OpenSSL, GNU |
21 | TLS, or CDSA libraries which do. | |
7428af94 | 22 | |
23 | ||
24 | OVERVIEW OF ENCRYPTION SUPPORT IN CUPS | |
25 | ||
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 | |
4466102a | 28 | the OpenSSL, GNU TLS, or CDSA libraries and some new hooks in |
29 | the CUPS code. | |
7428af94 | 30 | |
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. | |
38 | ||
39 | The current implementation is very basic. The CUPS client | |
40 | software (lp, lpr, etc.) uses encryption as requested by the | |
1c9e0181 | 41 | user or server. |
42 | ||
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: | |
7428af94 | 47 | |
48 | Never | |
49 | ||
50 | Never do encryption. | |
51 | ||
52 | Always | |
53 | ||
54 | Always do SSL/TLS encryption using the https scheme. | |
55 | ||
56 | IfRequested | |
57 | ||
58 | Upgrade to TLS encryption if the server asks for it. | |
59 | This is the default setting. | |
60 | ||
61 | Required | |
62 | ||
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. | |
1c9e0181 | 67 | (same as using the "-E" option) |
7428af94 | 68 | |
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 | |
b1d503b0 | 73 | to 443. To provide both secure and normal methods, add a line |
74 | reading: | |
75 | ||
76 | SSLPort 443 | |
77 | ||
78 | to /etc/cups/cupsd.conf. | |
7428af94 | 79 | |
80 | ||
81 | BEFORE YOU BEGIN | |
82 | ||
4466102a | 83 | You'll need the OpenSSL, GNU TLS, or CDSA libraries from: |
7428af94 | 84 | |
4466102a | 85 | http://www.openssl.org/ |
86 | http://www.gnutls.org/ | |
87 | http://www.intel.com/labs/archive/cdsa.htm | |
7428af94 | 88 | |
89 | ||
90 | CONFIGURING WITH ENCRYPTION SUPPORT | |
91 | ||
4466102a | 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" | |
94 | option: | |
7428af94 | 95 | |
96 | ./configure --enable-ssl | |
97 | ||
4466102a | 98 | If the library stuff is not in a standard location, make sure to |
7428af94 | 99 | define the CFLAGS, CXXFLAGS, and LDFLAGS environment variables |
100 | with the appropriate compiler and linker options first. | |
101 | ||
102 | ||
103 | GENERATING A SERVER CERTIFICATE AND KEY | |
104 | ||
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 | |
108 | Netscape and MSIE: | |
109 | ||
110 | openssl req -new -x509 -keyout /etc/cups/ssl/server.key \ | |
111 | -out /etc/cups/ssl/server.crt -days 365 -nodes | |
112 | ||
113 | chmod 600 /etc/cups/ssl/server.* | |
114 | ||
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! | |
119 | ||
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... | |
123 | ||
124 | ||
125 | REPORTING PROBLEMS | |
126 | ||
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. | |
133 | ||
134 | If you are running a version of Linux, be sure to provide the | |
135 | Linux distribution you have, too. | |
136 | ||
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 | |
142 | resources available. |