Sovite.ProxyProtocol.Header (sovite v0.6.0)

Copy Markdown View Source

A parsed PROXY protocol header, see Sovite.ProxyProtocol.

  • :version - 1 or 2.
  • :command - :proxy, or :local for a connection the proxy made itself, such as a health check. A :local header carries no addresses: the receiver uses the real connection endpoints.
  • :transport - :tcp4, :tcp6, :udp4, :udp6, :unix, :unix_dgram (UNIX stream and datagram sockets), or :unspec (version 1 UNKNOWN, version 2 AF_UNSPEC, and every :local header).
  • :source, :destination - {ip, port}, or {:local, path} for UNIX sockets. nil with :unspec.
  • :tlvs - version 2 TLVs as {type, value}, in the order received, unknown types included. This is what Sovite.ProxyProtocol.encode_v2/1 sends. Build well-known ones with Sovite.ProxyProtocol.tlv/2.

The well-known TLVs among :tlvs, decoded (nil when absent):

  • :alpn - PP2_TYPE_ALPN, the negotiated application protocol, such as "h2".
  • :authority - PP2_TYPE_AUTHORITY, the host name the client asked for, usually the TLS SNI.
  • :unique_id - PP2_TYPE_UNIQUE_ID, an opaque connection ID of up to 128 bytes.
  • :ssl - PP2_TYPE_SSL, see ssl/0.
  • :netns - PP2_TYPE_NETNS, the network namespace name.

PP2_TYPE_CRC32C is checked by Sovite.ProxyProtocol.parse/2 and PP2_TYPE_NOOP is padding; both stay in :tlvs only.

Summary

Types

address()

An endpoint: an IP address and port, or a UNIX socket path.

ssl()

What a TLS-terminating proxy knew about the client connection (PP2_TYPE_SSL)

t()
tlv()

A version 2 TLV.

transport()

A transport protocol and address family.

Types

address()

@type address() :: {:inet.ip_address(), :inet.port_number()} | {:local, binary()}

An endpoint: an IP address and port, or a UNIX socket path.

ssl()

@type ssl() :: %{
  client: [:ssl | :cert_conn | :cert_sess],
  verify: non_neg_integer(),
  version: String.t() | nil,
  cn: String.t() | nil,
  cipher: String.t() | nil,
  sig_alg: String.t() | nil,
  key_alg: String.t() | nil,
  tlvs: [tlv()]
}

What a TLS-terminating proxy knew about the client connection (PP2_TYPE_SSL):

  • :client - which of PP2_CLIENT_SSL (:ssl, the client used TLS), PP2_CLIENT_CERT_CONN (:cert_conn, it sent a certificate on this connection), and PP2_CLIENT_CERT_SESS (:cert_sess, it sent one in this TLS session) are set.
  • :verify - 0 if the client certificate was presented and verified, nonzero otherwise.
  • :version, :cn, :cipher, :sig_alg, :key_alg - the PP2_SUBTYPE_SSL_* sub-TLVs: TLS version ("TLSv1.3"), client certificate common name, cipher, certificate signature and key algorithms. nil when absent.
  • :tlvs - all sub-TLVs, in the order received.

t()

@type t() :: %Sovite.ProxyProtocol.Header{
  alpn: binary() | nil,
  authority: String.t() | nil,
  command: :proxy | :local,
  destination: address() | nil,
  netns: String.t() | nil,
  source: address() | nil,
  ssl: ssl() | nil,
  tlvs: [tlv()],
  transport: transport(),
  unique_id: binary() | nil,
  version: 1 | 2
}

tlv()

@type tlv() :: {type :: 0..255, value :: binary()}

A version 2 TLV.

transport()

@type transport() :: :tcp4 | :tcp6 | :udp4 | :udp6 | :unix | :unix_dgram | :unspec

A transport protocol and address family.