Skip to content
Fast RFC 5389 STUN implementation in go
Go Shell Other
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
api all: use gortc.io import Jul 22, 2019
cmd all: use gortc.io import Jul 22, 2019
e2e all: use gortc.io import Jul 22, 2019
fuzz fuzz: use "fuzz" directory instead of "examples" Aug 1, 2018
internal hmac: cleanup vendor script Aug 11, 2019
testdata iana: fix tests after fixes Nov 16, 2018
.codecov.yml codecov: increase coverage target to 98% Aug 17, 2018
.editorconfig add .editorconfig Aug 8, 2019
.gitignore e2e: capture traffic (udp and tcp) Aug 21, 2018
.golangci.yml ci: ignore evalOlder for build helpers Jul 22, 2019
.travis.yml ci: add go111module Jul 22, 2019
AUTHORS all: add backkem to AUTHORS Jun 22, 2018
CONTRIBUTORS A+C: add CONTRIBUTORS Jul 18, 2019
Dockerfile all: use gortc.io import Jul 22, 2019
LICENSE license: use more uniformal BSD-3-Clause Jul 19, 2018
Makefile all: use gortc.io import Jul 22, 2019
README.md readme: update to custom imports Aug 8, 2019
addr.go all: update godoc references to RFC Jun 29, 2018
addr_test.go a:addr: add UnexpectedEOF test Jun 25, 2017
agent.go {agent,client: add NoopHandler Aug 11, 2018
agent_test.go {agent,client: add NoopHandler Aug 11, 2018
appveyor.yml ci: fix appveyor clone folder Jul 22, 2019
attributes.go attributes: implement Setter for RawAttribute Nov 16, 2018
attributes_debug.go attrs: add CheckOverflow and IsAttrSizeOverflow Aug 2, 2018
attributes_debug_test.go attrs: add CheckOverflow and IsAttrSizeOverflow Aug 2, 2018
attributes_test.go attributes: implement Setter for RawAttribute Nov 16, 2018
checks.go all: use gortc.io import Jul 22, 2019
checks_debug.go all: use gortc.io import Jul 22, 2019
client.go Fix Client crash on ARM Jul 16, 2019
client_test.go Unlambda test functions Jul 22, 2019
errorcode.go iana: add test for error codes and fix Code{RoleConflict,Unauthorized} Nov 16, 2018
errorcode_test.go a:errorcode: fix code of StaleNonce Aug 14, 2018
errors.go errors: remove ErrAttributeSizeInvalid Aug 8, 2018
errors_test.go errors: improve coverage Feb 26, 2017
fingerprint.go all: fix linter warnings Feb 9, 2019
fingerprint_debug.go all: report detailed fingerprint mismatch only in debug mode Aug 1, 2018
fingerprint_test.go all: improve linters config and fix some warnings Feb 18, 2019
fuzz.go fuzz: fix code after error refactor Aug 2, 2018
fuzz_test.go fuzz: use "fuzz" directory instead of "examples" Aug 1, 2018
go.mod all: use gortc.io import Jul 22, 2019
go.test.sh ci: replace condition with double brackets Aug 8, 2019
helpers.go message: add ForEach helper Aug 2, 2018
helpers_test.go all: use gortc.io import Jul 22, 2019
iana_test.go iana: add test for error codes and fix Code{RoleConflict,Unauthorized} Nov 16, 2018
integrity.go all: use gortc.io import Jul 22, 2019
integrity_debug.go all: report detailed integrity mismatch only in debug mode Aug 1, 2018
integrity_test.go all: fix linter warnings Feb 9, 2019
message.go Fix buffer grow for n < length Jul 16, 2019
message_test.go Optimize internal buffer Jul 16, 2019
rfc5769_test.go a:integrity: rename NewLongtermIntegrity to NewLongTermIntegrity Feb 18, 2017
stun.go stun: update turn link in doc Aug 1, 2018
stun_test.go all: refactor errors, improve coverage, refactor Jun 26, 2017
textattrs.go Optimize text attributes Jul 16, 2019
textattrs_test.go attrs: add CheckOverflow and IsAttrSizeOverflow Aug 2, 2018
uattrs.go all: reduce newline overuse Mar 8, 2019
uattrs_test.go all: improve coverage (fix #26) Feb 26, 2017
uri.go uri: mitigate breaking change Aug 14, 2019
uri_test.go uri: mitigate breaking change Aug 14, 2019
xor.go all: refactor attributes Feb 11, 2017
xor_test.go all: fix linters warnings; update makefile Apr 29, 2016
xoraddr.go attrs: add CheckOverflow and IsAttrSizeOverflow Aug 2, 2018
xoraddr_test.go attrs: add CheckOverflow and IsAttrSizeOverflow Aug 2, 2018

README.md

Master status GoDoc codecov

STUN

Package stun implements Session Traversal Utilities for NAT (STUN) [RFC5389] protocol and client with no external dependencies and zero allocations in hot paths. Client supports automatic request retransmissions. Complies to gortc principles as core package.

See example and stun server for simple usage. Also see gortc/turn for TURN [RFC5766] implementation and gortcd for TURN and STUN server. This repo was merged to pion/stun at version v1.19.0.

Example

You can get your current IP address from any STUN server by sending binding request. See more idiomatic example at cmd/stun-client.

package main

import (
	"fmt"

	"gortc.io/stun"
)

func main() {
	// Creating a "connection" to STUN server.
	c, err := stun.Dial("udp", "stun.l.google.com:19302")
	if err != nil {
		panic(err)
	}
	// Building binding request with random transaction id.
	message := stun.MustBuild(stun.TransactionID, stun.BindingRequest)
	// Sending request to STUN server, waiting for response message.
	if err := c.Do(message, func(res stun.Event) {
		if res.Error != nil {
			panic(res.Error)
		}
		// Decoding XOR-MAPPED-ADDRESS attribute from message.
		var xorAddr stun.XORMappedAddress
		if err := xorAddr.GetFrom(res.Message); err != nil {
			panic(err)
		}
		fmt.Println("your IP is", xorAddr.IP)
	}); err != nil {
		panic(err)
	}
}

Supported RFCs

Stability stability-mature GitHub tag

Package is currently stable, no backward incompatible changes are expected with exception of critical bugs or security fixes.

Additional attributes are unlikely to be implemented in scope of stun package, the only exception is constants for attribute or message types.

RFC 3489 notes

RFC 5389 obsoletes RFC 3489, so implementation was ignored by purpose, however, RFC 3489 can be easily implemented as separate package.

Requirements

Go 1.10 is currently supported and tested in CI. Should work on 1.9 and tip.

Testing

Client behavior is tested and verified in many ways:

  • End-To-End with long-term credentials
    • coturn: The coturn server (linux)
  • Bunch of code static checkers (linters)
  • Standard unit-tests with coverage reporting (linux {amd64, arm64}, windows and darwin)
  • Explicit API backward compatibility check, see api directory

See TeamCity project and e2e directory for more information. Also the Wireshark .pcap files are available for e2e test in artifacts for build.

Benchmarks

Intel(R) Core(TM) i7-8700K:

version: 1.16.5
goos: linux
goarch: amd64
pkg: github.com/gortc/stun
PASS
benchmark                                         iter       time/iter      throughput   bytes alloc        allocs
---------                                         ----       ---------      ----------   -----------        ------
BenchmarkMappedAddress_AddTo-12               30000000     36.40 ns/op                        0 B/op   0 allocs/op
BenchmarkAlternateServer_AddTo-12             50000000     36.70 ns/op                        0 B/op   0 allocs/op
BenchmarkAgent_GC-12                            500000   2552.00 ns/op                        0 B/op   0 allocs/op
BenchmarkAgent_Process-12                     50000000     38.00 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_GetNotFound-12              200000000      6.90 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_Get-12                      200000000      7.61 ns/op                        0 B/op   0 allocs/op
BenchmarkClient_Do-12                          2000000   1072.00 ns/op                        0 B/op   0 allocs/op
BenchmarkErrorCode_AddTo-12                   20000000     67.00 ns/op                        0 B/op   0 allocs/op
BenchmarkErrorCodeAttribute_AddTo-12          30000000     52.20 ns/op                        0 B/op   0 allocs/op
BenchmarkErrorCodeAttribute_GetFrom-12       100000000     12.00 ns/op                        0 B/op   0 allocs/op
BenchmarkFingerprint_AddTo-12                 20000000    102.00 ns/op     430.08 MB/s        0 B/op   0 allocs/op
BenchmarkFingerprint_Check-12                 30000000     54.80 ns/op     948.38 MB/s        0 B/op   0 allocs/op
BenchmarkBuildOverhead/Build-12                5000000    333.00 ns/op                        0 B/op   0 allocs/op
BenchmarkBuildOverhead/BuildNonPointer-12      3000000    536.00 ns/op                      100 B/op   4 allocs/op
BenchmarkBuildOverhead/Raw-12                 10000000    181.00 ns/op                        0 B/op   0 allocs/op
BenchmarkMessageIntegrity_AddTo-12             1000000   1053.00 ns/op      18.98 MB/s        0 B/op   0 allocs/op
BenchmarkMessageIntegrity_Check-12             1000000   1135.00 ns/op      28.17 MB/s        0 B/op   0 allocs/op
BenchmarkMessage_Write-12                    100000000     27.70 ns/op    1011.09 MB/s        0 B/op   0 allocs/op
BenchmarkMessageType_Value-12               2000000000      0.49 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_WriteTo-12                  100000000     12.80 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_ReadFrom-12                  50000000     25.00 ns/op     801.19 MB/s        0 B/op   0 allocs/op
BenchmarkMessage_ReadBytes-12                100000000     18.00 ns/op    1113.03 MB/s        0 B/op   0 allocs/op
BenchmarkIsMessage-12                       2000000000      1.08 ns/op   18535.57 MB/s        0 B/op   0 allocs/op
BenchmarkMessage_NewTransactionID-12           2000000    673.00 ns/op                        0 B/op   0 allocs/op
BenchmarkMessageFull-12                        5000000    316.00 ns/op                        0 B/op   0 allocs/op
BenchmarkMessageFullHardcore-12               20000000     88.90 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_WriteHeader-12              200000000      8.18 ns/op                        0 B/op   0 allocs/op
BenchmarkMessage_CloneTo-12                   30000000     37.90 ns/op    1795.32 MB/s        0 B/op   0 allocs/op
BenchmarkMessage_AddTo-12                    300000000      4.77 ns/op                        0 B/op   0 allocs/op
BenchmarkDecode-12                           100000000     22.00 ns/op                        0 B/op   0 allocs/op
BenchmarkUsername_AddTo-12                    50000000     23.20 ns/op                        0 B/op   0 allocs/op
BenchmarkUsername_GetFrom-12                 100000000     17.90 ns/op                        0 B/op   0 allocs/op
BenchmarkNonce_AddTo-12                       50000000     34.40 ns/op                        0 B/op   0 allocs/op
BenchmarkNonce_AddTo_BadLength-12            200000000      8.29 ns/op                        0 B/op   0 allocs/op
BenchmarkNonce_GetFrom-12                    100000000     17.50 ns/op                        0 B/op   0 allocs/op
BenchmarkUnknownAttributes/AddTo-12           30000000     48.10 ns/op                        0 B/op   0 allocs/op
BenchmarkUnknownAttributes/GetFrom-12        100000000     20.90 ns/op                        0 B/op   0 allocs/op
BenchmarkXOR-12                               50000000     25.80 ns/op   39652.86 MB/s        0 B/op   0 allocs/op
BenchmarkXORSafe-12                            3000000    515.00 ns/op    1988.04 MB/s        0 B/op   0 allocs/op
BenchmarkXORFast-12                           20000000     73.40 ns/op   13959.30 MB/s        0 B/op   0 allocs/op
BenchmarkXORMappedAddress_AddTo-12            20000000     56.70 ns/op                        0 B/op   0 allocs/op
BenchmarkXORMappedAddress_GetFrom-12          50000000     37.40 ns/op                        0 B/op   0 allocs/op
ok  	github.com/gortc/stun	76.868s

Build status

Build Status Build status

License

BSD 3-Clause License

You can’t perform that action at this time.