Proposal: x/net/ethernet: new package for ethernet sockets

[mdlayher]

At this time, no official x/net package is available to create and use ethernet sockets in Go. I have written a couple of packages which can be used for this purpose, but I'd like to try to create an x/net/ethernet package as an official Go x/net subproject.

My packages can be found at:

• https://github.com/mdlayher/raw
• https://github.com/mdlayher/ethernet

Ethernet sockets are useful for low-level networking applications like ARP, LLDP, ATA over Ethernet, and a wide variety of other networking protocols. This package would make use of Linux's raw sockets and the BSD family's BPF to enable this functionality, and I already have working examples for these operating systems in my raw package. Adding support for other operating systems should be possible over time, but I have no personal experience working with ethernet sockets outside of Linux and BSD.

The proposed API could look something like:

package ethernet

// An Ethernet frame, which the Conn and RawConn types marshal
// and unmarshal to transport data
type Frame struct {
    // Contains usual Ethernet fields
}

// net.Addr implementation which indicates source or destination
// hardware address of Ethernet frame
type Addr struct {
    HardwareAddr net.HardwareAddr
}
func (a *Addr) Network() string
func (a *Addr) String() string

// Protocol identifier used to filter traffic by EtherType
type EtherType uint16

// A net.PacketConn which wraps and unwraps bytes from ethernet
// frames seamlessly.
type Conn struct {}
func Listen(ifi *net.Interface, et EtherType) (*Conn, error)
func (c *Conn) Close() error
func (c *Conn) LocalAddr() net.Addr
func (c *Conn) ReadFrom(b []byte) (int, net.Addr, error)
func (c *Conn) SetBPF(filter []bpf.RawInstruction) error
func (c *Conn) SetDeadline(t time.Time) error
func (c *Conn) SetReadDeadline(t time.Time) error
func (c *Conn) SetWriteDeadline(t time.Time) error
func (c *Conn) WriteTo(b []byte, addr net.Addr) (int, error)

// A modified Conn which returns all Ethernet frame data on incoming
// frames and enables writing arbitrary outgoing frames.
type RawConn struct{}
func ListenRaw(ifi *net.Interface, et EtherType) (*RawConn, error)
func (c *RawConn) Close() error
func (c *RawConn) ReadFrom(b []byte) (f *Frame, p []byte, error)
func (c *RawConn) SetBPF(filter []bpf.RawInstruction) error
func (c *RawConn) SetDeadline(t time.Time) error
func (c *RawConn) SetReadDeadline(t time.Time) error
func (c *RawConn) SetWriteDeadline(t time.Time) error
func (c *RawConn) WriteTo(f *Frame, b []byte) error

I am curious if 802.11Q VLAN tags should be included in this package. In general, the operating system seamlessly handles adding and removing VLAN tags as needed, so it may not be necessary, but could also be nice to have.

In addition, since the runtime network poller is not accessible outside of package net at the moment, the SetDeadline methods may just return an error until implemented later. See my other proposal at #15984 .

If implemented, this package would fix #8432.

Thanks for your time, and please feel free to ask for clarification if needed.

[mdlayher]

/cc @mikioh

[mdlayher]

Ping, @mikioh .

[mikioh]

Thank you for your proposal. A few random thoughts.

• Perhaps datalink might be a better package name
  • I'm not keen on providing Ethernet marshaler/unmarshaler
• It's okay that this package focuses on a bit slow BPF/LSF and AF_PACKET socket IO
  • Having a separate package that implements Netmap/DPDK-like faster stuff sounds reasonable
• s/Conn/PacketConn/
• It's fine to have an internal kqueue/epoll code fragments
• Probably we need a type that can be used to configure BPF/LSF files and AF_PACKET sockets; maybe 'type Listener struct { }`?

A simple question: What's the reason why we need to provide RawConn on Linux?

[mdlayher]

• Perhaps datalink might be a better package name
  • I'm not keen on providing Ethernet marshaler/unmarshaler

