ethernet

README

ethernet

Package ethernet implements marshaling and unmarshaling of IEEE 802.3 Ethernet II frames and IEEE 802.1Q VLAN tags. MIT Licensed.

For more information about using Ethernet frames in Go, check out my blog post: Network Protocol Breakdown: Ethernet and Go.

Documentation

Overview

Package ethernet implements marshaling and unmarshaling of IEEE 802.3 Ethernet II frames and IEEE 802.1Q VLAN tags.

Index

• Constants
• Variables
• type EtherType
  • func (i EtherType) String() string
• type Frame
  • func (f *Frame) MarshalBinary() ([]byte, error)
  • func (f *Frame) MarshalFCS() ([]byte, error)
  • func (f *Frame) UnmarshalBinary(b []byte) error
  • func (f *Frame) UnmarshalFCS(b []byte) error
• type Priority
• type VLAN
  • func (v *VLAN) MarshalBinary() ([]byte, error)
  • func (v *VLAN) UnmarshalBinary(b []byte) error

Constants

const (
	// VLANNone is a special VLAN ID which indicates that no VLAN is being
	// used in a Frame.  In this case, the VLAN's other fields may be used
	// to indicate a Frame's priority.
	VLANNone = 0x000

	// VLANMax is a reserved VLAN ID which may indicate a wildcard in some
	// management systems, but may not be configured or transmitted in a
	// VLAN tag.
	VLANMax = 0xfff
)

Variables

var Broadcast = net.HardwareAddr{0xff, 0xff, 0xff, 0xff, 0xff, 0xff}

Broadcast is a special hardware address which indicates a Frame should be sent to every device on a given LAN segment.

var ErrInvalidFCS = errors.New("invalid frame check sequence")

ErrInvalidFCS is returned when Frame.UnmarshalFCS detects an incorrect Ethernet frame check sequence in a byte slice for a Frame.

var ErrInvalidVLAN = errors.New("invalid VLAN")

ErrInvalidVLAN is returned when a VLAN tag is invalid due to one of the following reasons:

• Priority of greater than 7 is detected
• ID of greater than 4094 (0xffe) is detected
• A customer VLAN does not follow a service VLAN (when using Q-in-Q)

Types

type EtherType

type EtherType uint16

An EtherType is a value used to identify an upper layer protocol encapsulated in a Frame.

A list of IANA-assigned EtherType values may be found here: http://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.xhtml.

const (
	EtherTypeIPv4 EtherType = 0x0800
	EtherTypeARP  EtherType = 0x0806
	EtherTypeIPv6 EtherType = 0x86DD

	// EtherTypeVLAN and EtherTypeServiceVLAN are used as 802.1Q Tag Protocol
	// Identifiers (TPIDs).
	EtherTypeVLAN        EtherType = 0x8100
	EtherTypeServiceVLAN EtherType = 0x88a8
)

Common EtherType values frequently used in a Frame.

func (EtherType) String

func (i EtherType) String() string

type Frame

type Frame struct {
	// Destination specifies the destination hardware address for this Frame.
	//
	// If this address is set to Broadcast, the Frame will be sent to every
	// device on a given LAN segment.
	Destination net.HardwareAddr

	// Source specifies the source hardware address for this Frame.
	//
	// Typically, this is the hardware address of the network interface used to
	// send this Frame.
	Source net.HardwareAddr

	// ServiceVLAN specifies an optional 802.1Q service VLAN tag, for use with
	// 802.1ad double tagging, or "Q-in-Q". If ServiceVLAN is not nil, VLAN must
	// not be nil as well.
	//
	// Most users should leave this field set to nil and use VLAN instead.
	ServiceVLAN *VLAN

	// VLAN specifies an optional 802.1Q customer VLAN tag, which may or may
	// not be present in a Frame.  It is important to note that the operating
	// system may automatically strip VLAN tags before they can be parsed.
	VLAN *VLAN

	// EtherType is a value used to identify an upper layer protocol
	// encapsulated in this Frame.
	EtherType EtherType

	// Payload is a variable length data payload encapsulated by this Frame.
	Payload []byte
}

A Frame is an IEEE 802.3 Ethernet II frame. A Frame contains information such as source and destination hardware addresses, zero or more optional 802.1Q VLAN tags, an EtherType, and payload data.

func (*Frame) MarshalBinary

func (f *Frame) MarshalBinary() ([]byte, error)

MarshalBinary allocates a byte slice and marshals a Frame into binary form.

func (*Frame) MarshalFCS

func (f *Frame) MarshalFCS() ([]byte, error)

MarshalFCS allocates a byte slice, marshals a Frame into binary form, and finally calculates and places a 4-byte IEEE CRC32 frame check sequence at the end of the slice.

Most users should use MarshalBinary instead. MarshalFCS is provided as a convenience for rare occasions when the operating system cannot automatically generate a frame check sequence for an Ethernet frame.

func (*Frame) UnmarshalBinary

func (f *Frame) UnmarshalBinary(b []byte) error

UnmarshalBinary unmarshals a byte slice into a Frame.

func (*Frame) UnmarshalFCS

func (f *Frame) UnmarshalFCS(b []byte) error

UnmarshalFCS computes the IEEE CRC32 frame check sequence of a Frame, verifies it against the checksum present in the byte slice, and finally, unmarshals a byte slice into a Frame.

Most users should use UnmarshalBinary instead. UnmarshalFCS is provided as a convenience for rare occasions when the operating system cannot automatically verify a frame check sequence for an Ethernet frame.

type Priority

type Priority uint8

Priority is an IEEE P802.1p priority level. Priority can be any value from 0 to 7.

It is important to note that priority 1 (PriorityBackground) actually has a lower priority than 0 (PriorityBestEffort). All other Priority constants indicate higher priority as the integer values increase.

const (
	PriorityBackground           Priority = 1
	PriorityBestEffort           Priority = 0
	PriorityExcellentEffort      Priority = 2
	PriorityCriticalApplications Priority = 3
	PriorityVideo                Priority = 4
	PriorityVoice                Priority = 5
	PriorityInternetworkControl  Priority = 6
	PriorityNetworkControl       Priority = 7
)

IEEE P802.1p recommended priority levels. Note that PriorityBackground has a lower priority than PriorityBestEffort.

type VLAN

type VLAN struct {
	// Priority specifies a IEEE P802.1p priority level.  Priority can be any
	// value from 0 to 7.
	Priority Priority

	// DropEligible indicates if a Frame is eligible to be dropped in the
	// presence of network congestion.
	DropEligible bool

	// ID specifies the VLAN ID for a Frame.  ID can be any value from 0 to
	// 4094 (0x000 to 0xffe), allowing up to 4094 VLANs.
	//
	// If ID is 0 (0x000, VLANNone), no VLAN is specified, and the other fields
	// simply indicate a Frame's priority.
	ID uint16
}

A VLAN is an IEEE 802.1Q Virtual LAN (VLAN) tag. A VLAN contains information regarding traffic priority and a VLAN identifier for a given Frame.

func (*VLAN) MarshalBinary

func (v *VLAN) MarshalBinary() ([]byte, error)

MarshalBinary allocates a byte slice and marshals a VLAN into binary form.

func (*VLAN) UnmarshalBinary

func (v *VLAN) UnmarshalBinary(b []byte) error

UnmarshalBinary unmarshals a byte slice into a VLAN.