Initial commit

Author: Brendan Jackman

.gitignore

@@ -0,0 +1,7 @@
+.eggs/
+bwt_uapi.h
+*.egg-info
+.tox/
+build/
+**/__pycache__/
+*.pyc

LICENSE.txt

@@ -0,0 +1,37 @@
+# Python library for Generic Netlink
+
+At [Blu Wireless](https://bluwireless.com/) we needed a tool for doing NL80211
+interactions in Python test code. We couldn't find any libraries that facilitate
+this in a way that leverages the strengths of Python, so we wrote
+something. Most of the original code was specific to Blu Wireless' technology,
+but the generic stuff was pulled out to create this library.
+
+Netlink and Generic Netlink themselves aren't very complicated, but the
+attribute system can result in reams of boilerplate code. The aim of this
+library is to reduce that boilerplate. The key observation is that for
+some/most/all genl families, given knowledge about which attributes appear in
+which context and what type their payload should have, attribute sets can be
+mapped to Python dictionaries. So to use this library you provide a _schema_
+expressing that knowledge about attribute semantics in the protocol you're
+using, and it gives you an ergonomic way to build and parse messages.
+
+The best way to see what this really means is to take a look at nl80211.py,
+where we define an example schema for NL80211 commands, and
+examples/nl80211_dump.py, which uses that schema to query NL80211 for
+information about a given WiFi adapter.
+
+Works on both Python 2 and 3.
+
+## Known limitations
+
+- It would make sense for this library to help you build and parse multi-part
+  Netlink messages, but it doesn't.
+
+- The library niftily maps between full-length attribute names and short Python
+  names (e.g. `msg["NL80211_ATTR_IFINDEX"]` can be rewritten as
+  `msg.ifindex`). But this doesn't work fully for nested attributes,
+  e.g. `msg["NL80211_ATTR_KEY"]["NL80211_KEY_DEFAULT"]` cannot be rewritten as
+  `msg.key.default`.
+
+- No HTML documentation. There are docstrings in the code, though. The most
+  interesting bit is `nlattr.NlAttrSchema`.

README.md

@@ -0,0 +1,12 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[dev-packages]
+
+[packages]
+"a571e24" = {path = "./py-genl"}
+
+[requires]
+python_version = "3.6"

examples/Pipfile

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+
+# SPDX-License-Identifier: GPL-2.0
+# Copyright (c) 2019 Blu Wireless Technology
+
+"""
+Example program to dump a wireless interface info from nl80211
+
+Pass interface name as sole argument
+"""
+
+from sys import argv
+import socket
+
+from genl.nl80211 import nl80211_schema, NL80211_CMD_GET_INTERFACE
+from genl import lookup_genl_family, if_nametoindex
+from genl.netlink import (get_genl_message, parse_genl_message,
+                          NETLINK_GENERIC, NLM_F_REQUEST)
+
+
+def main():
+    # We need to look up the family ID which will go in the nl header's type
+    # field. This also gives us the IDs we'd need to subscribe the socket to any
+    # broadcast groups exposed by the family.
+    family = lookup_genl_family("nl80211")
+
+    sock = socket.socket(socket.AF_NETLINK, socket.SOCK_RAW, NETLINK_GENERIC)
+    sock.bind((0, 0))
+
+    # We use get_genl_message to build a Generic Netlink message. The nl80211
+    # command goes in the cmd field of the genl header.
+    # The payload is built using the canned nl0211 schema, using kwargs to
+    # specify the attribute values used to express command params.
+    # We could instead pass a dict, in which case we'd use the full attribute
+    # names instead of shortened Pythonic names, e.g. instead of ifindex=foo
+    # we could pass {"NL80211_ATTR_IFINDEX": foo}.
+    msg = get_genl_message(
+        mtype=family.id,
+        flags=NLM_F_REQUEST,
+        cmd=NL80211_CMD_GET_INTERFACE,
+        payload=nl80211_schema.build(ifindex=if_nametoindex(argv[1])))
+    sock.send(msg)
+
+    # Note the fixed size receive. This library lacks support for multi-part
+    # messages.
+    msg = sock.recv(8192)
+    # Parse out the nl and genl header
+    nl_header, genl_header, payload = parse_genl_message(msg)
+    # Now we use the same canned schema to parse then attributes in the reply
+    # payload
+    info = nl80211_schema.parse(payload)
+
+    # The attributes can be accessed like a dict; in this case the keys are the
+    # full attribute names. For exmple if your WiFi is connected to a network ,
+    # these prints will include a line something like:
+    #   NL80211_ATTR_SSID = Darude-LANStorm
+    print("Raw data:")
+    for key in info:
+        print("  {} = {}".format(key, info[key]))
+
+    # Then for convenience we can also access the attributes as Python
+    # attributes using nicer names. The nl80211 schema (see nl80211.py) doesn't
+    # specify the names for the Python attributes, so we get the default
+    # behaviour, which is that the Python names are determined by finding the
+    # full name's unique suffix amongst its siblings and lower-casing it.
+    # So instead of info["NL80211_ATTR_SSID"] we can just access info.ssid.
+    print("\nname: '{}' | MAC: {} | Current SSID: '{}'".format(
+        info.ifname,
+        ":".join("{:02x}".format(b) for b in info.mac),
+        info.ssid))
+
+if __name__ == "__main__":
+    main()

examples/Pipfile.lock

@@ -0,0 +1 @@
+..

examples/nl80211_dump.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: GPL-2.0
+# Copyright (c) 2019 Blu Wireless Technology
+
+import ctypes
+import ctypes.util
+from collections import namedtuple
+import socket
+import os
+import errno
+
+from .nlattr import NlAttrSchema
+from .netlink import (NLM_F_REQUEST,
+                      GENL_ID_CTRL, GNL_FAMILY_VERSION,
+                      NETLINK_GENERIC,
+                      NetlinkError,
+                      get_genl_message,
+                      parse_genl_message)
+
+
+# From linux/genetlink.h
+CTRL_CMD_GETFAMILY = None  # To relax the linter
+genl_ctrl_constants = {
+    "CTRL_CMD_GETFAMILY": 3,
+    "CTRL_ATTR_FAMILY_ID": 1,
+    "CTRL_ATTR_FAMILY_NAME": 2,
+    "CTRL_ATTR_MCAST_GROUPS": 7,
+    "CTRL_ATTR_MCAST_GRP_NAME": 1,
+    "CTRL_ATTR_VERSION": 3,
+    "CTRL_ATTR_HDRSIZE": 4,
+    "CTRL_ATTR_MAXATTR": 5,
+    "CTRL_ATTR_OPS": 6,
+    "CTRL_ATTR_MCAST_GRP_ID": 2,
+}
+globals().update(genl_ctrl_constants)
+
+
+# We'll need to use the GETFAMILY command, which is part of the core generic
+# netlink system, to query the system's IDs for nl80211. Define a schema for
+# that.
+getfamily_spec = [
+    {
+        "name": "CTRL_ATTR_FAMILY_ID",
+        "type": "u16",
+    },
+    {
+        "name": "CTRL_ATTR_FAMILY_NAME",
+        "type": "str"
+    },
+    {
+        "name": "CTRL_ATTR_VERSION",
+        "type": "u32",
+    },
+    {
+        "name": "CTRL_ATTR_HDRSIZE",
+        "type": "u32",
+    },
+    {
+        "name": "CTRL_ATTR_MAXATTR",
+        "type": "u32",
+    },
+    {
+        "name": "CTRL_ATTR_OPS",
+        "type": "bytes",  # Actually a nested thing, don't care about it.
+    },
+    {
+        "name": "CTRL_ATTR_MCAST_GROUPS",
+        "type": "list",
+        "subelem_type": [
+            {
+                "name": "CTRL_ATTR_MCAST_GRP_NAME",
+                "type": "str"
+            },
+            {
+                "name": "CTRL_ATTR_MCAST_GRP_ID",
+                "type": "u32"
+            }
+        ],
+    }
+]
+getfamily_schema = NlAttrSchema.from_spec(getfamily_spec, genl_ctrl_constants)
+
+
+GenlFamilyInfo = namedtuple("GenlFamilyInfo", ["id", "mcast_groups"])
+
+
+def lookup_genl_family(family_name):
+    """
+    Look up a generic netlink family by name
+
+    Returns a GenlFamilyInfo with the numerical family ID and the IDs of the
+    multicast groups it exposes
+    """
+    cmd = get_genl_message(
+        mtype=GENL_ID_CTRL,
+        flags=NLM_F_REQUEST,
+        cmd=CTRL_CMD_GETFAMILY,
+        version=GNL_FAMILY_VERSION,
+        payload=getfamily_schema.build(family_name=family_name))
+
+    sock = socket.socket(socket.AF_NETLINK, socket.SOCK_RAW, NETLINK_GENERIC)
+    try:
+        sock.bind((0, 0))
+        sock.sendall(cmd)
+        data = sock.recv(4096)
+        nl_header, genl_header, genl_body = parse_genl_message(data)
+        response = getfamily_schema.parse(genl_body)
+
+        mcast_groups = {}
+        for entry in response["CTRL_ATTR_MCAST_GROUPS"]:
+            group_name = entry["CTRL_ATTR_MCAST_GRP_NAME"].strip()
+            mcast_groups[group_name] = entry["CTRL_ATTR_MCAST_GRP_ID"]
+
+        return GenlFamilyInfo(response["CTRL_ATTR_FAMILY_ID"], mcast_groups)
+    finally:
+        sock.close()
+
+
+# Make if_nametoindex(3) and if_indextoname(3) from libc available (for newer
+# Pythons this is in the standard library anyway).
+_libc = ctypes.CDLL(ctypes.util.find_library("c"), use_errno=True)
+_if_nametoindex = _libc.if_nametoindex
+_if_nametoindex.argtypes = [ctypes.c_char_p]
+_if_nametoindex.restype = ctypes.c_uint
+
+_if_indextoname = _libc.if_indextoname
+_if_indextoname.argtypes = [ctypes.c_uint, ctypes.c_char_p]
+_if_indextoname.restype = ctypes.c_char_p
+
+IF_NAMESIZE = 16
+
+
+def if_nametoindex(name):
+    index = _if_nametoindex(name.encode("ascii"))
+
+    if index == 0:
+        op_errno = ctypes.get_errno()
+        if op_errno == errno.ENODEV:
+            raise NetlinkError("no interface called '%s'" % name)
+        else:
+            raise OSError(op_errno, os.strerror(op_errno))
+
+    return index
+
+
+def if_indextoname(index):
+    name = _if_indextoname(index, b" " * IF_NAMESIZE)
+
+    if not name:
+        op_errno = ctypes.get_errno()
+        if op_errno == errno.ENXIO:
+            raise NetlinkError("no interface with index %d" % index)
+        else:
+            raise OSError(op_errno, os.strerror(op_errno))
+
+    return name.decode("ascii")