stun

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 4, 2019 License: MIT Imports: 11 Imported by: 0

README


Pion STUN

A Go implementation of STUN

Pion stun Slack Widget Waffle board
Build Status GoDoc Coverage Status Go Report Card


Roadmap

The library is used as a part of our WebRTC implementation. Please refer to that roadmap to track our major milestones.

Community

Pion has an active community on the Golang Slack. Sign up and join the #pion channel for discussions and support. You can also use Pion mailing list.

We are always looking to support your projects. Please reach out if you have something to build!

If you need commercial support or don't want to use public methods you can contact us at team@pion.ly

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible:

License

MIT License - see LICENSE for full text

Documentation

Index

Constants

View Source 
const (
	ProtocolUDP protocolNumber = 0x11
)

ProtocolUDP User Datagram https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml

View Source 
const (

	// TransactionIDSize is the size of the transaction according to RFC 5389: 96 bits
	TransactionIDSize = 96 / 8
)

Variables

View Source 
var (
	// Err300TryAlternate a ErrorCode value - TryAlernate
	Err300TryAlternate = ErrorCode{3, 0, []byte("Try Alternate: The client should contact an alternate server for this request.")}
	// Err400BadRequest a ErrorCode value - BadRequest
	Err400BadRequest = ErrorCode{4, 0, []byte("Bad Request: The request was malformed.")}
	// Err401Unauthorized a ErrorCode value - Unauthorized
	Err401Unauthorized = ErrorCode{4, 1, []byte("Unauthorized: The request did not contain the correct credentials to proceed.")}
	// Err420UnknownAttributes a ErrorCode value - UnknownAttributes
	Err420UnknownAttributes = ErrorCode{4, 20, []byte("Unknown Attribute: The server received a STUN packet containing a comprehension-required attribute that it did not understand.")}
	// Err437AllocationMismatch a ErrorCode value - AllocationMismatch
	Err437AllocationMismatch = ErrorCode{4, 37, []byte("AllocationMismatch: 5-TUPLE didn't match, or conflicted with existing state.")}
	// Err438StaleNonce a ErrorCode value - StaleNonce
	Err438StaleNonce = ErrorCode{4, 38, []byte("Stale Nonce: The NONCE used by the client was no longer valid.")}
	// Err442UnsupportedTransportProtocol a ErrorCode value - UnsupportedTransportProtocol
	Err442UnsupportedTransportProtocol = ErrorCode{4, 42, []byte("Unsupported Transport Protocol: UDP is the only supported transport protocol.")}
	// Err500ServerError a ErrorCode value - ServerError
	Err500ServerError = ErrorCode{5, 0, []byte("Server Error: The server has suffered a temporary error.")}
	// Err508InsufficentCapacity a ErrorCode value - InsufficentCapacity
	Err508InsufficentCapacity = ErrorCode{5, 8, []byte("Insufficent Capacity: The server doesn't have the capacity to fulfill this request.")}
)
View Source 
var (

	// ErrResponseTooBig is returned if more than maxMessageSize bytes are returned in the response
	// see https://tools.ietf.org/html/rfc5389#section-7 for the size limit
	ErrResponseTooBig = errors.New("received too much data")
)

Functions

func BuildAndSend 

func BuildAndSend(conn net.PacketConn, addr *TransportAddr, class MessageClass, method Method, transactionID []byte, attrs ...Attribute) error

BuildAndSend is building message, pack using attribute and send

func GenerateTransactionID 

func GenerateTransactionID() []byte

GenerateTransactionID returns 16bytes ids

func IsSTUN 

func IsSTUN(packet []byte) bool

IsSTUN determines if a package is likely a STUN package Used for de-multiplexing STUN packages

func MessageIntegrityCalculateHMAC 

func MessageIntegrityCalculateHMAC(key, message []byte) ([]byte, error)

MessageIntegrityCalculateHMAC returns hmac checksum

Types

type AttrType 

type AttrType uint16

AttrType represents an attribute type https://tools.ietf.org/html/rfc5389#section-15 

