Add variables to support TLS version and cipher in the OTLP exporter

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.

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] | -    | -      | -   | -    | -   | -    | -     |

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.