= SSL [/wiki/Encryption Encryption] =

[[BR]]

{{{#!div class="box"
== Introduction ==

New in version 1.0, for more details see #1252.

This option can more easily go through some firewalls and may be required by some network policies. Client certificates can also be used for authentication.

There are a lot more options to configure and certificates to deal with.
See [https://docs.python.org/2/library/ssl.html], on which this is based.

It is only applicable to TCP sockets, not unix domain sockets.
Do not assume that you can just enable SSL to make your connection secure.
}}}

{{{#!div class="box"
== Example ==

* use an existing certificate "cert.pem" (see below for creating one)
* start a server with TCP and SSL support:
{{{
xpra start --start=xterm \
    --bind-tcp=0.0.0.0:10000 --ssl-cert=/path/to/cert.pem --ssl=on
}}}
or for SSL only:
{{{
xpra start --start=xterm \
    --bind-ssl=0.0.0.0:10000 --ssl-cert=/path/to/cert.pem
}}}
* client:
{{{
xpra attach ssl:127.0.0.1:10001
}}}
}}}


{{{#!div class="box"
== SSL Mode ==

The TCP to SSL socket upgrade can be used with SSL clients, websockets clients (html5 clients) or HTTPS connections.
Unfortunately, not all of them at the same time. (see ticket:1213#comment:5 for details - #1504 may eventually lift this limitation)

The option {{{ssl=MODE}}} can be used to select which clients protocols will be allowed on the {{{bind-tcp}}} sockets:
||= Mode  =||||||= Client Protocol =||
|| ||= SSL =||= Websockets =||= Secure Websockets =||
||auto [[BR]](default)|| Yes || Yes || No ||
||TCP|| Yes || No || No ||
||www|| No || Yes || Yes ||
}}}


{{{#!div class="box"
== Using a self signed certificates ==

Generate a certificate:
{{{
openssl req -new -x509 -days 365 -nodes -out self.pem -keyout self.pem -sha256
}}}

To avoid this error when the client connects:
{{{
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:590)
}}}
'''temporarily''' add {{{--ssl-server-verify-mode=none}}} to your client command line
}}}


{{{#!div class="box"
== Securing SSL with self signed CA and certificates ==

See [https://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf The Most Dangerous Code in the World: Validating SSL Certificates in Non-Browser Software] and [https://blog.sucuri.net/2016/03/beware-unverified-tls-certificates-php-python.html Beware of Unverified TLS Certificates in PHP & Python].
See also: [https://lwn.net/Articles/666353/ Fallout from the Python certificate verification change].

Since the server certificate will not be signed by any recognized certificate authorities, you will need to send the verification data to the client via some other means... This will no be handled by xpra, it simply cannot be. (same as the AES key, at which point... you might as well use AES)


----

{{{
# generate your CA key and certificate:
openssl genrsa -out ca.key 4096
# (provide the 'Common Name', ie: 'Example Internal CA')
openssl req -new -x509 -days 365 -key ca.key -out ca.crt
# generate your server key:
openssl genrsa -out server.key 4096
# make a signing request from the server key:
# (you must provide the 'Common Name' here, ie: 'localhost' or 'test.internal')
openssl req -new -key server.key -out server.csr
# sign it with your CA key:
openssl x509 -req -days 365 \
    -in server.csr -out server.crt \
    -CA ca.crt -CAkey ca.key \
    -CAserial ./caserial -CAcreateserial
# verify it (it should print "OK"):
openssl verify -CAfile ca.crt ./server.crt
}}}
You can now start your xpra server using this key:
{{{
xpra start --start=xterm \
    --bind-tcp=0.0.0.0:10000 --ssl=on --ssl-cert=`pwd`/server.crt --ssl-key=`pwd`/server.key
}}}
Use openssl to verify that this xpra server uses SSL and that the certificate can be verified using the "ca.crt" authority file: (it should print {{{Verify return code: 0 (ok)}}}):
{{{
openssl s_client -connect 127.0.0.1:10000  -CAfile /path/to/ca.crt < /dev/null
}}}
Connect the xpra client:
{{{
xpra attach ssl:localhost:10000 --ssl-ca-cert=/path/to/ca.crt
}}}
}}}

{{{#!div class="box"
== Sending the CA data ==

In some cases, it may be desirable to supply the CA certificate on the command line or in a session file. Here's how.

Convert a CA file to hex:
{{{
python -c "import sys,binascii;print binascii.hexlify(open(sys.argv[1]).read())" ca.crt
}}}
Convert hex back to data to verify (only part of the data shown here):
{{{
python -c "import sys,binascii;print binascii.unhexlify(sys.argv[1])" \
    2d2d2d2d2d424547494e2043455254494649434154452d2d2d2d2d0a4d4949
}}}
Use it directly in the xpra command:
{{{
xpra attach ssl:localhost:10000 \
    --ssl-ca-data=2d2d2d2d2d424547494e...4452d2d2d2d2d0a
}}}
Alternatively, place all of these in a connection file you can just double click on:
{{{
echo > ssl-test.xpra <<EOF
host=localhost
autoconnect=true
port=10000
mode=ssl
ssl-ca-data=2d2d2d2d2d424547494e...4452d2d2d2d2d0a
EOF
}}}
}}}