TLSPretense
Setup¶ ↑
The following sections cover a basic configuration to get TLSPretense
up and running. It should be straightforward to modify the test setup from there.
Test Environment¶ ↑
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:
- client
-
A piece of software that makes network requests using SSL/TLS.
- client host
-
The computer or virtual machine that will run the client software.
TLSPretense
host-
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 | | . +-------------+ | +--------------------+ | . | +--------------+ | . +------------------------+ . +------------------+ .
Installing TLSPretense
¶ ↑
General Case¶ ↑
The following assumes that the gem
command refers to the Ruby 1.9.3 version of gem. If the Ruby 1.9.3 version on your system has a suffix, use that version of gem
instead. Install with rubygems:
umask 0022 ; sudo gem install tlspretense
Ubuntu 12.04 and Later¶ ↑
If you are using Ubuntu, The ruby1.9.1 package on Ubuntu 12.04 is actually Ruby 1.9.3 (1.9.1 in this case is the ABI version, not the software version). Assuming you haven't already installed Ruby 1.9.3:
sudo apt-get install ruby1.9.1-full
then install with rubygems:
umask 0022 ; sudo gem1.9.1 install tlspretense
Create a TLSPretense
Project¶ ↑
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
Updating TLSPretense
¶ ↑
Just install TLSPretense
again using rubygems. At present, TLSPretense
does not provide any versioning or migration of its configuration file.
Configuration¶ ↑
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.
top-level settings¶ ↑
- hostname: www.isecpartners.com
-
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. - listener_port: 54321
-
The port that the proxy will listen on. You probably don't need to change this.
packetthief¶ ↑
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:
- implementation
-
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¶ ↑
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
, anddefaultparentsubject
-
These keys are just placed here to get them out of the way. They are referenced later in the certificate definitions.
- outdir
-
This specifies where to write the generated certificates to. For now, don't modify this option or it may break something.
- missing_serial_generation
-
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.
- customgoodca
-
If this key exists and contains the
certfile
andkeyfile
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¶ ↑
logger: level: INFO file: '-'
These options set up the logging facility.
- level
-
The log severity to report. Log messages that are less severe than this level go unreported.
- file
-
Where to write log entries to. The default of '-' refers to STDOUT.
certs¶ ↑
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¶ ↑
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.
- alias
-
The “short” identifier for the test.
- name
-
A longer description of the test.
- certchain
-
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.
- expected_result
-
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.
Certificate Generation¶ ↑
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
Client Host Setup¶ ↑
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.
For information on configuring TLSPretense
on a Mac OS X system, see: Mac OS X Setup
Running the tests¶ ↑
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
Output¶ ↑
At present, TLSPretense
prints a summary of the tests run and their results once all tests have run.