The following sections cover a basic configuration to get TLSPretense up and running. It should be straightforward to modify the test setup from there.
TLSPretense was designed to be run as an intercepting proxy in order to be able to test a client that may make multple HTTPS/SSL/TLS requests to multiple remote hosts. This means that TLSPretense is expected to run on a different system from the client software being tested, although it is possible to run TLSPretense within one virtual machine and to have the client software run in another.
First, a few definitions:
A piece of software that makes network requests using SSL/TLS.
The computer or virtual machine that will run the client software.
A computer or virtual machines running a Unix-like OS that will act as a network gateway for the client host.
The TLSPretense host needs to have two network interfaces: an external interface for connecting to the outer LAN/Internet and to the remote hosts that the client will connect to, and an internal interface that the client host will use as its gateway.
One common setup is to use a laptop for the TLSPretense host with an ethernet connection and wifi. The ethernet can be wired into an actual network, and the wifi can be run as a wireless access point that the client host will connect to.
This setup has the following network topography:
+------------------------+ LAN +------------------+ WAN | Client Host | . | TLSPretense Host | . | +--------------------+ | . | | . | | Client | | . | +----------+ | . | | ==============>| Firewall | | . | | +----------------+ | | . | +----------+ | . | | | CA TrustStore | | | . | | | . +-------------+ | | | | | | . | +------V-------+ | . | Original | | | | TLSPretense CA | | | . | | TLSPretense ==========>| Destination | | | +----------------+ | | . | | Test Harness | | . +-------------+ | +--------------------+ | . | +--------------+ | . +------------------------+ . +------------------+ .
Install with rubygems:
umask 0022 ; sudo gem install tlspretense
Create a new project:
tlspretense init myproject cd myproject
Now edit the config.yml file to suit your needs. TLSPretense installs a default CA when you create your project directory, but you can replace it with your own test CA. You can also create a new CA if you want (using the goodca certificate definition in the project’s config.yml):
tlspretense ca
Next, create certificates for the test cases (you should rerun this if you modify any of the certificate descriptions in config.yml):
tlspretense certs
You will also need to setup the host’s networking stack and firewall to support TLSPretense. More details can be found in TLSPretense Setup and in the system-specific guides.
Finally, to run all of the configured test cases:
sudo tlspretense run
Or just certain tests (in the order specified):
sudo tlspretense run unknownca wrongcname
Just install TLSPretense again using rubygems. At present, TLSPretense does not provide any versioning or migration of its configuration file.
All configuration of the test suite happens through your project’s config.yml. What follows is a brief discussion of each section and what you might want to change.
This is the most important setting in the configuration file. It specifies the hostname that the client will connect to that you would like to have tested. For connections to this hostname (determined by whether the certificate supplied by the original destination matches the hostname), TLSPretense will present a test certificate chain. For all other hosts, it will take the host certificate used by that host and re-sign it using the “goodca” certificate.
The port that the proxy will listen on. You probably don’t need to change this.
packetthief: protocol: tcp dest_port: 443 in_interface: eth1
This section describes the firewall rule that will redirect traffic. The
most relevant subvalue is :in_interface, which should contain
the name of the network interface that the client’s network traffic will
come in on. Also, if you will be testing non-https traffic, change
dest_port to the port that the client will connect to.
One additional optional parameter exists in this this section:
If this optional value is set, then the specified implementation will be used. If implementation is left commented out, then TLSPretense will choose the most appropriate firewall implementation, if possible. Current values:
netfilter Linux netfilter
ipfw MacOSX/BSD ipfw
certmaker:
defaultsubject: &defaultsubject "C=US, CN=%HOSTNAME%"
defaultsubjectwithnull: &defaultsubjectwithnull "C=US, CN=%HOSTNAME%\0.foo.com"
defaultparentsubject: &defaultparentsubject "C=US, CN=%PARENTHOSTNAME%"
outdir: certs
missing_serial_generation: random
customgoodca:
certfile: ca/goodcacert.pem
keyfile: ca/goodcakey.pem
#keypass: changeme
This section deals with configuring the creation of the certificates used by the tests.
defaultsubject, defaultsubjectwithnull, and defaultparentsubject
These keys are just placed here to get them out of the way. They are referenced later in the certificate definitions.
This specifies where to write the generated certificates to. For now, don’t modify this option or it may break something.
This key specifies how to choose a serial number for each generated certificate. Currently, there are only two options. You can set a number, which will be used as the serial number for all generated certificates (this will break any SSL client that checks for serial number uniqueness). The other option is to set it to “random” which will generate a random serial number — this is the recommended setting, and there is an incredibly small chance that two certificates might have the same serial number.
If this key exists and contains the certfile and
keyfile sub-keys, then it specifies a certificate authority to
be used as the “goodca” instead of generating a new CA. The third optional
value, keypass, can specify a password for the private key’s
file.
logger: level: INFO file: '-'
These options set up the logging facility.
The log severity to report. Log messages that are less severe than this level go unreported.
Where to write log entries to. The default of ‘-’ refers to STDOUT.
This section defines the certificates used by the test cases. It makes
heavy use of YAML’s references and anchors to mutate a particular
certificate. The only special entry is “goodca”. If
customgoodca is configured in the certmaker
section, then that certificate will be used in tests in place of the goodca
defined here.
Make changes to the certificates if you need to customize them for your client.
tests: - alias: baseline name: Baseline Happy Test certchain: - baseline - goodca expected_result: connected ...
This final section defines a list of all of the tests to run.
The “short” identifier for the test.
A longer description of the test.
A list of certificates to present to the client in the order they should be presented. SSL/TLS requires the certificate chain to present the certificate representing the server first, followed by the chain of certificate authorities and intermediate CAs, with the final certificate being a CA.
The expected outcome for the test. “connected” means that we expect the client to finish the TLS handshake, while “rejected” means we expect the TLS handshake to fail before finishing.
You need to pre-generate the certificates you’ll use for the tests. You can do this from your project directory with:
tlspretense certs
It can generate an entire ecosystem of certificates from scratch, or it can use an existing CA instead of generating a new goodca. See the certmaker and certs sections of config.yml.
WARNING: Running this command a second time will regenerate all of the certificates in the certs directory! However, by default it will just copy the CA from the ca directory each time it is run.
It you want to create a new CA, run:
tlspretense ca
The client host must be configured to use the TLSPretense host as its gateway. This involves configuring the TLSPretense host to act like a NAT router or network bridge, and it requires you to configure the client host. You must also install the “goodca” CA used by TLSPretense onto the client host and configure the client to trust that CA. You do not need to configure any client-side proxy settings (like you would for HTTP-level proxying).
If you are planning to use Linux for the TLSPretense host and you are familiar with Mallory, then Mallory’s network configuration tutorials may help you out, although TLSPretense manages the firewall rule that redirects network traffic itself.
For a sample Linux-specific configuration, see: Linux Setup
While in your project directory, run all tests with:
sudo tlspretense run
The command will more than likely need to be run as root so that it can add and remove its firewall rules.
If you only want to run certain tests, you can do so by specifying which tests you want to run as command line arguments, and it will run just those tests in the order specified, instead of in the order they are defined in config.yml:
sudo tlspretense run baseline nullincname selfsigned
For information about other command line options run TLSPretense without any options, or call the run sub-command with -h or –help:
tlspretense tlspretense run -h
At present, TLSPretense prints a summary of the tests run and their results once all tests have run.