Skip to content

User Guide

Keith Mendoza edited this page Aug 20, 2019 · 2 revisions
Clone this wiki locally


The main purpose of tlslookieloo is to be able to record messages between a client and a server. Below is a diagram of tlslookieloo's relationship to the client and server components being tested.

--------------      --------------      --------
| client app |<---->|tlslookieloo|<---->|server|
--------------      --------------      --------

This configuration makes up a "target". It is also possible to configure a tlslookieloo instance to handle multiple targets as depicted in the diagram below.

                                      |--->|server 1|
                                      |    ----------
--------------      --------------    |    ----------
| client app |<---->|tlslookieloo|<------->|server 2|
--------------      --------------    |    ----------
                                      |    ----------
                                      |--->|server 3|

In this particular case tlslookieloo has 3 targets to test.

Defining targets

The targets definition file is a YAML file that contains a sequence of targets. Each target is a mapping of the following keys

  • name = The application identification. Mainly used for human consumption and in tlslookieloo logs.
  • clientport = Port tlslookieloo will listen for the client application on.
  • clientcert = Path to the TLS certificate tlslookieloo will use for the TLS handshake with the client app. The file should be in PEM format, and it can contain both the public and private keys. See "clientkey" below if the private key is in a separate file.
  • serverhost = Hostname of the target's server-side.
  • serverport = Port the target's server-side is listening to.
  • recordfile = Path to record data between the 2 sides of the target to. The data are stored as text, and non-printable characters are hex-encoded.

These keys are the minimum required to define a target. The following are optional, depending on the target and user's preference:

  • clientkey = Path to the TLS private key if it's not in the "clientcert" file. If this is defined the key contained in this file will be used as the private key, regardless of whether the "clientcert" file contains a private key in it too.
  • clientauthcert = Path to the client authentication keys. This is similar to "clientcert" in terms of what keys can be in the file.
  • clientauthkey = Path to the client authentication private key, if not in "clientcertauth".
  • clienauthca = Path to the acceptable client authentication CA (or chain).
  • timeout = Number in seconds to wait for a message from either client or server. If it's not set the target will wait 5 seconds.
  • servercachainfile = Path to the PEM file containing the CA certificate chain of "clientcert".

Below is an example of a targets definition containing 2 applications that are running on the same host.

- name: "Micro-one"
  serverhost: "server"
  serverport: 8908
  clientport: 9988
  clientcert: "test_certs/cert.pem"
  clientkey: "test_certs/key.pem"
  recordfile: "app1.msgs"

- name: "Micro-2"
  serverhost: "servertwo"
  serverport: 9087
  clientport: 8899
  clientcert: "test_certs/certapp2.pem"
  clientkey: "test_certs/keyapp2.pem"
  recordfile: "app2.msgs"

In this example the target designated micro-one will have the client connect to tlslookieloo on port 9988 using the test_certs/cert.pem and test_certs/key.pem server key-pair. The server-side is listening in server:8908. Messages are to be recorded in app1.msgs. Micro-2 will have the client connect to tlslookieloo on port 9087 using the test_certs/certapp2.pem and test_certs/keyapp2.pem server key-pair. The server-side is listening in server:9087. Messages are to be recorded in app2.msgs.

TLS client authentication handling

When the client-side connects to tlslookieloo the public key the client sent to TLS lookieloo during the handshake is compared against the public key in "clientauthcert". Should the keys not match, the handshake is terminated by tlslookieloo.

The keys in clientauthcert and clientauthkey (if it's set) are used when tlslookieloo connects to the server-side. If the server rejects the client authentication key tlslookieloo will simply terminate the connection to the client-side application.

Below is a configuration of 1 target that uses TLS client authentication.

- name: "auth-one"
  serverhost: "server"
  serverport: 8908
  clientport: 9988
  clientcert: "test_certs/auth-cert.pem"
  clientkey: "test_certs/auth-key.pem"
  recordfile: "auth-one.msgs"
  clientauthcert: "testclientauth.pem"
  clientauthkey: "testclientauthkey.pem"
  clientauthca: "devca.pem"

The record file

The record file contains messages sent beween the client and server that tlslookieloo is monitoring. It has the following format:

===YYYY-mm-dd 00:00:00 BEGIN <src>--><dest>===
Message data
possibly multiple lines <F3><AB><DE><00><01><33><97><E5>


In the header line "YYYY-mm-dd 00:00:00" is the date and time the message was recorded. is the source of the message, and is the destination of the message. This section is either client-->server or server-->client. The ===END== is used to indicate one block of data relayed by tlslookieloo. Note that the footer will always be in its own line. In the sample format above the data recorded had a newline character as its last byte. If the data recorded's last byte is "E5" then there will be no blank space above the footer line.