11.7. User Accessible Tables

User Accessible Tables are a type of preference table which may be associated with particular protocols or with the application as a whole.

User Accessible Tables have a common editor dialog which works as described in Section 11.5.6, “Expert Items” and Section 11.5.7, “Filter Buttons”. Note that the name of the file appears in the lower right corner of the dialog.

The files are saved in a CSV format, where values are either double quoted ASCII strings (using C-style backslash escapes for non-printable characters) or unquoted hexstrings, depending on the field type. They can be edited directly when Wireshark is not running, though this is discouraged. Entries can also be appended to the table by passing an appropriate CSV formatted record string on the command line.

Most UATs are stored in the configuration profile:

Other UATs are stored in the personal configuration directory and are common to all profiles:

11.7.1. ESS Category Attributes

Wireshark uses this table to map ESS Security Category attributes to textual representations. The values to put in this table are usually found in an XML SPIF, which is used for defining security labels.

This table is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

Tag Set
An Object Identifier representing the Category Tag Set.
Value
The value (Label And Cert Value) representing the Category.
Name
The textual representation for the value.

11.7.2. MaxMind Database Paths

If your copy of Wireshark supports MaxMind’s MaxMindDB library, you can use their databases to match IP addresses to countries, cites, autonomous system numbers, and other bits of information. Some databases are available at no cost for registered users, while others require a licensing fee. See the MaxMind web site for more information.

The configuration for the MaxMind database is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

Database pathname
This specifies a directory containing MaxMind data files. Any files ending with .mmdb will be automatically loaded.

By default Wireshark will always search for data files in /usr/share/GeoIP and /var/lib/GeoIP on non-Windows platforms and in C:\ProgramData\GeoIP and C:\GeoIP on Windows. You can put any additional search paths here, e.g. C:\Program Files\Wireshark\GeoIP might be a good choice on Windows.

[Note]Note

While the default search paths are not listed in the user table, they are in the list viewable by opening HelpAbout Wireshark and selecting the "Folders" tab.

Previous versions of Wireshark supported MaxMind’s original GeoIP Legacy database format. They were configured similar to MaxMindDB files above, except GeoIP files must begin with Geo and end with .dat. They are no longer supported and MaxMind stopped distributing GeoLite Legacy databases in April 2018.

11.7.3. IEEE 802.11 WLAN Decryption Keys

Wireshark can decrypt WEP and WPA/WPA2/WPA3 in pre-shared (or personal) mode, as well as in enterprise mode. Security improvements in more recent 802.11 releases require distinct session keys, instead of being able to decipher all traffic to a given access point with a single known password and SSID.

You can add decryption keys using Wireshark’s IEEE 802.11 preferences. Up to 64 keys are supported.

11.7.3.1. Adding Keys

Go to EditPreferencesProtocolsIEEE 802.11, or, from the pop-up menu in the "Packet List" or "Packet Details" pane from a frame that contains IEEE 802.11, Protocol PreferencesIEEE 802.11 wireless LAN. You should see a window that looks like this:

Figure 11.19. "IEEE 802.11 wireless LAN" preferences

ws wireless ieee 80211 pref

Click on the "Edit…​" button next to "Decryption Keys" to add keys. You should see a window that looks like this:

Figure 11.20. 802.11 Decryption Key Types

ws wireless key type

When you click the + button to add a new key, there are five key types you can choose from: wep, wpa-pwd, wpa-psk, tk, or msk. The correct key type(s) depend on the Cipher Suite and Authentication and Key Management Suite (AKMS) used to encrypt the wireless traffic.

wep

The key must be provided as a string of hexadecimal numbers, with or without colons, and will be parsed as a WEP key. WEP keys can be 40-bit (5 bytes, or 10 hexadecimal characters), 104-bit, or occasionally 128-bit:

a1:b2:c3:d4:e5
0102030405060708090a0b0c0d
wpa-pwd

The password and SSID are used to create a raw pre-shared WPA key. The password can be between 8 and 63 characters, and the SSID can be up to 32 bytes. (Typically both are printable ASCII, but that is not a hard limitation of the specification, only a recommendation.)

MyPassword:MySSID

You can optionally omit the colon and SSID, and Wireshark will try to decrypt packets using the last-seen SSID. This may not work for captures taken in busy environments, since the last-seen SSID may not be correct.

MyPassword
[Note]Note

The WPA passphrase and SSID let you encode non-printable or otherwise troublesome characters using URI-style percent escapes, e.g., %20 for a space. As a result you have to escape the percent characters themselves using %25. You also must escape colons in the passphrase or SSID themselves as %3a, in order to distinguish them from a colon as a separator between the passphrase and SSID.

[Warning]Warning

The WPA pass-phrase and SSID method is for WPA/WPA2-Personal only. It will not work for WPA3-Personal, which uses SAE (Simultaneous Authentication of Equals), nor for the Enterprise / 802.1X / EAP modes.

wpa-psk

The key must be provided as a hexadecimal string, and is parsed as a PSK (Pre-Shared Key) or PMK (Pairwise Master Key). For WPA/WPA2-Personal, the PSK and the PMK are identical, and directly derived from the passphrase and SSID above. The keys can be 256 bits (32 bytes, 64 hex characters) or 384 bits (48 bytes, 96 hex characters).

0102030405060708091011...6061626364
tk
The key must be provided as a hexadecimal string, and is parsed as a PTK (Pairwise Transient Key) or GTK (Group Temporal Key). The keys can be 16 or 32 bytes (128 or 256 bits), depending on the cipher suite used. (5 and 13 byte WEP TKs are not yet supported.)
msk
The key must be provided as a hexadecimal string, and is parsed as a MSK (Master Session Key). This is used for FT-EAP (IEEE 802.11r Fast BSS Transition with EAP authentication). The key can be 64 or 128 bytes.

Figure 11.21. 802.11 Decryption Key Examples

ws wireless key examples

11.7.3.2. Gotchas

Along with decryption keys there are other preference settings that affect decryption.

  • Make sure Enable decryption is selected.
  • You may have to toggle Assume Packets Have FCS and Ignore the Protection bit depending on how your 802.11 driver delivers frames.
11.7.3.2.1. Capturing the 4-way Handshake

WPA and WPA2 use keys derived from an EAPOL handshake, which occurs when a machine joins a Wi-Fi network, to encrypt traffic. Unless all four handshake packets are present for the session you’re trying to decrypt, Wireshark won’t be able to decrypt the traffic. You can use the display filter eapol to locate EAPOL packets in your capture.

In order to capture the handshake for a machine, you will need to force the machine to (re-)join the network while the capture is in progress. One way to do this is to put the machine to sleep (for smartphones and tablets, "turning off" the machine puts it to sleep) before you start the capture, start the capture, and then wake the machine up. You will need to do this for all machines whose traffic you want to see.

If a TK is provided as a key, then the EAPOL 4-way handshake is not necessary, as the TK is what the handshake derives. However, all available TKs will be tried agi

11.7.3.2.2. Too Many Associations

WPA and WPA2 use individual keys for each device. Wireshark is able to handle up to 256 active associations, which should be enough in most circumstances. Nevertheless, if a capture has too many devices and too many associations, then while the packet list may show all packets decoded on the first pass, randomly accessing different packets in the packet details will result in some packets failing to be properly deciphered.

Filtering out only the relevant packets (e.g. with "wlan.addr") and saving into a new file should get decryption working in all cases, though it may require editing keys in the preferences or restarting Wireshark in order to free used associations. For the same reason, it is possible to be able to decode packets in a capture file without any EAPOL packets in it, as long as Wireshark did see the handshake for this communication in another capture without being restarted or editing keys. This can sometimes lead to exporting selected packets to a new file, opening that file and decoding seeming to work, but then decoding suddenly fail on the new file after Wireshark is restarted or keys are edited. If decoding suddenly stops working on a capture make sure the needed EAPOL packets are still in it.

11.7.3.2.3. WPA/WPA2 Enterprise/Rekeys

As long as you can somehow extract the PMK from either the client or the Radius Server and configure the key (as PSK) all supported Wireshark versions will decode the traffic just fine up to the first EAPOL rekey.

EAPoL rekey is often enabled for WPA/WPA2 enterprise and will change the used encryption key similar to the procedure for the initial connect, but it can also be configured and used for pre-shared (personal) mode.

Decrypting IEEE 802.11r Fast BSS Transition roaming requires capturing reassociation frames for similar reasons, and is supported by recent Wireshark versions.

11.7.3.2.4. WPA3 Per-Connection Decryption

In WPA3, a different PMK is used for each connection in order to achieve forward secrecy. Capturing the 4-way handshake and knowing the network password is not enough to decrypt packets; you must obtain the PMK from either the client or access point (typically by enabling logging in wpa_supplicant or hostapd with the -d -K flags) and use this as the decryption key in Wireshark. Even then, the decryption will only work for packets between that client and access point, not for all devices on that network.

11.7.3.2.5. TKs and Performance

The TKs are the actual transient keys used to encrypt packets, which are derived during the handshake. If known, they can decrypt packets without having the handshake packets in a capture. However, having TKs as encryption keys in the table will affect IEEE 802.11 dissector performance as each encrypted packet will be tested against every TK until decryption is successful. If the table is configured with many TKs, none of which match any encrypted frame in the capture, performance can be slow.

Once a match is found, an association is formed similar to in the usual method and decryption of other frames with the same key should be on par with normal decryption flow. Thus, if most frames in the capture match TKs (or other keys), and only a limited number of TKs are configured, the performance impact is slight.

11.7.4. IKEv2 decryption table

Wireshark can decrypt Encrypted Payloads of IKEv2 (Internet Key Exchange version 2) packets if necessary information is provided. Note that you can decrypt only IKEv2 packets with this feature. If you want to decrypt IKEv1 packets or ESP packets, use Log Filename setting under ISAKMP protocol preference or settings under ESP protocol preference respectively.

This is handled by a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

Initiator’s SPI
Initiator’s SPI of the IKE_SA. This field takes hexadecimal string without “0x” prefix and the length must be 16 hex chars (represents 8 octets).
Responder’s SPI
Responder’s SPI of the IKE_SA. This field takes hexadecimal string without “0x” prefix and the length must be 16 hex chars (represents 8 octets).
SK_ei
Key used to encrypt/decrypt IKEv2 packets from initiator to responder. This field takes hexadecimal string without “0x” prefix and its length must meet the requirement of the encryption algorithm selected.
SK_er
Key used to encrypt/decrypt IKEv2 packets from responder to initiator. This field takes hexadecimal string without “0x” prefix and its length must meet the requirement of the encryption algorithm selected.
Encryption Algorithm
Encryption algorithm of the IKE_SA.
SK_ai
Key used to calculate Integrity Checksum Data for IKEv2 packets from responder to initiator. This field takes hexadecimal string without “0x” prefix and its length must meet the requirement of the integrity algorithm selected.
SK_ar
Key used to calculate Integrity Checksum Data for IKEv2 packets from initiator to responder. This field takes hexadecimal string without “0x” prefix and its length must meet the requirement of the integrity algorithm selected.
Integrity Algorithm
Integrity algorithm of the IKE_SA.

11.7.5. Object Identifiers

Many protocols that use ASN.1 use Object Identifiers (OIDs) to uniquely identify certain pieces of information. In many cases, they are used in an extension mechanism so that new object identifiers (and associated values) may be defined without needing to change the base standard.

While Wireshark has knowledge about many of the OIDs and the syntax of their associated values, the extensibility means that other values may be encountered.

