cherf - CHARGED PERFORATOR.

"Perforates" NAT tables for p2p communication using a signaling server.

Usage:

run signaling server:

  cherf server <port>

attach stdio to remote port

  cherf client attach <remote_port> <server_addr> <server_port> <remote_name>

advertise for connections on signaling server:

  cherf client advertise <server_addr> <server_port>

for usage with ProxyCommand (with ProxyUseFdpass yes):

  cherf client ssh <server_addr> <server_port> <remote_name>


File structure:

~/.cherf
  ├── cert          -- your PEM X059 certificate, signed by server if client
  ├── key           -- your PEM X509 associated private key
  ├── store         -- concatenated list of trusted CA certificates (PEM X509)
  └── <server>.sha1 -- raw SHA1 fingerprint of server

Protocol specification:

This tool is a TCP holepuncher, and is designed to work on all NAT types other
than symmetric NAT. There are two communication protocols utilized to acheive
this goal: the signaling protocol and the p2p protocol. Both are designed to
run overtop TCP with TLS. First, the signaling protocol:

The first byte transmitted in each packet specifies the type of the packet. The
types of packets are as follows:

ConnectRequest:

  + 0 -- + 1 -------------- 8 + 9 ------- X +
  | 0x00 | fingerprint length | fingerprint |
  + ---- + ------------------ + ----------- +

    A ConnectRequest is sent when a client would like to connect to a remote,
    specified by the given (SHA1) fingerprint.

ListenRequest:

  + 0 -- +
  | 0x01 |
  + ---- +

    A ListenRequest is sent by a (future) remote to advertise its availability
    for connections. The signaling server will generate its SHA1 fingerprint
    from the TLS key exchange.

ConnectData:

  + 0 -- + 1 -- + 2 -- + 3 ------- 6 + 7 ------- 10 +
  | 0x02 | 0x04 | 0x00 | port nunber | IPv4 address |
  + ---- + ---- + ---- + ----------- + ------------ +
                          OR
  + 0 -- + 1 -- + 2 -- + 3 ------- 6 + 7 ------- 22 +
  | 0x02 | 0x06 | 0x00 | port number | IPv6 address |
  + ---- + ---- + ---- + ----------- + ------------ +

    ConnectData is sent from the signaling server to the two clients that will
    be connected to each other. ConnectData of the first type (type 4) is sent
    when the corresponding client has an IPv4 address, while ConnectData of the
    second type (type 6) is sent when the corresponding clinet has an IPv6
    address. The 3rd byte is currently unused, and will always be zero.

Error:

  + 0 -- + 1 -------- +
  | 0xFF | error code |
  + ---- + ---------- +

    An Error message is sent whenever an error occurs. The corresponding codes
    are:
      * NoSuchFingerprint -- Sent when a client requests the SHA1 fingerprint
        that is not matched in the signaling server's database
      * InvalidCert -- Sent when a client sends a malformed certificate.

The p2p protocol is much simpler: once a TCP connection is establised, the
client's first byte sent specifies the port to connect to. Then bidirectional
communication is established on said port.

Advanced features:

The advertising client uses the splice(2) facility on Linux, and the SO_SPLICE
socket option on FreeBSD to perform zerocopy socket splicing.