Skip to content

Latest commit

 

History

History

proprot

README.md

ProProt - Proxy Protocol v2 implementation Java library

Overview:

ProProt is a library to parse and generate network connection headers based on the Proxy Protocol version 2 (PPv2): https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt. The library also supports Proxy Protocol v2 extensions with custom TLVs, such as that from VPC Endpoint Services: http://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#proxy-protocol.

Usage:

Example 1: Reading

InputStream in = ...
ProxyProtocol protocol = new ProxyProtocol();
Header header = protocol.read(in);

Example 2: Writing

ByteArrayOutputStream out = new ByteArrayOutputStream();
final Header header = new Header();
header.setCommand(Command.LOCAL);
header.setAddressFamily(AddressFamily.AF_UNSPEC);
header.setTransportProtocol(TransportProtocol.UNSPEC);

TlvRaw tlv = new TlvRaw();
tlv.setType(0xF0);
tlv.setValue(new byte[] {1, 2, 3, 4, 5, 6, 7, 8});
header.addTlv(tlv);
ProxyProtocol protocol = new ProxyProtocol();
protocol.write(header, out);

Example 3: Parsing input from AWS Network Load Balancer with TLV type 0xEA. See Compatibility_AwsNetworkLoadBalancerTest.

Unless explicitly specified all the values used throughout the library can not be null.

The library allows to extend the protocol with custom TLVs. You can use either the predefined types TlvRaw and TlvSubTypeRaw or define your own.

Installation

Prerequisites

  • Java 8

Install Package

Choose your installation method - Maven or Jar file.

via Maven

Add ProProt as a dependency on your pom.xml:

<dependency>
    <groupId>com.amazonaws.proprot</groupId>
    <artifactId>proprot</artifactId>
    <version>1.0</version>
</dependency>

via jar file

You can drop the jar file of the library: proprot-1.0.jar.

Dependencies

Addition considerations and best practices:

  1. ProProt validates the header data consistency and integrity against random changes.
  2. Neither Proxy Protocol nor ProProt's implementation provides header signature nor cryptographically strong integrity check. They assume that the Proxy Protocol header is generated by trusted sources and can not be maliciously tampered during transmission.
  3. If needed, users can extend the protocol with custom TLVs supporting stronger header validation.
  4. This library is only for Proxy Protocol version 2. It will not work with Proxy Protocol version 1.
  5. If the incoming address family is specified, then addresses must also be specified.
  6. If the incoming header command is LOCAL, we validate the address family with the provided addresses, and then discard them.
  7. Any security concerns or problems will be announced through this README.

License

ProProt is licensed under the Apache 2.0 License: https://www.apache.org/licenses/LICENSE-2.0 .