TLS Key Extraction¶
Extracting keys and decrypting workloads requires five steps:
Installing
Nubeva Sensors
Creating
Source Groups
Installing
Decryptor Engines
Configuring
Cloud Tools
Mirroing traffic
The visual tiggers for each step are marked in the figure below:

Installing Nubeva Sensors¶
As shown in figure 1 in the previous section Nubeva Sensors
mirror traffic as well as extract session keys from encrypted traffic. Nubeva Sensors
are available for Linux and MS Windows.
Linux sensors are available as Docker containers as well as a standalone installation. You can skip this step if your instance is already running the required version of Docker. If you need to install docker please refer to Docker Installation for instructions.

Click on the top icon in the left corner of the Source Group box.
This will pop up a box similar to the figure below. Select ‘Container Sensor’ from the drop-down menu. Click the button on the right to copy the installation command.

Paste this command into a command shell on the cloud instance. The sensor container will automatically download and install.
About 10-20 seconds after installation, the
Active sensors
counter in theSource Groups
box will increase by 1 indicating that the sensor is active.
To launch a native Linux installer select the options shown in the figure below:

To launch a Windows sensor, select “Windows Sensor” from the drop-down.

Paste this command into a command shell on the cloud instance. The sensor installer will automatically download and install from Docker Hub.
Note
The last command is:
& "$DownloadDir\installer.exe" NUTOKEN_USERINPUT=$NubevaTok API_URL_ARG=${InstallerArg} /q;
To enable detailed logging replace the last command with:
& "$DownloadDir\installer.exe" NUTOKEN_USERINPUT=$NubevaTok API_URL_ARG=${InstallerArg} /q /L*V "$DownloadDir\installer.log";
"Debugging logs are in: '$DownloadDir\installer.log'
To uninstall a Windows sensor run:
wmic product where "description='Nubeva Sensor' “ uninstall
Tip
Nubeva sensors can be run as daemonsets in Kubernetes clusters. Nubeva sensors require
Kubernetes
versions 1.11 or greater. If you would like to extract keys from nodes running in a Kubernetes cluster please do the following:
Download https://nubevalabs.s3.amazonaws.com/nuAgentDaemonSet.yaml
Edit the file and replace the value of the
nutoken placeholder
with the value that is used in your project. This is the value of thenutoken
parameter in the sensor-launch dialogs depicted above.Run
kubectl apply -f nuAgentDaemonSet.yaml
The next step is to configure source groups.
Creating Source Groups¶
Source groups instruct sensors to extract keys. Sensors are grouped based on their metadata and custom tags. A sensor must be included in a source group in order to extract keys. The following links provide additional information: AWS Metadata, AWS Custom Tags, Azure Metadata, Azure Custom Tags.
As new sensors with matching meta-data and/or custom tags appear, they are automatically added to the source group. This is a powerful adaptation to the elastic nature of cloud environments. For instance, if you routinely spin up/down instances with web scaling events, selecting filters such as AMI type, VPC, subnet, or custom tag values, will ensure that any new sensors that appear will be immediately added to the source groups and start extracting keys.
Note
For additional security and scaling, Nubeva supports Amazon DynamoDB as a Private KeyDB. Sensors store session keys in a private DynamoDB table in your account. Other cloud DBs such as Azure Cosmos DB or Google Cloud Data-store are on the road-map. Please contact us if you are interested in those platforms.
Security in Amazon DynamoDB: All communication of keys and associated meta-data is encrypted both in transit and at rest. The session keys for the sensor to KeyDB communication is NEVER saved. All user data stored in Amazon DynamoDB is fully encrypted at rest. DynamoDB encryption at rest provides enhanced security by encrypting all data at rest using encryption keys stored in AWS Key Management Service (AWS KMS). Nubeva has no access to this Private KeyDB running on Amazon DynamoDB.
Using Amazon VPC endpoints to access DynamoDB: For additional security Nubeva suggests that you use VPC endpoints for all connectivity to a Private KeyDB running on Amazon DynamoDB.. When you create a VPC endpoint for DynamoDB, any requests to a DynamoDB endpoint within the Region (for example, dynamodb.us-west-2.amazonaws.com) are routed to a private DynamoDB endpoint within the Amazon network. You don’t need to modify your applications running on EC2 instances in your VPC. The endpoint name remains the same, but the route to DynamoDB stays entirely within the Amazon network, and does not access the public Internet.
These are the steps to create a source group:

Click on the lower icon at the top right of the “Source Group” box. This will load the Source Group editing window.

Name the new source group.
Click on the
Filter Type
(leftmost) drop down to select either ‘Metadata’ or ‘Custom Tags’.
Note
On AWS permission has to be given to describe all instances because the scope of DescribeInstances cannot be limited to a single instance. Creating an AWS IAM role for custom tag support
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances"
],
"Resource": "*"
}
]
}
Click on the
Metadata
Category in the “Source Inclusion Policy” and choose something. Select the condition and select the values. Then click the ‘+’ button.You can add multiple conditions.
Select save. This will return you to the dashboard.
Tip
By default key extraction is turned on. The check box in the upper right corner allows you to turn key discovery on/off for the sensors included in the source group.
Launching Decryptors¶
Docker is a prerequisite to running containers. You can skip this step If your instance is already running the required version of Docker. If you need to install Docker please refer to Docker Installation for instructions.

Click on the “Lock” (top) icon on the top left of the Destination Group box.
This will display the popup depicted in figure below. Click the button on the right to copy the installation command.

Paste this command into a command shell on the decryptor cloud instance. The decryptor container will automatically download and install.
About 10-20 seconds after installation, the decryptor counter in the Destination Groups box will increase by 1 indicating that the decryptor is active.
If you would like to launch a cloud security tool to process the decrypted packets, please refer to the Tool Launcher section.
Note
Refer to Deploying Security Tools for comprehensive instructions for launching security tools based on the AWS Well-Architected Architecture.
The final step is to mirror traffic to your decryptor. This can be done by using AWS VPC Traffic Mirrors or by defining destinations
and connections
between source groups
and destinations
.
Key Extraction QuickStart¶
To familiarize yourself with basic key extraction you can run a Simple Sensor
configuration. This configuration runs a single sensor instance extracting keys to a local file on the same instance where the sensor is running.

You can launch a simple sensor configuration by adding a paramters to a Container Sensor’s launch command. A full command example is listed below.
docker run -v /:/host -v /var/run/docker.sock:/var/run/docker.sock --cap-add NET_ADMIN --cap-add SYS_ADMIN --cap-add SYS_RESOURCE --cap-add SYS_PTRACE --name nubeva-agent -d --restart=always --net=host --pid host nubeva/nuagent --accept-eula --contained on --nutoken <Nubeva-Token> --sslcredobj eyJ0eXBlIjoibGNsIiwicmVnaW9uIjoiL2hvc3QvdG1wLyIsImRvbWFpbiI6ImtleXMubG9nIn0K
The Nubeva-Token
will be included in the command when you copy from the sensor-launch dialog (Installing Nubeva Sensors). The last parameter which is added to the launch command is listed below. This parameter instructs the sensor to store keys in /tmp/keys.log
.
--sslcredobj eyJ0eXBlIjoibGNsIiwicmVnaW9uIjoiL2hvc3QvdG1wLyIsImRvbWFpbiI6ImtleXMubG9nIn0K
You can install nubevalab/tlsgenertor which is a standard traffic generator container. The command to launch the generator is:
docker run -dti nubevalab/tlsgenerator
In addition you may install a dockerized version of Wireshark that is accessible using HTTPS. To deploy the container run:
docker run -v /tmp:/keys -p 14500:14500 --restart unless-stopped -dti --cap-add NET_ADMIN --net=host --name wireshark ffeldhaus/wireshark
The directory of the keys file is mapped to the /keys
directory on the Wireshark container, so the key file will be /keys/keys.log
.
Note
The user-name and password for accessing Wireshark are wireshark
You can deploy all three elements using a cloud formation template stored at https://nubevalabs.s3.amazonaws.com/nubeva-simplesensor.template.yaml. To launch the template you need a VPC and a Nubeva Token. The CloudFormation template installs all three containers and sets up a cron job to run a generator container every minute. The figure below depicts the containers running.
