proxyprotocol.tlv

class proxyprotocol.tlv.Type(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

The PROXY protocol TLV standard type values.

See also

ProxyProtocolTLV

PP2_TYPE_ALPN = 1
PP2_TYPE_AUTHORITY = 2
PP2_TYPE_CRC32C = 3
PP2_TYPE_NOOP = 4
PP2_TYPE_UNIQUE_ID = 5
PP2_TYPE_SSL = 32
PP2_TYPE_NETNS = 48
PP2_SUBTYPE_SSL_VERSION = 33
PP2_SUBTYPE_SSL_CN = 34
PP2_SUBTYPE_SSL_CIPHER = 35
PP2_SUBTYPE_SSL_SIG_ALG = 36
PP2_SUBTYPE_SSL_KEY_ALG = 37
PP2_TYPE_MIN_CUSTOM = 224
PP2_TYPE_MAX_CUSTOM = 239
PP2_TYPE_MIN_EXPERIMENT = 240
PP2_TYPE_MAX_EXPERIMENT = 247
PP2_TYPE_MIN_FUTURE = 248
PP2_TYPE_MAX_FUTURE = 255
class proxyprotocol.tlv.SSLClient(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

The PROXY protocol PP2_TYPE_SSL client flags.

See also

ProxyProtocolSSLTLV

PP2_CLIENT_SSL = 1
PP2_CLIENT_CERT_CONN = 2
PP2_CLIENT_CERT_SESS = 4
class proxyprotocol.tlv.ExtType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Non-standard extension TLV types.

See also

ProxyProtocolExtTLV

PP2_TYPE_EXT_COMPRESSION = 1
PP2_TYPE_EXT_SECRET_BITS = 2
PP2_TYPE_EXT_PEERCERT = 3
PP2_TYPE_EXT_DNSBL = 4
class proxyprotocol.tlv.TLV(data=b'', init=None)[source]

Defines the basic parsing and structure of a PROXY protocol TLV vector. The unpacked TLV values are available as dict-style keys of this object, e.g. tlv[0xE2]. To serialize back to a bytestring, use bytes(tlv).

Parameters:

  • data (bytes) – TLV data to parse.

  • init (Optional[Mapping[int, bytes]]) – A mapping of types to values to initialize the TLV, such as another TLV.

property size: int

The size of the TLV when converted to bytes.

class proxyprotocol.tlv.ProxyProtocolTLV(data=b'', init=None, *, alpn=None, authority=None, crc32c=None, unique_id=None, ssl=None, netns=None, ext=None, auto_crc32c=False)[source]

Defines the TLV values that may be appended to a PROXY protocol header. These values can provide additional information not stored in the address data. Refer to the PROXY protocol spec for more information about each TLV.

Parameters:
property size: int

The size of the TLV when converted to bytes.

with_checksum(*before)[source]

Return a copy of the current TLV values with the crc32c checksum populated according to the rules in the PROXY protocol spec.

Parameters:

before (bytes) – The data in the PROXY protocol header before the TLV, which is included in the checksum.

Return type:

ProxyProtocolTLV

verify_checksum(*before)[source]

Verifies the crc32c checksum, if present, correctly matches the expected value computed for the PROXY protocol header. If this method returns False, the connection should likely be aborted.

Parameters:

before (bytes) – The data in the PROXY protocol header before the TLV, which is included in the checksum.

Return type:

bool

property alpn: bytes | None

The PP2_TYPE_ALPN value.

property authority: str | None

The PP2_TYPE_AUTHORITY value.

property crc32c: int | None

The PP2_TYPE_CRC32C value.

property unique_id: bytes

The PP2_TYPE_UNIQUE_ID value.

property ssl: ProxyProtocolSSLTLV

The PP2_TYPE_SSL value.

property netns: str | None

The PP2_TYPE_NETNS value.

property ext: ProxyProtocolExtTLV

The PP2_TYPE_NOOP value, possibly parsed as an extension TLV.

class proxyprotocol.tlv.ProxyProtocolSSLTLV(data=b'', init=None, *, has_ssl=None, has_cert_conn=None, has_cert_sess=None, verified=None, version=None, cn=None, cipher=None, sig_alg=None, key_alg=None)[source]

The PP2_TYPE_SSL TLV, which is prefixed with a struct containing client and verify values, then follows with PP2_SUBTYPE_SSL_* TLVs.

Parameters:

  • data (bytes) – TLV data to parse.

  • init (Optional[Mapping[int, bytes]]) – A mapping of types to values to initialize the TLV, such as another TLV.

  • has_ssl (Optional[bool])

  • has_cert_conn (Optional[bool])

  • has_cert_sess (Optional[bool])

  • verified (Optional[bool])

  • version (Optional[str])

  • cn (Optional[str])

  • cipher (Optional[str])

  • sig_alg (Optional[str])

  • key_alg (Optional[str])

property client: int

The client field in the PP2_TYPE_SSL value.

property verify: int

The verify field in the PP2_TYPE_SSL value.

property has_ssl: bool

True if the PP2_CLIENT_SSL flag was set.

property has_cert_conn: bool

True if the PP2_CLIENT_CERT_CONN flag was set.

property has_cert_sess: bool

True if the PP2_CLIENT_CERT_SESS flag was set.

property verified: bool

True if the client provided a certificate that was successfully verified.

property version: str | None

The PP2_SUBTYPE_SSL_VERSION value.

property cn: str | None

The PP2_SUBTYPE_SSL_CN value.

property cipher: str | None

The PP2_SUBTYPE_SSL_CIPHER value.

property sig_alg: str | None

The PP2_SUBTYPE_SSL_SIG_ALG value.

property key_alg: str | None

The PP2_SUBTYPE_SSL_KEY_ALG value.

class proxyprotocol.tlv.ProxyProtocolExtTLV(data=b'', init=None, *, compression=None, secret_bits=None, peercert=None, dnsbl=None)[source]

Non-standard extension TLV, which is hidden inside a PP2_TYPE_NOOP and must start with MAGIC_PREFIX.

Parameters:

  • data (bytes) – TLV data to parse.

  • init (Optional[Mapping[int, bytes]]) – A mapping of types to values to initialize the TLV, such as another TLV.

  • compression (Optional[str])

  • secret_bits (Optional[int])

  • peercert (Optional[PeerCert])

  • dnsbl (Optional[str])

MAGIC_PREFIX: ClassVar[bytes] = b'\x88\x1by\xc1\xce\x96\x85\xb0'

The PP2_TYPE_NOOP value must begin with this byte sequence to be parsed as a ProxyProtocolExtTLV.

property compression: str | None

The PP2_TYPE_EXT_COMPRESSION value. This is used by the compression value.

property secret_bits: int | None

The PP2_TYPE_EXT_SECRET_BITS value. This is used to populate the third member of the cipher tuple.

property peercert: Mapping[str, Any] | None

The PP2_TYPE_EXT_PEERCERT value. This is used by the peercert value.

property dnsbl: str | None

The PP2_TYPE_EXT_DNSBL value. This is the hostname or other identifier that reports a status or reputation of the connecting IP address.