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