Merge changes from 1.1.x into 1.2 devel.

[thirdparty/cups.git] / ENCRYPTION.txt

ENCRYPTION - CUPS v1.1.7 - 02/21/2001
-------------------------------------

This file describes the encryption support provided by CUPS.

WARNING: CLIENTS CURRENTLY TRUST ALL CERTIFICATES FROM SERVERS. 
This makes the CUPS client applications vulnerable to "man in
the middle" attacks, so we don't recommend using this to do
remote administration over WANs at this time.

Future versions of CUPS will keep track of server certificates
and provide a callback/confirmation interface for accepting new
certificates and warning when a certificate has changed.


LEGAL STUFF

BEFORE USING THE ENCRYPTION SUPPORT, PLEASE VERIFY THAT IT IS
LEGAL TO DO SO IN YOUR COUNTRY.  CUPS by itself doesn't include
any encryption code, but it can link against the OpenSSL library
which does.


OVERVIEW OF ENCRYPTION SUPPORT IN CUPS

CUPS supports SSL/2.0, SSL/3.0, and TLS/1.0 encryption using
keys as large as 128-bits.  Encryption support is provided via
the OpenSSL library and some new hooks in the CUPS code.

CUPS provides support for dedicated (https) and "upgrade" (TLS)
encryption of sessions.  The "HTTP Upgrade" method is described
in RFC 2817; basically, the client can be secure or unsecure,
and the client or server initiates an upgrade to a secure
connection via some new HTTP fields and status codes.  The HTTP
Upgrade method is new and no browsers we know of support it yet.
Stick with "https" for web browsers.

The current implementation is very basic.  The CUPS client
software (lp, lpr, etc.) uses encryption as requested by the
user or server.

The user can specify the "-E" option with the printing commands
to force encryption of the connection.  Encryption can also be
specified using the Encryption directive in the client.conf file
or in the CUPS_ENCRYPTION environment variable:

    Never

        Never do encryption.

    Always

        Always do SSL/TLS encryption using the https scheme.

    IfRequested

	Upgrade to TLS encryption if the server asks for it.
	This is the default setting.

    Required

	Always upgrade to TLS encryption as soon as the
	connection is made.  This is different than the "Always"
	mode above since the connection is initially unsecure
	and the client initiates the upgrade to TLS encryption.
	(same as using the "-E" option)

These keywords are also used in the cupsd.conf file to secure
particular locations.  To secure all traffic on the server, listen
on port 443 (https port) instead of port 631 and change the "ipp"
service listing (or add it if you don't have one) in /etc/services
to 443.  To provide both secure and normal methods, add a line
reading:

    SSLPort 443

to /etc/cups/cupsd.conf.


BEFORE YOU BEGIN

You'll need the OpenSSL library from:

    http://www.openssl.org


CONFIGURING WITH ENCRYPTION SUPPORT

Once you have the OpenSSL library installed, you'll need to
configure CUPS to use it with the "--enable-ssl" option:

    ./configure --enable-ssl

If the OpenSSL stuff is not in a standard location, make sure to
define the CFLAGS, CXXFLAGS, and LDFLAGS environment variables
with the appropriate compiler and linker options first.


GENERATING A SERVER CERTIFICATE AND KEY

The following OpenSSL command will generate a server certificate
and key that you can play with.  Since the certificate is not
properly signed it will generate all kinds of warnings in
Netscape and MSIE:

    openssl req -new -x509 -keyout /etc/cups/ssl/server.key \
        -out /etc/cups/ssl/server.crt -days 365 -nodes

    chmod 600 /etc/cups/ssl/server.*

The "-nodes" option prevents the certificate and key from being
encrypted.  The cupsd process runs in the background, detached
from any input source; if you encrypt these files then cupsd
will not be able to load them!

Send all rants about non-encrypted certificate and key files to
/dev/null.  It makes sense to encrypt user files, but not for
files used by system processes/daemons...


REPORTING PROBLEMS

If you have problems, READ THE DOCUMENTATION FIRST!  If the
documentation does not solve your problems please send an email
to "cups-support@cups.org".  Include your operating system and
version, compiler and version, and any errors or problems you've
run into. The "/var/log/cups/error_log" file should also be sent,
as it often helps to determine the cause of your problem.

If you are running a version of Linux, be sure to provide the
Linux distribution you have, too.

Please note that the "cups-support@cups.org" email address goes
to the CUPS developers; they are busy people, so your email may
go unanswered for days or weeks.  In general, only general build
or distribution problems will actually get answered - for
end-user support see the "README.txt" for a summary of the
resources available.