kcp

README

Introduction

kcp-go is a Reliable-UDP library for golang.

This library is designed to provide smooth, resilient, ordered, error-checked and anonymous delivery of streams over UDP packets. It has been battle-tested with the open-source project kcptun. Millions of devices, ranging from low-end MIPS routers to high-end servers, have deployed kcp-go-powered programs in various applications, including online games, live broadcasting, file synchronization, and network acceleration.

Lastest Release

Features

1. Designed for latency-sensitive scenarios.
2. Cache-friendly and memory-optimized design, offering extremely high performance core.
3. Handles >5K concurrent connections on a single commodity server.
4. Compatible with net.Conn and net.Listener, serving as a drop-in replacement for net.TCPConn.
5. FEC (Forward Error Correction) support with Reed-Solomon Codes.
6. Packet-level encryption support with AES, TEA, 3DES, Blowfish, Cast5, Salsa20, etc., in CFB mode, generating completely anonymous packets.
7. Only a fixed number of goroutines are created for the entire server application, with costs in context switching between goroutines taken into consideration.
8. Compatible with skywind3000's C version with various improvements.
9. Platform-dependent optimizations: sendmmsg and recvmmsg exploited for Linux.

Documentation

For complete documentation, see the associated Godoc.

Specification

NONCE:
  16bytes cryptographically secure random number, nonce changes for every packet.
  
CRC32:
  CRC-32 checksum of data using the IEEE polynomial
 
FEC TYPE:
  typeData = 0xF1
  typeParity = 0xF2
  
FEC SEQID:
  monotonically increasing in range: [0, (0xffffffff/shardSize) * shardSize - 1]
  
SIZE:
  The size of KCP frame plus 2

KCP Header
+------------------+
| conv      uint32 |
+------------------+
| cmd       uint8  |
+------------------+
| frg       uint8  |
+------------------+
| wnd      uint16  |
+------------------+
| ts       uint32  |
+------------------+
| sn       uint32  |
+------------------+
| una      uint32  |
+------------------+
| rto      uint32  |
+------------------+
| xmit     uint32  |
+------------------+
| resendts uint32  |
+------------------+
| fastack  uint32  |
+------------------+
| acked    uint32  |
+------------------+
| data     []byte  |
+------------------+

Layer-Model of KCP-GO

+-----------------+
| SESSION         |
+-----------------+
| KCP(ARQ)        |
+-----------------+
| FEC(OPTIONAL)   |
+-----------------+
| CRYPTO(OPTIONAL)|
+-----------------+
| UDP(PACKET)     |
+-----------------+
| IP              |
+-----------------+
| LINK            |
+-----------------+
| PHY             |
+-----------------+

Looing for a C++ client?

1. https://github.com/xtaci/libkcp -- FEC enhanced KCP session library for iOS/Android in C++

Examples

1. simple examples
2. kcptun client
3. kcptun server

Benchmark

===
Model Name:	MacBook Pro
Model Identifier:	MacBookPro14,1
Processor Name:	Intel Core i5
Processor Speed:	3.1 GHz
Number of Processors:	1
Total Number of Cores:	2
L2 Cache (per Core):	256 KB
L3 Cache:	4 MB
Memory:	8 GB
===

