From e89996c8cd6ff110c28038ea7d3bb43aa36565c7 Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Mon, 9 Jan 2023 23:30:35 +0100 Subject: [PATCH 1/5] Adds specifications for OTLP EXPORTER TLS #2932 --- spec-compliance-matrix.md | 2 + specification/protocol/exporter.md | 68 ++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index be6dbfa7968..4ed0e16d57e 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -318,6 +318,8 @@ Note: Support for environment variables is optional. | SchemaURL in ResourceMetrics and ScopeMetrics | | | + | | + | | - | | | | - | | | SchemaURL in ResourceLogs and ScopeLogs | | | + | | + | | - | | | | - | | | Honors the [user agent spec](specification/protocol/exporter.md#user-agent) | | | | | | | | + | | | | | +| Honors the [TLS version spec](specification/protocol/exporter.md#tls-version) | | | | | | | | | | | | | +| Honors the [TLS cipher spec](specification/protocol/exporter.md#tls-cipher) | | | | | | | | | | | | | | **[Zipkin](specification/trace/sdk_exporters/zipkin.md)** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | | Zipkin V1 JSON | X | - | + | | + | - | - | - | - | - | - | - | | Zipkin V1 Thrift | X | - | + | | [-][py1174] | - | - | - | - | - | - | - | diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 4d58a4d3870..e12d3de39d4 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -32,6 +32,24 @@ The following configuration options MUST be available to configure the OTLP expo - Default: n/a - Env vars: `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE` `OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE` `OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE` `OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE` +- **TLS minimum version**: Minimum TLS version to use with SSL. + Should only be used for a secure connection. + See [TLS version](./exporter.md#tls-version) for more details. + - Default: n/a + - Env vars: `OTEL_EXPORTER_OTLP_MIN_TLS` `OTEL_EXPORTER_OTLP_TRACES_MIN_TLS` `OTEL_EXPORTER_OTLP_METRICS_MIN_TLS` `OTEL_EXPORTER_OTLP_LOGS_MIN_TLS` + +- **TLS maximum version**: Maximum TLS version to use with SSL. + Should only be used for a secure connection. + See [TLS version](./exporter.md#tls-version) for more details. + - Default: n/a + - Env vars: `OTEL_EXPORTER_OTLP_MAX_TLS` `OTEL_EXPORTER_OTLP_TRACES_MAX_TLS` `OTEL_EXPORTER_OTLP_METRICS_MAX_TLS` `OTEL_EXPORTER_OTLP_LOGS_MAX_TLS` + +- **TLS cipher list**: Cipher list to use with SSL. + Should only be used for a secure connection. + See [TLS cipher](./exporter.md#tls-cipher) for more details. + - Default: n/a + - Env vars: `OTEL_EXPORTER_OTLP_CIPHER_LIST` `OTEL_EXPORTER_OTLP_TRACES_CIPHER_LIST` `OTEL_EXPORTER_OTLP_METRICS_CIPHER_LIST` `OTEL_EXPORTER_OTLP_LOGS_CIPHER_LIST` + - **Headers**: Key-value pairs to be used as headers associated with gRPC or HTTP requests. See [Specifying headers](./exporter.md#specifying-headers-via-environment-variables) for more details. - Default: n/a - Env vars: `OTEL_EXPORTER_OTLP_HEADERS` `OTEL_EXPORTER_OTLP_TRACES_HEADERS` `OTEL_EXPORTER_OTLP_METRICS_HEADERS` `OTEL_EXPORTER_OTLP_LOGS_HEADERS` @@ -150,6 +168,56 @@ unless SDKs have good reasons to choose `grpc` as the default (e.g. for backward compatibility reasons when `grpc` was already the default in a stable SDK release). +### TLS version + +When using a secure connection with SSL, +configuration options `OTEL_EXPORTER_OTLP_MIN_TLS` and `OTEL_EXPORTER_OTLP_MAX_TLS` +are used to further restrict the version of the TLS protocol negotiated by the +secure connection. + +The minimum and maximum TLS version are not an arbitrary string, +a TLS version string is an enumerated list of valid version names. + +The list of valid TLS version names is implementation dependent. + +When TLS of the corresponding version is supported by the implementation, +valid version names SHOULD use the following syntax: + +- `TLSv1.0` +- `TLSv1.1` +- `TLSv1.2` +- `TLSv1.3` + +Valid version names MAY include other versions not in this list. + +When an environment variable is set to a non empty value, +and when the name is not valid for the implementation (unknown), +the exporter MUST raise an error, +and MUST fail to connect to the exporter endpoint. + +When `OTEL_EXPORTER_OTLP_MIN_TLS` is set to a valid version name, +the OTLP exporter MUST use a TLS version greater or equal to `OTEL_EXPORTER_OTLP_MIN_TLS`. + +When `OTEL_EXPORTER_OTLP_MAX_TLS` is set to a valid version name, +the OTLP exporter MUST use a TLS version lesser or equal to `OTEL_EXPORTER_OTLP_MAX_TLS`. + +### TLS cipher + +When using a secure connection with SSL, +the configuration option `OTEL_EXPORTER_OTLP_CIPHER_LIST` +is used to further restrict the cipher negotiated by the secure connection. + +The format of this variable is a textual list of cipher names, separated by +a colon (:) character. + +The list of valid cipher names is implementation dependent. + +When connecting to the exporter endpoint, the exporter MUST use a cipher +from the list of cipher names provided. + +If no suitable cipher can be used, +the exporter MUST fail to connect to the endpoint. + ### Specifying headers via environment variables The `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS`, `OTEL_EXPORTER_OTLP_METRICS_HEADERS` environment variables will contain a list of key value pairs, and these are expected to be represented in a format matching to the [W3C Correlation-Context](https://github.com/w3c/baggage/blob/master/baggage/HTTP_HEADER_FORMAT.md), except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings. From 26a3ebb616406ca817ca4fd4bd62ff73830e5b44 Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Mon, 9 Jan 2023 23:59:03 +0100 Subject: [PATCH 2/5] Add CHANGELOG entry --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9fa8748835b..c3dce9754f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -44,6 +44,9 @@ release. "always_off" and "trace_based". ([#2919](https://github.com/open-telemetry/opentelemetry-specification/pull/2919)) +- Add TLS min version, TLS max version, and TLS cipher list in OTLP exporter. + ([#3088](https://github.com/open-telemetry/opentelemetry-specification/pull/3088)) + ### Telemetry Schemas ### Common From 32ed6e24ce3b31a352c5ecd5fa020d4b2086c7dd Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Thu, 12 Jan 2023 19:13:28 +0100 Subject: [PATCH 3/5] Rewording for clarity. --- specification/protocol/exporter.md | 66 ++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 16 deletions(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index e12d3de39d4..351d58a58e0 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -36,18 +36,23 @@ The following configuration options MUST be available to configure the OTLP expo Should only be used for a secure connection. See [TLS version](./exporter.md#tls-version) for more details. - Default: n/a + - Type: enum + - Enum items: see details - Env vars: `OTEL_EXPORTER_OTLP_MIN_TLS` `OTEL_EXPORTER_OTLP_TRACES_MIN_TLS` `OTEL_EXPORTER_OTLP_METRICS_MIN_TLS` `OTEL_EXPORTER_OTLP_LOGS_MIN_TLS` - **TLS maximum version**: Maximum TLS version to use with SSL. Should only be used for a secure connection. See [TLS version](./exporter.md#tls-version) for more details. - Default: n/a + - Type: enum + - Enum items: see details - Env vars: `OTEL_EXPORTER_OTLP_MAX_TLS` `OTEL_EXPORTER_OTLP_TRACES_MAX_TLS` `OTEL_EXPORTER_OTLP_METRICS_MAX_TLS` `OTEL_EXPORTER_OTLP_LOGS_MAX_TLS` - **TLS cipher list**: Cipher list to use with SSL. Should only be used for a secure connection. See [TLS cipher](./exporter.md#tls-cipher) for more details. - Default: n/a + - Type: string - Env vars: `OTEL_EXPORTER_OTLP_CIPHER_LIST` `OTEL_EXPORTER_OTLP_TRACES_CIPHER_LIST` `OTEL_EXPORTER_OTLP_METRICS_CIPHER_LIST` `OTEL_EXPORTER_OTLP_LOGS_CIPHER_LIST` - **Headers**: Key-value pairs to be used as headers associated with gRPC or HTTP requests. See [Specifying headers](./exporter.md#specifying-headers-via-environment-variables) for more details. @@ -175,20 +180,31 @@ configuration options `OTEL_EXPORTER_OTLP_MIN_TLS` and `OTEL_EXPORTER_OTLP_MAX_T are used to further restrict the version of the TLS protocol negotiated by the secure connection. -The minimum and maximum TLS version are not an arbitrary string, -a TLS version string is an enumerated list of valid version names. +The minimum and maximum TLS version are enumerated values, +listing TLS version names. -The list of valid TLS version names is implementation dependent. +The list of TLS version names is implementation dependent. When TLS of the corresponding version is supported by the implementation, -valid version names SHOULD use the following syntax: +version names SHOULD use the following syntax: + +- `1.0` +- `1.1` +- `1.2` +- `1.3` + +Version names MAY include other versions not in this list. + +In other words: + +- the specification does not require that TLS v1.0 is supported by an implementation, + it only requires that if TLS v1.0 is implemented, + the enum value to represent it should be `1.0` +- an implementation is free to add more versions, for example + `1.4` when TLS version 1.4 becomes available. + -- `TLSv1.0` -- `TLSv1.1` -- `TLSv1.2` -- `TLSv1.3` -Valid version names MAY include other versions not in this list. When an environment variable is set to a non empty value, and when the name is not valid for the implementation (unknown), @@ -207,16 +223,34 @@ When using a secure connection with SSL, the configuration option `OTEL_EXPORTER_OTLP_CIPHER_LIST` is used to further restrict the cipher negotiated by the secure connection. -The format of this variable is a textual list of cipher names, separated by -a colon (:) character. +This variable is a complex type, serialized as a string, +so there are several things to consider. + +From an end user point of view: + +- end users are expected to know how to write a value + for environment variable `OTEL_EXPORTER_OTLP_CIPHER_LIST` +- hence, valid cipher names should be specified somewhere +- and, how to represent a list should be specified somewhere + +From an opentelemetry implementation point of view: + +- the data format in `OTEL_EXPORTER_OTLP_CIPHER_LIST` is implementation dependent, + because it ultimately depends on the software package used + to implement SSL/TLS, which will vary. +- Not every SSL/TLS package, and therefore every opentelemetry + implementation, will use the same representation for cipher names and + lists, so the implementation needs to have some freedom here. -The list of valid cipher names is implementation dependent. +This is resolved by introducing a documentation requirement: -When connecting to the exporter endpoint, the exporter MUST use a cipher -from the list of cipher names provided. +- the opentelemetry implementation MUST, in the documentation, + provide details about how the cipher list is represented. + When a third party library is used, this can be achieved for example by + pointing to the relevant third party library documentation. -If no suitable cipher can be used, -the exporter MUST fail to connect to the endpoint. +For example with curl, the ciphers are documented +[here](https://curl.se/docs/ssl-ciphers.html). ### Specifying headers via environment variables From a50ccf67e6da24fe0d6187a333cfa9aa3994d4a4 Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Thu, 12 Jan 2023 22:01:44 +0100 Subject: [PATCH 4/5] Format cleanup, misc rewording. --- specification/protocol/exporter.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 351d58a58e0..d01542b4847 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -203,9 +203,6 @@ In other words: - an implementation is free to add more versions, for example `1.4` when TLS version 1.4 becomes available. - - - When an environment variable is set to a non empty value, and when the name is not valid for the implementation (unknown), the exporter MUST raise an error, @@ -229,19 +226,21 @@ so there are several things to consider. From an end user point of view: - end users are expected to know how to write a value - for environment variable `OTEL_EXPORTER_OTLP_CIPHER_LIST` -- hence, valid cipher names should be specified somewhere -- and, how to represent a list should be specified somewhere + for environment variable `OTEL_EXPORTER_OTLP_CIPHER_LIST`, +- hence, valid cipher names should be specified somewhere, +- and, how to represent a list should be specified somewhere. From an opentelemetry implementation point of view: - the data format in `OTEL_EXPORTER_OTLP_CIPHER_LIST` is implementation dependent, because it ultimately depends on the software package used - to implement SSL/TLS, which will vary. -- Not every SSL/TLS package, and therefore every opentelemetry + to implement SSL/TLS, which will vary, +- not every SSL/TLS package, and therefore every opentelemetry implementation, will use the same representation for cipher names and lists, so the implementation needs to have some freedom here. +These two points of view appear to be conflicting. + This is resolved by introducing a documentation requirement: - the opentelemetry implementation MUST, in the documentation, @@ -249,7 +248,7 @@ This is resolved by introducing a documentation requirement: When a third party library is used, this can be achieved for example by pointing to the relevant third party library documentation. -For example with curl, the ciphers are documented +To illustrate with `curl`, the ciphers are documented [here](https://curl.se/docs/ssl-ciphers.html). ### Specifying headers via environment variables From f730cfc8289cd54804a0b391ff696947d565de69 Mon Sep 17 00:00:00 2001 From: Marc Alff Date: Thu, 26 Jan 2023 01:18:21 +0100 Subject: [PATCH 5/5] Clarified CURL case which needs 2 variables, added examples. --- specification/protocol/exporter.md | 97 +++++++++++++++++++++++++++++- 1 file changed, 94 insertions(+), 3 deletions(-) diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index d01542b4847..29cdd20e4ac 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -55,6 +55,13 @@ The following configuration options MUST be available to configure the OTLP expo - Type: string - Env vars: `OTEL_EXPORTER_OTLP_CIPHER_LIST` `OTEL_EXPORTER_OTLP_TRACES_CIPHER_LIST` `OTEL_EXPORTER_OTLP_METRICS_CIPHER_LIST` `OTEL_EXPORTER_OTLP_LOGS_CIPHER_LIST` +- **TLS cipher suite**: Cipher suite to use with SSL. + Should only be used for a secure connection. + See [TLS cipher](./exporter.md#tls-cipher) for more details. + - Default: n/a + - Type: string + - Env vars: `OTEL_EXPORTER_OTLP_CIPHER_SUITE` `OTEL_EXPORTER_OTLP_TRACES_CIPHER_SUITE` `OTEL_EXPORTER_OTLP_METRICS_CIPHER_SUITE` `OTEL_EXPORTER_OTLP_LOGS_CIPHER_SUITE` + - **Headers**: Key-value pairs to be used as headers associated with gRPC or HTTP requests. See [Specifying headers](./exporter.md#specifying-headers-via-environment-variables) for more details. - Default: n/a - Env vars: `OTEL_EXPORTER_OTLP_HEADERS` `OTEL_EXPORTER_OTLP_TRACES_HEADERS` `OTEL_EXPORTER_OTLP_METRICS_HEADERS` `OTEL_EXPORTER_OTLP_LOGS_HEADERS` @@ -214,10 +221,35 @@ the OTLP exporter MUST use a TLS version greater or equal to `OTEL_EXPORTER_OTLP When `OTEL_EXPORTER_OTLP_MAX_TLS` is set to a valid version name, the OTLP exporter MUST use a TLS version lesser or equal to `OTEL_EXPORTER_OTLP_MAX_TLS`. +#### Example 1 + +Traces sent to an endpoint using TLS 1.2 or newer + +```bash +export OTEL_EXPORTER_OTLP_TRACES_MIN_TLS=1.2 +``` + +#### Example 2 + +Metrics sent to an endpoint using TLS 1.1 or older + +```bash +export OTEL_EXPORTER_OTLP_METRICS_MAX_TLS=1.1 +``` + +#### Example 3 + +Logs sent to an endpoint using TLS 1.3 + +```bash +export OTEL_EXPORTER_OTLP_LOGS_MIN_TLS=1.3 +export OTEL_EXPORTER_OTLP_LOGS_MAX_TLS=1.3 +``` + ### TLS cipher When using a secure connection with SSL, -the configuration option `OTEL_EXPORTER_OTLP_CIPHER_LIST` +the configuration option `OTEL_EXPORTER_OTLP_CIPHER_SUITE` is used to further restrict the cipher negotiated by the secure connection. This variable is a complex type, serialized as a string, @@ -226,13 +258,13 @@ so there are several things to consider. From an end user point of view: - end users are expected to know how to write a value - for environment variable `OTEL_EXPORTER_OTLP_CIPHER_LIST`, + for environment variable `OTEL_EXPORTER_OTLP_CIPHER_SUITE`, - hence, valid cipher names should be specified somewhere, - and, how to represent a list should be specified somewhere. From an opentelemetry implementation point of view: -- the data format in `OTEL_EXPORTER_OTLP_CIPHER_LIST` is implementation dependent, +- the data format in `OTEL_EXPORTER_OTLP_CIPHER_SUITE` is implementation dependent, because it ultimately depends on the software package used to implement SSL/TLS, which will vary, - not every SSL/TLS package, and therefore every opentelemetry @@ -248,9 +280,68 @@ This is resolved by introducing a documentation requirement: When a third party library is used, this can be achieved for example by pointing to the relevant third party library documentation. +To illustrate with `openssl 1.1.1`, the ciphers are documented +[here](https://www.openssl.org/docs/man1.1.1/man1/ciphers.html). + To illustrate with `curl`, the ciphers are documented [here](https://curl.se/docs/ssl-ciphers.html). +To illustrate with `go`, the ciphers are documented +[here](https://golang.org/pkg/crypto/tls/#pkg-constants). + +For some implementations, only one variable is necessary (for example, GO), +in which case only the variable `OTEL_EXPORTER_OTLP_CIPHER_SUITE` is used. + +For other implementations, due to constraints of the underlying SSL library +used (for example, openssl and CURL), it is necessary to separate ciphers +for TLS <= 1.2 on one list, and TLS >= 1.3 in another list. + +Such implementations MAY use two variables: + +- `OTEL_EXPORTER_OTLP_CIPHER_LIST` for all TLS <= 1.2 ciphers +- `OTEL_EXPORTER_OTLP_CIPHER_SUITE` for all TLS >= 1.3 ciphers + +#### Example 1 + +The implementation is documented to use the openssl syntax. + +Traces sent to an endpoint using TLS ciphers: + +* `ECDHE-ECDSA-AES256-GCM-SHA384` (TLS <= 1.2) +* `ECDHE-RSA-AES256-GCM-SHA384` (TLS <= 1.2) + +```bash +export OTEL_EXPORTER_OTLP_TRACES_CIPHER_LIST="ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384" +``` + +#### Example 2 + +The implementation is documented to use the GO syntax. + +Metrics sent to an endpoint using TLS ciphers: + +* `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` (0xc030) (TLS <= 1.2) +* `TLS_AES_128_GCM_SHA256` (0x1301) (TLS 1.3) + +```bash +export OTEL_EXPORTER_OTLP_METRICS_CIPHER_SUITE="0xc030,0x1301" +``` + +#### Example 3 + +The implementation is documented to use the CURL syntax. + +Logs sent to an endpoint using TLS ciphers: + +* `AES256-GCM-SHA384` (TLS <= 1.2) +* `ECDHE-ECDSA-AES256-SHA384` (TLS <= 1.2) +* `TLS_AES_256_GCM_SHA384` (TLS >= 1.3) + +```bash +export OTEL_EXPORTER_OTLP_LOGS_CIPHER_LIST="AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384" +export OTEL_EXPORTER_OTLP_LOGS_CIPHER_SUITE="TLS_AES_256_GCM_SHA384" +``` + ### Specifying headers via environment variables The `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS`, `OTEL_EXPORTER_OTLP_METRICS_HEADERS` environment variables will contain a list of key value pairs, and these are expected to be represented in a format matching to the [W3C Correlation-Context](https://github.com/w3c/baggage/blob/master/baggage/HTTP_HEADER_FORMAT.md), except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings.