data-plane-api/api/lds.proto

// This is heavily derived from
// https://lyft.github.io/envoy/docs/configuration/listeners/listeners.html
// The v2 gRPC API differences are tagged with [V2-API-DIFF].

syntax = "proto3";

import "api/node.proto";

import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

// The Envoy instance initiates an RPC at startup to discover a list of
// listeners. Updates are delivered via streaming from the LDS server and
// consist of a complete update of all listeners. Existing connections will be
// allowed to drain from listeners that are no longer present.
service ListenerDiscoveryService {
  rpc StreamListeners(ListenerDiscoveryRequest) returns
      (stream ListenerDiscoverResponse) {}
}

message ListenerDiscoveryRequest {
  Node node = 1;
}

message ListenerDiscoverResponse {
  repeated Listener listeners = 1;
}

// [V2-API-DIFF] Addresses now have .proto structure.
message ListenerAddress {
  message SocketAddress {
    // Bind to 0.0.0.0 or :: to support the use of prefix/suffix matching in
    // FilterChainMatch.
    google.protobuf.StringValue address = 1;
    google.protobuf.UInt32Value port = 2;
  }
  message Pipe {
    google.protobuf.StringValue path = 1;
  }
  oneof address {
    SocketAddress socket_address = 1;
    Pipe pipe = 2;
  }
}

message DataSource {
  oneof specifier {
    google.protobuf.StringValue filename = 1;
    google.protobuf.BytesValue inline = 2;
  }
}

// SSL certs can be loaded from file or delivered inline [V2-API-DIFF]. Individual fields may
// be loaded from either.
message SslCertificate {
  DataSource cert_chain = 1;
  DataSource private_key = 2;
  DataSource ocsp_staple = 3;
  repeated DataSource signed_certificate_timestamp = 4;
}

message ClientSslContext {
  // SSL certificate data containing certificate authority certificates to use
  // in verifying a presented client side certificate. If not specified and a
  // client certificate is presented it will not be verified.
  DataSource ca_cert = 1;

  // If specified, Envoy will verify (pin) the hash of the presented client side
  // certificate.
  google.protobuf.StringValue verify_certificate_hash = 2;

  // An optional list of subject alt names. If specified, Envoy will verify that
  // the client certificate’s subject alt name matches one of the specified
  // values.
  repeated google.protobuf.StringValue verify_subject_alt_name = 3;

  // Client must present a signed time-stamped OCSP response.
  google.protobuf.BoolValue require_ocsp_staple = 4;

  // Client must present signed certificate time-stamp.
  google.protobuf.BoolValue require_signed_certificate_timestamp = 5;
}

// [V2-API-DIFF] This has been reworked to support alternative modes of
// certificate/key delivery, for consistency with the upstream SSL context and
// to segregate the client/server aspects of the SSL context.
message SslContext {
  // Multiple SSL certificates can be associated with the same context, e.g. to
  // allow both RSA and ECDSA certificates for the same SNI [V2-API-DIFF].
  repeated SslCertificate ssl_certificates = 1;

  ClientSslContext client_ssl_context = 2;

  // Supplies the list of ALPN protocols that the listener should expose.
  repeated google.protobuf.StringValue alpn_protocols = 3;

  enum TLSProtocol {
    TLS_AUTO = 0;
    TLSv1_0 = 1;
    TLSv1_1 = 2;
    TLSv1_2 = 3;
    TLSv1_3 = 4;
  }
  // Allowed TLS protocols.
  TLSProtocol tls_minimum_protocol_version = 4;
  TLSProtocol tls_maximum_protocol_version = 5;

  // If specified, the TLS listener will only support the specified cipher list.
  repeated google.protobuf.StringValue cipher_suites = 6;

  // If specified, the TLS connection will only support the specified ECDH
  // curves. If not specified, the default curves (X25519, P-256) will be used.
  repeated google.protobuf.StringValue ecdh_curves = 7;
}

message Filter {
  // The type of filter to instantiate. Most filters implement a specific type,
  // though it is theoretically possible for a filter to be written such that it
  // can operate in multiple modes. Supported types are read, write, and both.
  enum Type {
    BOTH = 0;
    READ = 1;
    WRITE = 2;
  }
  Type type = 1;
  // The name of the filter to instantiate. The name must match a supported
  // filter.
  google.protobuf.StringValue name = 2;
  // Filter specific configuration which depends on the filter being
  // instantiated. See the supported filters for further documentation.
  google.protobuf.Struct config = 3;
}

// Specifies the match criteria for selecting a specific filter chain for a
// listener [V2-API-DIFF].
message FilterChainMatch {
  // If non-empty, the SNI domains to consider. May contain a wildcard prefix,
  // e.g. *.example.com.
  repeated google.protobuf.StringValue sni_domains = 1;

  // If non-empty, an IP address and prefix length to match addresses when the
  // listener is bound to 0.0.0.0/::.
  google.protobuf.StringValue address_prefix = 2;
  google.protobuf.UInt32Value prefix_len = 3;

  // If non-empty, an IP address and suffix length to match addresses when the
  // listener is bound to 0.0.0.0/::.
  google.protobuf.StringValue address_suffix = 4;
  google.protobuf.UInt32Value suffix_len = 5;
}

// Grouping of FilterChainMatch criteria, SslContext, the actual filter chain
// and related parameters.
message FilterChain {
  FilterChainMatch filter_chain_match = 1;
  SslContext ssl_context = 2;
  // A list of individual network filters that make up the filter chain for
  // connections established with the listener. Order matters as the filters are
  // processed sequentially as connection events happen.  Note: If the filter
  // list is empty, the connection will close by default.
  repeated Filter filter_chain = 3;

  // Whether the listener should expect a PROXY protocol V1 header on new
  // connections. If this option is enabled, the listener will assume that that
  // remote address of the connection is the one specified in the header. Some
  // load balancers including the AWS ELB support this option. If the option is
  // absent or set to false, Envoy will use the physical peer address of the
  // connection as the remote address.
  google.protobuf.BoolValue use_proxy_proto = 4;
}

message Listener {
  // The address that the listener should listen on.
  ListenerAddress address = 1;

  // A list of filter chains to consider for this listener. The FilterChain with
  // the most specific FilterChainMatch criteria is used on a connection. The
  // algorithm works as follows:
  // 1. If SNI information is presented at connection time, only the
  //    FilterChains matching the SNI are considered. Otherwise, only
  //    FilterChains with no SNI domains are considered.
  // 2. Of the FilterChains from step 1, the longest prefix match on the
  //    bound destination address is used to select the next set of
  //    FilterChains. This may be one FilterChain or multiple if there is
  //    a tie.
  // 3. The longest suffix match on the bound destination address is used to
  //    select the FilterChain from step 2 that is used.
  repeated FilterChain filter_chains = 2;

  // Whether the listener should not bind to the port. A listener that doesn’t bind
  // can only receive connections redirected from other listeners that set
  // use_origin_dst parameter to true. Default is true.
  google.protobuf.BoolValue bind_to_port = 3;

  // If a connection is redirected using iptables, the port on which the proxy
  // receives it might be different from the original destination port. When
  // this flag is set to true, the listener hands off redirected connections to
  // the listener associated with the original destination port. If there is no
  // listener associated with the original destination port, the connection is
  // handled by the listener that receives it. Default is false.
  google.protobuf.BoolValue use_original_dst = 4;

  // Soft limit on size of the listener’s new connection read and write buffers.
  // If unspecified, an implementation defined default is applied (1MiB).
  google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5;
}