diff --git a/CHANGELOG.md b/CHANGELOG.md index 844fd3d94ad..9d0747c51f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -196,6 +196,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 - No changes. diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index a19b9b16e80..bd63b9c7001 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -319,6 +319,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..29cdd20e4ac 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -32,6 +32,36 @@ 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 + - 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` + +- **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` @@ -150,6 +180,168 @@ 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 enumerated values, +listing TLS version names. + +The list of TLS version names is implementation dependent. + +When TLS of the corresponding version is supported by the implementation, +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. + +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`. + +#### 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_SUITE` +is used to further restrict the cipher negotiated by the secure connection. + +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_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_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 + 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, + 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. + +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.