$ go test -v -run=^$ -bench .
beginning tests, encryption:salsa20, fec:10/3
goos: darwin
goarch: amd64
pkg: github.com/xtaci/kcp-go
BenchmarkSM4-4                 	   50000	     32180 ns/op	  93.23 MB/s	       0 B/op	       0 allocs/op
BenchmarkAES128-4              	  500000	      3285 ns/op	 913.21 MB/s	       0 B/op	       0 allocs/op
BenchmarkAES192-4              	  300000	      3623 ns/op	 827.85 MB/s	       0 B/op	       0 allocs/op
BenchmarkAES256-4              	  300000	      3874 ns/op	 774.20 MB/s	       0 B/op	       0 allocs/op
BenchmarkTEA-4                 	  100000	     15384 ns/op	 195.00 MB/s	       0 B/op	       0 allocs/op
BenchmarkXOR-4                 	20000000	        89.9 ns/op	33372.00 MB/s	       0 B/op	       0 allocs/op
BenchmarkBlowfish-4            	   50000	     26927 ns/op	 111.41 MB/s	       0 B/op	       0 allocs/op
BenchmarkNone-4                	30000000	        45.7 ns/op	65597.94 MB/s	       0 B/op	       0 allocs/op
BenchmarkCast5-4               	   50000	     34258 ns/op	  87.57 MB/s	       0 B/op	       0 allocs/op
Benchmark3DES-4                	   10000	    117149 ns/op	  25.61 MB/s	       0 B/op	       0 allocs/op
BenchmarkTwofish-4             	   50000	     33538 ns/op	  89.45 MB/s	       0 B/op	       0 allocs/op
BenchmarkXTEA-4                	   30000	     45666 ns/op	  65.69 MB/s	       0 B/op	       0 allocs/op
BenchmarkSalsa20-4             	  500000	      3308 ns/op	 906.76 MB/s	       0 B/op	       0 allocs/op
BenchmarkCRC32-4               	20000000	        65.2 ns/op	15712.43 MB/s
BenchmarkCsprngSystem-4        	 1000000	      1150 ns/op	  13.91 MB/s
BenchmarkCsprngMD5-4           	10000000	       145 ns/op	 110.26 MB/s
BenchmarkCsprngSHA1-4          	10000000	       158 ns/op	 126.54 MB/s
BenchmarkCsprngNonceMD5-4      	10000000	       153 ns/op	 104.22 MB/s
BenchmarkCsprngNonceAES128-4   	100000000	        19.1 ns/op	 837.81 MB/s
BenchmarkFECDecode-4           	 1000000	      1119 ns/op	1339.61 MB/s	    1606 B/op	       2 allocs/op
BenchmarkFECEncode-4           	 2000000	       832 ns/op	1801.83 MB/s	      17 B/op	       0 allocs/op
BenchmarkFlush-4               	 5000000	       272 ns/op	       0 B/op	       0 allocs/op
BenchmarkEchoSpeed4K-4         	    5000	    259617 ns/op	  15.78 MB/s	    5451 B/op	     149 allocs/op
BenchmarkEchoSpeed64K-4        	    1000	   1706084 ns/op	  38.41 MB/s	   56002 B/op	    1604 allocs/op
BenchmarkEchoSpeed512K-4       	     100	  14345505 ns/op	  36.55 MB/s	  482597 B/op	   13045 allocs/op
BenchmarkEchoSpeed1M-4         	      30	  34859104 ns/op	  30.08 MB/s	 1143773 B/op	   27186 allocs/op
BenchmarkSinkSpeed4K-4         	   50000	     31369 ns/op	 130.57 MB/s	    1566 B/op	      30 allocs/op
BenchmarkSinkSpeed64K-4        	    5000	    329065 ns/op	 199.16 MB/s	   21529 B/op	     453 allocs/op
BenchmarkSinkSpeed256K-4       	     500	   2373354 ns/op	 220.91 MB/s	  166332 B/op	    3554 allocs/op
BenchmarkSinkSpeed1M-4         	     300	   5117927 ns/op	 204.88 MB/s	  310378 B/op	    6988 allocs/op
PASS
ok  	github.com/xtaci/kcp-go	50.349s

=== Raspberry Pi 4 ===

➜  kcp-go git:(master) cat /proc/cpuinfo
processor	: 0
model name	: ARMv7 Processor rev 3 (v7l)
BogoMIPS	: 108.00
Features	: half thumb fastmult vfp edsp neon vfpv3 tls vfpv4 idiva idivt vfpd32 lpae evtstrm crc32
CPU implementer	: 0x41
CPU architecture: 7
CPU variant	: 0x0
CPU part	: 0xd08
CPU revision	: 3

