# Licensed to Elasticsearch B.V. under one or more contributor
# license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright
# ownership. Elasticsearch B.V. licenses this file to you under
# the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# 	http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
---
- name: tls
  title: TLS
  group: 2
  short: Fields describing a TLS connection.
  description: >
    Fields related to a TLS connection. These fields focus on the TLS protocol itself
    and intentionally avoids in-depth analysis of the related x.509 certificate files.
  type: group
  fields:

    - name: version
      level: extended
      type: keyword
      description: Numeric part of the version parsed from the original string.
      example: "1.2"

    - name: version_protocol
      level: extended
      type: keyword
      description: Normalized lowercase protocol name parsed from original string.
      example: "tls"

    - name: cipher
      type: keyword
      level: extended
      description: String indicating the cipher used during the current connection.
      example: "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256"

    - name: curve
      type: keyword
      level: extended
      description: String indicating the curve used for the given cipher, when applicable.
      example: "secp256r1"

    - name: resumed
      type: boolean
      level: extended
      description: Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation.

    - name: established
      type: boolean
      level: extended
      description: >
        Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel.

    - name: next_protocol
      type: keyword
      level: extended
      short: String indicating the protocol being tunneled.
      description: >
        String indicating the protocol being tunneled. Per the values in the IANA registry
        (https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids),
        this string should be lower case.
      example: "http/1.1"

    - name: client.ja3
      type: keyword
      level: extended
      description: A hash that identifies clients based on how they perform an SSL/TLS handshake.
      example: d4e5b18d6b55c71272893221c96ba240

    - name: client.server_name
      type: keyword
      level: extended
      short: Hostname the client is trying to connect to. Also called the SNI.
      description: >
        Also called an SNI, this tells the server which hostname to which the client is attempting to connect to.
        When this value is available, it should get copied to `destination.domain`.
      example: "www.elastic.co"

    - name: client.supported_ciphers
      type: keyword
      level: extended
      description: Array of ciphers offered by the client during the client hello.
      example: "[\"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384\", \"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384\", \"...\"]"
      normalize:
        - array

    - name: client.subject
      type: keyword
      level: extended
      description: Distinguished name of subject of the x.509 certificate presented by the client.
      example: "CN=myclient, OU=Documentation Team, DC=example, DC=com"

    - name: client.issuer
      type: keyword
      level: extended
      description: Distinguished name of subject of the issuer of the x.509 certificate presented by the client.
      example: "CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"

    - name: client.not_before
      type: date
      level: extended
      description: Date/Time indicating when client certificate is first considered valid.
      example: "1970-01-01T00:00:00.000Z"

    - name: client.not_after
      type: date
      level: extended
      description: Date/Time indicating when client certificate is no longer considered valid.
      example: "2021-01-01T00:00:00.000Z"

    - name: client.certificate_chain
      type: keyword
      level: extended
      short: Array of PEM-encoded certificates that make up the certificate chain offered by the client.
      description: >
        Array of PEM-encoded certificates that make up the certificate chain offered by the client. This is
        usually mutually-exclusive of `client.certificate` since that value should be the first certificate
        in the chain.
      example: "[\"MII...\", \"MII...\"]"
      normalize:
        - array

    - name: client.certificate
      type: keyword
      level: extended
      short: PEM-encoded stand-alone certificate offered by the client.
      description: >
        PEM-encoded stand-alone certificate offered by the client. This is usually mutually-exclusive of
        `client.certificate_chain` since this value also exists in that list.
      example: "MII..."

    - name: client.hash.md5
      type: keyword
      level: extended
      short: Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client.
      description: >
        Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client.
        For consistency with other hash values, this value should be formatted as an uppercase hash.
      example: 0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC

    - name: client.hash.sha1
      type: keyword
      level: extended
      short: >
        Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client.
      description: >
        Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client.
        For consistency with other hash values, this value should be formatted as an uppercase hash.
      example: 9E393D93138888D288266C2D915214D1D1CCEB2A

    - name: client.hash.sha256
      type: keyword
      level: extended
      short: Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client.
      description: >
        Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client.
        For consistency with other hash values, this value should be formatted as an uppercase hash.
      example: 0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0

    - name: server.ja3s
      type: keyword
      level: extended
      description: A hash that identifies servers based on how they perform an SSL/TLS handshake.
      example: 394441ab65754e2207b1e1b457b3641d

    - name: server.subject
      type: keyword
      level: extended
      description: Subject of the x.509 certificate presented by the server.
      example: "CN=www.example.com, OU=Infrastructure Team, DC=example, DC=com"

    - name: server.issuer
      type: keyword
      level: extended
      description: Subject of the issuer of the x.509 certificate presented by the server.
      example: "CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"

    - name: server.not_before
      type: date
      level: extended
      description: Timestamp indicating when server certificate is first considered valid.
      example: "1970-01-01T00:00:00.000Z"

    - name: server.not_after
      type: date
      level: extended
      description: Timestamp indicating when server certificate is no longer considered valid.
      example: "2021-01-01T00:00:00.000Z"

    - name: server.certificate_chain
      type: keyword
      level: extended
      short: Array of PEM-encoded certificates that make up the certificate chain offered by the server.
      description: >
        Array of PEM-encoded certificates that make up the certificate chain offered by the server. This is
        usually mutually-exclusive of `server.certificate` since that value should be the first certificate
        in the chain.
      example: "[\"MII...\", \"MII...\"]"
      normalize:
        - array

    - name: server.certificate
      type: keyword
      level: extended
      short: PEM-encoded stand-alone certificate offered by the server.
      description: >
        PEM-encoded stand-alone certificate offered by the server. This is usually mutually-exclusive of
        `server.certificate_chain` since this value also exists in that list.
      example: "MII..."

    - name: server.hash.md5
      type: keyword
      level: extended
      short: Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server.
      description: >
        Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server.
        For consistency with other hash values, this value should be formatted as an uppercase hash.
      example: 0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC

    - name: server.hash.sha1
      type: keyword
      level: extended
      short: Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server.
      description: >
        Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server.
        For consistency with other hash values, this value should be formatted as an uppercase hash.
      example: 9E393D93138888D288266C2D915214D1D1CCEB2A

    - name: server.hash.sha256
      type: keyword
      level: extended
      short: Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server.
      description: >
        Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server.
        For consistency with other hash values, this value should be formatted as an uppercase hash.
      example: 0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0