index.rst (3504B)
1 .. _mozilla_projects_nss_key_log_format: 2 3 NSS Key Log Format 4 ================== 5 6 .. container:: 7 8 Key logs can be written by NSS so that external programs can decrypt TLS connections. Wireshark 9 1.6.0 and above can use these log files to decrypt packets. You can tell Wireshark where to find 10 the key file via *Edit→Preferences→Protocols→TLS→(Pre)-Master-Secret log filename*. 11 12 Key logging is enabled by setting the environment variable ``SSLKEYLOGFILE`` to point to a file. 13 Note: starting with :ref:`mozilla_projects_nss_nss_3_24_release_notes` (used by Firefox 48 and 49 14 only), the ``SSLKEYLOGFILE`` approach is disabled by default for optimized builds using the 15 Makefile (those using gyp via ``build.sh`` are *not* affected). Distributors can re-enable it at 16 compile time though (using the ``NSS_ALLOW_SSLKEYLOGFILE=1`` make variable) which is done for the 17 official Firefox binaries. (See `bug 18 1188657 <https://bugzilla.mozilla.org/show_bug.cgi?id=1188657>`__.) Notably, Debian does not have 19 this option enabled, see `Debian bug 20 842292 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=842292>`__. 21 22 This key log file is a series of lines. Comment lines begin with a sharp character ('#') and are 23 ignored. Secrets follow the format ``<Label> <space> <ClientRandom> <space> <Secret>`` where: 24 25 - ``<Label>`` describes the following secret. 26 - ``<ClientRandom>`` is 32 bytes Random value from the Client Hello message, encoded as 64 27 hexadecimal characters. 28 - ``<Secret>`` depends on the Label (see below). 29 30 The following labels are defined, followed by a description of the secret: 31 32 - ``RSA``: 48 bytes for the premaster secret, encoded as 96 hexadecimal characters (removed in 33 NSS 3.34) 34 - ``CLIENT_RANDOM``: 48 bytes for the master secret, encoded as 96 hexadecimal characters (for 35 SSL 3.0, TLS 1.0, 1.1 and 1.2) 36 - ``CLIENT_EARLY_TRAFFIC_SECRET``: the hex-encoded early traffic secret for the client side (for 37 TLS 1.3) 38 - ``CLIENT_HANDSHAKE_TRAFFIC_SECRET``: the hex-encoded handshake traffic secret for the client 39 side (for TLS 1.3) 40 - ``SERVER_HANDSHAKE_TRAFFIC_SECRET``: the hex-encoded handshake traffic secret for the server 41 side (for TLS 1.3) 42 - ``CLIENT_TRAFFIC_SECRET_0``: the first hex-encoded application traffic secret for the client 43 side (for TLS 1.3) 44 - ``SERVER_TRAFFIC_SECRET_0``: the first hex-encoded application traffic secret for the server 45 side (for TLS 1.3) 46 - ``EARLY_EXPORTER_SECRET``: the hex-encoded early exporter secret (for TLS 1.3). 47 - ``EXPORTER_SECRET``: the hex-encoded exporter secret (for TLS 1.3) 48 49 The ``RSA`` form allows ciphersuites using RSA key-agreement to be logged and was the first form 50 supported by Wireshark 1.6.0. It has been superseded by ``CLIENT_RANDOM`` which also works with 51 other key-agreement algorithms (such as those based on Diffie-Hellman) and is supported since 52 Wireshark 1.8.0. 53 54 The TLS 1.3 lines are supported since NSS 3.34 (`bug 55 1287711 <https://bugzilla.mozilla.org/show_bug.cgi?id=1287711>`__) and Wireshark 2.4 56 (``EARLY_EXPORTER_SECRET`` exists since NSS 3.35, `bug 57 1417331 <https://bugzilla.mozilla.org/show_bug.cgi?id=1417331>`__). The size of the hex-encoded 58 secret depends on the selected cipher suite. It is 64, 96 or 128 characters for SHA256, SHA384 or 59 SHA512 respectively. 60 61 For Wireshark usage, see `TLS - Wireshark Wiki <https://wiki.wireshark.org/TLS>`__.