Add Access Point scanning (#117)

* Add access point scanning and associated tests

---------

Co-authored-by: Justin Slauson <justin.slauson@outlook.com>

Author: initsuj

client.go

@@ -1,6 +1,7 @@
 package wifi
 
 import (
+	"context"
 	"time"
 )
 
@@ -52,6 +53,18 @@ func (c *Client) BSS(ifi *Interface) (*BSS, error) {
 	return c.c.BSS(ifi)
 }
 
+// AccessPoints retrieves the currently known BSS around the specified Interface.
+func (c *Client) AccessPoints(ifi *Interface) ([]*BSS, error) {
+	return c.c.AccessPoints(ifi)
+}
+
+// Scan requests the wifi interface to scan for new access points.
+//
+// Use context.WithDeadline to set a timeout.
+func (c *Client) Scan(ctx context.Context, ifi *Interface) error {
+	return c.c.Scan(ctx, ifi)
+}
+
 // StationInfo retrieves all station statistics about a WiFi interface.
 //
 // Since v0.2.0: if there are no stations, an empty slice is returned instead

client_linux.go

@@ -5,11 +5,13 @@ package wifi
 
 import (
 	"bytes"
+	"context"
 	"crypto/sha1"
 	"encoding/binary"
 	"errors"
 	"net"
 	"os"
+	"sync"
 	"time"
 	"unicode/utf8"
 
@@ -20,8 +22,12 @@ import (
 	"golang.org/x/sys/unix"
 )
 
-// errNotSupported is returned when an operation is not supported
-var ErrNotSupported = errors.New("not supported")
+var (
+	ErrNotSupported      = errors.New("not supported")
+	ErrScanGroupNotFound = errors.New("scan multicast group unavailable")
+	ErrScanAborted       = errors.New("scan aborted by the kernel")
+	ErrScanValidation    = errors.New("scan validation failed")
+)
 
 // A client is the Linux implementation of osClient, which makes use of
 // netlink, generic netlink, and nl80211 to provide access to WiFi device
@@ -30,6 +36,9 @@ type client struct {
 	c             *genetlink.Conn
 	familyID      uint16
 	familyVersion uint8
+
+	// scan is used to synchronize access to the Scan method.
+	scan sync.Mutex
 }
 
 // newClient dials a generic netlink connection and verifies that nl80211
@@ -67,6 +76,8 @@ func initClient(c *genetlink.Conn) (*client, error) {
 		c:             c,
 		familyID:      family.ID,
 		familyVersion: family.Version,
+
+		scan: sync.Mutex{},
 	}, nil
 }
 
@@ -180,6 +191,21 @@ func (c *client) BSS(ifi *Interface) (*BSS, error) {
 	return parseBSS(msgs)
 }
 
+// AccessPoints requests that nl80211 return all currently known BSS
+// from the specified Interface.
+func (c *client) AccessPoints(ifi *Interface) ([]*BSS, error) {
+	msgs, err := c.get(
+		unix.NL80211_CMD_GET_SCAN,
+		netlink.Dump,
+		ifi,
+		nil,
+	)
+	if err != nil {
+		return nil, err
+	}
+	return parseGetScanResult(msgs)
+}
+
 // StationInfo requests that nl80211 return all station info for the specified
 // Interface.
 func (c *client) StationInfo(ifi *Interface) ([]*StationInfo, error) {
@@ -233,6 +259,105 @@ func (c *client) SurveyInfo(ifi *Interface) ([]*SurveyInfo, error) {
 	return surveys, nil
 }
 
+// Scan requests that nl80211 perform a scan for new access points using
+// the specified Interface. This process is long running and uses
+// a separate connection to nl80211.
+//
+// Use context.WithDeadline to set a timeout.
+//
+// If a scan is already in progress, this function will return a syscall.EBUSY
+// error. If the response cannot be validated, the returned error
+// will include ErrScanValidation.
+//
+// Use func AccessPoints to retrieve the results.
+func (c *client) Scan(ctx context.Context, ifi *Interface) error {
+	c.scan.Lock()
+	defer c.scan.Unlock()
+
+	// use secondary connection for multicast receives
+	conn, err := genetlink.Dial(&netlink.Config{Strict: true})
+	if err != nil {
+		return err
+	}
+
+	defer conn.Close()
+
+	if deadline, ok := ctx.Deadline(); ok {
+		err := conn.SetDeadline(deadline)
+		if err != nil {
+			return err
+		}
+	}
+
+	family, err := conn.GetFamily(unix.NL80211_GENL_NAME)
+	if err != nil {
+		return err
+	}
+
+	var id uint32
+	for _, group := range family.Groups {
+		if group.Name == unix.NL80211_MULTICAST_GROUP_SCAN {
+			err = conn.JoinGroup(group.ID)
+			if err != nil {
+				return err
+			}
+
+			id = group.ID
+			break
+		}
+	}
+
+	if id == 0 {
+		return ErrScanGroupNotFound
+	}
+
+	// Leave group on exit. Err is non-actionable
+	defer func() { _ = conn.LeaveGroup(id) }()
+
+	enc := netlink.NewAttributeEncoder()
+	enc.Nested(unix.NL80211_ATTR_SCAN_SSIDS, func(ae *netlink.AttributeEncoder) error {
+		ae.Bytes(unix.NL80211_SCHED_SCAN_MATCH_ATTR_SSID, nlenc.Bytes(""))
+		return nil
+	})
+
+	ifi.encode(enc)
+
+	data, err := enc.Encode()
+	if err != nil {
+		return err
+	}
+
+	req := genetlink.Message{
+		Header: genetlink.Header{
+			Command: unix.NL80211_CMD_TRIGGER_SCAN,
+			Version: c.familyVersion,
+		},
+		Data: data,
+	}
+
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+
+	result := make(chan error, 1)
+	go func(ctx context.Context, conn *genetlink.Conn, ifiIndex int, familyVersion uint8, result chan<- error) {
+
+		defer close(result)
+		result <- listenNewScanResults(ctx, conn, ifiIndex, familyVersion)
+
+	}(ctx, conn, ifi.Index, c.familyVersion, result)
+
+	flags := netlink.Request | netlink.Acknowledge
+
+	_, err = conn.Send(req, family.ID, flags)
+	if err != nil {
+		cancel()
+	}
+
+	err2 := <-result
+
+	return errors.Join(err, err2)
+}
+
 // SetDeadline sets the read and write deadlines associated with the connection.
 func (c *client) SetDeadline(t time.Time) error {
 	return c.c.SetDeadline(t)
@@ -295,6 +420,94 @@ func (c *client) execute(
 	)
 }
 
+// listenNewScanResults listens for new scan results or scan abort messages
+// from the netlink connection. It processes the messages associated with the
+// specified interface index and family version, verifying attributes and
+// handling context cancellations.
+//
+// The caller should not receive on the given connection and is responsible
+// for closing it.
+func listenNewScanResults(ctx context.Context, conn *genetlink.Conn, ifiIndex int, familyVersion uint8) error {
+	for ctx.Err() == nil {
+		msgs, _, err := conn.Receive()
+		if err != nil {
+			return err
+		}
+
+		// test for context cancellation and abandon work if so
+		if ctx.Err() != nil {
+			return err
+		}
+
+		for _, msg := range msgs {
+			if msg.Header.Version != familyVersion {
+				break
+			}
+
+			switch msg.Header.Command {
+			case unix.NL80211_CMD_SCAN_ABORTED:
+				return ErrScanAborted
+			case unix.NL80211_CMD_NEW_SCAN_RESULTS:
+				// attempt to verify the interface
+				attrs, err := netlink.UnmarshalAttributes(msg.Data)
+				if err != nil {
+					return errors.Join(ErrScanValidation, err)
+				}
+
+				var intf Interface
+				if err := (&intf).parseAttributes(attrs); err != nil {
+					return errors.Join(ErrScanValidation, err)
+				}
+
+				if ifiIndex != intf.Index {
+					continue
+				}
+
+				return nil
+			default:
+				continue
+			}
+
+		}
+	}
+
+	return ctx.Err()
+}
+
+// parseGetScanResult parses all the BSS from nl80211 CMD_GET_SCAN response messages.
+func parseGetScanResult(msgs []genetlink.Message) ([]*BSS, error) {
+	// reimplementing https://github.com/mdlayher/wifi/pull/79
+	bsss := make([]*BSS, 0, len(msgs))
+	for _, m := range msgs {
+		attrs, err := netlink.UnmarshalAttributes(m.Data)
+		if err != nil {
+			return nil, err
+		}
+
+		var bss BSS
+		for _, a := range attrs {
+			if a.Type != unix.NL80211_ATTR_BSS {
+				continue
+			}
+
+			nattrs, err := netlink.UnmarshalAttributes(a.Data)
+			if err != nil {
+				return nil, err
+			}
+
+			if !attrsContain(nattrs, unix.NL80211_BSS_STATUS) {
+				bss.Status = BSSStatusNotAssociated
+			}
+
+			if err := (&bss).parseAttributes(nattrs); err != nil {
+				continue
+			}
+		}
+		bsss = append(bsss, &bss)
+	}
+	return bsss, nil
+}
+
 // parseInterfaces parses zero or more Interfaces from nl80211 interface
 // messages.
 func parseInterfaces(msgs []genetlink.Message) ([]*Interface, error) {

client_linux_integration_test.go

@@ -4,11 +4,13 @@
 package wifi_test
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"os"
 	"sync"
 	"testing"
+	"time"
 
 	"github.com/mdlayher/wifi"
 )
@@ -78,6 +80,7 @@ func execN(t *testing.T, n int, expect []string, workerID int) {
 					panicf("[worker_id %d; iteration %d] failed to retrieve survey info for device %s: %v", workerID, i, ifi.Name, err)
 				}
 			}
+
 			names[ifi.Name]++
 		}
 	}