Wireshark uses this table to allow the user to define the name and syntax of Object Identifiers that Wireshark does not know about (for example, a privately defined X.400 extension). It also allows the user to override the name and syntax of Object Identifiers that Wireshark does know about (e.g., changing the name “id-at-countryName” to just “c”).

This table is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

OID
The string representation of the Object Identifier e.g., “2.5.4.6”.
Name
The name that should be displayed by Wireshark when the Object Identifier is dissected e.g., (“c”);
Syntax
The syntax of the value associated with the Object Identifier. This must be one of the syntaxes that Wireshark already knows about (e.g., “PrintableString”).

11.7.6. PRES Users Context List

Wireshark uses this table to map a presentation context identifier to a given object identifier when the capture does not contain a PRES package with a presentation context definition list for the conversation.

This table is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

Context Id
An Integer representing the presentation context identifier for which this association is valid.
Syntax Name OID
The object identifier representing the abstract syntax name, which defines the protocol that is carried over this association.

11.7.7. SCCP users Table

Wireshark uses this table to map specific protocols to a certain DPC/SSN combination for SCCP.

This table is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

Network Indicator
An Integer representing the network indicator for which this association is valid.
Called DPCs
A range of integers representing the dpcs for which this association is valid.
Called SSNs
A range of integers representing the ssns for which this association is valid.
User protocol
The protocol that is carried over this association

11.7.8. SMI (MIB and PIB) Modules

If your copy of Wireshark supports libSMI, you can specify a list of MIB and PIB modules here. The COPS and SNMP dissectors can use them to resolve OIDs.

Module name
The name of the module, e.g., IF-MIB.

11.7.9. SMI (MIB and PIB) Paths

If your copy of Wireshark supports libSMI, you can specify one or more paths to MIB and PIB modules here.

Directory name
A module directory, e.g., /usr/local/snmp/mibs. Wireshark automatically uses the standard SMI path for your system, so you usually don’t have to add anything here.

11.7.10. SNMP Enterprise Specific Trap Types

Wireshark uses this table to map specific-trap values to user defined descriptions in a Trap PDU. The description is shown in the packet details specific-trap element.

This table is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

Enterprise OID
The object identifier representing the object generating the trap.
Trap Id
An Integer representing the specific-trap code.
Description
The description to show in the packet details.

11.7.11. SNMP users Table

Wireshark uses this table to verify authentication and to decrypt encrypted SNMPv3 packets.

This table is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

Engine ID
If given this entry will be used only for packets whose engine id is this. This field takes a hexadecimal string in the form 0102030405.
Username
This is the userName. When a single user has more than one password for different SNMP-engines the first entry to match both is taken, if you need a catch all engine-id (empty) that entry should be the last one.
Authentication model
Which auth model to use (either “MD5” or “SHA1”).
Password
The authentication password. Use \xDD for unprintable characters. A hexadecimal password must be entered as a sequence of \xDD characters. For example, the hex password 010203040506 must be entered as \x01\x02\x03\x04\x05\x06. The \ character must be treated as an unprintable character, i.e., it must be entered as \x5C or \x5c.
Privacy protocol
Which encryption algorithm to use (either “DES” or “AES”).
Privacy password
The privacy password. Use \xDD for unprintable characters. A hexadecimal password must be entered as a sequence of \xDD characters. For example, the hex password 010203040506 must be entered as \x01\x02\x03\x04\x05\x06. The \ character must be treated as an unprintable character, i.e., it must be entered as \x5C or \x5c.

11.7.12. Tektronix K12xx/15 RF5 protocols Table

The Tektronix K12xx/15 rf5 file format uses helper files (*.stk) to identify the various protocols that are used by a certain interface. Wireshark doesn’t read these stk files, it uses a table that helps it identify which lowest layer protocol to use.

Stk file to protocol matching is handled by a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

