You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+6-7Lines changed: 6 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,32 +6,32 @@ An ANSI C library to parse and create [PROXY protocol](https://www.haproxy.org/d
6
6
* Compilable with most compilers and usable at any platform as it is written in ANSI C.
7
7
8
8
## Installation
9
-
The library should be compilable to any platform as it is written in ANSI C. It comes with a Makefile which can create the shared library `libproxyprotocol.so` which can then be linked to your application. Special care has been taken to make it work with Windows as well. In that case you have to compile it to a DLL yourself. In case of windows remember that you have to link with the `ws2_32.lib`. An example of this is shown in tests.
9
+
The library should be compilable to any platform as it is written in ANSI C. It comes with a Makefile which can create the shared library `libproxyprotocol.so` which can then be linked to your application. Special care has been taken to make it work with Windows as well. In that case you have to compile it to a .dll/.lib yourself. In case of Windows remember that you have to link with the `ws2_32.lib`. An example of this is shown in tests.
10
10
11
11
## API
12
12
### Parsing
13
-
To parse a PROXY protocol header you need to use `pp_parse()` with the following parameters:
13
+
**`pp_parse()`**: parsing a PROXY protocol header. Parameters:
14
14
*`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.
15
15
*`uint32_t pktlen`: Data's length. Normally it will be the return value of a `recv(MSG_PEEK)`.
16
16
*`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
17
17
*`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.
18
18
19
19
You shall not pass your `pp_info_t` variable to `pp_parse()` again without first clearing it with `pp_info_clear()` (see below)
20
20
21
-
To extract TLVs' values it is strongly suggested that you use `pp_info_get_tlv_value()` with the following parameters:
*`pp_info_t *pp_info`: The `pp_info_t` used in the `pp_parse()`
23
23
*`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.
24
24
*`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
25
25
*`uint16_t *value_len_out`: The length of the value so that applications can copy and use the value properly
26
-
*`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 thenthe 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.**
26
+
*`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.**
27
27
28
-
To clear a `pp_info_t` structure you**MUST** use `pp_info_clear()` with the following parameter:
28
+
**`pp_info_clear()`**: clearing a `pp_info_t` structure. You**MUST** use it. Parameter:
29
29
*`pp_info_t *pp_info`: A pointer to the `pp_info_t` used in `pp_parse()`
30
30
31
31
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.
32
32
33
33
### Creating
34
-
To create a PROXY protocol header you need to use `pp_create_hdr()` with the following parameters:
34
+
**`pp_create_hdr()`**: create a PROXY protocol header. Parameters:
35
35
*`uint8_t version`: `1` or `2` depending on the PROXY protocol version you want to use.
36
36
*`uint8_t fam`: Transport and address family. The values match exactly the specification:
37
37
* v2
@@ -54,5 +54,4 @@ To create a PROXY protocol header you need to use `pp_create_hdr()` with the fol
54
54
See `examples/client_server.c`
55
55
56
56
## In progress
57
-
* Parsing `PP2_TYPE_SSL` TLV of the v2 PROXY protocol header is not yet supported. TLVs of this type will not be saved in the `pp_info_t` structure. Will be added in the next release. Draft PR https://github.com/kosmas-valianos/libproxyprotocol/pull/5
58
57
* Creating v2 PROXY protocol headers with TLVs is not yet supported. Will be added in the next release
0 commit comments