@@ -112,3 +115,39 @@ func testClient(t *testing.T) *wifi.Client {
 func panicf(format string, a ...interface{}) {
 	panic(fmt.Sprintf(format, a...))
 }
+
+func TestClient_AccessPoints(t *testing.T) {
+	if os.Geteuid() != 0 {
+		t.Skipf("skipping, must be run as root")
+	}
+
+	c, err := wifi.New()
+	if err != nil {
+		t.Fatalf("failed to create client: %v", err)
+	}
+
+	ifis, err := c.Interfaces()
+	if err != nil {
+		t.Fatalf("failed to retrieve interfaces: %v", err)
+	}
+
+	for _, ifi := range ifis {
+		if ifi.Name == "" || ifi.Type != wifi.InterfaceTypeStation {
+			continue
+		}
+
+		ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(30*time.Second))
+		defer cancel()
+
+		err = c.Scan(ctx, ifi)
+		if err != nil {
+			t.Fatalf("failed to scan access points for device %s: %v", ifi.Name, err)
+		}
+
+		_, err := c.AccessPoints(ifi)
+		if err != nil {
+			t.Fatalf("failed to retrieve access points for device %s: %v", ifi.Name, err)
+		}
+
+	}
+}

client_others.go

@@ -4,6 +4,7 @@
 package wifi
 
 import (
+	"context"
 	"fmt"
 	"runtime"
 	"time"
@@ -21,8 +22,10 @@ func newClient() (*client, error) { return nil, errUnimplemented }
 func (*client) Close() error                                     { return errUnimplemented }
 func (*client) Interfaces() ([]*Interface, error)                { return nil, errUnimplemented }
 func (*client) BSS(_ *Interface) (*BSS, error)                   { return nil, errUnimplemented }
+func (client) AccessPoints(ifi *Interface) ([]*BSS, error)       { return nil, errUnimplemented }
 func (*client) StationInfo(_ *Interface) ([]*StationInfo, error) { return nil, errUnimplemented }
 func (*client) SurveyInfo(_ *Interface) ([]*SurveyInfo, error)   { return nil, errUnimplemented }
+func (*client) Scan(ctx context.Context, ifi *Interface) error   { return errUnimplemented }
 func (*client) Connect(_ *Interface, _ string) error             { return errUnimplemented }
 func (*client) Disconnect(_ *Interface) error                    { return errUnimplemented }
 func (*client) ConnectWPAPSK(_ *Interface, _, _ string) error    { return errUnimplemented }

wifi.go

@@ -239,6 +239,9 @@ const (
 	// BSSStatusAssociated indicates that a client is associated with a BSS.
 	BSSStatusAssociated
 
+	// BSSStatusNotAssociated indicates that a client is not associated with a BSS.
+	BSSStatusNotAssociated
+
 	// BSSStatusIBSSJoined indicates that a client has joined an independent BSS.
 	BSSStatusIBSSJoined
 )
@@ -250,6 +253,8 @@ func (s BSSStatus) String() string {
 		return "authenticated"
 	case BSSStatusAssociated:
 		return "associated"
+	case BSSStatusNotAssociated:
+		return "unassociated"
 	case BSSStatusIBSSJoined:
 		return "IBSS joined"
 	default: