TLS Key Extraction

Extracting keys and decrypting workloads requires five steps:

  1. Installing Nubeva Sensors

  2. Creating Source Groups

  3. Installing Decryptor Engines

  4. Configuring Cloud Tools

  5. Mirroing traffic

The visual tiggers for each step are marked in the figure below:

../_images/SetupDecryption.png

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.

  1. 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.

../_images/LaunchSensor.png

  1. Click on the top icon in the left corner of the Source Group box.

  2. 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.

../_images/ContainerSensor.png

  1. Paste this command into a command shell on the cloud instance. The sensor container will automatically download and install.

  2. About 10-20 seconds after installation, the Active sensors counter in the Source Groups box will increase by 1 indicating that the sensor is active.

  1. To launch a native Linux installer select the options shown in the figure below:

../_images/NativeLinuxSensor.png

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

../_images/WindowsSensor.png

  1. 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:

  1. Download https://nubevalabs.s3.amazonaws.com/nuAgentDaemonSet.yaml

  2. 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 the nutoken parameter in the sensor-launch dialogs depicted above.

  3. 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:

../_images/LaunchSensor.png

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

../_images/LaunchSourceGroup.png

  1. Name the new source group.

  2. 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": "*"
        }
    ]
}

  1. Click on the Metadata Category in the “Source Inclusion Policy” and choose something. Select the condition and select the values. Then click the ‘+’ button.

  2. You can add multiple conditions.

  3. 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

  1. 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.

../_images/LaunchDecryptor.png

  1. Click on the “Lock” (top) icon on the top left of the Destination Group box.

  2. This will display the popup depicted in figure below. Click the button on the right to copy the installation command.

../_images/LaunchDecryptorEngine.png

  1. Paste this command into a command shell on the decryptor cloud instance. The decryptor container will automatically download and install.

  2. About 10-20 seconds after installation, the decryptor counter in the Destination Groups box will increase by 1 indicating that the decryptor is active.

  3. 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.

../_images/simplesensor.png

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.

../_images/SimpleSensorConfig.png