grasshopper

README

🦗 grasshopper

Grasshopper is a UDP packet forwarder that listens for incoming packets and forwards them to a configured destination. It optionally supports cryptography for both incoming and outgoing packets, using different keys and methods.

Architecture

Grasshopper functions as a chained relay system. Take a chained DNS query For example:

                      ┌────────────┐                 ┌───────────────┐                                 
                      │ ENCRYPTED  │                 │ RE-ENCRYPTION │                                 
                      └──────┬─────┘                 │ AES ───► 3DES │                                 
                             │                       └───┬───────────┘                                 
                             │                           │                                             
                  ┌─────────┐▼             ┌────────────┐│             ┌─────────┐                     
                <HOP0>   HOPS(AES)         │  DECRYPTED │▼          <HOP5>      HOPS(FINAL)            
┌─────────┐       └       ┌────┐           └  DATA   HOPS(3DES)        │       ┌─┴──┐ ┌────────────┐
│ dig xxx ├─► CLEAR TEXT  │HOP1┼── CIPHER ──► PACKET  ┌─┴──┐           └ DNS   │Hop6├─► 8.8.8.8:53 │
│ @hop0   │       ┌       │Hop2│   (AES)   ┌          │Hop4├─ CIPHER ──► QUERY │Hop7│ └────────────┘
└─────────┘       │  ▲    │HOP3│         <HOP2>  ▲    │Hop5│  (3DES)   ┌       └─┬──┘                  
                  │  │    └────┘           │     │    └─┬──┘           │         │                     
                  └──┼──────┘              └─────┼──────┘              └─────────┘                     
                     │                           │                                                     
                  ┌──┼────────┐                  │                                                     
                  │           │                  │                                                     
                  │ OPTIONAL  ├──────────────────┘                                                     
                  │ PACKET    │                                                                        
                  │ PROCESSOR │                                                                        
                  │           │                                                                        
                  └───────────┘                                                                        

Installation

Install the latest version of Grasshopper using the following command:

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

Parameters

Grasshopper supports the following parameters:

Grasshopper is a UDP packet forwarder that listens for incoming packets and forwards them to a configured destination. It optionally supports cryptography for both incoming and outgoing packets, using different keys and methods.  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          Cryptography method for incoming data. Available options: aes, aes-128, aes-192, qpp, salsa20, blowfish, twofish, cast5, 3des, tea, xtea, sm4, none (default "qpp")
      --co string          Cryptography method for incoming data. Available options: aes, aes-128, aes-192, qpp, salsa20, blowfish, twofish, cast5, 3des, tea, xtea, sm4, none (default "qpp")
  -c, --config string      config file name
  -h, --help               help for grasshopper
      --ki string          Secret key to encrypt and decrypt for the last hop(client-side) (default "it's a secret")
      --ko string          Secret key to encrypt and decrypt for the next hops (default "it's a secret")
  -l, --listen string      Listener address, eg: "IP:1234" (default ":1234")
  -n, --nexthops strings   Servers to randomly forward to (default [127.0.0.1:3000])
      --sockbuf int        Socket buffer size for the listener (default 1048576)
      --timeout duration   Idle timeout duration for a UDP connection (default 1m0s)
  -t, --toggle             Help message for toggle
  -v, --version            version for grasshopper

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

Cryptography Support

• SM4(国密)
• AES(Advanced Encryption Standard), 128,192,256 bit
• QPP(Quantum Permutation Pad)
• Salsa20(https://en.wikipedia.org/wiki/Salsa20)
• Blowfish(https://en.wikipedia.org/wiki/Blowfish_(cipher))
• Twofish(https://en.wikipedia.org/wiki/Twofish)
• Cast5(https://en.wikipedia.org/wiki/CAST-128)
• 3DES(https://en.wikipedia.org/wiki/Triple_DES)
• Tea(Tiny Encryption Algorithm)
• XTea(https://en.wikipedia.org/wiki/XTEA)

Cases-Ⅰ Secure Echo

Step 1: Start a UDP Echo Server

Use ncat to start a UDP echo server on port 5000:

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

Step 2: Start a Level-2 Relayer to the Echo Server

Run the following command to start a relayer:

./grasshopper start --ci aes --co none -l "127.0.0.1:4001" -n "127.0.0.1:5000"

• --ci aes: Applies cryptography on incoming packets.
• --co none: Transfers plaintext to the ncat echo server.

Step 3: Start a Level-1 Relayer to the Level-2 Relayer

Run the following command to start another relayer:

./grasshopper start --ci none --co aes -l "127.0.0.1:4000" -n "127.0.0.1:4001"

• --ci none: No cryptography is applied to incoming packets.
• --co aes: Encrypts and relays packets to the next hop.

Step 4: Start a Demo Client

Use ncat to send UDP packets and interact with the relayer chain:

ncat -u 127.0.0.1 2132

Case-Ⅱ Secure DNS query(random selection)

┌──────────── YOUR─LAPTOP ──────────────┐           ┌────────── CLOUD─SERVER ───────────┐
│                                       │           │                                   │
│                                       │           │                                   │
│ ┌───────────────────┐   ┌──────────┐  │           │ ┌──────────┐   ┌───────────────┐  │
│ │                   │   │          │  │           │ │          │   │               │  │
│ │ dig google.com    ├───► Level-1  │  │           │ │ Level-2  ├───► Google DNS:53 │  │
│ │ @127.0.0.1 -p 4000│   │ Relayer  ┼──┼ ENCRYPTED ┼─► Relayer  │   │ CloudFlare:53 │  │
│ │                   │   │          │  │    UDP    │ │          │   │               │  │
│ └───────────────────┘   └──────────┘  │           │ └──────────┘   └───────────────┘  │
│                                       │           │                                   │
│                                       │           │                                   │
└───────────────────────────────────────┘           └───────────────────────────────────┘

Step 1: Start a Level-2 Relayer to the Google DNS Server(On your Cloud Server🖥️)

./grasshopper start --ci aes --co none -l "CLOUD_PUBLIC_IP:4000" -n "8.8.8.8:53,1.1.1.1:53"

• --ci aes: Decrypts the packet from Level-1 Relayer.
• --co none: Transfers decrypted plaintext DNS query packet to Google DNS.

Step 2: Start a Level-1 Relayer to the Level-2 Relayer(On your Laptop💻)

./grasshopper start --ci none --co aes -l "127.0.0.1:4000" -n "CLOUD_PUBLIC_IP:4000"

• --ci none: Since dig command queries in plaintext, we do not need to decrypt the packet.
• --co aes: Decrypts and relays packets to Level-2 Relayer

Step 3: Query Level-1 Relayer with dig(On your Laptop💻)

dig google.com @127.0.0.1 -p 4000

Documentation

Index

• type BlockCrypt
  • func NewAESBlockCrypt(key []byte) (BlockCrypt, error)
  • func NewBlowfishBlockCrypt(key []byte) (BlockCrypt, error)
  • func NewCast5BlockCrypt(key []byte) (BlockCrypt, error)
  • func NewQPPCrypt(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 NewQPPCrypt

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

NewQPPCrypt https://link.springer.com/content/pdf/10.1140/epjqt/s40507-023-00164-3.pdf

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.