Skip to content

Commit 659f03c

Browse files
svrnmlmolkovaAlexanderWertjoaopgrassi
authored
Add Semantic conventions for TLS/SSL encrypted communication (open-telemetry#21)
Signed-off-by: svrnm <neumanns@cisco.com> Co-authored-by: Liudmila Molkova <limolkova@microsoft.com> Co-authored-by: Alexander Wert <AlexanderWert@users.noreply.github.com> Co-authored-by: Joao Grassi <joao.grassi@dynatrace.com>
1 parent f6fec98 commit 659f03c

File tree

4 files changed

+217
-0
lines changed

4 files changed

+217
-0
lines changed

‎CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ release.
2020
([#435](https://github.com/open-telemetry/semantic-conventions/pull/435))
2121
- Add `http.flavor` and `http.user_agent` to list of deprecated attributes
2222
([#503](https://github.com/open-telemetry/semantic-conventions/pull/503))
23+
- Add Semantic conventions for TLS/SSL encrypted communication.
24+
([#21](https://github.com/open-telemetry/semantic-conventions/pull/21))
2325

2426
### Fixes
2527

‎docs/attributes-registry/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ Currently, the following namespaces exist:
4242
* [Server](server.md)
4343
* [Source](source.md)
4444
* [Thread](thread.md)
45+
* [TLS](tls.md)
4546
* [URL](url.md)
4647
* [User agent](user-agent.md)
4748

‎docs/attributes-registry/tls.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<!--- Hugo front matter used to generate the website version of this page:
2+
--->
3+
4+
# TLS
5+
6+
## TLS Attributes
7+
8+
<!-- semconv registry.tls(omit_requirement_level) -->
9+
| Attribute | Type | Description | Examples |
10+
|---|---|---|---|
11+
| `tls.cipher` | string | String indicating the [cipher](https://datatracker.ietf.org/doc/html/rfc5246#appendix-A.5) used during the current connection. [1] | `TLS_RSA_WITH_3DES_EDE_CBC_SHA`; `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` |
12+
| `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...` |
13+
| `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...]` |
14+
| `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` |
15+
| `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` |
16+
| `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` |
17+
| `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` |
18+
| `tls.client.ja3` | string | A hash that identifies clients based on how they perform an SSL/TLS handshake. | `d4e5b18d6b55c71272893221c96ba240` |
19+
| `tls.client.not_after` | string | Date/Time indicating when client certificate is no longer considered valid. | `2021-01-01T00:00:00.000Z` |
20+
| `tls.client.not_before` | string | Date/Time indicating when client certificate is first considered valid. | `1970-01-01T00:00:00.000Z` |
21+
| `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` |
22+
| `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` |
23+
| `tls.client.supported_ciphers` | string[] | Array of ciphers offered by the client during the client hello. | `["TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..."]` |
24+
| `tls.curve` | string | String indicating the curve used for the given cipher, when applicable | `secp256r1` |
25+
| `tls.established` | boolean | Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel. | `True` |
26+
| `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` |
27+
| `tls.protocol.name` | 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` |
28+
| `tls.protocol.version` | 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` |
29+
| `tls.resumed` | boolean | Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation. | `True` |
30+
| `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...` |
31+
| `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...]` |
32+
| `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` |
33+
| `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` |
34+
| `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` |
35+
| `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` |
36+
| `tls.server.ja3s` | string | A hash that identifies servers based on how they perform an SSL/TLS handshake. | `d4e5b18d6b55c71272893221c96ba240` |
37+
| `tls.server.not_after` | string | Date/Time indicating when server certificate is no longer considered valid. | `2021-01-01T00:00:00.000Z` |
38+
| `tls.server.not_before` | string | Date/Time indicating when server certificate is first considered valid. | `1970-01-01T00:00:00.000Z` |
39+
| `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` |
40+
41+
**[1]:** 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).
42+
43+
`tls.protocol.name` 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.
44+
45+
| Value | Description |
46+
|---|---|
47+
| `ssl` | ssl |
48+
| `tls` | tls |
49+
<!-- endsemconv -->

‎model/registry/tls.yaml

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
groups:
2+
- id: registry.tls
3+
prefix: tls
4+
type: attribute_group
5+
brief: "This document defines semantic convention attributes in the TLS namespace."
6+
attributes:
7+
- id: cipher
8+
brief: >
9+
String indicating the [cipher](https://datatracker.ietf.org/doc/html/rfc5246#appendix-A.5) used during the current connection.
10+
type: string
11+
note: >
12+
The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the
13+
[registered TLS Cipher Suits](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4).
14+
examples:
15+
[
16+
"TLS_RSA_WITH_3DES_EDE_CBC_SHA",
17+
"TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
18+
]
19+
- id: client.certificate
20+
type: string
21+
brief: >
22+
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.
23+
examples: ["MII..."]
24+
- id: client.certificate_chain
25+
type: string[]
26+
brief: >
27+
Array of PEM-encoded certificates that make up the certificate chain offered by the client.
28+
This is usually mutually-exclusive of `client.certificate` since that value should be the first certificate in the chain.
29+
examples: ["MII...", "MI..."]
30+
- id: client.hash.md5
31+
type: string
32+
brief: >
33+
Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client.
34+
For consistency with other hash values, this value should be formatted as an uppercase hash.
35+
examples: ["0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC"]
36+
- id: client.hash.sha1
37+
type: string
38+
brief: >
39+
Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client.
40+
For consistency with other hash values, this value should be formatted as an uppercase hash.
41+
examples: ["9E393D93138888D288266C2D915214D1D1CCEB2A"]
42+
- id: client.hash.sha256
43+
type: string
44+
brief: >
45+
Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client.
46+
For consistency with other hash values, this value should be formatted as an uppercase hash.
47+
examples:
48+
["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"]
49+
- id: client.issuer
50+
type: string
51+
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."
52+
examples:
53+
["CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"]
54+
- id: client.ja3
55+
type: string
56+
brief: "A hash that identifies clients based on how they perform an SSL/TLS handshake."
57+
examples: ["d4e5b18d6b55c71272893221c96ba240"]
58+
- id: client.not_after
59+
type: string
60+
brief: "Date/Time indicating when client certificate is no longer considered valid."
61+
examples: ["2021-01-01T00:00:00.000Z"]
62+
- id: client.not_before
63+
type: string
64+
brief: "Date/Time indicating when client certificate is first considered valid."
65+
examples: ["1970-01-01T00:00:00.000Z"]
66+
- id: client.server_name
67+
type: string
68+
brief: "Also called an SNI, this tells the server which hostname to which the client is attempting to connect to."
69+
examples: ["opentelemetry.io"]
70+
- id: client.subject
71+
type: string
72+
brief: "Distinguished name of subject of the x.509 certificate presented by the client."
73+
examples: ["CN=myclient, OU=Documentation Team, DC=example, DC=com"]
74+
- id: client.supported_ciphers
75+
type: string[]
76+
brief: Array of ciphers offered by the client during the client hello.
77+
examples:
78+
[
79+
'"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..."',
80+
]
81+
- id: curve
82+
brief: "String indicating the curve used for the given cipher, when applicable"
83+
type: string
84+
examples: ["secp256r1"]
85+
- id: established
86+
brief: "Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel."
87+
type: boolean
88+
examples: [true]
89+
- id: next_protocol
90+
brief: >
91+
String indicating the protocol being tunneled.
92+
Per the values in the [IANA registry](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids),
93+
this string should be lower case.
94+
type: string
95+
examples: ["http/1.1"]
96+
- id: protocol.name
97+
brief: >
98+
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)
99+
type:
100+
allow_custom_values: true
101+
members:
102+
- id: ssl
103+
value: ssl
104+
- id: tls
105+
value: tls
106+
- id: protocol.version
107+
brief: >
108+
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)
109+
type: string
110+
examples: ["1.2", "3"]
111+
- id: resumed
112+
brief: "Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation."
113+
type: boolean
114+
examples: [true]
115+
- id: server.certificate
116+
type: string
117+
brief: >
118+
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.
119+
examples: ["MII..."]
120+
- id: server.certificate_chain
121+
type: string[]
122+
brief: >
123+
Array of PEM-encoded certificates that make up the certificate chain offered by the server.
124+
This is usually mutually-exclusive of `server.certificate` since that value should be the first certificate in the chain.
125+
examples: ["MII...", "MI..."]
126+
- id: server.hash.md5
127+
type: string
128+
brief: >
129+
Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server.
130+
For consistency with other hash values, this value should be formatted as an uppercase hash.
131+
examples: ["0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC"]
132+
- id: server.hash.sha1
133+
type: string
134+
brief: >
135+
Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server.
136+
For consistency with other hash values, this value should be formatted as an uppercase hash.
137+
examples: ["9E393D93138888D288266C2D915214D1D1CCEB2A"]
138+
- id: server.hash.sha256
139+
type: string
140+
brief: >
141+
Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server.
142+
For consistency with other hash values, this value should be formatted as an uppercase hash.
143+
examples:
144+
["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"]
145+
- id: server.issuer
146+
type: string
147+
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."
148+
examples:
149+
["CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"]
150+
- id: server.ja3s
151+
type: string
152+
brief: "A hash that identifies servers based on how they perform an SSL/TLS handshake."
153+
examples: ["d4e5b18d6b55c71272893221c96ba240"]
154+
- id: server.not_after
155+
type: string
156+
brief: "Date/Time indicating when server certificate is no longer considered valid."
157+
examples: ["2021-01-01T00:00:00.000Z"]
158+
- id: server.not_before
159+
type: string
160+
brief: "Date/Time indicating when server certificate is first considered valid."
161+
examples: ["1970-01-01T00:00:00.000Z"]
162+
- id: server.subject
163+
type: string
164+
brief: "Distinguished name of subject of the x.509 certificate presented by the server."
165+
examples: ["CN=myserver, OU=Documentation Team, DC=example, DC=com"]

0 commit comments

Comments
 (0)