Decoder: Decrypt Incoming Packets

Document created by RSA Information Design and Development Employee on Sep 13, 2017Last modified by RSA Information Design and Development Employee on Apr 23, 2020
Version 23Show Document
  • View in full screen mode

Beginning with NetWitness Platform 11.0, administrators can configure a Network Decoder to decrypt incoming packets using the sslKeys command. Enabled parsers see the unencrypted packet payload and create metadata accordingly. If the Decoder is not configured to decrypt incoming packets, most enabled parsers see only encrypted garbage and fail to create meaningful metadata.

Note: If FIPS is enabled, the list of ciphers for decryption is restricted to only those that are FIPS approved.

The sslKeys command provides a way to upload premaster or private keys to the Decoder, so that captured encrypted packets that match the keys can be decrypted before parsing. Administrators configure the Decoder by entering the sslKeys command using the NwConsole command line interface or the Decoder RESTful interface.

This is an example of the command line interface.

The RESTful interface form at the path: /decoder/sslkeys allows uploading a single PEM-encoded private key, a single file containing multiple private keys concatenated together, or a single file of multiple premaster keys.

This is an example of the RESTful interface form.

Although the packets are decrypted during the parse stage, only the encrypted packets are written to disk. The matching premaster key used for decrypting is written to the tls.premaster meta key, which analysts can use to subsequently view unencrypted packets on demand.

Details for administrators to configure decryption of incoming packets, and for analysts to view unencrypted packets on demand are provided below.

Decryption of Secure SMTP

