Merge pull request #10 from kosmas-valianos/docserrorfix

Docs and error reporting fixes

Author: kosmas-valianos

README.md

@@ -10,48 +10,54 @@ The library should be compilable to any platform as it is written in ANSI C. It
 
 ## API
 ### Parsing
-**`pp_parse()`**: parsing a PROXY protocol header. Parameters:
-* `uint8_t *pkt`: Pointer to a buffer with the data to parse. Normally it will be the buffer used to peek data from a socket.
-* `uint32_t pktlen`: Data's length. Normally it will be the return value of a `recv(MSG_PEEK)`.
-* `pp_info_t *proxy_info`: Pointer to a `pp_info_t` variable which will be used to save all the extracted information of the PROXY protocol header including the TLVs
-* `return value: int32_t`: The length of the PROXY protocol header in case of success or a negative integer in case of error. You can use `pp_strerror()` to get a descriptive error message. In case the data dont't match any of the v1/v2 signatures `0` is returned.
+**`int32_t pp_parse_hdr(uint8_t *buffer, uint32_t buffer_length, pp_info_t *pp_info)`**:
 
-You shall not pass your `pp_info_t` variable to `pp_parse()` again without first clearing it with `pp_info_clear()` (see below)
+Inpects the buffer for a PROXY protocol header and extracts all the information if any.
+* `buffer`:         Pointer to a buffer with the data to parse. Normally it will be the buffer used to peek data from a socket.
+* `buffer_length`:  Buffer's length. Typically the bytes read from the `recv(MSG_PEEK)` operation.
+* `pp_info`:        Pointer to a `pp_info_t` structure which will get filled with all the extracted information.
+* `return`:
+   * \> 0 Length of the PROXY protocol header
+   * == 0 No PROXY protocol header found
+   * <  0 Error occurred. `pp_strerror()` with that value can be used to get a descriptive message
 
-**`pp_info_get_tlv_value()`**: extracting TLVs' values. Parameters:
-* `pp_info_t *pp_info`: The `pp_info_t` used in the `pp_parse()`
-* `uint8_t type`: The type of the TLV you are looking for as per the specification e.g. PP2_TYPE_AWS, PP2_TYPE_AZURE etc.
-* `uint8_t subtype`: The subtype of the TLV you are looking for (in case it is needed else 0 to get it ignored) as per the specification e.g. PP2_SUBTYPE_AWS_VPCE_ID, PP2_SUBTYPE_AZURE_PRIVATEENDPOINT_LINKID
-* `uint16_t *value_len_out`: The length of the value so that applications can copy and use the value properly
-* `return value: uint8_t *`: Pointer to the value. In case the value is a string e.g. PP2_TYPE_AWS-PP2_SUBTYPE_AWS_VPCE_ID then the buffer is NULL terminated so that it can be used directly for string operations like `strcmp()` etc. **Do not manipulate these data in any way, rather make copies of them if you need to modify them.**
+You shall not pass your `pp_info_t` variable to `pp_parse()` again without first clearing it with `pp_info_clear()`
 
-**`pp_info_clear()`**: clearing a `pp_info_t` structure. You **MUST** use it. Parameter:
-* `pp_info_t *pp_info`: A pointer to the `pp_info_t` used in `pp_parse()`
+**`void pp_info_clear(pp_info_t *pp_info)`**
 
-It basically clears the saved TLVs structure. For v1 it is not really needed as there are not any TLVs but to be safe always use it! A PROXY protocol sender might change from v1 to v2 so better to have your application prepared.
+Clears the `pp_info_t` structure and frees any allocated memory associated with it. Shall always be called after a call to `pp_parse()`
+* `pp_info`: Pointer to a filled `pp_info_t` structure which has been used to a previous call to `pp_parse()`
+
+**`const uint8_t *pp_info_get_*(const pp_info_t *pp_info, uint16_t *length);`**
+
+Searches for the specified TLV and returns its value
+* `pp_info` Pointer to a `pp_info_t` structure used in `pp_parse()`
+* `length`  Pointer to a `uint16_t` where the TLV's value length will be set
+* `return`  Pointer to a buffer holding the TLV's value if found else `NULL`. In case of US-ASCII value the buffer is `NULL` terminated
 
 ### Creating
