DOC: Protocol doc: add checksum, TLV type ranges

Add the CRC32c checksum TLV PP2_TYPE_CHECKSUM. Reserve TLV type ranges
CUSTOM, EXPERIMENT and FUTURE. Clarify that only UNSPEC protocol byte is
mandatory to implement on the receiver.

diff --git a/doc/proxy-protocol.txt b/doc/proxy-protocol.txt
index 8fba74db79a2aa3447087964a885834e3db67ce3..06b99dcddc806bf51a5ed6849130aac1cc05d04d 100644 (file)
--- a/doc/proxy-protocol.txt
+++ b/doc/proxy-protocol.txt
@@ -1,4 +1,4 @@
-2015/08/24                                                        Willy Tarreau
+2017/01/30                                                        Willy Tarreau
                                                            HAProxy Technologies
                                The PROXY protocol
                                  Versions 1 & 2
@@ -23,6 +23,8 @@ Revision history
    2014/06/14 - fix v2 header check in example code, and update Forwarded spec
    2014/07/12 - update list of implementations (add Squid)
    2015/05/02 - update list of implementations and format of the TLV add-ons
+   2017/01/30 - added the checksum TLV and reserved TLV type ranges, clarified
+                wording
 
 
 1. Background
@@ -428,9 +430,10 @@ In practice, the following protocol bytes are expected :
     AF_UNIX protocol family. Address length is 2*108 = 216 bytes.
 
 
-Only the UNSPEC protocol byte (\x00) is mandatory. A receiver is not required
-to implement other ones, provided that it automatically falls back to the
-UNSPEC mode for the valid combinations above that it does not support.
+Only the UNSPEC protocol byte (\x00) is mandatory to implement on the receiver.
+A receiver is not required to implement other ones, provided that it
+automatically falls back to the UNSPEC mode for the valid combinations above
+that it does not support.
 
 The 15th and 16th bytes is the address length in bytes in network endian order.
 It is used so that the receiver knows how many address bytes to skip even when
@@ -523,17 +526,53 @@ bytes specified by the length.
             uint8_t value[0];
         };
 
+A receiver may choose to skip over and ignore the TLVs he is not interested in
+or he does not understand. Senders can generate the TLVs only for
+the information they choose to publish.
+
 The following types have already been registered for the <type> field :
 
         #define PP2_TYPE_ALPN           0x01
         #define PP2_TYPE_AUTHORITY      0x02
+        #define PP2_TYPE_CHECKSUM       0x03
         #define PP2_TYPE_SSL            0x20
         #define PP2_SUBTYPE_SSL_VERSION 0x21
         #define PP2_SUBTYPE_SSL_CN      0x22
         #define PP2_TYPE_NETNS          0x30
 
 
-2.2.1. The PP2_TYPE_SSL type and subtypes
+2.2.1. The PP2_TYPE_CHECKSUM type
+
+The value of the type PP2_TYPE_CHECKSUM is a 32-bit number storing the CRC32c
+checksum of the PROXY protocol header.
+
+When the checksum is supported by the sender after constructing the header
+the sender MUST:
+
+ - initialize the checksum field to '0's.
+
+ - calculate the CRC32c checksum of the PROXY header as described in RFC4960,
+   Appendix B [8].
+
+ - put the resultant value into the checksum field, and leave the rest of
+   the bits unchanged.
+
+If the checksum is provided as part of the PROXY header and the checksum
+functionality is supported by the receiver, the receiver MUST:
+
+ - store the received CRC32c checksum value aside.
+
+ - replace the 32 bits of the checksum field in the received PROXY header with
+   all '0's and calculate a CRC32c checksum value of the whole PROXY header.
+
+ - verify that the calculated CRC32c checksum is the same as the received
+   CRC32c checksum. If it is not, the receiver MUST treat the TCP connection
+   providing the header as invalid.
+
+The default procedure for handling an invalid TCP connection is to abort it.
+
+
+2.2.2. The PP2_TYPE_SSL type and subtypes
 
 For the type PP2_TYPE_SSL, the value is itselv a defined like this :
 
@@ -571,12 +610,36 @@ In all cases, the string representation (in UTF8) of the Common Name field
 using the TLV format and the type PP2_SUBTYPE_SSL_CN.
 
 
-2.2.2. The PP2_TYPE_NETNS type
+2.2.3. The PP2_TYPE_NETNS type
 
 The type PP2_TYPE_NETNS defines the value as the string representation of the
 namespace's name.
 
 
+2.2.4. Reserved type ranges
+
+The following range of 16 type values is reserved for application-specific
+data and will be never used by the PROXY Protocol. If you need more values
+consider extending the range with a type field in your TLVs.
+
+        #define PP2_TYPE_MIN_CUSTOM    0xE0
+        #define PP2_TYPE_MAX_CUSTOM    0xEF
+
+This range of 8 values is reserved for temporary experimental use by
+application developers and protocol designers. The values from the range will
+never be used by the PROXY protocol and should not be used by production
+functionality.
+
+        #define PP2_TYPE_MIN_EXPERIMENT 0xF0
+        #define PP2_TYPE_MAX_EXPERIMENT 0xF7
+
+The following range of 8 values is reserved for future use, potentially to
+extend the protocol with multibyte type values.
+
+        #define PP2_TYPE_MIN_FUTURE    0xF8
+        #define PP2_TYPE_MAX_FUTURE    0xFF
+
+
 3. Implementations
 
 Haproxy 1.5 implements version 1 of the PROXY protocol on both sides :
@@ -803,6 +866,7 @@ The following links were referenced in the document.
 [5] https://github.com/bumptech/stud/pull/81
 [6] https://www.varnish-cache.org/docs/trunk/phk/ssl_again.html
 [7] http://wiki.squid-cache.org/Squid-3.5
+[8] https://tools.ietf.org/html/rfc4960#appendix-B
 
 
 9. Sample code