➜  kcp-go git:(master)  go test -run=^$ -bench .
2020/01/05 19:25:13 beginning tests, encryption:salsa20, fec:10/3
goos: linux
goarch: arm
pkg: github.com/xtaci/kcp-go/v5
BenchmarkSM4-4                     20000             86475 ns/op          34.69 MB/s           0 B/op          0 allocs/op
BenchmarkAES128-4                  20000             62254 ns/op          48.19 MB/s           0 B/op          0 allocs/op
BenchmarkAES192-4                  20000             71802 ns/op          41.78 MB/s           0 B/op          0 allocs/op
BenchmarkAES256-4                  20000             80570 ns/op          37.23 MB/s           0 B/op          0 allocs/op
BenchmarkTEA-4                     50000             37343 ns/op          80.34 MB/s           0 B/op          0 allocs/op
BenchmarkXOR-4                    100000             22266 ns/op         134.73 MB/s           0 B/op          0 allocs/op
BenchmarkBlowfish-4                20000             66123 ns/op          45.37 MB/s           0 B/op          0 allocs/op
BenchmarkNone-4                  3000000               518 ns/op        5786.77 MB/s           0 B/op          0 allocs/op
BenchmarkCast5-4                   20000             76705 ns/op          39.11 MB/s           0 B/op          0 allocs/op
Benchmark3DES-4                     5000            418868 ns/op           7.16 MB/s           0 B/op          0 allocs/op
BenchmarkTwofish-4                  5000            326896 ns/op           9.18 MB/s           0 B/op          0 allocs/op
BenchmarkXTEA-4                    10000            114418 ns/op          26.22 MB/s           0 B/op          0 allocs/op
BenchmarkSalsa20-4                 50000             36736 ns/op          81.66 MB/s           0 B/op          0 allocs/op
BenchmarkCRC32-4                 1000000              1735 ns/op         589.98 MB/s
BenchmarkCsprngSystem-4          1000000              2179 ns/op           7.34 MB/s
BenchmarkCsprngMD5-4             2000000               811 ns/op          19.71 MB/s
BenchmarkCsprngSHA1-4            2000000               862 ns/op          23.19 MB/s
BenchmarkCsprngNonceMD5-4        2000000               878 ns/op          18.22 MB/s
BenchmarkCsprngNonceAES128-4     5000000               326 ns/op          48.97 MB/s
BenchmarkFECDecode-4              200000              9081 ns/op         165.16 MB/s         140 B/op          1 allocs/op
BenchmarkFECEncode-4              100000             12039 ns/op         124.59 MB/s          11 B/op          0 allocs/op
BenchmarkFlush-4                  100000             21704 ns/op               0 B/op          0 allocs/op
BenchmarkEchoSpeed4K-4              2000            981182 ns/op           4.17 MB/s       12384 B/op        424 allocs/op
BenchmarkEchoSpeed64K-4              100          10503324 ns/op           6.24 MB/s      123616 B/op       3779 allocs/op
BenchmarkEchoSpeed512K-4              20         138633802 ns/op           3.78 MB/s     1606584 B/op      29233 allocs/op
BenchmarkEchoSpeed1M-4                 5         372903568 ns/op           2.81 MB/s     4080504 B/op      63600 allocs/op
BenchmarkSinkSpeed4K-4             10000            121239 ns/op          33.78 MB/s        4647 B/op        104 allocs/op
BenchmarkSinkSpeed64K-4             1000           1587906 ns/op          41.27 MB/s       50914 B/op       1115 allocs/op
BenchmarkSinkSpeed256K-4             100          16277830 ns/op          32.21 MB/s      453027 B/op       9296 allocs/op
BenchmarkSinkSpeed1M-4               100          31040703 ns/op          33.78 MB/s      898097 B/op      18932 allocs/op
PASS
ok      github.com/xtaci/kcp-go/v5      64.151s

Typical Flame Graph

Key Design Considerations

1. Slice vs. Container/List

kcp.flush() loops through the send queue for retransmission checking every 20 ms.

I wrote a benchmark comparing sequential loops through a slice and a container/list here:

BenchmarkLoopSlice-4   	2000000000	         0.39 ns/op
BenchmarkLoopList-4    	100000000	        54.6 ns/op

The list structure introduces heavy cache misses compared to the slice, which has better locality. For 5,000 connections with a 32-window size and a 20 ms interval, using a slice costs 6 μs (0.03% CPU) per kcp.flush(), while using a list costs 8.7 ms (43.5% CPU).

2. Timing Accuracy vs. Syscall clock_gettime

Timing is critical to the RTT estimator. Inaccurate timing leads to false retransmissions in KCP, but calling time.Now() costs 42 cycles (10.5 ns on a 4 GHz CPU, 15.6 ns on my MacBook Pro 2.7 GHz).

The benchmark for time.Now() is here:

BenchmarkNow-4         	100000000	        15.6 ns/op

In kcp-go, after each kcp.output() function call, the current clock time is updated upon return. For a single kcp.flush() operation, the current time is queried from the system once. For 5,000 connections, this costs 5000 * 15.6 ns = 78 μs (a fixed cost when no packet needs to be sent). For 10 MB/s data transfer with a 1400 MTU, kcp.output() is called around 7500 times, costing 117 μs for time.Now() every second.

3. Memory Management

Primary memory allocation is done from a global buffer pool, xmit.Buf. In kcp-go, when we need to allocate some bytes, we get them from that pool, which returns a fixed-capacity 1500 bytes (mtuLimit). The rx queue, tx queue, and fec queue all receive bytes from this pool and return them after use to prevent unnecessary zeroing of bytes. The pool mechanism maintains a high watermark for slice objects, allowing these in-flight objects to survive periodic garbage collection, while also being able to return memory to the runtime when idle.

4. Information Security

kcp-go is shipped with built-in packet encryption powered by various block encryption algorithms and works in Cipher Feedback Mode. For each packet to be sent, the encryption process starts by encrypting a nonce from the system entropy, ensuring that encryption of the same plaintext never results in the same ciphertext.

The contents of the packets are completely anonymous with encryption, including the headers (FEC, KCP), checksums, and contents. Note that no matter which encryption method you choose at the upper layer, if you disable encryption, the transmission will be insecure, as the header is plaintext and susceptible to tampering, such as jamming the sliding window size, round-trip time, FEC properties, and checksums. AES-128 is suggested for minimal encryption, as modern CPUs come with AES-NI instructions and perform better than salsa20 (check the table above).