Match string
A partial match for an stk filename, the first match wins, so if you have a specific case and a general one the specific one must appear first in the list.
Protocol
This is the name of the encapsulating protocol (the lowest layer in the packet data) it can be either just the name of the protocol (e.g., mtp2, eth_withoutfcs, sscf-nni ) or the name of the encapsulation protocol and the “application” protocol over it separated by a colon (e.g., sscop:sscf-nni, sscop:alcap, sscop:nbap, …​)

11.7.13. User DLTs dissector table

When a pcap file uses one of the user DLTs (147 to 162) Wireshark uses this table to know which dissector(s) to use for each user DLT.

This table is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

DLT
One of the user dlts.
Payload dissector
This is the name of the payload dissector (the lowest layer in the packet data). (e.g., “eth_withfcs, "eth_withoutfcs”, and "eth_maybefcs" respectively for Ethernet frames that do, do not, or might possibly include the FCS at the end, “ip” for trying IPv4 then IPv6)
Header size
If there is a header (before the payload) this tells which size this header is. A value of 0 disables the header dissector.
Header dissector
The name of the header dissector to be used (uses “data” as default).
Trailer size
If there is a trailer (after the payload) this tells which size this trailer is. A value of 0 disables the trailer dissector.
Trailer dissector
The name of the trailer dissector to be used (uses “data” as default).

11.7.14. Protobuf Search Paths

The binary wire format of Protocol Buffers (Protobuf) messages are not self-described protocol. For example, the varint wire type in protobuf packet may be converted to int32, int64, uint32, uint64, sint32, sint64, bool or enum field types of protocol buffers language. Wireshark should be configured with Protocol Buffers language files (*.proto) to enable proper dissection of protobuf data (which may be payload of gRPC) based on the message, enum and field definitions.

You can specify protobuf search paths at the Protobuf protocol preferences. For example, if you defined a proto file with path d:/my_proto_files/helloworld.proto and the helloworld.proto contains a line of import "google/protobuf/any.proto"; because the any type of official protobuf library is used. And the real path of any.proto is d:/protobuf-3.4.1/include/google/protobuf/any.proto. You should add the d:/protobuf-3.4.1/include/ and d:/my_proto_files paths into protobuf search paths.

The configuration for the protobuf search paths is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

Protobuf source directory
This specifies a directory containing protobuf source files. For example, d:/protobuf-3.4.1/include/ and d:/my_proto_files in Windows, or /usr/include/ and /home/alice/my_proto_files in Linux/UNIX.
Load all files
If this option is enabled, Wireshark will load all *.proto files in this directory and its subdirectories when Wireshark startup or protobuf search paths preferences changed. Note that the source directories that configured to protobuf official or third libraries path (like d:/protobuf-3.4.1/include/) should not be set to load all files, that may cause unnecessary memory use.

11.7.15. Protobuf UDP Message Types

If the payload of UDP on certain ports is Protobuf encoding, Wireshark use this table to know which Protobuf message type should be used to parsing the data on the specified UDP port(s).

The configuration for UDP Port(s) to Protobuf message type maps is a user table, as described in Section 11.7, “User Accessible Tables”, with the following fields:

UDP Ports
The range of UDP ports. The format may be "8000" or "8000,8008-8088,9080".
Message Type
The Protobuf message type as which the data on the specified udp port(s) should be parsed. The message type is allowed to be empty, that means let Protobuf to dissect the data on specified UDP ports as normal wire type without precise definitions.

Tips: You can create your own dissector to call Protobuf dissector. If your dissector is written in C language, you can pass the message type to Protobuf dissector by data parameter of call_dissector_with_data() function. If your dissector is written in Lua, you can pass the message type to Protobuf dissector by pinfo.private["pb_msg_type"]. The format of data and pinfo.private["pb_msg_type"] is

    "message," message_type_name

For example:

    message,helloworld.HelloRequest

the helloworld is package name, HelloRequest is message type.