const (
	AttrMappedAddress      AttrType = 0x0001 // STUN
	AttrResponseAddress    AttrType = 0x0002 // STUN Invalid
	AttrChangeAddress      AttrType = 0x0003 // STUN Invalid
	AttrSourceAddress      AttrType = 0x0004 // STUN Invalid
	AttrChangedAddress     AttrType = 0x0005 // STUN Invalid
	AttrUsername           AttrType = 0x0006 // STUN
	AttrPassword           AttrType = 0x0007 // STUN Invalid
	AttrMessageIntegrity   AttrType = 0x0008 // STUN
	AttrErrorCode          AttrType = 0x0009 // STUN
	AttrUnknownAttributes  AttrType = 0x000A // STUN
	AttrReflectedFrom      AttrType = 0x000B // STUN Invalid
	AttrChannelNumber      AttrType = 0x000C // TURN
	AttrLifetime           AttrType = 0x000D // TURN
	AttrBandwidth          AttrType = 0x0010 // TURN Invalid
	AttrXORPeerAddress     AttrType = 0x0012 // TURN
	AttrData               AttrType = 0x0013 // TURN
	AttrXORRelayedAddress  AttrType = 0x0016 // TURN
	AttrEvenPort           AttrType = 0x0018 // TURN
	AttrRequestedTransport AttrType = 0x0019 // TURN
	AttrDontFragment       AttrType = 0x001A // TURN
	AttrTimerVal           AttrType = 0x0021 // TURN
	AttrReservationToken   AttrType = 0x0022 // TURN
	AttrRealm              AttrType = 0x0014 // STUN
	AttrNonce              AttrType = 0x0015 // STUN
	AttrXORMappedAddress   AttrType = 0x0020 // STUN
)

Comprehension-required range (0x0000-0x7FFF) 

const (
	AttrSoftware        AttrType = 0x8022 // STUN
	AttrAlternateServer AttrType = 0x8023 // STUN
	AttrFingerprint     AttrType = 0x8028 // STUN
)

Comprehension-optional range (0x8000-0xFFFF): 

const (
	AttrPriority       AttrType = 0x0024 // STUN ICE
	AttrUseCandidate   AttrType = 0x0025 // STUN ICE
	AttrIceControlled  AttrType = 0x8029 // STUN ICE
	AttrIceControlling AttrType = 0x802A // STUN ICE
)

https://tools.ietf.org/html/rfc5245#section-19.1 ICE STUN Attributes

func (AttrType) String 

func (t AttrType) String() string

type Attribute 

type Attribute interface {
	Pack(message *Message) error
	Unpack(message *Message, rawAttribute *RawAttribute) error
}

Attribute can implement Pack and Unpack

type ChannelData 

type ChannelData struct {
	ChannelNumber uint16
	Length        uint16
	Data          []byte
}

ChannelData is struct including ChannelNumber and Data

func NewChannelData 

func NewChannelData(packet []byte) (*ChannelData, error)

NewChannelData return ChannelData from packet

type ChannelNumber 

type ChannelNumber struct {
	ChannelNumber uint16
}

A ChannelNumber is a 4-byte header that identifies a Channel. Each channel number in use is bound to a specific peer and thus serves as a shorthand for the peer's host transport address. https://tools.ietf.org/html/rfc5766#section-2.5

func (*ChannelNumber) Pack 

func (x *ChannelNumber) Pack(message *Message) error

Pack a ChannelNumber attribute, adding it to the passed message

func (*ChannelNumber) Unpack 

func (x *ChannelNumber) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack a ChannelNumber, deserializing the rawAttribute and populating the struct

type Client 

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

Client is a STUN client that sents STUN requests and receives STUN responses

func NewClient 

func NewClient(protocol, server string, deadline time.Duration) (*Client, error)

NewClient creates a configured STUN client

func (*Client) Close 

func (c *Client) Close() error

Close disconnects the client

func (*Client) LocalAddr 

func (c *Client) LocalAddr() net.Addr

LocalAddr returns local address of the client

func (*Client) Request 

