From 50c160c7bb813c8c72075ba812133fe7550c5d3c Mon Sep 17 00:00:00 2001
From: Pier-Hugues Pellerin <phpellerin@gmail.com>
Date: Mon, 18 Jun 2018 03:02:35 -0400
Subject: [PATCH] Proposal: TLS related fields (#6)

While working on the TCP inputs for beats I am able to extract information about the TLS envelope,
this might be useful information for post-mortems or audit. Also, this was a feature requested on
the beats input on the Logstash side.

We are also extracting some information in [packetbeat](https://github.com/elastic/beats/blob/master/packetbeat/protos/tls/_meta/fields.yml) from the work of @adriansr.

Concerning the TCP or the beats input, I think we can extract the following field and provide some
useful information.

- TLS version
- Remote Certificates (mutual auth)
- ServerName
- Cipher used.

Where OR should this information be in the ECS schema? Maybe we could add a `transport` top level
key and have something like this.

| Field  | Description  | Type  | Example  |
|---|---|---|---|
tls.version| string representation of the tls version| keyword|	TLSv1.1 |
tls.certificates| array of certificates used by the client.|text| raw certificate|
tls.servername| server name requested by client|keyword| localhost[1]
tls.ciphersuite| Name of the cipher used| keyword|  ECDHE-ECDSA-AES-128-CBC-SHA

[1]:https://en.wikipedia.org/wiki/Server_Name_Indication
---
 README.md       | 17 +++++++++++++++++
 schema.csv      |  4 ++++
 schemas/tls.yml | 37 +++++++++++++++++++++++++++++++++++++
 template.json   | 20 ++++++++++++++++++++
 4 files changed, 78 insertions(+)
 create mode 100644 schemas/tls.yml

diff --git a/README.md b/README.md
index 6977420a43..fad3c4c0fc 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,7 @@ ECS defines these fields.
  * [Process fields](#process)
  * [Service fields](#service)
  * [Source fields](#source)
+ * [TLS fields](#tls)
  * [URL fields](#url)
  * [User fields](#user)
  * [User agent fields](#user_agent)
@@ -358,6 +359,22 @@ Source fields describe details about the source of the event.
 | <a name="source.subdomain"></a>`source.subdomain`  | Source subdomain.  | keyword  |   |   |
 
 
+## <a name="tls"></a> TLS fields
+
+The tls fields contain the TLS related data about a specific connection.
+
+
+| Field  | Description  | Type  | Multi Field  | Example  |
+|---|---|---|---|---|
+| <a name="tls.version"></a>`tls.version`  | TLS version.  | keyword  |   | `TLSv1.2`  |
+| <a name="tls.certificates"></a>`tls.certificates`  | An array of certificates.  | keyword  |   |   |
+| <a name="tls.servername"></a>`tls.servername`  | Server name requested by the client.  | keyword  |   | `localhost`  |
+| <a name="tls.ciphersuite"></a>`tls.ciphersuite`  | Name of the cipher used for the communication.  | keyword  |   | `ECDHE-ECDSA-AES-128-CBC-SHA`  |
+
+
+As an example in the case of Filebeat and the TCP input, the `version` field would be the version of the TLS protocol in use, the `certificates` would be the chain of certificates provided by the client and the `ciphersuite` is the encryption algorithm used for the communication.
+
+
 ## <a name="url"></a> URL fields
 
 URL fields provide a complete URL, with scheme, host, and path. The URL object can be reused in other prefixes, such as `host.url.*` for example. Keep the structure consistent whenever you use URL fields.
diff --git a/schema.csv b/schema.csv
index aae85fecdb..7493534db9 100644
--- a/schema.csv
+++ b/schema.csv
@@ -120,6 +120,10 @@ source.ip,ip,0,
 source.mac,keyword,1,
 source.port,long,1,
 source.subdomain,keyword,1,
+tls.certificates,keyword,0,
+tls.ciphersuite,keyword,0,ECDHE-ECDSA-AES-128-CBC-SHA
+tls.servername,keyword,0,localhost
+tls.version,keyword,0,TLSv1.2
 url.fragment,keyword,0,
 url.host.name,keyword,0,elastic.co
 url.href,text,0,https://elastic.co:443/search?q=elasticsearch#top
diff --git a/schemas/tls.yml b/schemas/tls.yml
new file mode 100644
index 0000000000..37bf65deac
--- /dev/null
+++ b/schemas/tls.yml
@@ -0,0 +1,37 @@
+---
+- name: tls
+  title: TLS
+  group: 2
+  description: >
+    The tls fields contain the TLS related data about a specific connection.
+
+  footnote: >
+    As an example in the case of Filebeat and the TCP input, the `version` field would be the
+    version of the TLS protocol in use, the `certificates` would be the chain of certificates
+    provided by the client and the `ciphersuite` is the encryption algorithm used for the
+    communication.
+  fields:
+    - name: version
+      type: keyword
+      description: >
+        TLS version.
+
+      example: TLSv1.2
+    - name: certificates
+      type: keyword
+      description: >
+        An array of certificates.
+      ignore_above: -1
+      doc_values: false
+    - name: servername
+      type: keyword
+      description: >
+        Server name requested by the client.
+
+      example: localhost
+    - name: ciphersuite
+      type: keyword
+      description: >
+        Name of the cipher used for the communication.
+
+      example: ECDHE-ECDSA-AES-128-CBC-SHA
diff --git a/template.json b/template.json
index e5a5a77187..9009d8bdc8 100644
--- a/template.json
+++ b/template.json
@@ -621,6 +621,26 @@
           "ignore_above": 1024,
           "type": "keyword"
         },
+        "tls": {
+          "properties": {
+            "certificates": {
+              "doc_values": false,
+              "type": "keyword"
+            },
+            "ciphersuite": {
+              "ignore_above": 1024,
+              "type": "keyword"
+            },
+            "servername": {
+              "ignore_above": 1024,
+              "type": "keyword"
+            },
+            "version": {
+              "ignore_above": 1024,
+              "type": "keyword"
+            }
+          }
+        },
         "url": {
           "properties": {
             "fragment": {