Other possible attacks on kcp-go include:

• Traffic analysis: Data flow on specific websites may have patterns while exchanging data. This type of eavesdropping has been mitigated by adopting smux to mix data streams and introduce noise. A perfect solution has not yet appeared, but theoretically, shuffling/mixing messages on a larger scale network may mitigate this problem.
• Replay attack: Since asymmetrical encryption has not been introduced into kcp-go, capturing packets and replaying them on a different machine is possible. Note that hijacking the session and decrypting the contents is still impossible. Upper layers should use an asymmetrical encryption system to guarantee the authenticity of each message (to process each message exactly once), such as HTTPS/OpenSSL/LibreSSL. Signing requests with private keys can eliminate this type of attack.

Connection Termination

Control messages like SYN/FIN/RST in TCP are not defined in KCP. You need a keepalive/heartbeat mechanism at the application level. A real-world example is to use a multiplexing protocol over the session, such as smux (which has an embedded keepalive mechanism). See kcptun for an example.

FAQ

Q: I'm handling >5K connections on my server, and the CPU utilization is so high.

A: A standalone agent or gate server for running kcp-go is suggested, not only to reduce CPU utilization but also to improve the precision of RTT measurements (timing), which indirectly affects retransmission. Increasing the update interval with SetNoDelay, such as conn.SetNoDelay(1, 40, 1, 1), will dramatically reduce system load but may lower performance.

Q: When should I enable FEC?

A: Forward error correction is critical for long-distance transmission because packet loss incurs a huge time penalty. In the complex packet routing networks of the modern world, round-trip time-based loss checks are not always efficient. The significant deviation of RTT samples over long distances usually leads to a larger RTO value in typical RTT estimators, which slows down the transmission.

Q: Should I enable encryption?

A: Yes, for the security of the protocol, even if the upper layer has encryption.

Who is using this?

1. https://github.com/xtaci/kcptun -- A Secure Tunnel Based On KCP over UDP.
2. https://github.com/getlantern/lantern -- Lantern delivers fast access to the open Internet.
3. https://github.com/smallnest/rpcx -- A RPC service framework based on net/rpc like alibaba Dubbo and weibo Motan.
4. https://github.com/gonet2/agent -- A gateway for games with stream multiplexing.
5. https://github.com/syncthing/syncthing -- Open Source Continuous File Synchronization.

Links

1. https://github.com/xtaci/smux/ -- A Stream Multiplexing Library for golang with least memory
2. https://github.com/xtaci/libkcp -- FEC enhanced KCP session library for iOS/Android in C++
3. https://github.com/skywind3000/kcp -- A Fast and Reliable ARQ Protocol
4. https://github.com/klauspost/reedsolomon -- Reed-Solomon Erasure Coding in Go

Documentation

Overview

Package kcp-go is a Reliable-UDP library for golang.

This library intents to provide a smooth, resilient, ordered, error-checked and anonymous delivery of streams over UDP packets.

The interfaces of this package aims to be compatible with net.Conn in standard library, but offers powerful features for advanced users.

Index

