ENCRYPTION.txt

   1 ENCRYPTION - CUPS v1.1.20 - 11/24/2003
   2 --------------------------------------
   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
  20 any encryption code, but it can link against the OpenSSL, GNU
  21 TLS, or CDSA libraries which do.
  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
  28 the OpenSSL, GNU TLS, or CDSA libraries and some new hooks in
  29 the CUPS code.
  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
  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:
  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.
  67         (same as using the "-E" option)
  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
  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.
  79
  80
  81 BEFORE YOU BEGIN
  82
  83 You'll need the OpenSSL, GNU TLS, or CDSA libraries from:
  84
  85     http://www.openssl.org/
  86     http://www.gnutls.org/
  87     http://www.intel.com/labs/archive/cdsa.htm
  88
  89
  90 CONFIGURING WITH ENCRYPTION SUPPORT
  91
  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:
  95
  96     ./configure --enable-ssl
  97
  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.
 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.