func (c *Client) Request() (*Message, error)

Request executes a STUN request against the clients server

type Data 

type Data struct {
	Data []byte
}

A Data represents the attribute is present in all Send and Data indications. The value portion of this attribute is variable length and consists of the application data (that is, the data that would immediately follow the UDP header if the data was been sent directly between the client and the peer). If the length of this attribute is not a multiple of 4, then padding must be added after this attribute.

func (*Data) Pack 

func (d *Data) Pack(message *Message) error

Pack a Data attribute, adding it to the passed message

func (*Data) Unpack 

func (d *Data) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack a Data, deserializing the rawAttribute and populating the struct

type ErrorCode 

type ErrorCode struct {
	ErrorClass  int
	ErrorNumber int
	Reason      []byte
}

An ErrorCode attribute is used in error response messages. It contains a numeric error code value in the range of 300 to 699 plus a textual reason phrase encoded in UTF-8 

0                   1                   2                   3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Reserved, should be 0 |Class| Number | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Reason Phrase (variable) .. +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

func (*ErrorCode) Pack 

func (e *ErrorCode) Pack(message *Message) error

Pack a ErrorCode attribute, adding it to the passed message

func (*ErrorCode) Unpack 

func (e *ErrorCode) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack a ErrorCode, deserializing the rawAttribute and populating the struct

type EvenPort 

type EvenPort struct {
	ReserveAdditional bool
}

A EvenPort attribute allows the client to request that the port in the relayed transport address be even, and (optionally) that the server reserve the next-higher port number. The value portion of this attribute is 1 byte long.

func (*EvenPort) Pack 

func (e *EvenPort) Pack(message *Message) error

Pack a EvenNumber attribute, adding it to the passed message

func (*EvenPort) Unpack 

func (e *EvenPort) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack a EvenPort, deserializing the rawAttribute and populating the struct

type Fingerprint 

type Fingerprint struct {
	Fingerprint uint32
}

A Fingerprint attribute MAY be present in all STUN messages. The value of the attribute is computed as the CRC-32 of the STUN message up to (but excluding) the FINGERPRINT attribute itself, XOR'ed with the 32-bit value 0x5354554e (the XOR helps in cases where an application packet is also using CRC-32 in it)

func (*Fingerprint) Pack 

func (s *Fingerprint) Pack(message *Message) error

Pack with Fingerprint

func (*Fingerprint) Unpack 

func (s *Fingerprint) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack with Fingerprint

type IceControlled 

type IceControlled struct {
	TieBreaker uint64
}

IceControlled struct representated tiebreak

func (*IceControlled) Pack 

func (i *IceControlled) Pack(message *Message) error

Pack with TieBreak

func (*IceControlled) Unpack 

func (i *IceControlled) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack with TieBreak

type IceControlling 

type IceControlling struct {
	TieBreaker uint64
}

IceControlling struct representated tiebreak

func (*IceControlling) Pack 

func (i *IceControlling) Pack(message *Message) error

Pack with TieBreak

func (*IceControlling) Unpack 

func (i *IceControlling) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack with TieBreak

type Lifetime 

type Lifetime struct {
	Duration uint32
}

Lifetime represented duration

func (*Lifetime) Pack 

func (x *Lifetime) Pack(message *Message) error

Pack with Lifetime duration

func (*Lifetime) Unpack 

func (x *Lifetime) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack with lifetime

type Message 

type Message struct {
	Class         MessageClass
	Method        Method
	Length        uint16
	TransactionID []byte
	Attributes    []*RawAttribute
	Raw           []byte
}

Message structs

func Build 

func Build(class MessageClass, method Method, transactionID []byte, attrs ...Attribute) (*Message, error)

Build return messsage which is built from class, method, transactionID, and pack message using attribute

func NewMessage 

func NewMessage(packet []byte) (*Message, error)

NewMessage parses a binary STUN message into a Message struct TODO Break this apart, too big

func (*Message) AddAttribute 

func (m *Message) AddAttribute(attrType AttrType, v []byte)