-**`pp_create_hdr()`**: create a PROXY protocol header. Parameters:
-* `uint8_t version`: `1` or `2` depending on the PROXY protocol version you want to use.
-* `uint8_t fam`: Transport and address family. The values match exactly the specification:
-  * v2 
-    * `'\x00'` : UNSPEC
-    * `'\x11'` : TCP over IPv4
-    * `'\x12'` : UDP over IPv4
-    * `'\x21'` : TCP over IPv6
-    * `'\x22'` : UDP over IPv6
-    * `'\x31'` : UNIX stream
-    * `'\x32'` : UNIX datagram
-  * v1
-    * `AF_INET`
-    * `AF_INET6`
-* `pp_info_t *pp_info` : Pointer to a filled `pp_info_t` structure. Note that at the moment tlvs from the `tlv_array_t tlv_array` inside it will not be included in the header. This functionality will be added with the next release.
-* `uint32_t *pp_hdr_len`: Output parameter where the length of the the PROXY protocol header will be stored.
-* `uint32_t *error`: Outpur parameter where its value will be set to a negative integer in case of error or `ERR_NULL` in case of success. You can use `pp_strerror()` to get a descriptive error message
-* `return value: uint8_t *`: Pointer to a dynamically allocated buffer where the PROXY protocol header exists. Shall be freed with `free()`
+**`uint8_t *pp_create_hdr(uint8_t version, const pp_info_t *pp_info, uint16_t *pp_hdr_len, int32_t *error)`**:
+
+Creates a PROXY protocol header considering the information inside the pp_info.
+* `version`:
+   * 0 Create a v1 PROXY protocol header.
+   * 1 Create a v2 PROXY protocol header.
+* `pp_info`:    Pointer to a filled `pp_info_t` structure whose information will be used for the creation of the PROXY protocol header.
+* `pp_hdr_len`: Pointer to a `uint16_t` where the length of the create PROXY protocol header will be set
+* `error`:      Pointer to a `int32_t` where the error value will be set
+   * `ERR_NULL` No error occurred
+   * < 0        Error
+* `return`: Pointer to a heap allocated buffer containing the PROXY protocol header. Must be freed with free()
+
+### Error reporting
+**`const char *pp_strerror(int32_t error)`**
+
+Returns a descriptive error message
+* `error`:  `int32_t` value from other API functions
+* `return`: Pointer to the descriptive message if the error value is recognized else `NULL`
 
 ## Example
 See `examples/client_server.c`
 
 ## In progress
-* Creating v2 PROXY protocol headers with TLVs is not yet supported. Will be added in the next release
+* Creating v2 PROXY protocol headers with TLVs is not yet supported. Will be added in the next major release

src/proxy_protocol.c

@@ -392,7 +392,7 @@ void pp_info_clear(pp_info_t *pp_info)
     memset(pp_info, 0, sizeof(*pp_info));
 }
 
