1<h1 align="center">
2  <br>
3  Pion STUN
4  <br>
5</h1>
6<h4 align="center">A Go implementation of STUN</h4>
7<p align="center">
8  <a href="https://pion.ly"><img src="https://img.shields.io/badge/pion-stun-gray.svg?longCache=true&colorB=brightgreen" alt="Pion stun"></a>
9  <!--<a href="https://sourcegraph.com/github.com/pion/webrtc?badge"><img src="https://sourcegraph.com/github.com/pion/webrtc/-/badge.svg" alt="Sourcegraph Widget"></a>-->
10  <a href="https://pion.ly/slack"><img src="https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen" alt="Slack Widget"></a>
11  <br>
12  <a href="https://travis-ci.org/pion/stun"><img src="https://travis-ci.org/pion/stun.svg?branch=master" alt="Build Status"></a>
13  <a href="https://pkg.go.dev/github.com/pion/stun"><img src="https://godoc.org/github.com/pion/stun?status.svg" alt="GoDoc"></a>
14  <a href="https://codecov.io/gh/pion/stun"><img src="https://codecov.io/gh/pion/stun/branch/master/graph/badge.svg" alt="Coverage Status"></a>
15  <a href="https://goreportcard.com/report/github.com/pion/stun"><img src="https://goreportcard.com/badge/github.com/pion/stun" alt="Go Report Card"></a>
16  <!--<a href="https://www.codacy.com/app/Sean-Der/webrtc"><img src="https://api.codacy.com/project/badge/Grade/18f4aec384894e6aac0b94effe51961d" alt="Codacy Badge"></a>-->
17  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
18</p>
19<br>
20
21### Roadmap
22The library is used as a part of our WebRTC implementation. Please refer to that [roadmap](https://github.com/pion/webrtc/issues/9) to track our major milestones.
23
24### Community
25Pion has an active community on the [Golang Slack](https://invite.slack.golangbridge.org/). Sign up and join the **#pion** channel for discussions and support. You can also use [Pion mailing list](https://groups.google.com/forum/#!forum/pion).
26
27We are always looking to support **your projects**. Please reach out if you have something to build!
28
29If you need commercial support or don't want to use public methods you can contact us at [team@pion.ly](mailto:team@pion.ly)
30
31### Contributing
32Check out the **[contributing wiki](https://github.com/pion/webrtc/wiki/Contributing)** to join the group of amazing people making this project possible:
33
34* [Sean DuBois](https://github.com/Sean-Der) - *Original Author*
35* [Raphael Randschau](https://github.com/nicolai86) - *STUN client*
36* [Michiel De Backker](https://github.com/backkem) - *Minor fixes*
37* [Y.Horie](https://github.com/u5surf) - *Fix lint issues*
38* [Aleksandr Razumov](https://github.com/ernado) - *The v0.3 version*
39* [songjiayang](https://github.com/songjiayang)
40* [Adam Kiss](https://github.com/masterada)
41* [Moises Marangoni](https://github.com/Moisesbr)
42* [Yutaka Takeda](https://github.com/enobufs)
43* [Hugo Arregui](https://github.com/hugoArregui)
44* [Maanas Royy](https://github.com/maanas)
45* [Atsushi Watanabe](https://github.com/at-wat)
46* [Cecylia Bocovich](https://github.com/cohosh)
47* [Christian Muehlhaeuser](https://github.com/muesli)
48
49# STUN
50Package stun implements Session Traversal Utilities for NAT (STUN) [[RFC5389](https://tools.ietf.org/html/rfc5389)]
51protocol and [client](https://pkg.go.dev/github.com/pion/stun#Client) with no external dependencies and zero allocations in hot paths.
52Client [supports](https://pkg.go.dev/github.com/pion/stun#WithRTO) automatic request retransmissions.
53
54# Example
55You can get your current IP address from any STUN server by sending
56binding request. See more idiomatic example at `cmd/stun-client`.
57```go
58package main
59
60import (
61	"fmt"
62
63	"github.com/pion/stun"
64)
65
66func main() {
67	// Creating a "connection" to STUN server.
68	c, err := stun.Dial("udp", "stun.l.google.com:19302")
69	if err != nil {
70		panic(err)
71	}
72	// Building binding request with random transaction id.
73	message := stun.MustBuild(stun.TransactionID, stun.BindingRequest)
74	// Sending request to STUN server, waiting for response message.
75	if err := c.Do(message, func(res stun.Event) {
76		if res.Error != nil {
77			panic(res.Error)
78		}
79		// Decoding XOR-MAPPED-ADDRESS attribute from message.
80		var xorAddr stun.XORMappedAddress
81		if err := xorAddr.GetFrom(res.Message); err != nil {
82			panic(err)
83		}
84		fmt.Println("your IP is", xorAddr.IP)
85	}); err != nil {
86		panic(err)
87	}
88}
89```
90
91## Supported RFCs
92- [x] [RFC 5389](https://tools.ietf.org/html/rfc5389) — Session Traversal Utilities for NAT
93- [x] [RFC 5769](https://tools.ietf.org/html/rfc5769) — Test Vectors for STUN
94- [x] [RFC 6062](https://tools.ietf.org/html/rfc6062) — TURN extensions for TCP allocations
95- [x] [RFC 7064](https://tools.ietf.org/html/rfc7064) — STUN URI
96- [x] (TLS-over-)TCP client support
97- [ ] [ALTERNATE-SERVER](https://tools.ietf.org/html/rfc5389#section-11) support [#48](https://github.com/pion/stun/issues/48)
98- [ ] [RFC 5780](https://tools.ietf.org/html/rfc5780) — NAT Behavior Discovery Using STUN [#49](https://github.com/pion/stun/issues/49)
99
100# Stability
101Package is currently stable, no backward incompatible changes are expected
102with exception of critical bugs or security fixes.
103
104Additional attributes are unlikely to be implemented in scope of stun package,
105the only exception is constants for attribute or message types.
106
107# RFC 3489 notes
108RFC 5389 obsoletes RFC 3489, so implementation was ignored by purpose, however,
109RFC 3489 can be easily implemented as separate package.
110
111# Requirements
112Go 1.12 is currently supported and tested in CI.
113
114# Testing
115Client behavior is tested and verified in many ways:
116  * End-To-End with long-term credentials
117    * **coturn**: The coturn [server](https://github.com/coturn/coturn/wiki/turnserver) (linux)
118  * Bunch of code static checkers (linters)
119  * Standard unit-tests with coverage reporting (linux {amd64, **arm**64}, windows and darwin)
120  * Explicit API backward compatibility [check](https://github.com/gortc/api), see `api` directory
121
122See [TeamCity project](https://tc.gortc.io/project.html?projectId=stun&guest=1) and `e2e` directory
123for more information. Also the Wireshark `.pcap` files are available for e2e test in
124artifacts for build.
125
126# Benchmarks
127
128Intel(R) Core(TM) i7-8700K:
129
130```
131version: 1.16.5
132goos: linux
133goarch: amd64
134pkg: github.com/pion/stun
135PASS
136benchmark                                         iter       time/iter      throughput   bytes alloc        allocs
137---------                                         ----       ---------      ----------   -----------        ------
138BenchmarkMappedAddress_AddTo-12               30000000     36.40 ns/op                        0 B/op   0 allocs/op
139BenchmarkAlternateServer_AddTo-12             50000000     36.70 ns/op                        0 B/op   0 allocs/op
140BenchmarkAgent_GC-12                            500000   2552.00 ns/op                        0 B/op   0 allocs/op
141BenchmarkAgent_Process-12                     50000000     38.00 ns/op                        0 B/op   0 allocs/op
142BenchmarkMessage_GetNotFound-12              200000000      6.90 ns/op                        0 B/op   0 allocs/op
143BenchmarkMessage_Get-12                      200000000      7.61 ns/op                        0 B/op   0 allocs/op
144BenchmarkClient_Do-12                          2000000   1072.00 ns/op                        0 B/op   0 allocs/op
145BenchmarkErrorCode_AddTo-12                   20000000     67.00 ns/op                        0 B/op   0 allocs/op
146BenchmarkErrorCodeAttribute_AddTo-12          30000000     52.20 ns/op                        0 B/op   0 allocs/op
147BenchmarkErrorCodeAttribute_GetFrom-12       100000000     12.00 ns/op                        0 B/op   0 allocs/op
148BenchmarkFingerprint_AddTo-12                 20000000    102.00 ns/op     430.08 MB/s        0 B/op   0 allocs/op
149BenchmarkFingerprint_Check-12                 30000000     54.80 ns/op     948.38 MB/s        0 B/op   0 allocs/op
150BenchmarkBuildOverhead/Build-12                5000000    333.00 ns/op                        0 B/op   0 allocs/op
151BenchmarkBuildOverhead/BuildNonPointer-12      3000000    536.00 ns/op                      100 B/op   4 allocs/op
152BenchmarkBuildOverhead/Raw-12                 10000000    181.00 ns/op                        0 B/op   0 allocs/op
153BenchmarkMessageIntegrity_AddTo-12             1000000   1053.00 ns/op      18.98 MB/s        0 B/op   0 allocs/op
154BenchmarkMessageIntegrity_Check-12             1000000   1135.00 ns/op      28.17 MB/s        0 B/op   0 allocs/op
155BenchmarkMessage_Write-12                    100000000     27.70 ns/op    1011.09 MB/s        0 B/op   0 allocs/op
156BenchmarkMessageType_Value-12               2000000000      0.49 ns/op                        0 B/op   0 allocs/op
157BenchmarkMessage_WriteTo-12                  100000000     12.80 ns/op                        0 B/op   0 allocs/op
158BenchmarkMessage_ReadFrom-12                  50000000     25.00 ns/op     801.19 MB/s        0 B/op   0 allocs/op
159BenchmarkMessage_ReadBytes-12                100000000     18.00 ns/op    1113.03 MB/s        0 B/op   0 allocs/op
160BenchmarkIsMessage-12                       2000000000      1.08 ns/op   18535.57 MB/s        0 B/op   0 allocs/op
161BenchmarkMessage_NewTransactionID-12           2000000    673.00 ns/op                        0 B/op   0 allocs/op
162BenchmarkMessageFull-12                        5000000    316.00 ns/op                        0 B/op   0 allocs/op
163BenchmarkMessageFullHardcore-12               20000000     88.90 ns/op                        0 B/op   0 allocs/op
164BenchmarkMessage_WriteHeader-12              200000000      8.18 ns/op                        0 B/op   0 allocs/op
165BenchmarkMessage_CloneTo-12                   30000000     37.90 ns/op    1795.32 MB/s        0 B/op   0 allocs/op
166BenchmarkMessage_AddTo-12                    300000000      4.77 ns/op                        0 B/op   0 allocs/op
167BenchmarkDecode-12                           100000000     22.00 ns/op                        0 B/op   0 allocs/op
168BenchmarkUsername_AddTo-12                    50000000     23.20 ns/op                        0 B/op   0 allocs/op
169BenchmarkUsername_GetFrom-12                 100000000     17.90 ns/op                        0 B/op   0 allocs/op
170BenchmarkNonce_AddTo-12                       50000000     34.40 ns/op                        0 B/op   0 allocs/op
171BenchmarkNonce_AddTo_BadLength-12            200000000      8.29 ns/op                        0 B/op   0 allocs/op
172BenchmarkNonce_GetFrom-12                    100000000     17.50 ns/op                        0 B/op   0 allocs/op
173BenchmarkUnknownAttributes/AddTo-12           30000000     48.10 ns/op                        0 B/op   0 allocs/op
174BenchmarkUnknownAttributes/GetFrom-12        100000000     20.90 ns/op                        0 B/op   0 allocs/op
175BenchmarkXOR-12                               50000000     25.80 ns/op   39652.86 MB/s        0 B/op   0 allocs/op
176BenchmarkXORSafe-12                            3000000    515.00 ns/op    1988.04 MB/s        0 B/op   0 allocs/op
177BenchmarkXORFast-12                           20000000     73.40 ns/op   13959.30 MB/s        0 B/op   0 allocs/op
178BenchmarkXORMappedAddress_AddTo-12            20000000     56.70 ns/op                        0 B/op   0 allocs/op
179BenchmarkXORMappedAddress_GetFrom-12          50000000     37.40 ns/op                        0 B/op   0 allocs/op
180ok  	github.com/pion/stun	76.868s
181```
182
183### License
184MIT License - see [LICENSE](LICENSE) for full text
185