I'd be okay with making this package called datalink, but since I assume most folks would use it for ethernet sockets anyway, I figured I would go for the more common use case. If this package were to be a raw datalink package, should another package be created to leverage it with ethernet sockets (x/net/ethernet or maybe even x/net/datalink/ethernet)?

• It's okay that this package focuses on a bit slow BPF/LSF and AF_PACKET socket IO
  • Having a separate package that implements Netmap/DPDK-like faster stuff sounds reasonable

I'm not familiar with Netmap or DPDK, but perhaps they could be cleanly integrated into this package at some point too.

• Probably we need a type that can be used to configure BPF/LSF files and AF_PACKET sockets; maybe 'type Listener struct { }`?

Sure, but what type of options would need to be configured? Would this be things like the ability to set the socket to nonblocking, or change the direction of traffic to capture using BPF?

A simple question: What's the reason why we need to provide RawConn on Linux?

Maybe we don't. My intention for the RawConn type was to enable writing arbitrary ethernet frames, but perhaps it isn't needed after all. If this package only focuses on "datalink" sockets, then this functionality is totally unneeded.

[mikioh]

I think that providing separated datalink IO and datalink wire-format/coding packages makes sense. Because the former needs to work on abstraction of various kernel system calls and data types, and the latter should take a burden of various wire-formats/codings come from IEEE wildcats. For example,

package datalink

type PacketConn struct { /* TBD */ } // implements net.PacketConn interface and a few fancy datalink IO specific methods
type Listener struct {} // or Datalink or Config or something else
func (ln Listener) Listen(ifi *net.Inteface) (PacketConn, error)

--

package ether // or ethernet

type Frame interface { Tag; Stack }
type Tag interface { Len() int; Marshal() ([]byte, error) } 
type Stack interface { Lower() Tag; Upper() Tag }

type Dot3 struct {}
  :
type Dot1ad struct {}

If this package were to be a raw datalink package, should another package be created to leverage it with ethernet sockets (x/net/ethernet or maybe even x/net/datalink/ethernet)?

For the package that provides Ethernet encoding/decoding functionality, all of us know a variety of MAC/LLC sublayers from DIX/dot3 through dot22, and dot1 higher layers including MAC bridging through congestion notification. Ah, I have no strong opinion on it. Probably we can use github.com/google/gopacket package.

Sure, but what type of options would need to be configured?

There are a few options that should be configured before calling bind on AF_PACKET sockets, I guess.

[bradfitz]

Assigning to @mikioh to make a decision.

[joshlf]

A simple question: What's the reason why we need to provide RawConn on Linux?

I just found this proposal because I was searching for a way to read and emit raw ethernet frames in Go. My intended project is a "universal auto-join" tool which is used in security testing settings to join any network, regardless of configuration (presence of DHCP, MAC filtering, etc). I need to have direct access to raw frames for this project to do things like packet sniffing, ARP spoofing, manually speaking DHCP, etc.

[mdlayher]

@joshlf as an interim solution, you can use my packages:

• https://github.com/mdlayher/raw
• https://github.com/mdlayher/ethernet

[joshlf]

@mdlayher Thanks, I will :)

While we're on the subject - if this proposal ends up getting adopted, I'd suggest two additions from your raw package:

• Be able to create a connection which returns frames of any protocol/ethertype
• Be able to listen for ethernet frames not destined to the current host or to the broadcast MAC address (ie, promiscuous mode)

[mdlayher]

Hey @mikioh :

package datalink

type PacketConn struct { /* TBD */ } // implements net.PacketConn interface and a few fancy datalink IO specific methods
type Listener struct {} // or Datalink or Config or something else
func (ln Listener) Listen(ifi *net.Inteface) (PacketConn, error)

^ I'd be happy to look into implementing your proposed API here for a x/net/datalink. Does that work for you?

Looks like it's up to you to accept the proposal, if I understand the process correctly.

We can leave ethernet and things that run on top of x/net/datalink for later.

[joshlf]

func (ln Listener) Listen(ifi *net.Inteface) (PacketConn, error)

Why have a Listener type? Why not just a Listen function at the top level?