cryptonas-archive/v0.3.1/README.ssl

90 lines
3.3 KiB
Plaintext

Encrypting the http traffic to the CryptoBox webserver with SSL
This file describes how to encrypt your connection to the CryptoBox webserver.
This is highly recommended as the encryption password for your data could be
exposed to intruders in your local network otherwise.
There are several ways for setting up a SSL connection:
- run the CryptoBox webserver behind an ssl-enabled webserver
- use stunnel to provide an SSL socket
- use the a proxy server (e.g. pound)
- ...
At the end of this document you will find some information on how to turn off
SSL detection of the CryptoBox. You should read it, if there is no solution
for your specific setup available or if you are _very_ sure, that you do not
need encrypted http connections.
-------------------------------------------------------------------
1) CryptoBox behind an ssl-enabled webserver
Read the documentation of your favourite webserver to learn how to enable
ssl encryption.
The CryptoBox webserver cannot detect whether the connection is encrypted
or not since it is behind the proxy webserver and does not share its
environment. Thus you have to tell the CryptoBox in the request header
whether the connection is encrypted or not.
for apache2:
1) enable the 'headers' module (for debian: "a2enmod headers")
2) add this line to your ssl-enabled virtualhost:
RequestHeader set X-SSL-Request 1
3) restart your webserver
for lighthttpd:
TODO
-------------------------------------------------------------------
2) CryptoBox behind stunnel
You may want to tunnel the traffic between the cryptobox-server
and your browser. "stunnel" is an excellent candidate for this job.
If you do not have an ssl certificate yet, then you should create
one first. On Debian: "apt-get install ssl-cert" and run the following
command (replace the <NAMES>; a default CERT_CONF is shipped with the
cryptobox-server package):
make-ssl-cert <CERT_CONF> <CERT_FILE_NAME>
In case, that you already have a certificate just run this command:
stunnel -p <CERT_FILE_NAME> -r localhost:80 -d 443
And maybe you want to add the last command to your bootup scripts.
-------------------------------------------------------------------
3) CryptoBox behind a proxy server
As there are many proxy servers around, we cannot describe all of them. As
an example, we will explain the setup of the load-balancing proxy 'pound'.
Just add the following lines to you /etc/pound/pound.cfg:
# Remove the X-SSL-Request header from incoming
# connections to prevent hackers from spoofing it
HeadRemove "X-SSL-Request"
# Add an extra header to tell the CryptoBox that
# the external connection is secure
HTTPSHeaders 0 "X-SSL-Request: 1"
This example is taken from:
http://jamesthornton.com/writing/openacs-pound.html
-------------------------------------------------------------------
4) Problems with SSL detection?
If the CryptoBox continues to complain about the unencrypted connection, even
if it runs behind an ssl-enabled webserver or behind stunnel, then you can do
one of the following things:
- set the request header value "X-SSL-Request" to "1" (the digit 'one')
- set the environment setting "HTTPS" to a non-empty value during the
startup of the CryptoBox webserver. Maybe /etc/default/cryptobox-server
would be the right place for this.
- let the CryptoBox webserver listen to port 443