keithmendozasr / tlslookieloo

Utility to view stream between TLS-based client and server.

tlslookieloo

Utility to view stream message between server and client

Longer idea

tlslookieloo is a utility to help troubleshoot network-related issues between a server and client. A client will connect to tlslookieloo, who in turn, will connect to the target server. tlslookieloo will then store/display the unencrypted message between the two.

Dependencies

These are all minimum version

• C++ 17 compatible compiler
• cmake 3.13
• OpenSSL 1.1.1
• yaml-cpp 0.6

Submodules

The following are included as submodules of this project:

• googletest
• log4cplus

Make sure to process the git submodule with --recurse accordingly.

Compilation

This project has been tested on Debian 10 and macOS Catalina. Below are the steps used to compile on Debian 10:

1. Install the following software packages:
   1. libssl-dev
   2. cmake
   3. libyaml-cpp
2. git submodule update --recursive --init
3. mkdir build
4. cd build
5. cmake ..
6. cmake --build .
7. ctest (make sure all passes)

Instructions for building on macOS is in the Building on macOS wiki page.

How to run

1. cd to build directory from the previous section.
2. Generate a self-signed TLS certificate openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out app1.crt -keyout app1.key
3. Start tlslookieloo ./src/tlslookieloo -t../samples/targets.yaml
4. Make the necessary system changes to resolve "www.example.com" to the IP of the machine you're running tlslookieloo on.
5. In a browser go to https://www.example.com:9988.
6. You should see a certificate warning if you're browser is connected to your tlslookieloo instance. Allow accordingly.
7. The "Example" page should load
8. Messages between your browser and www.example.com's server are recorded in app1.msgs

See the User Guide for more information.

Docker container

A docker containers available on Docker Hub. Here's a sample invocation:

1. Create a directory $HOME/docker-files to use as a bind mount.
2. Place the certificate-key pair from "How to run" above in $HOME/docker-files
3. Copy targets.yaml and logger.properties from tlslookieloo/samples directory into the directory from the previou step.
4. docker run -d -p 9988:9988 --name testrun --mount="type=bind,source=$HOME/docker-files,dst=/data" tlslookieloo:edge -t /data/docker.yaml -l /data/dockerlog.prop
5. Open your browser and go to http://localhost:9988
6. If all went well, the docker-files folder should now contain the app1.msgs and tlslookieloo.log files.

tlslookieloo's Issues

Client-side SSL context should only be loaded at start

Currently, the client-side SSL context is reloaded every time a client-side connection is received. The context should only be created at program start and used throughout the program lifetime.

Any non-alphanumeric or punctuation "character" should be recorded with its hex-encoded value

Is your feature request related to a problem? Please describe.
There are situations where things line CR (ascii 10) and LF (ascii 13) characters as the line-breaking delimiters

Describe the solution you'd like
Anything other than A-Za-z0-9 and punctuation characters should be in the hex-encoded form in the records file.

Describe alternatives you've considered

Additional context
Screenshot of a record file displayed in vim

Screenshot of same file displayed in the browser

Containerize tlslookieloo

Is your feature request related to a problem? Please describe.
I think making this available as a docker container would be helpful to those that have to test software in a Docker environment

Describe the solution you'd like
For a Docker container of tlslookieloo to be available; preferably published on Docker Hub

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Complete ServerSide unit tests

The following methods do not have unit tests

• waitForConnect
• sockConnect
• socketReady

Clean up FRIEND_TEST macro calls

Is your feature request related to a problem? Please describe.
Having a ton of FRIEND_TEST in the class definitions means that updating that list triggers a rebuild of many intermediate object files.

Describe the solution you'd like
Unit test should run with as few FRIEND_TEST calls as possible

Update unit tests to use the MOCK_METHOD macro without parameter count suffix

We should switch to the gMock MOCK_METHOD macro that doesn't need to know the parameter count in advanced.

Exiting with 0 on error

Describe the bug
When an issue is encountered that terminates the program; the exit code is 0.

To Reproduce
Steps to reproduce the behavior:

1. Create a target file that contains a record file path that includes a non-existent directory
2. Start tlslookieloo using the target file
3. Run the target client
4. Observe tlslookieloo exits
5. Observe the error log stating the record file can't be created.
6. Print the exit code and observe it's zero.

Expected behavior
tlslookieloo should exit with non-zero code when an error occurs that terminates the program.

Console or log output
N/A

Environment:

• OS: Debian
• Version 10

Attachments
N/A

Bad targets file example

The wiki shows an example of the targets file, however it fails to work properly.

File contents:

- name: "daemonz"
  serverhost: "daemo.nz"
  serverport: 8908
  clientport: 9988
  clientcert: "test_certs/cert.pem"
  clientkey: "test_certs/key.pem"
  recordfile: "app1.msgs"

Result:

INFO - Parsing targets file
ERROR - Failed to parse targets file, cause: bad file. Exiting
INFO - tlslookieloo exiting

Update TargetTest storeMessage* cases to work with commit 9abb35a2

Commit 9abb35a added date and time to the recorded message header. However, the unit tests where not updated. Need to figure out how best to have gmock verify the parameter passed in.

Functional test can't be run in parallel with another functional test

Describe the bug
When the functional tests are run by ctest --parallel they all end up failing

To Reproduce
Steps to reproduce the behavior:

1. Build project
2. cd to the build directory
3. ctest --parallel 2
4. Observe all the functional tests fail

Expected behavior
The functional tests should pass regardless of whether it's ran serially or in parallel with other functional tests.

Environment:

• OS: Debian
• Version: 10

Functional testing

Plan is to use Robot Framwork to develop the functional tests.

Complete ClientSide unit tests

Need unit tests for the following methods:

• startListener
• acceptClient
• waitSocketReadable

Debian package

Is your feature request related to a problem? Please describe.
It would be nice if a Debian package is available. After all, this project was developed in Debian 10.

Describe the solution you'd like
For a Debian package to be available; preferably published in Launchpad.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Configurable message buffer size

Is your feature request related to a problem? Please describe.
The amount of data recorded maxes out at 1024-bytes at a chunk. So, if one end sends a message block that's more than 1024-bytes it's recorded in chunks in the record file.

Describe the solution you'd like
If possible, all of the message block should be recorded in 1 chunk.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Consecutive messages from same source should be contained in 1 header and footer line

Is your feature request related to a problem? Please describe.
There are situations where parts of a message from one end of a system may get broken down in chunks for whatever reason. For example, an HTTP Response could be recorded as multiple chunks causing header and footer lines to get in between the complete HTTP message.

Describe the solution you'd like
If a messages can be identified as part of the same it should be contained under 1 header and footer line.

Describe alternatives you've considered
#13 might prove helpful; but, there are times where the complete message may be larger than estimated. It's also possible that the OS, or TLS library, may break the message down in transit and expect the receiver to be able to assemble the message back.