Add Semantic conventions for TLS/SSL encrypted communication

CONTRIBUTING.md

@@ -21,18 +21,18 @@ key, but non-obvious, aspects:
 - All descriptions, normative language are defined in the `docs/`
   directory.
   - We provide tooling to generate Markdown documentation from the formal
-    YAML definitons.  See [Yaml to Markdown](#yaml-to-markdown).
+    YAML definitons. See [Yaml to Markdown](#yaml-to-markdown).
   - We use Hugo to render [semantic conventions on our website](https://opentelemetry.io/docs/specs/semconv/).
     You will see `<!--- Hugo front matter used to generate ...` sections
-    in markdown.  See [Hugo frontmatter](#hugo-frontmatter) for details.
+    in markdown. See [Hugo frontmatter](#hugo-frontmatter) for details.
 - All changes to existing attributes, metrics, etc. MUST be allowed as
   per our [stability guarantees](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/versioning-and-stability.md#semantic-conventions-stability) and
-  defined in a schema file.  As part of any contribution, you should
+  defined in a schema file. As part of any contribution, you should
   include attribute changes defined in the `schema-next.yaml` file.
   For details, please read [the schema specification](https://opentelemetry.io/docs/specs/otel/schemas/).
 - After creating a pull request, please update the [CHANGELOG](CHANGELOG.md) file with
   a description of your changes.
-  
+
 Please make sure all Pull Requests are compliant with these rules!
 
 ### Hugo frontmatter

docs/tls/README.md

@@ -0,0 +1,18 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: URL
+path_base_for_github_subdir:
+  from: content/en/docs/specs/semconv/url/_index.md
+  to: url/README.md
+--->
+
+# TLS Semantic Conventions
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions for TLS (and related protocols like SSL and DTLS).
+
+Semantic conventions for TLS are defined for the following signals:
+
+* [TLS](tls-spans.md): For describing TLS client and server *spans*.
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

docs/tls/tls-spans.md

@@ -0,0 +1,80 @@
+# Semantic Conventions for TLS spans
+
+**Status**: [Experimental](../../document-status.md)
+
+This document defines semantic conventions for TLS/SSL client and server Spans.
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [Semantic Conventions for TLS spans](#semantic-conventions-for-tls-spans)
+  - [Common Attributes](#common-attributes)
+  - [Client attributes](#client-attributes)
+  - [Server attributes](#server-attributes)
+
+<!-- tocstop -->
+
+## Common Attributes
+
+These attributes may be used for base information of any TLS/SSL encrypted communication.
+
+<!-- semconv tls -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `tls.protocol.name` | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | Required |
+| `tls.protocol.version` | string | Normalized lowercase protocol name parsed from original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `ssl` | Conditionally Required: if not `tls` |
+| `tls.cipher` | string | String indicating the [cipher](https://datatracker.ietf.org/doc/html/rfc5246#appendix-A.5) used during the current connection. | `TLS_RSA_WITH_3DES_EDE_CBC_SHA`; `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` | Opt-In |
+| `tls.curve` | string | String indicating the curve used for the given cipher, when applicable | `secp256r1` | Opt-In |
+| `tls.established` | boolean | Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel. | `True` | Opt-In |
+| `tls.next_protocol` | string | 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. | `http/1.1` | Opt-In |
+| `tls.resumed` | boolean | Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation. | `True` | Opt-In |
+
+`tls.protocol.version` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+
+| Value  | Description |
+|---|---|
+| `ssl` | ssl |
+| `tls` | tls |
+<!-- endsemconv -->
+
+The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the [registered TLS Cipher Suits](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4).
+
+## Client attributes
+
+The following additional attributes describe the client participating in secure communication.
+
+<!-- semconv tls.client -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `tls.client.certificate` | string | 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. | `MII...` | Opt-In |
+| `tls.client.certificate_chain` | string[] | 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. | `[MII..., MI...]` | Opt-In |
+| `tls.client.issuer` | string | Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client. | `CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com` | Opt-In |
+| `tls.client.ja3` | string | A hash that identifies clients based on how they perform an SSL/TLS handshake. | `d4e5b18d6b55c71272893221c96ba240` | Opt-In |
+| `tls.client.not_after` | string | Date/Time indicating when client certificate is no longer considered valid. | `2021-01-01T00:00:00.000Z` | Opt-In |
+| `tls.client.not_before` | string | Date/Time indicating when client certificate is first considered valid. | `1970-01-01T00:00:00.000Z` | Opt-In |
+| `tls.client.server_name` | string | Also called an SNI, this tells the server which hostname to which the client is attempting to connect to. | `opentelemetry.io` | Opt-In |
+| `tls.client.subject` | string | Distinguished name of subject of the x.509 certificate presented by the client. | `CN=myclient, OU=Documentation Team, DC=example, DC=com` | Opt-In |
+| `tls.client.hash.md5` | string | 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. | `0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC` | Opt-In |
+| `tls.client.hash.sha1` | string | 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. | `9E393D93138888D288266C2D915214D1D1CCEB2A` | Opt-In |
+| `tls.client.hash.sha256` | string | 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. | `0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0` | Opt-In |
+<!-- endsemconv -->
+
+## Server attributes
+
+The following additional attributes describe the server participating in secure communication.
+
+<!-- semconv tls.server -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `tls.server.certificate` | string | 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. | `MII...` | Opt-In |
+| `tls.server.certificate_chain` | string[] | 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. | `[MII..., MI...]` | Opt-In |
+| `tls.server.issuer` | string | Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client. | `CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com` | Opt-In |
+| `tls.server.ja3s` | string | A hash that identifies servers based on how they perform an SSL/TLS handshake. | `d4e5b18d6b55c71272893221c96ba240` | Opt-In |
+| `tls.server.not_after` | string | Date/Time indicating when server certificate is no longer considered valid. | `2021-01-01T00:00:00.000Z` | Opt-In |
+| `tls.server.not_before` | string | Date/Time indicating when server certificate is first considered valid. | `1970-01-01T00:00:00.000Z` | Opt-In |
+| `tls.server.subject` | string | Distinguished name of subject of the x.509 certificate presented by the server. | `CN=myserver, OU=Documentation Team, DC=example, DC=com` | Opt-In |
+| `tls.server.hash.md5` | string | 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. | `0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC` | Opt-In |
+| `tls.server.hash.sha1` | string | 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. | `9E393D93138888D288266C2D915214D1D1CCEB2A` | Opt-In |
+| `tls.server.hash.sha256` | string | 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. | `0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0` | Opt-In |
+<!-- endsemconv -->

model/trace/tls.yaml

@@ -0,0 +1,199 @@
+groups:
+  - id: tls
+    prefix: tls
+    type: span
+    brief: "This document defines semantic conventions for TLS/SSL client and server Spans."
+    attributes:
+      - id: protocol.name
+        requirement_level: required
+        brief: >
+          Numeric part of the version parsed from the original string of the
+          negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES)
+        type: string
+        examples: ["1.2", "3"]
+      - id: protocol.version
+        requirement_level:
+          conditionally_required: if not `tls`
+        brief: >
+          Normalized lowercase protocol name parsed from original string of the
+          negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES)
+        type:
+          allow_custom_values: true
+          members:
+            - id: ssl
+              value: ssl
+            - id: tls
+              value: tls
+      - id: cipher
+        requirement_level: opt_in
+        brief: >
+          String indicating the [cipher](https://datatracker.ietf.org/doc/html/rfc5246#appendix-A.5)
+          used during the current connection.
+        type: string
+        examples:
+          [
+            "TLS_RSA_WITH_3DES_EDE_CBC_SHA",
+            "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
+          ]
+      - id: curve
+        requirement_level: opt_in
+        brief: "String indicating the curve used for the given cipher, when applicable"
+        type: string
+        examples: ["secp256r1"]
+      - id: established
+        requirement_level: opt_in
+        brief: "Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel."
+        type: boolean
+        examples: [true]
+      - id: next_protocol
+        requirement_level: opt_in
+        brief: >
+          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.
+        type: string
+        examples: ["http/1.1"]
+      - id: resumed
+        requirement_level: opt_in
+        brief: "Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation."
+        type: boolean
+        examples: [true]
+  - id: tls.client
+    prefix: tls.client
+    type: span
+    brief: "The following additional attributes describe the client participating in secure communication."
+    attributes:
+      - id: certificate
+        type: string
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples: ["MII..."]
+      - id: certificate_chain
+        type: string[]
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples: ["MII...", "MI..."]
+      - id: issuer
+        type: string
+        requirement_level: opt_in
+        brief: "Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client."
+        examples:
+          ["CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"]
+      - id: ja3
+        type: string
+        requirement_level: opt_in
+        brief: "A hash that identifies clients based on how they perform an SSL/TLS handshake."
+        examples: ["d4e5b18d6b55c71272893221c96ba240"]
+      - id: not_after
+        type: string
+        requirement_level: opt_in
+        brief: "Date/Time indicating when client certificate is no longer considered valid."
+        examples: ["2021-01-01T00:00:00.000Z"]
+      - id: not_before
+        type: string
+        requirement_level: opt_in
+        brief: "Date/Time indicating when client certificate is first considered valid."
+        examples: ["1970-01-01T00:00:00.000Z"]
+      - id: server_name
+        type: string
+        requirement_level: opt_in
+        brief: "Also called an SNI, this tells the server which hostname to which the client is attempting to connect to."
+        examples: ["opentelemetry.io"]
+      - id: subject
+        type: string
+        requirement_level: opt_in
+        brief: "Distinguished name of subject of the x.509 certificate presented by the client."
+        examples: ["CN=myclient, OU=Documentation Team, DC=example, DC=com"]
+      - id: hash.md5
+        type: string
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples: ["0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC"]
+      - id: hash.sha1
+        type: string
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples: ["9E393D93138888D288266C2D915214D1D1CCEB2A"]
+      - id: hash.sha256
+        type: string
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples:
+          ["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"]
+  - id: tls.server
+    prefix: tls.server
+    type: span
+    brief: "The following additional attributes describe the server participating in secure communication."
+    attributes:
+      - id: certificate
+        type: string
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples: ["MII..."]
+      - id: certificate_chain
+        type: string[]
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples: ["MII...", "MI..."]
+      - id: issuer
+        type: string
+        requirement_level: opt_in
+        brief: "Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client."
+        examples:
+          ["CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"]
+      - id: ja3s
+        type: string
+        requirement_level: opt_in
+        brief: "A hash that identifies servers based on how they perform an SSL/TLS handshake."
+        examples: ["d4e5b18d6b55c71272893221c96ba240"]
+      - id: not_after
+        type: string
+        requirement_level: opt_in
+        brief: "Date/Time indicating when server certificate is no longer considered valid."
+        examples: ["2021-01-01T00:00:00.000Z"]
+      - id: not_before
+        type: string
+        requirement_level: opt_in
+        brief: "Date/Time indicating when server certificate is first considered valid."
+        examples: ["1970-01-01T00:00:00.000Z"]
+      - id: subject
+        type: string
+        requirement_level: opt_in
+        brief: "Distinguished name of subject of the x.509 certificate presented by the server."
+        examples: ["CN=myserver, OU=Documentation Team, DC=example, DC=com"]
+      - id: hash.md5
+        type: string
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples: ["0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC"]
+      - id: hash.sha1
+        type: string
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples: ["9E393D93138888D288266C2D915214D1D1CCEB2A"]
+      - id: hash.sha256
+        type: string
+        requirement_level: opt_in
+        brief: >
+          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.
+        examples:
+          ["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"]