grasshopper

README

🦗 grasshopper

The grasshopper will listen for incoming UDP packets and forward them to the configured destination. Optionally, the listener can be configured to apply cryptogrraphy on both the incoming and outgoing packets, with different keys and methods.

Architecture

The grasshopper acts like a chained-relayer, for example

gh = grasshopper
client --------------> relayer1(gh) --------------> relayer2(gh) -----------------> relayer3(gh) --------------------> destination.
        plaintext                     encrypted                    re-encrypted                        decrypted

Install

go install  github.com/xtaci/grasshopper/cmd/grasshopper@latest     

Parameters

The grasshopper will listen for incoming UDP packets and forward them to the configured destination.
Optionally, the listener can be configured to apply cryptogrraphy on both the incoming and outgoing packets, with different keys and methods.

Usage:
  grasshopper [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  start       Start a listener for UDP packet forwarding

Flags:
      --ci string          The crytpgraphy method for incoming data, available: aes, aes-128, aes-192, salsa20, blowfish, twofish, cast5, 3des, tea, xtea, sm4, none (default "3des")
      --co string          The crytpgraphy method for outgoing data, available: aes, aes-128, aes-192, salsa20, blowfish, twofish, cast5, 3des, tea, xtea, sm4, none (default "3des")
  -h, --help               help for grasshopper
      --ki string          The secret to encrypt and decrypt for the last hop(incoming) (default "it's a secret")
      --ko string          The secret to encrypt and decrypt for the next hop(outgoing) (default "it's a secret")
  -l, --listen string      listener address, eg: "IP:1234" (default ":1234")
  -n, --nexthops strings   the servers to randomly forward to (default [127.0.0.1:3000])
      --sockbuf int        socket buffer for listener (default 1048576)
      --timeout duration   set how long an UDP connection can live when in idle(in seconds) (default 10m0s)
  -t, --toggle             Help message for toggle

Use "grasshopper [command] --help" for more information about a command.

Example Usage

Step 1: start an UDP echo server with ncat with port 5000

ncat -e /bin/cat -k -u -l 5000

Step 2: Start the Level-2 relayer to ncat echo

./grasshopper start --ci aes --co none -l "127.0.0.1:4001" -n "127.0.0.1:5000"
--ci aes means we apply cryptography on incoming packets
--co none means we transfer cleartext to ncat echo server

Step 3: Start the Level-1 relayer to Level-2 relayer, meanwhile encrypt the packet

./grasshopper start --ci none --co aes -l "127.0.0.1:4000" -n "127.0.0.1:4001"
--ci none means we don't apply cryptography on incoming packets
--co aes means we encrypt and relay the encrypted packets to next hop

Step 4: Start a demo client, try to type in something.

ncat -u 127.0.0.1 2132

Documentation

Index

• type BlockCrypt
  • func NewAESBlockCrypt(key []byte) (BlockCrypt, error)
  • func NewBlowfishBlockCrypt(key []byte) (BlockCrypt, error)
  • func NewCast5BlockCrypt(key []byte) (BlockCrypt, error)
  • func NewSM4BlockCrypt(key []byte) (BlockCrypt, error)
  • func NewSalsa20BlockCrypt(key []byte) (BlockCrypt, error)
  • func NewTEABlockCrypt(key []byte) (BlockCrypt, error)
  • func NewTripleDESBlockCrypt(key []byte) (BlockCrypt, error)
  • func NewTwofishBlockCrypt(key []byte) (BlockCrypt, error)
  • func NewXTEABlockCrypt(key []byte) (BlockCrypt, error)
• type Listener
  • func ListenWithOptions(laddr string, nexthops []string, sockbuf int, timeout time.Duration, ...) (*Listener, error)
  • func (l *Listener) Close() error
  • func (l *Listener) Start()
• type OnClientInCallback
• type OnNextHopInCallback

Types

type BlockCrypt

type BlockCrypt interface {
	// Encrypt encrypts the whole block in src into dst.
	// Dst and src may point at the same memory.
	Encrypt(dst, src []byte)

	// Decrypt decrypts the whole block in src into dst.
	// Dst and src may point at the same memory.
	Decrypt(dst, src []byte)
}

BlockCrypt defines encryption/decryption methods for a given byte slice. Notes on implementing: the data to be encrypted contains a builtin nonce at the first 16 bytes

func NewAESBlockCrypt

func NewAESBlockCrypt(key []byte) (BlockCrypt, error)

NewAESBlockCrypt https://en.wikipedia.org/wiki/Advanced_Encryption_Standard

func NewBlowfishBlockCrypt

func NewBlowfishBlockCrypt(key []byte) (BlockCrypt, error)

NewBlowfishBlockCrypt https://en.wikipedia.org/wiki/Blowfish_(cipher)

func NewCast5BlockCrypt

func NewCast5BlockCrypt(key []byte) (BlockCrypt, error)

NewCast5BlockCrypt https://en.wikipedia.org/wiki/CAST-128

func NewSM4BlockCrypt

func NewSM4BlockCrypt(key []byte) (BlockCrypt, error)

NewSM4BlockCrypt https://github.com/tjfoc/gmsm/tree/master/sm4

func NewSalsa20BlockCrypt

func NewSalsa20BlockCrypt(key []byte) (BlockCrypt, error)

NewSalsa20BlockCrypt https://en.wikipedia.org/wiki/Salsa20

func NewTEABlockCrypt

func NewTEABlockCrypt(key []byte) (BlockCrypt, error)

NewTEABlockCrypt https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm

func NewTripleDESBlockCrypt

func NewTripleDESBlockCrypt(key []byte) (BlockCrypt, error)

NewTripleDESBlockCrypt https://en.wikipedia.org/wiki/Triple_DES

func NewTwofishBlockCrypt

func NewTwofishBlockCrypt(key []byte) (BlockCrypt, error)

NewTwofishBlockCrypt https://en.wikipedia.org/wiki/Twofish

func NewXTEABlockCrypt

func NewXTEABlockCrypt(key []byte) (BlockCrypt, error)

NewXTEABlockCrypt https://en.wikipedia.org/wiki/XTEA

type Listener

type Listener struct {
	// contains filtered or unexported fields
}

Listener represents a UDP server that listens for incoming connections and relays them to the next hop.

func ListenWithOptions

func ListenWithOptions(laddr string,
	nexthops []string,
	sockbuf int,
	timeout time.Duration,
	crypterIn BlockCrypt, crypterOut BlockCrypt,
	onClientIn OnClientInCallback,
	onNextHopIn OnNextHopInCallback,
	logger *log.Logger) (*Listener, error)

ListenWithOptions initializes a new Listener with the provided options. Parameters: - laddr: Address to listen on. - nexthop: Addresses to forward packets to. - sockbuf: Socket buffer size in bytes. - timeout: Session timeout duration. - crypterIn: Cryptographic handler for decrypting incoming packets. - crypterOut: Cryptographic handler for encrypting outgoing packets. - pre: Prerouting function for processing incoming packets. - post: Postrouting function before forwarding packets to the next hop. - logger: Logger instance for logging.

func (*Listener) Close

func (l *Listener) Close() error

Close terminates the listener, releasing resources.

func (*Listener) Start

func (l *Listener) Start()

Start begins the listener loop, handling incoming packets and forwarding them. It blocks until the listener is closed or encounters an error.

type OnClientInCallback

type OnClientInCallback func(client net.Addr, in []byte) (out []byte)

OnClientInCallback is a callback function that processes incoming packets from clients

type OnNextHopInCallback

type OnNextHopInCallback func(hop net.Addr, client net.Addr, in []byte) (out []byte)

OnNextHopInCallback is a callback function that processes incoming packets from the next hop.