This version (1.1) of our TLS implementation corresponds to the ACM
TISSEC submitted paper. The previous version (1.0) corresponds to ACM
CCS'08 paper "Cryptographically Verified Implementations for TLS".


DIRECTORY STRUCTURE
===================
README				This file
Makefile			Commands to compile and verify the TLS implementation
version				Version number

/lib/interfaces			Library interfaces
/lib concrete			Concrete libraries
/lib/symbolic			Symbolic libraries
formats.ml[i]			TLS constants and message formats	
conversions.ml[i]		Bitstring encodings of TLS constants and datatypes
handshake.ml[i]			Handshake (and Resumption) protocol implementation
record.ml[i]			Record protocol implementation

preambule.query			definitions of clauses used in the ProVerif queries
hsauth.query 			ProVerif queries for the Full Handshake Authentication Theorem
resauth.query 			ProVerif queries for the Resumption Authentication Theorem
hssecr.query 			ProVerif queries for the Handshake Secrecy Theorem
recauth.query 			ProVerif queries for the Record Authentication Theorem
recsecr.query			ProVerif queries for the Record Secrecy Theorem
passwd.query			ProVerif queries for the Password-Based User Authentication Theorem

tls.cvl				library of crypto assumptions used in our analysis
crypto-record_auth.cv		crypto assumptions for the Record Authentication Theorem
crypto-record_secr.cv		crypto assumptions for the Record Secrecy Theorem
crypto-hs.cv			crypto assumptions for the Handshake PMS Random Secrecy Theorem
crypto-ha.cv			crypto assumptions for the Handshake Master Secret Authentication Theorem
record_auth.cvquery		CryptoVerif queries for the Record Authentication Theorem
ha.cvquery			CryptoVerif queries for the Handshake Master Secret Authentication Theorem
types.cv			CryptoVerif types used in our analysis
decl.txt			list of functions that are declared by hand (ie not generated by FS2CV)

/fs2cv/fs2cv.exe 		Model extractor for computational verification
/bin/fs2pv.exe			Model extractor for symbolic verification
/bin/goal2gen.exe		Helper tool generating attack traces from ProVerif output 
				(compatible with ProVerif versions up to 1.14pl5)

/ssl1/ssl1.pv			ProVerif script modelling a version of SSL1
/ssl1/ssl1.attack		Alice-Bob description of the attack found by ProVerif


REQUIREMENTS AND INSTALLATION
=============================
- for concrete and symbolic execution 
    F# compiler version 1.9.6.2 (http://research.microsoft.com/en-us/um/cambridge/projects/fsharp/)
    .NET libraries (in particular System.Security.dll)
- for symbolic verification: 
    ProVerif tool (http://www.proverif.ens.fr/)
- for computational verification: 
    CryptoVerif tool (http://www.cryptoverif.ens.fr/)

To run the server one needs to provide a server certificate.  Thus to
acquire and install a signed certificate, or use makecert.exe in the
following way, for instance:
  $ makecert.exe -pe -n CN=CertName -sr CurrentUser -ss My
or 
  $ makecert.exe -pe -n CN=CertName -sr LocalMachine -ss My
where 'CertName' is the certificate name used by the TLS server (see
below).
('makecert.exe' is a tool provided by the .NET Framework)

Installation consists in compiling the two (concrete and symbolic) executables:
  $ make tls.exe	# builds an executable which runs concretly (it interoperates)
  $ make tls-a.exe 	# builds an executable which runs symbolically (it doesn't interoperate)


TLS VERIFICATION
================
  $ make pvall		# performs symbolic verification with the fs2pv/ProVerif tool chain 
  $ make cv 		# performs symbolic verification with the fs2cv/CryptoVerif tool chain 

See the Makefile on how to perform verification on specific queries.


TLS EXECUTIONS
==============

CONCRETE EXECUTIONS
-------------------
To execute, type:
  $ ./tls.exe client -connect https://what.ever.site
(with the options -http and -reconnect)

 $ ./tls.exe server
(with the options -http and -certname cn, where cn is the certificate
name the server should use)
You can test the server by connecting with your favorite browser to https://localhost:8081/


Type './tls.exe client -help' or './tls.exe server -help' for all
options.


The program supports all RSA modes using DES, AES, RC4, MD5, and
SHA1 primitives. That is, it supports the following ciphersuites:
      TLS_RSA_WITH_AES_128_CBC_SHA
      TLS_RSA_WITH_RC4_128_MD5
      TLS_RSA_WITH_RC4_128_SHA       
      TLS_RSA_WITH_DES_CBC_SHA
      TLS_NULL_WITH_NULL_NULL
      TLS_RSA_WITH_NULL_MD5               
      TLS_RSA_WITH_NULL_SHA

It implements the SSL 3.0, TLS 1.0, and TLS 1.1 versions with the
above modes.


SYMBOLIC EXECUTIONS
-------------------
To execute, run: 
  $ ./new-a.exe
for a symbolic execution of the Handshake protocol between one client
and one server. 

You can also run:
  $ ./new-a.exe -reconnect
for a symbolic execution of the Handshake protocol followed by a
symbolic execution of the Resumption protocol between one client and
one server.

You can also run:
  $ ./new-a.exe -passwd

for a symbolic execution of the Password-based Client Authentication
application on top of TLS (there is single user, 'guest' with password
'password' in the )


Remarks related to the papers presenting our TLS implementation
===============================================================

Formats module contains the files formats_ciphersuites.ml[i] and
formats.ml[i]. Conversions modules contains the files
conversions_lowlevel.ml[i] and conversions.ml[i].

The '--define tlsonly' option corresponds to the verification of
TLS 1.0 as presented in the our papers.
Remove this option if you want to enable SSL3.  