• Constants
• func Dial(raddr string) (net.Conn, error)
• func Listen(laddr string) (net.Listener, error)
• type BlockCrypt
  • func NewAESBlockCrypt(key []byte) (BlockCrypt, error)
  • func NewBlowfishBlockCrypt(key []byte) (BlockCrypt, error)
  • func NewCast5BlockCrypt(key []byte) (BlockCrypt, error)
  • func NewNoneBlockCrypt(key []byte) (BlockCrypt, error)
  • func NewSM4BlockCrypt(key []byte) (BlockCrypt, error)
  • func NewSalsa20BlockCrypt(key []byte) (BlockCrypt, error)
  • func NewSimpleXORBlockCrypt(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 Entropy
• type KCP
  • func NewKCP(conv uint32, output output_callback) *KCP
  • func (kcp *KCP) Check() uint32
  • func (kcp *KCP) Input(data []byte, regular, ackNoDelay bool) int
  • func (kcp *KCP) NoDelay(nodelay, interval, resend, nc int) int
  • func (kcp *KCP) PeekSize() (length int)
  • func (kcp *KCP) Recv(buffer []byte) (n int)
  • func (kcp *KCP) ReleaseTX()
  • func (kcp *KCP) Send(buffer []byte) int
  • func (kcp *KCP) SetMtu(mtu int) int
  • func (kcp *KCP) Update()
  • func (kcp *KCP) WaitSnd() int
  • func (kcp *KCP) WndSize(sndwnd, rcvwnd int) int
• type Listener
  • func ListenWithOptions(laddr string, block BlockCrypt, dataShards, parityShards int) (*Listener, error)
  • func ServeConn(block BlockCrypt, dataShards, parityShards int, conn net.PacketConn) (*Listener, error)
  • func (l *Listener) Accept() (net.Conn, error)
  • func (l *Listener) AcceptKCP() (*UDPSession, error)
  • func (l *Listener) Addr() net.Addr
  • func (l *Listener) Close() error
  • func (l *Listener) Control(f func(conn net.PacketConn) error) error
  • func (l *Listener) SetDSCP(dscp int) error
  • func (l *Listener) SetDeadline(t time.Time) error
  • func (l *Listener) SetReadBuffer(bytes int) error
  • func (l *Listener) SetReadDeadline(t time.Time) error
  • func (l *Listener) SetWriteBuffer(bytes int) error
  • func (l *Listener) SetWriteDeadline(t time.Time) error
• type Snmp
  • func (s *Snmp) Copy() *Snmp
  • func (s *Snmp) Header() []string
  • func (s *Snmp) Reset()
  • func (s *Snmp) ToSlice() []string
• type TimedSched
  • func NewTimedSched(parallel int) *TimedSched
  • func (ts *TimedSched) Close()
  • func (ts *TimedSched) Put(f func(), deadline time.Time)
• type UDPSession
  • func DialWithOptions(raddr string, block BlockCrypt, dataShards, parityShards int) (*UDPSession, error)
  • func NewConn(raddr string, block BlockCrypt, dataShards, parityShards int, ...) (*UDPSession, error)
  • func NewConn2(raddr net.Addr, block BlockCrypt, dataShards, parityShards int, ...) (*UDPSession, error)
  • func NewConn3(convid uint32, raddr net.Addr, block BlockCrypt, dataShards, parityShards int, ...) (*UDPSession, error)
  • func NewConn4(convid uint32, raddr net.Addr, block BlockCrypt, dataShards, parityShards int, ...) (*UDPSession, error)
  • func (s *UDPSession) Close() error
  • func (s *UDPSession) Control(f func(conn net.PacketConn) error) error
  • func (s *UDPSession) GetConv() uint32
  • func (s *UDPSession) GetRTO() uint32
  • func (s *UDPSession) GetSRTT() int32
  • func (s *UDPSession) GetSRTTVar() int32
  • func (s *UDPSession) LocalAddr() net.Addr
  • func (s *UDPSession) Read(b []byte) (n int, err error)
  • func (s *UDPSession) RemoteAddr() net.Addr
  • func (s *UDPSession) SetACKNoDelay(nodelay bool)
  • func (s *UDPSession) SetDSCP(dscp int) error
  • func (s *UDPSession) SetDUP(dup int)
  • func (s *UDPSession) SetDeadline(t time.Time) error
  • func (s *UDPSession) SetMtu(mtu int) bool
  • func (s *UDPSession) SetNoDelay(nodelay, interval, resend, nc int)
  • func (s *UDPSession) SetReadBuffer(bytes int) error
  • func (s *UDPSession) SetReadDeadline(t time.Time) error
  • func (s *UDPSession) SetStreamMode(enable bool)
  • func (s *UDPSession) SetWindowSize(sndwnd, rcvwnd int)
  • func (s *UDPSession) SetWriteBuffer(bytes int) error
  • func (s *UDPSession) SetWriteDeadline(t time.Time) error
  • func (s *UDPSession) SetWriteDelay(delay bool)
  • func (s *UDPSession) Write(b []byte) (n int, err error)
  • func (s *UDPSession) WriteBuffers(v [][]byte) (n int, err error)

Constants

const (
	IKCP_RTO_NDL     = 30  // no delay min rto
	IKCP_RTO_MIN     = 100 // normal min rto
	IKCP_RTO_DEF     = 200
	IKCP_RTO_MAX     = 60000
	IKCP_CMD_PUSH    = 81 // cmd: push data
	IKCP_CMD_ACK     = 82 // cmd: ack
	IKCP_CMD_WASK    = 83 // cmd: window probe (ask)
	IKCP_CMD_WINS    = 84 // cmd: window size (tell)
	IKCP_ASK_SEND    = 1  // need to send IKCP_CMD_WASK
	IKCP_ASK_TELL    = 2  // need to send IKCP_CMD_WINS
	IKCP_WND_SND     = 32
	IKCP_WND_RCV     = 32
	IKCP_MTU_DEF     = 1400
	IKCP_ACK_FAST    = 3
	IKCP_INTERVAL    = 100
	IKCP_OVERHEAD    = 24
	IKCP_DEADLINK    = 20
	IKCP_THRESH_INIT = 2
	IKCP_THRESH_MIN  = 2
	IKCP_PROBE_INIT  = 7000   // 7 secs to probe window size
	IKCP_PROBE_LIMIT = 120000 // up to 120 secs to probe window
	IKCP_SN_OFFSET   = 12
)

Functions

func Dial

func Dial(raddr string) (net.Conn, error)

Dial connects to the remote address "raddr" on the network "udp" without encryption and FEC

func Listen

func Listen(laddr string) (net.Listener, error)

Listen listens for incoming KCP packets addressed to the local address laddr on the network "udp",

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 NewNoneBlockCrypt

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

NewNoneBlockCrypt does nothing but copying

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 NewSimpleXORBlockCrypt

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

NewSimpleXORBlockCrypt simple xor with key expanding

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 Entropy

type Entropy interface {
	Init()
	Fill(nonce []byte)
}

Entropy defines a entropy source

Entropy in this file generate random bits for the first 16-bytes of each packets.

type KCP

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

KCP defines a single KCP connection

func NewKCP

func NewKCP(conv uint32, output output_callback) *KCP

NewKCP create a new kcp state machine

'conv' must be equal in the connection peers, or else data will be silently rejected.

'output' function will be called whenever these is data to be sent on wire.

func (*KCP) Check

func (kcp *KCP) Check() uint32

(deprecated)

Check determines when should you invoke ikcp_update: returns when you should invoke ikcp_update in millisec, if there is no ikcp_input/_send calling. you can call ikcp_update in that time, instead of call update repeatly. Important to reduce unnacessary ikcp_update invoking. use it to schedule ikcp_update (eg. implementing an epoll-like mechanism, or optimize ikcp_update when handling massive kcp connections)

func (*KCP) Input

func (kcp *KCP) Input(data []byte, regular, ackNoDelay bool) int

Input a packet into kcp state machine.

'regular' indicates it's a real data packet from remote, and it means it's not generated from ReedSolomon codecs.

'ackNoDelay' will trigger immediate ACK, but surely it will not be efficient in bandwidth

func (*KCP) NoDelay

func (kcp *KCP) NoDelay(nodelay, interval, resend, nc int) int

NoDelay options fastest: ikcp_nodelay(kcp, 1, 20, 2, 1) nodelay: 0:disable(default), 1:enable interval: internal update timer interval in millisec, default is 100ms resend: 0:disable fast resend(default), 1:enable fast resend nc: 0:normal congestion control(default), 1:disable congestion control

func (*KCP) PeekSize

func (kcp *KCP) PeekSize() (length int)

PeekSize checks the size of next message in the recv queue

func (*KCP) Recv

func (kcp *KCP) Recv(buffer []byte) (n int)

Receive data from kcp state machine

Return number of bytes read.

Return -1 when there is no readable data.

Return -2 if len(buffer) is smaller than kcp.PeekSize().

func (*KCP) ReleaseTX

func (kcp *KCP) ReleaseTX()

Release all cached outgoing segments

func (*KCP) Send

func (kcp *KCP) Send(buffer []byte) int

Send is user/upper level send, returns below zero for error

func (*KCP) SetMtu

func (kcp *KCP) SetMtu(mtu int) int

SetMtu changes MTU size, default is 1400

func (*KCP) Update

func (kcp *KCP) Update()

(deprecated)

Update updates state (call it repeatedly, every 10ms-100ms), or you can ask ikcp_check when to call it again (without ikcp_input/_send calling). 'current' - current timestamp in millisec.

func (*KCP) WaitSnd

func (kcp *KCP) WaitSnd() int

WaitSnd gets how many packet is waiting to be sent

func (*KCP) WndSize

func (kcp *KCP) WndSize(sndwnd, rcvwnd int) int

WndSize sets maximum window size: sndwnd=32, rcvwnd=32 by default

type Listener

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

Listener defines a server which will be waiting to accept incoming connections

func ListenWithOptions

func ListenWithOptions(laddr string, block BlockCrypt, dataShards, parityShards int) (*Listener, error)

ListenWithOptions listens for incoming KCP packets addressed to the local address laddr on the network "udp" with packet encryption.

'block' is the block encryption algorithm to encrypt packets.

'dataShards', 'parityShards' specify how many parity packets will be generated following the data packets.

Check https://github.com/klauspost/reedsolomon for details

func ServeConn

func ServeConn(block BlockCrypt, dataShards, parityShards int, conn net.PacketConn) (*Listener, error)

ServeConn serves KCP protocol for a single packet connection.

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

Accept implements the Accept method in the Listener interface; it waits for the next call and returns a generic Conn.

func (*Listener) AcceptKCP

func (l *Listener) AcceptKCP() (*UDPSession, error)

AcceptKCP accepts a KCP connection

func (*Listener) Addr

func (l *Listener) Addr() net.Addr

Addr returns the listener's network address, The Addr returned is shared by all invocations of Addr, so do not modify it.

func (*Listener) Close

func (l *Listener) Close() error

Close stops listening on the UDP address, and closes the socket

func (*Listener) Control

func (l *Listener) Control(f func(conn net.PacketConn) error) error

Control applys a procedure to the underly socket fd. CAUTION: BE VERY CAREFUL TO USE THIS FUNCTION, YOU MAY BREAK THE PROTOCOL.

func (*Listener) SetDSCP

func (l *Listener) SetDSCP(dscp int) error

SetDSCP sets the 6bit DSCP field in IPv4 header, or 8bit Traffic Class in IPv6 header.

if the underlying connection has implemented `func SetDSCP(int) error`, SetDSCP() will invoke this function instead.

func (*Listener) SetDeadline

func (l *Listener) SetDeadline(t time.Time) error

SetDeadline sets the deadline associated with the listener. A zero time value disables the deadline.

func (*Listener) SetReadBuffer

func (l *Listener) SetReadBuffer(bytes int) error

SetReadBuffer sets the socket read buffer for the Listener

func (*Listener) SetReadDeadline

func (l *Listener) SetReadDeadline(t time.Time) error

SetReadDeadline implements the Conn SetReadDeadline method.

func (*Listener) SetWriteBuffer

func (l *Listener) SetWriteBuffer(bytes int) error

SetWriteBuffer sets the socket write buffer for the Listener

func (*Listener) SetWriteDeadline

func (l *Listener) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements the Conn SetWriteDeadline method.

type Snmp

type Snmp struct {
	BytesSent        uint64 // bytes sent from upper level
	BytesReceived    uint64 // bytes received to upper level
	MaxConn          uint64 // max number of connections ever reached
	ActiveOpens      uint64 // accumulated active open connections
	PassiveOpens     uint64 // accumulated passive open connections
	CurrEstab        uint64 // current number of established connections
	InErrs           uint64 // UDP read errors reported from net.PacketConn
	InCsumErrors     uint64 // checksum errors from CRC32
	KCPInErrors      uint64 // packet iput errors reported from KCP
	InPkts           uint64 // incoming packets count
	OutPkts          uint64 // outgoing packets count
	InSegs           uint64 // incoming KCP segments
	OutSegs          uint64 // outgoing KCP segments
	InBytes          uint64 // UDP bytes received
	OutBytes         uint64 // UDP bytes sent
	RetransSegs      uint64 // accmulated retransmited segments
	FastRetransSegs  uint64 // accmulated fast retransmitted segments
	EarlyRetransSegs uint64 // accmulated early retransmitted segments
	LostSegs         uint64 // number of segs inferred as lost
	RepeatSegs       uint64 // number of segs duplicated
	FECRecovered     uint64 // correct packets recovered from FEC
	FECErrs          uint64 // incorrect packets recovered from FEC
	FECParityShards  uint64 // FEC segments received
	FECShortShards   uint64 // number of data shards that's not enough for recovery
}

Snmp defines network statistics indicator

var DefaultSnmp *Snmp

DefaultSnmp is the global KCP connection statistics collector

func (*Snmp) Copy

func (s *Snmp) Copy() *Snmp

Copy make a copy of current snmp snapshot

func (*Snmp) Header

func (s *Snmp) Header() []string

Header returns all field names

func (*Snmp) Reset

func (s *Snmp) Reset()

Reset values to zero

func (*Snmp) ToSlice

func (s *Snmp) ToSlice() []string

ToSlice returns current snmp info as slice

type TimedSched

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

TimedSched represents the control struct for timed parallel scheduler

var SystemTimedSched *TimedSched = NewTimedSched(runtime.NumCPU())

SystemTimedSched is the library level timed-scheduler

func NewTimedSched

func NewTimedSched(parallel int) *TimedSched

NewTimedSched creates a parallel-scheduler with given parallelization

func (*TimedSched) Close

func (ts *TimedSched) Close()

Close terminates this scheduler

func (*TimedSched) Put

func (ts *TimedSched) Put(f func(), deadline time.Time)

Put a function 'f' awaiting to be executed at 'deadline'

type UDPSession

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

UDPSession defines a KCP session implemented by UDP

func DialWithOptions

func DialWithOptions(raddr string, block BlockCrypt, dataShards, parityShards int) (*UDPSession, error)

DialWithOptions connects to the remote address "raddr" on the network "udp" with packet encryption

'block' is the block encryption algorithm to encrypt packets.

'dataShards', 'parityShards' specify how many parity packets will be generated following the data packets.

Check https://github.com/klauspost/reedsolomon for details

func NewConn

func NewConn(raddr string, block BlockCrypt, dataShards, parityShards int, conn net.PacketConn) (*UDPSession, error)

NewConn establishes a session and talks KCP protocol over a packet connection.

func NewConn2

func NewConn2(raddr net.Addr, block BlockCrypt, dataShards, parityShards int, conn net.PacketConn) (*UDPSession, error)

NewConn2 establishes a session and talks KCP protocol over a packet connection.

func NewConn3

func NewConn3(convid uint32, raddr net.Addr, block BlockCrypt, dataShards, parityShards int, conn net.PacketConn) (*UDPSession, error)

NewConn3 establishes a session and talks KCP protocol over a packet connection.

func NewConn4

func NewConn4(convid uint32, raddr net.Addr, block BlockCrypt, dataShards, parityShards int, ownConn bool, conn net.PacketConn) (*UDPSession, error)

NewConn4 establishes a session and talks KCP protocol over a packet connection.

func (*UDPSession) Close

func (s *UDPSession) Close() error

Close closes the connection.

func (*UDPSession) Control

func (s *UDPSession) Control(f func(conn net.PacketConn) error) error

Control applys a procedure to the underly socket fd. CAUTION: BE VERY CAREFUL TO USE THIS FUNCTION, YOU MAY BREAK THE PROTOCOL.

func (*UDPSession) GetConv

func (s *UDPSession) GetConv() uint32

GetConv gets conversation id of a session

func (*UDPSession) GetRTO

func (s *UDPSession) GetRTO() uint32

GetRTO gets current rto of the session

func (*UDPSession) GetSRTT

func (s *UDPSession) GetSRTT() int32

GetSRTT gets current srtt of the session

func (*UDPSession) GetSRTTVar

func (s *UDPSession) GetSRTTVar() int32

GetRTTVar gets current rtt variance of the session

func (*UDPSession) LocalAddr

func (s *UDPSession) LocalAddr() net.Addr

LocalAddr returns the local network address. The Addr returned is shared by all invocations of LocalAddr, so do not modify it.

func (*UDPSession) Read

func (s *UDPSession) Read(b []byte) (n int, err error)

Read implements net.Conn

func (*UDPSession) RemoteAddr

func (s *UDPSession) RemoteAddr() net.Addr

RemoteAddr returns the remote network address. The Addr returned is shared by all invocations of RemoteAddr, so do not modify it.

func (*UDPSession) SetACKNoDelay

func (s *UDPSession) SetACKNoDelay(nodelay bool)

SetACKNoDelay changes ack flush option, set true to flush ack immediately,

func (*UDPSession) SetDSCP

func (s *UDPSession) SetDSCP(dscp int) error

SetDSCP sets the 6bit DSCP field in IPv4 header, or 8bit Traffic Class in IPv6 header.

if the underlying connection has implemented `func SetDSCP(int) error`, SetDSCP() will invoke this function instead.

It has no effect if it's accepted from Listener.

func (*UDPSession) SetDUP

func (s *UDPSession) SetDUP(dup int)

(deprecated)

SetDUP duplicates udp packets for kcp output.

func (*UDPSession) SetDeadline

func (s *UDPSession) SetDeadline(t time.Time) error

SetDeadline sets the deadline associated with the listener. A zero time value disables the deadline.

func (*UDPSession) SetMtu

func (s *UDPSession) SetMtu(mtu int) bool

SetMtu sets the maximum transmission unit(not including UDP header)

func (*UDPSession) SetNoDelay

func (s *UDPSession) SetNoDelay(nodelay, interval, resend, nc int)

SetNoDelay calls nodelay() of kcp https://github.com/skywind3000/kcp/blob/master/README.en.md#protocol-configuration

func (*UDPSession) SetReadBuffer

func (s *UDPSession) SetReadBuffer(bytes int) error

SetReadBuffer sets the socket read buffer, no effect if it's accepted from Listener

func (*UDPSession) SetReadDeadline

func (s *UDPSession) SetReadDeadline(t time.Time) error

SetReadDeadline implements the Conn SetReadDeadline method.

func (*UDPSession) SetStreamMode

func (s *UDPSession) SetStreamMode(enable bool)

SetStreamMode toggles the stream mode on/off

func (*UDPSession) SetWindowSize

func (s *UDPSession) SetWindowSize(sndwnd, rcvwnd int)

SetWindowSize set maximum window size

func (*UDPSession) SetWriteBuffer

func (s *UDPSession) SetWriteBuffer(bytes int) error

SetWriteBuffer sets the socket write buffer, no effect if it's accepted from Listener

func (*UDPSession) SetWriteDeadline

func (s *UDPSession) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements the Conn SetWriteDeadline method.

func (*UDPSession) SetWriteDelay

func (s *UDPSession) SetWriteDelay(delay bool)

SetWriteDelay delays write for bulk transfer until the next update interval

func (*UDPSession) Write

func (s *UDPSession) Write(b []byte) (n int, err error)

Write implements net.Conn

func (*UDPSession) WriteBuffers

func (s *UDPSession) WriteBuffers(v [][]byte) (n int, err error)

WriteBuffers write a vector of byte slices to the underlying connection