In version 11.3, NetWitness Platform supports opportunistic SSL/TLS decryption, which addresses RFC 3207 ( You can add an HTTPS parser option that provides a .csv list of destination ports of the session where the STARTTLS command will be searched, with at least one encryption key that has been uploaded. This enables the STARTTLS functionality.

Note: The .csv list must include all the destination ports of a session. If a destination port is not in the list, the search for STARTTLS will not be started.

The STARTTLS search is limited to the first 1024 bytes of the session's payload, to prevent performance degradation. If STARTTLS is found, the parser uses the next client packet with payload as the start of a TLS negotiation.

To add an HTTPS parser option for secure SMTP decryption:

  1. In the NetWitness Platform User Interface, go to ADMIN > Services.
  2. Select a Log Decoder service and click > View > Explore.
  3. In the left panel, select decoder > parsers > config.
  4. In parsers.options, enter an HTTPS parser option in the following format that provides a .csv list of the destination ports of the session where the STARTTLS command is searched:


    The following image shows an example of an HTTPS parser option for secure SMTP decryption.

    Log Decoder parser option for SMTP decryption

Performance Considerations

Decrypting packets in real time requires extra work in the parsing stage. Before implementing this feature, plan carefully to ensure the incoming traffic bandwidth does not overwhelm the available compute power. You may need more Decoders to decrypt traffic than you would need if not decrypting.

Packets captured on a Decoder normally have a timeout of ~60 seconds in the assembly stage before they are sent to the parsing step. If the Decoder is under memory pressure due to very high bandwidth, the lifetime of the packets in Assembler may be shortened. To alleviate this situation, you can configure a longer timeout value and increase the amount of memory available to hold packets in Assembly. Also, in order to perform decryption of the packets, the Decoder must receive the decryption key before the parsing stage.

Note: Currently, only TLS 1.2 and earlier protocols can be decrypted

With no feeds loaded, the following parsers enabled, and 50% of the sessions being decrypted,a Decoder can process traffic at 3 Gbps .

Parser NameDescription
SYSTEMSession Details
NETWORKNetwork Layer
GeoIPGeographic data based on ip.src and ip.dst
GeoIP2Geographic data by default based on IPv4 (ip.src, ip.dst) and IPv6 (ipv6.src, ipv6.dst) meta keys
HTTPHyper Text Transport Protocol (HTTP)
HTTP_LuaHyper Text Transport Protocol (HTTP) Lua
FTPFile Transfer Protocol (FTP)


Simple Mail Transport Protocol (SMTP)

POP3Post Office Protocol (POP3)


Network News Transport Protocol (NNTP)

DNSDomain Name Service (DNS)


Secure Socket Layer (SSL) Protocol

MAILStandard E-Mail Format (RFC822)


Extracts VCARD fullname and email information

PGPIdentifies PGP blocks within network traffic


Identifies SMIME blocks within network traffic

SSHSecure Shell (SSH)


Trivial File Transfer Protocol (TFTP)

DHCPDynamic Host Configuration Protocol (DHCP and BOOTP)


Extracts NETBIOS computer name information.

SNMPSimple Network Management Protocol (SNMP)


Network File System (NFS) protocol

RIPRouting Information Protocol (RIP).
TDSMSSQL and Sybase database protocol (TDS)


Oracle database protocol (TNS)

IRCInternet Relay Chat (IRC) protocol


Real Time Protocol (RTP) for audio/video

SIPSession Initiation Protocol (SIP)


H.323 Teleconferencing protocol

SCCPCisco Skinny Client Control Protocol


Google Talk (GTalk)

VlanGreVlan ID and GRE/EtherIP tunnel addresses


BitTorrent File Sharing Protocol

FIXFinancial Information eXchange Protocol


Gnutella file sharing protocol

IMAPInternet Message Access Protocol


Microsoft Remote Procedure Call protocol

RDPRemote Desktop Protocol


Command Shell Identification



A parser that extracts search terms

FeedParserExternal Feed Parser

Encryption Keys

The sslKeys command accepts two types of encryption keys:

  • Premaster key: the symmetric key used in the TLS payload stream for encryption and decryption.
  • Private key: the asymmetric private key used during the TLS handshake that encrypts the premaster.

Premaster Key

The premaster key is generated randomly and is ephemeral for the life of one specific TLS session. Normally, there is not a good way to get premaster keys to a Decoder in time for the parsing step. However, both Chrome and Firefox can write the premaster keys they generate to a file. This is useful for testing purposes. To configure your browser to do this, create an environment variable called SSLKEYLOGFILE and assign it the pathname of a file to which the keys will be written. The Decoder will accept the file exactly as written and will use all the decryption keys in the file for any encrypted traffic it captures.

This is a sample NwConsole script that uploads the file to a Decoder:

login <decoder>:50004 <username> <password>

send /decoder sslKeys --file-data=SSLKeys.txt

This is an example using a curl command (with the RESTful port) to upload the file to a Decoder:

curl -u "<username>:<password>" -H "Content-Type: application/octet-stream" --data-binary @"/path/SSLKeys.txt" -X POST "http://<hostname>:50104/decoder?msg=sslKeys"

After the symmetric keys are uploaded, they will immediately be used for any necessary decryption. Symmetric keys are stored in memory and there is a limit to how many can be stored at any point in time. As more keys are added, the earliest keys will be aged out. You can also add premaster keys by just passing the random and premaster parameters to sslKeys.

Private Keys or PEM files

Private keys are normally stored in PEM files and are the asymmetric keys generated by services that accept TLS traffic. These keys are used during the TLS handshake to encrypt the premaster symmetric key that will be used for the rest of the payload encryption.

For example, if you have a web server whose traffic you want visibility into, you need to upload the private key it uses to encrypt traffic. You only need to do this once, as it is stored permanently (or until removed by a delete command). Private keys are automatically encrypted before storing to protect them. After upload, you must issue a parser reload command so that the newly installed key becomes visible to the HTTPS parser. Now, all TLS handshakes that use that private key will be able to be decrypted by the Decoder.

Note: Not all ciphers suites use a "known" private key (for example, Ephemeral Diffie Hellman). Encrypted traffic with those ciphers cannot be decrypted unless the premaster key is uploaded to the Decoder before the session is parsed.

These are some sample commands that upload a PEM file to be used for decryption.

Using NwConsole:

send /decoder sslKeys pemFilename=MyKey.pem --file-data=/path/MyKey.pem

Using the RESTful interface (you must provide the pemFilename parameter in the URL):

curl -u "<username>:<password>" -H "Content-Type: application/octet-stream" --data-binary @"/path/MyKey.pem" -X POST "http://<hostname>:50104/decoder?msg=sslKeys&pemFilename=MyKey.pem"

Upload Multiple Premaster and Private Keys

You can use the RESTful interface form to facilitate uploading of multiple keys, both premaster and private at the same time.

  1. Open the RESTful API in your browser, and navigate to this path on the Decoder that you want to configure: /decoder/sslkeys.

    This is an example of the RESTful interface form.

  2. Next to Upload File 1, click Choose File and locate the premaster key file or PEM file that you want to upload on you local file system.
  3. (Optional) Repeat for Upload File 2 and Upload File 3.

    This is an example of the RESTful interface form with additional uploads.

  4. Click Upload.

    The files are uploaded to the Decoder and results are displayed in the form.

    This is an example of the RESTful interface form with results.

Parameters for Managing Keys

The sslKeys command has several parameters for managing premaster and private keys. This is the full list of parameters:

clear Removes all premaster keys from memory. Does not delete any PEM files installed on the system.
maxKeys Changes the maximum number of premaster keys that are stored in memory.
listPems Returns a list of all installed private key PEM files.
deletePem Deletes the named PEM file from the file system. You can pass this parameter more than once to remove multiple files.
random The random hash used to identify the premaster key.
premaster The premaster key that will be installed for the previous random parameter. They must show up in pairs and random must be first.

Return Values

Most sslKeys commands return name/value pairs of statistics about the premaster keys in memory. The statistics are listed in the following table.

added The number of premaster keys just added during this command.
total The total number of premaster keys loaded in memory.
agedOut The total number of premaster keys that were removed during this command; this is not a lifetime stat.
maxKeys The current maximum allowed premaster keys

Viewing Unencrypted Traffic

If packets are decrypted during the parse stage, encrypted packets are written to disk, and the matching premaster key used for decrypting is written to the tls.premaster meta key, analysts can view the unencrypted packets using the tls.premaster meta key.

One Decoder API that you can use to see the unencrypted packets is the /sdk/content RESTful service. You need to know the Session ID of the encrypted packets and the flags parameter masked to the value 128 (or 0x80 in hex). Point your browser to the Decoder RESTful interface and type in the following command, substituting the actual Session ID for <id>:


The Decoder returns a simple web page showing the packets after they are decrypted.

If you want to see what the packets look like encrypted, type in one of the following commands, substituting the Session ID for <id>:



For more information on the /sdk/content service, see the manual page for /sdk content.

Supported Cipher Suites

The following table lists which cipher-suites are supported using private keys, as well as those that are not supported.

Cipher Suite Name (RFC)Name (OpenSSL)Cipher SuiteTLS VersionKeyExch.FIPSPrivate Key
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384ECDHE-RSA-AES256-GCM-SHA384[0xc030]TLSv1.2Kx=ECDHCompliantNot Supported
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384ECDHE-ECDSA-AES256-GCM-SHA384[0xc02c]TLSv1.2Kx=ECDHCompliantNot Supported
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384ECDHE-RSA-AES256-SHA384[0xc028]TLSv1.2Kx=ECDHCompliantNot Supported
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384ECDHE-ECDSA-AES256-SHA384[0xc024]TLSv1.2Kx=ECDHCompliantNot Supported
TLS_DHE_DSS_WITH_AES_256_GCM_SHA384DHE-DSS-AES256-GCM-SHA384[0xa3]TLSv1.2Kx=DHCompliantNot Supported
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384DHE-RSA-AES256-GCM-SHA384[0x9f]TLSv1.2Kx=DHCompliantNot Supported
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256DHE-RSA-AES256-SHA256[0x6b]TLSv1.2Kx=DHCompliantNot Supported
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256DHE-DSS-AES256-SHA256[0x6a]TLSv1.2Kx=DHCompliantNot Supported
TLS_DHE_RSA_WITH_AES_256_CBC_SHADHE-RSA-AES256-SHA[0x39]SSLv3Kx=DHCompliantNot Supported
TLS_DHE_DSS_WITH_AES_256_CBC_SHADHE-DSS-AES256-SHA[0x38]SSLv3Kx=DHCompliantNot Supported
TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384ECDH-RSA-AES256-GCM-SHA384[0xc032]SSLv3Kx=ECDH/RSACompliantNot Supported
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384ECDH-RSA-AES256-SHA384[0xc02a]TLSv1.2Kx=ECDH/RSACompliantNot Supported
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384ECDH-ECDSA-AES256-SHA384[0xc026]TLSv1.2Kx=ECDH/ECDSACompliantNot Supported
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256ECDHE-RSA-AES128-GCM-SHA256[0xc02f]TLSv1.2Kx=ECDHCompliantNot Supported
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256ECDHE-ECDSA-AES128-GCM-SHA256[0xc02b]TLSv1.2Kx=ECDHCompliantNot Supported
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256ECDHE-RSA-AES128-SHA256[0xc027]TLSv1.2Kx=ECDHCompliantNot Supported
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256ECDHE-ECDSA-AES128-SHA256[0xc023]TLSv1.2Kx=ECDHCompliantNot Supported
TLS_DHE_DSS_WITH_AES_128_GCM_SHA256DHE-DSS-AES128-GCM-SHA256[0xa2]TLSv1.2Kx=DHCompliantNot Supported
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256DHE-RSA-AES128-GCM-SHA256[0x9e]TLSv1.2Kx=DHCompliantNot Supported
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256DHE-RSA-AES128-SHA256[0x67]TLSv1.2Kx=DHCompliantNot Supported
TLS_DHE_DSS_WITH_AES_128_CBC_SHA256DHE-DSS-AES128-SHA256[0x40]TLSv1.2Kx=DHCompliantNot Supported
TLS_DHE_RSA_WITH_AES_128_CBC_SHADHE-RSA-AES128-SHA[0x33]SSLv3Kx=DHCompliantNot Supported
TLS_DHE_DSS_WITH_AES_128_CBC_SHADHE-DSS-AES128-SHA[0x32]SSLv3Kx=DHCompliantNot Supported
TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256ECDH-RSA-AES128-GCM-SHA256[0xc031]TLSv1.2Kx=ECDH/RSACompliantNot Supported
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256ECDH-RSA-AES128-SHA256[0xc029]TLSv1.2Kx=ECDH/RSACompliantNot Supported
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256ECDH-ECDSA-AES128-SHA256[0xc025]TLSv1.2Kx=ECDH/ECDSACompliantNot Supported
TLS_ECDHE_RSA_WITH_RC4_128_SHAECDHE-RSA-RC4-SHA[0xc011]SSLv3Kx=ECDHNon-CompliantNot Supported
TLS_ECDH_RSA_WITH_RC4_128_SHAECDH-RSA-RC4-SHA[0xc00c]SSLv3Kx=ECDH/RSANon-CompliantNot Supported

TLS Certificate Hashing

The Network Decoder can produce hashes of certificates that are seen in the packet stream. These hashes are the SHA-1 value of any DER-encoded certificate encountered during a TLS handshake. The hashes produced can be used to compare network traffic with hashes from public SSL blacklists, such as the one from

The TLS Certificate hashing feature is disabled by default. To enable TLS Certificate hashing:

  1. Go to ADMIN > Services, select a Network Decoder service and The actions menu > View > Explore.
  2. Select decoder > parsers > config.
  3. In the values column next to parsers.options, type HTTPS="cert.sha1=true".
    When this option is enabled, the SHA-1 is stored as a text value in the cert.thumbprint meta key.

The SHA-256 hash of the certificate can be enabled by adding the parser option:


to a Network Decoder's /decoder/parsers/config/parsers.options configuration.

When this option is enabled, SHA-256 is stored as a text value in the meta keys:

JA3 and JA3S TLS Fingerprints

The Network Decoder can produce the JA3 value of TLS clients and the JA3S value of TLS servers that are observed in a Network session. The values that are produced conform to the values generated by the open source JA3 tools ( The JA3 features are disabled by default.

To enable JA3 features:

  1. In the NetWitness Platform User Interface, go to ADMIN > Services.
  2. Select a Decoder service and click The actions menu > View > Explore.
  3. In the left panel, select decoder > parsers > config.
  4. In parsers.options, add HTTPS="ja3=true ja3s=true".

  5. In the left panel, right click on parsers and select properties.

  6. In the right panel, in the lower pane, set the value in the first drop down to Reload.

  7. Click Send.

JA3 and JA3S can be enabled independently using these options. When enabled, the JA3 is stored as a text value in the meta key ja3. The JA3S is stored as a text value in the meta key ja3s.

Additional meta keys are activated using a mechanism similar to the JA3S and JA3S meta items. For example, ja3.orig is enabled by adding ja3.orig=true to the HTTPS parser options. This is also true for ja3s.orig, tls.extensionlen, and tls.cipherlen.

ja3.orig, tls.extensionlen, and tls.cipherlen are only created if JA3 is enabled.

ja3s.orig is only created if JA3S is enabled.

Community ID

The Network Decoder generates Community ID flow hash values that are compatible with the Community ID specification defined by

The Community ID is written to a text-formatted meta key named community.

The Community ID is generated on sessions containing TCP over IPv4, TCP over IPv6, UDP over IPV4, and UDP over IPV6.

You are here
Table of Contents > Decoder and Log Decoder Additional Procedures > Decrypt Incoming Packets