AddAttribute append bytes formatted RawAttribute to message

func (*Message) CommitLength 

func (m *Message) CommitLength()

CommitLength returns message length

func (*Message) GetAllAttributes 

func (m *Message) GetAllAttributes(attrType AttrType) ([]*RawAttribute, bool)

GetAllAttributes can get all RawAttributes which adopt attrbute type

func (*Message) GetOneAttribute 

func (m *Message) GetOneAttribute(attrType AttrType) (*RawAttribute, bool)

GetOneAttribute can get a RawAttribute which adopts attrbute type

func (*Message) Pack 

func (m *Message) Pack() []byte

Pack returns Message.Raw

type MessageClass 

type MessageClass byte

MessageClass of 0b00 is a request, a class of 0b01 is an 

indication, a class of 0b10 is a success response, and a class of
0b11 is an error response.

https://tools.ietf.org/html/rfc5389#section-6 

const (
	// ClassRequest describes a request method type
	ClassRequest MessageClass = 0x00
	// ClassIndication describes an indication method type
	ClassIndication MessageClass = 0x01
	// ClassSuccessResponse describes an success response method type
	ClassSuccessResponse MessageClass = 0x02
	// ClassErrorResponse describes an error response method type
	ClassErrorResponse MessageClass = 0x03
)

func (MessageClass) String 

func (m MessageClass) String() string

String prints the known class names and a hex format for unknown class names

type MessageIntegrity 

type MessageIntegrity struct {
	Key []byte
}

MessageIntegrity is struct represented MESSAGE-INTEGRITY attribute rfc5389#section-15.4

func (*MessageIntegrity) Pack 

func (m *MessageIntegrity) Pack(message *Message) error

Pack message with MessageIntegrity

func (*MessageIntegrity) Unpack 

func (m *MessageIntegrity) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack copy from Key to rawAttribute.Value

type Method 

type Method uint16

Method is selector which can be select MethodType 

const (
	MethodBinding          Method = 0x01 // STUN
	MethodSharedSecret     Method = 0x02 // STUN
	MethodAllocate         Method = 0x03 // TURN (Req/Rsp)
	MethodRefresh          Method = 0x04 // TURN (Req/Rsp)
	MethodSend             Method = 0x06 // TURN (Ind)
	MethodData             Method = 0x07 // TURN (Ind)
	MethodCreatePermission Method = 0x08 // TURN (Req/Rsp)
	MethodChannelBind      Method = 0x09 // TURN (Req/Rsp)
)

Method Type

func (Method) String 

func (m Method) String() string

String prints the known method names and a hex format for unknown method names

type Nonce 

type Nonce struct {
	Nonce string
}

Nonce struct represented by NONCE attribute rfc5389#section-15.8

func (*Nonce) Pack 

func (n *Nonce) Pack(message *Message) error

Pack with checking nonce max length

func (*Nonce) Unpack 

func (n *Nonce) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack nonce

type PacketType 

type PacketType int

PacketType is whether STUN or ChannelData 

const (
	PacketTypeSTUN        PacketType = iota
	PacketTypeChannelData PacketType = iota
)

PacketTypes

func GetPacketType 

func GetPacketType(packet []byte) (PacketType, error)

GetPacketType returns PacketType(whether STUN or ChannelData)

type Priority 

type Priority struct {
	Priority uint32
}

Priority is a STUN Priority message

func (*Priority) Pack 

func (p *Priority) Pack(message *Message) error

Pack a STUN Priority message

func (*Priority) Unpack 

func (p *Priority) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack a STUN Priority message

type RawAttribute 

type RawAttribute struct {
	Type   AttrType
	Length uint16
	Value  []byte
	Pad    uint16
	Offset int
}

RawAttribute represents an unprocessed view of the TLV structure for an attribute https://tools.ietf.org/html/rfc5389#section-15

type Realm 

type Realm struct {
	Realm string
}

Realm represented REALM attribute rfc5389#section-15.7

func (*Realm) Pack 

func (r *Realm) Pack(message *Message) error

Pack with checking realm max length

func (*Realm) Unpack 

func (r *Realm) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack realm

type RequestedTransport 

type RequestedTransport struct {
	Protocol protocolNumber
}

RequestedTransport represented transport protocol

func (*RequestedTransport) Pack 

func (r *RequestedTransport) Pack(message *Message) error

Pack always error

func (*RequestedTransport) Unpack 

func (r *RequestedTransport) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack RequestedTransport protocol

type ReservationToken 

type ReservationToken struct {
	ReservationToken string
}

ReservationToken struct representated RESERVATION-TOKEN attribute rfc5766#section-14.9

func (*ReservationToken) Pack 

func (r *ReservationToken) Pack(message *Message) error

Pack with checking reservationTokenMaxLength

func (*ReservationToken) Unpack 

func (r *ReservationToken) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack ReservationToken

type Software 

type Software struct {
	Software string
}

Software struct has SOFTWARE field that rfc5389#section-15.10

func (*Software) Pack 

func (s *Software) Pack(message *Message) error

Pack with checking softwareMaxLength

func (*Software) Unpack 

func (s *Software) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack Software field

type TransportAddr 

type TransportAddr struct {
	IP   net.IP
	Port int
}

TransportAddr is struct with ip address and port number

func NewTransportAddr 

func NewTransportAddr(addr net.Addr) (*TransportAddr, error)

NewTransportAddr returns transportadd struct within address and port

func (*TransportAddr) Addr 

func (a *TransportAddr) Addr() net.Addr

Addr returns net.UDPAddr from TransportAddr

func (*TransportAddr) Equal 

func (a *TransportAddr) Equal(b *TransportAddr) bool

Equal returns both of address and port is same

func (*TransportAddr) String 

func (a *TransportAddr) String() string

String returns "address:port"

type UnknownAttributes 

type UnknownAttributes struct {
	Attributes []AttrType
}

UnknownAttributes has several attrTypes

func (*UnknownAttributes) Pack 

func (u *UnknownAttributes) Pack(message *Message) error

Pack AttrUnknownAttributes

func (*UnknownAttributes) Unpack 

func (u *UnknownAttributes) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack always returns error

type UseCandidate 

type UseCandidate struct {
}

UseCandidate has no field struct

func (*UseCandidate) Pack 

func (u *UseCandidate) Pack(message *Message) error

Pack with use-candidate attribute

func (*UseCandidate) Unpack 

func (u *UseCandidate) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack use-candidate attribute

type Username 

type Username struct {
	Username string
}

Username struct

func (*Username) Pack 

func (u *Username) Pack(message *Message) error

Pack messsage using USERNAME attribute

func (*Username) Unpack 

func (u *Username) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack message as USERNAME

type XorAddress 

type XorAddress struct {
	IP   net.IP
	Port int
}

XorAddress is struct with in ip address and port number

func (*XorAddress) Unpack 

func (x *XorAddress) Unpack(message *Message, rawAttribute *RawAttribute) error

Unpack message checking address and port suites

type XorMappedAddress 

type XorMappedAddress struct {
	XorAddress
}

XorMappedAddress https://tools.ietf.org/html/rfc5389#section-15.2

func (*XorMappedAddress) Pack 

func (x *XorMappedAddress) Pack(message *Message) error

Pack writes an XorMappedAddress into a message

type XorPeerAddress 

type XorPeerAddress struct {
	XorAddress
}

XorPeerAddress include XorAddress which encoded in the same way as XOR-MAPPED-ADDRESS [RFC5389]

func (*XorPeerAddress) Pack 

func (x *XorPeerAddress) Pack(message *Message) error

Pack using XOR-PEER-ADDRESS

type XorRelayedAddress 

type XorRelayedAddress struct {
	XorAddress
}

XorRelayedAddress include XorAddress which encoded in the same way as XOR-MAPPED-ADDRESS [RFC5389]

func (*XorRelayedAddress) Pack 

func (x *XorRelayedAddress) Pack(message *Message) error

Pack using XOR-RELAYED-ADDRESS

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.