doc: add documentation for TLS eve-log

diff --git a/doc/userguide/output/eve/eve-json-format.rst b/doc/userguide/output/eve/eve-json-format.rst
index db3d7c96a0123c328a15c9c643f91df63dac618c..ad328d5403f4aa065a3677d33c11a9229ff01e0d 100644 (file)
--- a/doc/userguide/output/eve/eve-json-format.rst
+++ b/doc/userguide/output/eve/eve-json-format.rst
@@ -196,3 +196,61 @@ Example of a DNS answer with an IPv4 (resource record type 'A') return:
       "ttl":8,
       "rdata": "199.16.156.6"
   }
+
+Event type: TLS
+---------------
+
+Fields
+~~~~~~
+
+* "subject": The subject field from the TLS certificate
+* "issuer": The issuer field from the TLS certificate
+
+If extended logging is enabled the following fields are also included:
+
+* "fingerprint": The (SHA1) fingerprint of the TLS certificate
+* "sni": The Server Name Indication (SNI) extension sent by the client
+* "version": The SSL/TLS version used
+* "notbefore": The NotBefore field from the TLS certificate
+* "notafter": The NotAfter field from the TLS certificate
+
+In addition to this, custom logging also allows the following fields:
+
+* "certificate": The TLS certificate base64 encoded
+* "chain": The entire TLS certificate chain base64 encoded
+
+Examples
+~~~~~~~~
+
+Example of regular TLS logging:
+
+::
+
+  "tls": {
+      "subject": "C=US, ST=California, L=Mountain View, O=Google Inc, CN=*.google.com",
+      "issuerdn": "C=US, O=Google Inc, CN=Google Internet Authority G2"
+  }
+
+Example of extended TLS logging:
+
+::
+
+  "tls": {
+      "subject": "C=US, ST=California, L=Mountain View, O=Google Inc, CN=*.google.com",
+      "issuerdn": "C=US, O=Google Inc, CN=Google Internet Authority G2",
+      "fingerprint": "8f:51:12:06:a0:cc:4e:cd:e8:a3:8b:38:f8:87:59:e5:af:95:ca:cd",
+      "sni": "calendar.google.com",
+      "version": "TLS 1.2",
+      "notbefore": "2017-01-04T10:48:43",
+      "notafter": "2017-03-29T10:18:00"
+  }
+
+Example of certificate logging using TLS custom logging (subject, sni, certificate):
+
+::
+
+  "tls": {
+      "subject": "C=US, ST=California, L=Mountain View, O=Google Inc, CN=*.googleapis.com
+      "sni": "www.googleapis.com",
+      "certificate": "MIIE3TCCA8WgAwIBAgIIQPsvobRZN0gwDQYJKoZIhvcNAQELBQAwSTELMA [...]"
+   }

diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst
index a960e7e16cd94527c1e64f495174affeb117a0b8..65c74590105e1139ebdc9895550e0dc96e6d6a89 100644 (file)
--- a/doc/userguide/output/eve/eve-json-output.rst
+++ b/doc/userguide/output/eve/eve-json-output.rst
@@ -80,6 +80,10 @@ The most common way to use this is through 'EVE', which is a firehose approach w
             #custom: [a, aaaa, cname, mx, ns, ptr, txt]
         - tls:
             extended: yes     # enable this for extended logging information
+            # custom allows to control which tls fields that are included
+            # in eve-log
+            #custom: [subject, issuer, fingerprint, sni, version, not_before, not_after, certificate, chain]
+
         - files:
             force-magic: no   # force logging magic on all logged files
             # force logging of checksums, available hash functions are md5,
@@ -181,6 +185,24 @@ YAML::
 To reduce verbosity the output can be filtered by supplying the record types
 to be logged under ``custom``.
 
+TLS
+~~~
+
+TLS records are logged one record per session.
+
+YAML::
+
+        - tls:
+            extended: yes     # enable this for extended logging information
+            # custom allows to control which tls fields that are included
+            # in eve-log
+            #custom: [subject, issuer, fingerprint, sni, version, not_before, not_after, certificate, chain]
+
+The default is to log certificate subject and issuer. If ``extended`` is
+enabled, then the log gets more verbose.
+
+By using ``custom`` it is possible to select which TLS fields to log.
+
 Multiple Logger Instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~