/
tls.proto
302 lines (254 loc) · 14.4 KB
/
tls.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
syntax = "proto3";
package envoy.extensions.transport_sockets.tls.v3;
import "envoy/config/core/v3/extension.proto";
import "envoy/extensions/transport_sockets/tls/v3/common.proto";
import "envoy/extensions/transport_sockets/tls/v3/secret.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";
import "envoy/annotations/deprecation.proto";
import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";
import "validate/validate.proto";
option java_package = "io.envoyproxy.envoy.extensions.transport_sockets.tls.v3";
option java_outer_classname = "TlsProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/transport_sockets/tls/v3;tlsv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;
// [#protodoc-title: TLS transport socket]
// [#extension: envoy.transport_sockets.tls]
// The TLS contexts below provide the transport socket configuration for upstream/downstream TLS.
message UpstreamTlsContext {
option (udpa.annotations.versioning).previous_message_type =
"envoy.api.v2.auth.UpstreamTlsContext";
// Common TLS context settings.
//
// .. attention::
//
// Server certificate verification is not enabled by default. Configure
// :ref:`trusted_ca<envoy_v3_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.trusted_ca>` to enable
// verification.
CommonTlsContext common_tls_context = 1;
// SNI string to use when creating TLS backend connections.
string sni = 2 [(validate.rules).string = {max_bytes: 255}];
// If true, server-initiated TLS renegotiation will be allowed.
//
// .. attention::
//
// TLS renegotiation is considered insecure and shouldn't be used unless absolutely necessary.
bool allow_renegotiation = 3;
// Maximum number of session keys (Pre-Shared Keys for TLSv1.3+, Session IDs and Session Tickets
// for TLSv1.2 and older) to store for the purpose of session resumption.
//
// Defaults to 1, setting this to 0 disables session resumption.
google.protobuf.UInt32Value max_session_keys = 4;
}
// [#next-free-field: 9]
message DownstreamTlsContext {
option (udpa.annotations.versioning).previous_message_type =
"envoy.api.v2.auth.DownstreamTlsContext";
enum OcspStaplePolicy {
// OCSP responses are optional. If an OCSP response is absent
// or expired, the associated certificate will be used for
// connections without an OCSP staple.
LENIENT_STAPLING = 0;
// OCSP responses are optional. If an OCSP response is absent,
// the associated certificate will be used without an
// OCSP staple. If a response is provided but is expired,
// the associated certificate will not be used for
// subsequent connections. If no suitable certificate is found,
// the connection is rejected.
STRICT_STAPLING = 1;
// OCSP responses are required. Configuration will fail if
// a certificate is provided without an OCSP response. If a
// response expires, the associated certificate will not be
// used connections. If no suitable certificate is found, the
// connection is rejected.
MUST_STAPLE = 2;
}
// Common TLS context settings.
CommonTlsContext common_tls_context = 1;
// If specified, Envoy will reject connections without a valid client
// certificate.
google.protobuf.BoolValue require_client_certificate = 2;
// If specified, Envoy will reject connections without a valid and matching SNI.
// [#not-implemented-hide:]
google.protobuf.BoolValue require_sni = 3;
oneof session_ticket_keys_type {
// TLS session ticket key settings.
TlsSessionTicketKeys session_ticket_keys = 4;
// Config for fetching TLS session ticket keys via SDS API.
SdsSecretConfig session_ticket_keys_sds_secret_config = 5;
// Config for controlling stateless TLS session resumption: setting this to true will cause the TLS
// server to not issue TLS session tickets for the purposes of stateless TLS session resumption.
// If set to false, the TLS server will issue TLS session tickets and encrypt/decrypt them using
// the keys specified through either :ref:`session_ticket_keys <envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.session_ticket_keys>`
// or :ref:`session_ticket_keys_sds_secret_config <envoy_v3_api_field_extensions.transport_sockets.tls.v3.DownstreamTlsContext.session_ticket_keys_sds_secret_config>`.
// If this config is set to false and no keys are explicitly configured, the TLS server will issue
// TLS session tickets and encrypt/decrypt them using an internally-generated and managed key, with the
// implication that sessions cannot be resumed across hot restarts or on different hosts.
bool disable_stateless_session_resumption = 7;
}
// If specified, ``session_timeout`` will change the maximum lifetime (in seconds) of the TLS session.
// Currently this value is used as a hint for the `TLS session ticket lifetime (for TLSv1.2) <https://tools.ietf.org/html/rfc5077#section-5.6>`_.
// Only seconds can be specified (fractional seconds are ignored).
google.protobuf.Duration session_timeout = 6 [(validate.rules).duration = {
lt {seconds: 4294967296}
gte {}
}];
// Config for whether to use certificates if they do not have
// an accompanying OCSP response or if the response expires at runtime.
// Defaults to LENIENT_STAPLING
OcspStaplePolicy ocsp_staple_policy = 8 [(validate.rules).enum = {defined_only: true}];
}
// TLS context shared by both client and server TLS contexts.
// [#next-free-field: 15]
message CommonTlsContext {
option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.CommonTlsContext";
// Config for Certificate provider to get certificates. This provider should allow certificates to be
// fetched/refreshed over the network asynchronously with respect to the TLS handshake.
//
// DEPRECATED: This message is not currently used, but if we ever do need it, we will want to
// move it out of CommonTlsContext and into common.proto, similar to the existing
// CertificateProviderPluginInstance message.
//
// [#not-implemented-hide:]
message CertificateProvider {
// opaque name used to specify certificate instances or types. For example, "ROOTCA" to specify
// a root-certificate (validation context) or "TLS" to specify a new tls-certificate.
string name = 1 [(validate.rules).string = {min_len: 1}];
// Provider specific config.
// Note: an implementation is expected to dedup multiple instances of the same config
// to maintain a single certificate-provider instance. The sharing can happen, for
// example, among multiple clusters or between the tls_certificate and validation_context
// certificate providers of a cluster.
// This config could be supplied inline or (in future) a named xDS resource.
oneof config {
option (validate.required) = true;
config.core.v3.TypedExtensionConfig typed_config = 2;
}
}
// Similar to CertificateProvider above, but allows the provider instances to be configured on
// the client side instead of being sent from the control plane.
//
// DEPRECATED: This message was moved outside of CommonTlsContext
// and now lives in common.proto.
//
// [#not-implemented-hide:]
message CertificateProviderInstance {
// Provider instance name. This name must be defined in the client's configuration (e.g., a
// bootstrap file) to correspond to a provider instance (i.e., the same data in the typed_config
// field that would be sent in the CertificateProvider message if the config was sent by the
// control plane). If not present, defaults to "default".
//
// Instance names should generally be defined not in terms of the underlying provider
// implementation (e.g., "file_watcher") but rather in terms of the function of the
// certificates (e.g., "foo_deployment_identity").
string instance_name = 1;
// Opaque name used to specify certificate instances or types. For example, "ROOTCA" to specify
// a root-certificate (validation context) or "example.com" to specify a certificate for a
// particular domain. Not all provider instances will actually use this field, so the value
// defaults to the empty string.
string certificate_name = 2;
}
message CombinedCertificateValidationContext {
option (udpa.annotations.versioning).previous_message_type =
"envoy.api.v2.auth.CommonTlsContext.CombinedCertificateValidationContext";
// How to validate peer certificates.
CertificateValidationContext default_validation_context = 1
[(validate.rules).message = {required: true}];
// Config for fetching validation context via SDS API. Note SDS API allows certificates to be
// fetched/refreshed over the network asynchronously with respect to the TLS handshake.
SdsSecretConfig validation_context_sds_secret_config = 2
[(validate.rules).message = {required: true}];
// Certificate provider for fetching CA certs. This will populate the
// *default_validation_context.trusted_ca* field.
// [#not-implemented-hide:]
CertificateProvider validation_context_certificate_provider = 3
[deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
// Certificate provider instance for fetching CA certs. This will populate the
// *default_validation_context.trusted_ca* field.
// [#not-implemented-hide:]
CertificateProviderInstance validation_context_certificate_provider_instance = 4
[deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
}
reserved 5;
// TLS protocol versions, cipher suites etc.
TlsParameters tls_params = 1;
// :ref:`Multiple TLS certificates <arch_overview_ssl_cert_select>` can be associated with the
// same context to allow both RSA and ECDSA certificates.
//
// Only a single TLS certificate is supported in client contexts. In server contexts, the first
// RSA certificate is used for clients that only support RSA and the first ECDSA certificate is
// used for clients that support ECDSA.
//
// Only one of *tls_certificates*, *tls_certificate_sds_secret_configs*,
// and *tls_certificate_provider_instance* may be used.
// [#next-major-version: These mutually exclusive fields should ideally be in a oneof, but it's
// not legal to put a repeated field in a oneof. In the next major version, we should rework
// this to avoid this problem.]
repeated TlsCertificate tls_certificates = 2;
// Configs for fetching TLS certificates via SDS API. Note SDS API allows certificates to be
// fetched/refreshed over the network asynchronously with respect to the TLS handshake.
//
// The same number and types of certificates as :ref:`tls_certificates <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.tls_certificates>`
// are valid in the the certificates fetched through this setting.
//
// Only one of *tls_certificates*, *tls_certificate_sds_secret_configs*,
// and *tls_certificate_provider_instance* may be used.
// [#next-major-version: These mutually exclusive fields should ideally be in a oneof, but it's
// not legal to put a repeated field in a oneof. In the next major version, we should rework
// this to avoid this problem.]
repeated SdsSecretConfig tls_certificate_sds_secret_configs = 6
[(validate.rules).repeated = {max_items: 2}];
// Certificate provider instance for fetching TLS certs.
//
// Only one of *tls_certificates*, *tls_certificate_sds_secret_configs*,
// and *tls_certificate_provider_instance* may be used.
// [#not-implemented-hide:]
CertificateProviderPluginInstance tls_certificate_provider_instance = 14;
// Certificate provider for fetching TLS certificates.
// [#not-implemented-hide:]
CertificateProvider tls_certificate_certificate_provider = 9
[deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
// Certificate provider instance for fetching TLS certificates.
// [#not-implemented-hide:]
CertificateProviderInstance tls_certificate_certificate_provider_instance = 11
[deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
oneof validation_context_type {
// How to validate peer certificates.
CertificateValidationContext validation_context = 3;
// Config for fetching validation context via SDS API. Note SDS API allows certificates to be
// fetched/refreshed over the network asynchronously with respect to the TLS handshake.
SdsSecretConfig validation_context_sds_secret_config = 7;
// Combined certificate validation context holds a default CertificateValidationContext
// and SDS config. When SDS server returns dynamic CertificateValidationContext, both dynamic
// and default CertificateValidationContext are merged into a new CertificateValidationContext
// for validation. This merge is done by Message::MergeFrom(), so dynamic
// CertificateValidationContext overwrites singular fields in default
// CertificateValidationContext, and concatenates repeated fields to default
// CertificateValidationContext, and logical OR is applied to boolean fields.
CombinedCertificateValidationContext combined_validation_context = 8;
// Certificate provider for fetching validation context.
// [#not-implemented-hide:]
CertificateProvider validation_context_certificate_provider = 10
[deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
// Certificate provider instance for fetching validation context.
// [#not-implemented-hide:]
CertificateProviderInstance validation_context_certificate_provider_instance = 12
[deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
}
// Supplies the list of ALPN protocols that the listener should expose. In
// practice this is likely to be set to one of two values (see the
// :ref:`codec_type
// <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.codec_type>`
// parameter in the HTTP connection manager for more information):
//
// * "h2,http/1.1" If the listener is going to support both HTTP/2 and HTTP/1.1.
// * "http/1.1" If the listener is only going to support HTTP/1.1.
//
// There is no default for this parameter. If empty, Envoy will not expose ALPN.
repeated string alpn_protocols = 4;
// Custom TLS handshaker. If empty, defaults to native TLS handshaking
// behavior.
config.core.v3.TypedExtensionConfig custom_handshaker = 13;
}