Introduction
------------

AaltoTLS is an implementation of the SSL/TLS network protocol written completely
using C# and standard cryptographic libraries of .NET where relevant. It is
designed to run fully on open source Mono implementation as well, working around
possible bugs and incompatibilities if present. Focus of the project has been
mainly on clean layered structure of the code and easy extensibility, not so
much on performance or memory use. This is because the project has originally
been part of a research project. So benchmarking might be required before using
it in production environments.


Compiling the source code
-------------------------

There are two methods supported for compiling the source code. The preferred one
is using NAnt, in which running command "nant" in the AaltoTLS folder should
compile all source files to AaltoTLS-debug folder. If you wish to compile a
release build without the debugging information, it can be done running the
command "nant release" and it will compile the files to AaltoTLS-release
folder.

In development the MonoDevelop 2.6 IDE is used as well, and all the necessary
project files should be included. In this case opening the AaltoTLS.sln in
MonoDevelop should open the solution and "Build All" should build all the source
files into their respective folders.


Supported TLS features
----------------------

Protocol support:           SSLv3.0, TLSv1.0, TLSv1.1, TLSv1.2
Key exchange algorithms:    RSA, DHE, ECDHE
Signature algorithms:       RSA, DSS, ECDSA
Encryption algorithms:      RC4, DES-CBC, 3DES-CBC, AES-CBC, AES-GCM, SEED, Camellia, ARIA-CBC, ARIA-GCM
MAC algorithms:             SSLv3, MD5, SHA-1, SHA-256, SHA-384, SHA-512
Pseudorandom functions:     SSLv3, TLSv1, TLSv1.2 (SHA-256, SHA-384, SHA-512)


Future work to do
-----------------

Important work to do:
- Logging system that doesn't output to stdout
- Cipher suite selection based on security features

Less important features:
- TLS 1.2 signature_algorithms extension support
- Session resume using the SessionID of ClientHello
- Renegotiation support as described in RFC 5746

Clean up to be done:
- TLSSession and HandshakeSession both need cleaning up
- Better API for TLSSession required, like TcpClient


Implementation details
----------------------

Resolved library issues:

RSACryptoServiceProvider.SignData doesn't accept MD5SHA1CryptoServiceProvider,
because it doesn't have an OID. If RSA signatures is to be supported in SSL
3.0, TLS 1.0 and TLS 1.1, it needs to be done manually. That's why
SignatureAlgorithmRSA depends on BigInteger and is not included in the base
cipher suite plugin. The TLS 1.2 version of it doesn't depend on BigInteger at
all.

Support for ECC cipher suites was done using the ECDiffieHellmanCng and ECDsaCng
classes that are provided by .NET 3.5 when run on Windows 7, Windows Vista SP1
or later or Windows XP SP3. They are not available on older versions of Windows
or on other operating systems using Mono, therefore they are excluded from the
NAnt build file to cause as little trouble as possible. It's also worth to note
that using ECDiffieHellmanCng with TLS 1.2 is impossible, because the API
requires including premaster secret as part of the HMAC input. It's a stupid
API, but there's not much that can be done. SSLv3, TLSv1.0 and TLSv1.1 are
currently supported.


Things to note:

ARCFour cipher is separated into its own plugin, because it includes references
to RC4, which in turn is trademarked by RSA Security. Including this cipher is
highly recommended, since many servers only support RC4 ciphers for their fast
speed and simple implementation.

Diffie-Hellman and RSA signing depend on BigInteger implementation, which is not
available in .NET before the version 4.0. Since by the time of writing this
.NET 4.0 is not very widely used, a modified version of Microsoft BigInteger
implementation that should be almost identical with .NET 4.0 BigInteger is
included in the plugin. The BigInteger implementation is released under
Microsoft Public License, which is a free software license but not compatible
with GNU GPL.

