PROXY 协议支持 ¶

参数

error_msg ( str ) – Error message

返回

self

Sets the instance’s error attribute and returns itself.

参数

_raises ( bool ) – If True , raise exception if attribute not match/not found, instead of returning a bool. Defaults to False

引发

• ValueError – if _raises=True and attribute is found but value is wrong

• KeyError – if _raises=True and attribute is not found

A helper method to quickly verify whether an attribute exists and contain the same value as expected.

用法范例：

proxy_data.same_attribs(
    version=1,
    protocol=b"TCP4",
    unknown_attrib=None
)
							

In the above example, same_attribs will check that all attributes version , protocol ，和 unknown_attrib exist, and contains the values 1 , b"TCP4" ，和 None ，分别。

Missing attributes and/or differing values will return a False (unless _raises=True )

注意

For other examples, take a look inside the test_proxyprotocol.py file. That file extensively 使用 same_attribs .

__bool__ ( ) ¶

Allows an instance of ProxyData to be evaluated as boolean. In actuality, it simply returns the valid 特性。

ProxyTLV API ¶

class aiosmtpd.proxy_protocol. ProxyTLV ¶

This class parses the TLV portion of the PROXY Header and presents the value in an easy-to-use way: A “TLV Vector” whose “Type” is found in PP2_TYPENAME can be accessed through the .<NAME> 属性。

It is a subclass of dict , so all of dict ’s methods are available. It is basically a Dict[str, Any] with additional methods and attributes. The list below only describes methods & attributes added to this class.

PP2_TYPENAME : Dict [ int , str ] ¶

A mapping of numeric Type to a human-friendly Name.

The names are identical to the ones listed in the documentation , but with the PP2_TYPE_ / PP2_SUBTYPE_ prefixes removed.

注意

SSL Name is special. Rather than containing the TLV Subvectors as described in the standard, it is a bool value that indicates whether the PP2_SUBTYPE_SSL

tlv_loc : Dict [ str , int ] ¶

A mapping to show the start location of certain TLV Vectors.

The keys are the TYPENAME (see PP2_TYPENAME above), and the value is the offset from start of the TLV Vectors.

same_attribs ( _raises = False , ** kwargs ) → bool ¶

参数

_raises ( bool ) – If True , raise exception if attribute not match/not found, instead of returning a bool. Defaults to False

引发

• ValueError – if _raises=True and attribute is found but value is wrong

• KeyError – if _raises=True and attribute is not found

A helper method to quickly verify whether an attribute exists and contain the same value as expected.

用法范例：

assert isinstance(proxy_tlv, ProxyTLV)
proxy_tlv.same_attribs(
    AUTHORITY=b"some_authority",
    SSL=True,
)
							

In the above example, same_attribs will check that the attributes AUTHORITY and SSL exist, and contains the values b"some_authority" and True ，分别。

Missing attributes and/or differing values will return a False (unless _raises=True )

注意

For other examples, take a look inside the test_proxyprotocol.py file. That file extensively 使用 same_attribs .

classmethod from_raw ( raw ) → Optional [ ProxyTLV ] ¶

参数

raw ( Union [ bytes , bytearray ] ) – The raw bytes containing the TLV Vectors

返回

A new instance of ProxyTLV, or None if parsing failed

This triggers the parsing of raw bytes/bytearray into a ProxyTLV instance.

Internally it relies on the parse() classmethod to perform the parsing.

Unlike the default behavior of parse() , from_raw will NOT perform a partial parsing.

classmethod parse ( chunk , partial_ok = True ) → Dict [ str , 任何 ] ¶

参数

• chunk ( Union [ bytes , bytearray ] ) – The bytes to parse into TLV Vectors

• partial_ok ( bool ) – If True , return partially-parsed TLV Vectors as is. If False , (re)raise MalformedTLV

返回

A mapping of typenames and values

This performs a recursive parsing of the bytes. If it encounters a TYPE that ProxyTLV doesn’t recognize, the TLV Vector will be assigned a typename of “xNN”

Partial parsing is possible when partial_ok=True ; if during the parsing an error happened, parse will abort returning the TLV Vectors it had successfully decoded.

classmethod name_to_num ( name ) → Optional [ int ] ¶

参数

名称 ( str ) – The name to back-map into TYPE numeric

返回

The numeric value associated to the typename, None if no such mapping is found

This is a helper method to perform back-mapping of typenames.

CRC32C 计算注意事项 ¶

Neither the ProxyData nor ProxyTLV classes implement PROXYv2 CRC32C validation ; the main reason being that Python has no built-in module for calculating CRC32C. To perform CRC32C, third-party modules need to be installed, but we are uncomfortable doing that for the following reasons:

• There are more than one third-party modules providing CRC32C, e.g., crcmod , crc32c , google-crc32c , etc. Problem is, there is no known clear comparison between them, so we cannot tell easily which one is ‘best’.

• Some of these third-party modules seem to be no longer being maintained.

• Most of the available third-party modules are binary distribution. This potentially causes problems with existing binaries/libraries, not to mention possible (albeit unlikely) vector for malware.

• We really don’t like adding dependencies outside those that are really needed.

In short, we have strong reasons to NOT implement PROXYv2 CRC32C validation, and we have plans to NEVER implement it.

If you absolutely need PROXYv2 CRC32C validation, you should perform it yourself in the handle_PROXY() hook. To assist you, we have provided the whole_raw , tlv_start ，和 tlv_loc 属性。

You should do the following:

1. Choose a CRC32C module of your liking, install that, and import it.

2. Find the “CRC32C” TLV Vector in whole_raw ; it would start at byte tlv_start + tlv_loc["CRC32C"]

3. Zero out the 4-octet Value part of the “CRC32C” TLV Vector

4. Perform CRC32C calculation over the modified whole_raw

5. Convert the result to big-endian bytes, and compare with the .CRC32C attribute of the ProxyTLV instance

范例：

# The int(3) at end is to skip over the "T" and "L" part
offset = proxy_data.tlv_start + proxy_data.tlv.tlv_loc["CRC32C"] + 3
# Since whole_raw is a bytearray, we can do slice replacement
proxy_data.whole_raw[offset:offset + 4] = "\x00\x00\x00\x00"
# Actual syntax will depend on the module you use
calculated: int = crc32c(proxy_data.whole_raw)
# Adjust first part as necessary if calculated is not int
validated = calculated.to_bytes(4, "big") == proxy_data.tlv.CRC32C
								

Good luck!