-uint8_t *pp2_create_hdr(const pp_info_t *pp_info, uint16_t *pp2_hdr_len, uint32_t *error)
+uint8_t *pp2_create_hdr(const pp_info_t *pp_info, uint16_t *pp2_hdr_len, int32_t *error)
 {
     proxy_hdr_v2_t proxy_hdr_v2 = {
         .sig = "\x0D\x0A\x0D\x0A\x00\x0D\x0A\x51\x55\x49\x54\x0A",
@@ -479,7 +479,7 @@ uint8_t *pp2_create_hdr(const pp_info_t *pp_info, uint16_t *pp2_hdr_len, uint32_
     return pp2_hdr;
 }
 
-static uint8_t *pp1_create_hdr(const pp_info_t *pp_info, uint16_t *pp1_hdr_len, uint32_t *error)
+static uint8_t *pp1_create_hdr(const pp_info_t *pp_info, uint16_t *pp1_hdr_len, int32_t *error)
 {
     if (pp_info->transport_protocol != TRANSPORT_PROTOCOL_STREAM)
     {
@@ -530,7 +530,7 @@ static uint8_t *pp1_create_hdr(const pp_info_t *pp_info, uint16_t *pp1_hdr_len,
     return pp1_hdr;
 }
 
-uint8_t *pp_create_hdr(uint8_t version, const pp_info_t *pp_info, uint16_t *pp_hdr_len, uint32_t *error)
+uint8_t *pp_create_hdr(uint8_t version, const pp_info_t *pp_info, uint16_t *pp_hdr_len, int32_t *error)
 {
     if (version == 1)
     {

src/proxy_protocol.h

@@ -97,17 +97,17 @@ typedef struct
     tlv_array_t *tlv_array;
 } pp_info_t;
 
-/* Returns a descriptive error message.
+/* Returns a descriptive error message
  *
- * error    int32_t value from other API functions.
- * return   Pointer to the descriptive message if error value is recognized else NULL.
+ * error    int32_t value from other API functions
+ * return   Pointer to the descriptive message if the error value is recognized else NULL
  */
 const char *pp_strerror(int32_t error);
 
-/* Searches for the specified TLV and returns its value.
+/* Searches for the specified TLV and returns its value
  *
- * pp_info  Pointer to a pp_info_t structure used in pp_parse().
- * length   Pointer to a uint16_t where the TLV's value length will be set.
+ * pp_info  Pointer to a pp_info_t structure used in pp_parse()
+ * length   Pointer to a uint16_t where the TLV's value length will be set
  * return   Pointer to a buffer holding the TLV's value if found else NULL.
  *          In case of US-ASCII value the buffer is NULL terminated
  */
@@ -123,28 +123,34 @@ const uint8_t *pp_info_get_ssl_key_alg(const pp_info_t *pp_info, uint16_t *lengt
 const uint8_t *pp_info_get_ssl_netns(const pp_info_t *pp_info, uint16_t *length);
 const uint8_t *pp_info_get_aws_vpce_id(const pp_info_t *pp_info, uint16_t *length);
 const uint8_t *pp_info_get_azure_linkid(const pp_info_t *pp_info, uint16_t *length);
-void           pp_info_clear(pp_info_t *pp_info);
 
-/* Inpects the buffer for a PROXY protocol header and extracts all the information if any.
+/* Clears the pp_info_t structure and frees any allocated memory associated with it. Shall always be called after a call to pp_parse_hdr()
+ *
+ * pp_info  Pointer to a filled pp_info_t structure which has been used to a previous call to pp_parse_hdr()
+ */
+void pp_info_clear(pp_info_t *pp_info);
+
+/* Creates a PROXY protocol header considering the information inside the pp_info.
  *
  * version:     0 Create a v1 PROXY protocol header
  *              1 Create a v2 PROXY protocol header
- * pp_info      Pointer to a filled pp_info_t structure whose information will be used for the creation of the PROXY protocol header.
- * pp_hdr_len   Pointer to a uint16_t where the length of the create PROXY protocol header will be set.
- * error        Pointer to a uint32_t where the error value will be set.
+ * pp_info      Pointer to a filled pp_info_t structure whose information will be used for the creation of the PROXY protocol header
+ * pp_hdr_len   Pointer to a uint16_t where the length of the create PROXY protocol header will be set
+ * error        Pointer to a uint32_t where the error value will be set
  *                  ERR_NULL No error occurred
  *                  < 0      Error
+ * return       Pointer to a heap allocated buffer containing the PROXY protocol header. Must be freed with free()
  */
-uint8_t    *pp_create_hdr(uint8_t version, const pp_info_t *pp_info, uint16_t *pp_hdr_len, uint32_t *error);
+uint8_t *pp_create_hdr(uint8_t version, const pp_info_t *pp_info, uint16_t *pp_hdr_len, int32_t *error);
 
-/* Inpects the buffer for a PROXY protocol header and extracts all the information if any.
+/* Inpects the buffer for a PROXY protocol header and extracts all the information if any
  *
- * buffer   Buffer to be inspected and parsed. Typically the buffer given for a read operation
- * length   Buffer's length. Typically the bytes read from the read operation
- * pp_info  Pointer to a pp_info_t structure which will get filled with all the extracted information.
- * return   >  0 Length of the PROXY protocol header.
- *          == 0 No PROXY protocol header found.
- *          <  0 Error occurred. pp_strerror() with that value can be used to get a descriptive message
+ * buffer           Buffer to be inspected and parsed. Typically the buffer given for a read operation
+ * buffer_length    Buffer's length. Typically the bytes read from the read operation
+ * pp_info          Pointer to a pp_info_t structure which will get filled with all the extracted information
+ * return           >  0 Length of the PROXY protocol header
+ *                  == 0 No PROXY protocol header found
+ *                  <  0 Error occurred. pp_strerror() with that value can be used to get a descriptive message
  */
 int32_t pp_parse_hdr(uint8_t *buffer, uint32_t buffer_length, pp_info_t *pp_info);
 

tests/test.c

@@ -406,7 +406,7 @@ int main()
         else
         {
             uint16_t pp_hdr_len;
-            uint32_t error;
+            int32_t error;
             uint8_t *pp_hdr = pp_create_hdr(tests[i].version, &tests[i].pp_info_in, &pp_hdr_len, &error);
             if (!pp_hdr || error != ERR_NULL)
             {