Camellia cipher is separated into its own plugin, because it includes MIT
licensed CamelliaEngine class copyrighted by The Legion Of The Bouncy Castle.
The license is quite liberal, but because of copyright issues it is better to
keep it as a separate plugin. Camellia is quite widely used and even preferred
by some servers, so including this plugin is recommended.

ARIA cipher is separated into its own plugin, because it includes a MIT licensed
ARIAEngine with different copyright. ARIA is not a very common cipher to be used
with TLS and it is probably only used inside South Korea, so this should not be
an issue. It is included because the plugin is a very good sample plugin of how
to easily add CBC and GCM mode cipher suites with a crypto library where only
ECB is available.


Outstanding issues:

When running on Mono and not on real .NET, validating the certificate chain is
currently not possible, because Mono doesn't implement the X509 certificate
chain validation. Therefore it will always fail when run on Mono but will work
when run on .NET.

TLS 1.2 is fully supported, but the SignatureAlgorithms extension is not
supported, which means that all signatures are signed using SHA-1 hash. This
should not be an issue, since SHA-1 is still considered secure, but in the
future it might be good to upgrade support for stronger hash algorithms.

Deflate compression is supported by .NET in DeflateStream class, but this class
is not useful for our purposes. TLS requires that the deflate compression can
compress single packets as a continuous stream, but flush each packet separately
in the middle and send it through the wire. In Microsoft implementation of
DeflateStream the Flush() method is not implemented at all and therefore we
would have to compress each packet separately. This results in considerable
overhead and makes deflate perform badly in most use cases.


Server key generation
---------------------

Example key generation using openssl:

RSA keys (from 384 bits to 16384 bits in increments of 8 bits, 2048 used):
> openssl genrsa -out rsakey.pem 2048
> openssl req -new -x509 -days 365 -subj '/C=FI/ST=Uusimaa/L=Espoo/O=Aalto University/CN=localhost' -key rsakey.pem -out rsaca.pem
> openssl x509 -in rsaca.pem -outform DER -out rsaca.der
> ./PEM2XML.exe rsakey.pem rsakey.xml

DSA keys (from 512 bits to 1024 bits in increments of 64 bits, 1024 used):
> openssl dsaparam -noout -out dsakey.pem -genkey 1024
> openssl req -new -x509 -days 365 -subj '/C=FI/ST=Uusimaa/L=Espoo/O=Aalto University/CN=localhost' -key dsakey.pem -out dsaca.pem
> openssl x509 -in dsaca.pem -outform DER -out dsaca.der
> ./PEM2XML.exe dsakey.pem dsakey.xml

ECDSAkeys (either secp256r1, secp384r1 or secp521r1, secp256r1 used):
> openssl ecparam -noout -out ecdsakey.pem -genkey -name secp256r1
> openssl req -new -x509 -days 365 -subj '/C=FI/ST=Uusimaa/L=Espoo/O=Aalto University/CN=localhost' -key ecdsakey.pem -out ecdsaca.pem
> openssl x509 -in ecdsaca.pem -outform DER -out ecdsaca.der
> ./PEM2CNG.exe ecdsakey.pem ecdsakey.cng

Starting the server
> ./TLSServer.exe rsaca.der rsakey.xml
> ./TLSServer.exe dsaca.der dsakey.xml
> ./TLSServer.exe ecdsaca.der ecdsakey.cng

If you want to decrypt the resulting traffic using Wireshark, then go to
Preferences->Protocols->SSL and modify the "RSA keys list" to include:

"*,4433,http,[keypath]/rsa.key"

This should make Wireshark decrypt all connections that use RSA key exchange
method. The DH or DHE sessions cannot be decrypted, because Wireshark is unable
to obtain the pre-master secret from DH parameters, which is the point of
perfect forward secrecy provided by DH.

After all this, connecting to "https://localhost:4433" with any browser should
work, except that it is giving a warning about the certificate not being signed
by a known root CA, this is normal. If you do have a certificate signed by a
known root CA and with intermediate certificates, you can start TLSServer with:

> ./TLSServer.exe server.cer intermediate.cer key.xml