Build and Test a Linux MACsec Link with ip macsec

ip macsec builds an encrypted Ethernet link one piece at a time: device, transmit association, receive association. This guide creates a temporary MACsec device on an existing Ethernet link, adds one transmit and one receive secure association, inspects the result, and removes the test device again. The commands match iproute2 6.1.0-1ubuntu6.4.

Allow about twenty minutes if the parent interface and peer values are ready. You need iproute2, an Ethernet interface you can take responsibility for, and root for the state-changing commands. Use a maintenance window: adding or removing a device can disrupt traffic, and the test keys below are examples only, never use them for production traffic.

1. Check the installed syntax

Start with read-only checks, no elevated privileges needed unless your host restricts network information:

$ ip -V
ip utility, iproute2-6.1.0, libbpf 1.3.0
$ dpkg-query -W -f='${Package} ${Version}\n' iproute2
iproute2 6.1.0-1ubuntu6.4
$ ip macsec help
Usage: ip macsec add DEV tx sa { 0..3 } [ OPTS ] key ID KEY
...

The help output is the fastest way to spot a syntax difference on another release. This installed command accepts 128-bit or 256-bit keys, secure association numbers 0 to 3, packet numbers with pn, and extended packet numbers with xpn.

$ ip -br link
$ PARENT='eth0'
$ ip link show dev "$PARENT"

Swap in the real parent interface. Do not guess it from a tutorial, a wrong parent puts your test on the wrong network entirely.

2. Create the MACsec device

Choose a local device name and a port number. The port is part of the secure channel identifier, so it has to match the peer's design. This example enables encryption and leaves offload disabled, the documented default:

$ DEV='macsec-test0'
$ sudo ip link add link "$PARENT" name "$DEV" type macsec port 11 encrypt on
$ ip link show dev "$DEV"
42: macsec-test0@eth0: <BROADCAST,MULTICAST> mtu 1500 ...

Interface number and flags vary. What matters is that macsec-test0 exists and points at the right parent. Creating it changes kernel network state, so stop here if either value is wrong.

Existing-device error? Pick another name or go look at the current device, do not delete something just to make this example fit.

3. Add a transmit secure association

A secure association needs an association number, a packet number, a key identifier and a key. These values are for a disposable lab test only:

$ TX_SA_ID='01'
$ TX_KEY='81818181818181818181818181818181'
$ sudo ip macsec add "$DEV" tx sa 0 pn 1 on key "$TX_SA_ID" "$TX_KEY"
$ sudo ip macsec show dev "$DEV"
Device macsec-test0
    tx
        0: PN 1, state on, key 01

Output formatting differs between releases and may not show secret material. You should see a transmit association numbered 0, packet number 1, state on.

4. Add a receive channel and association

A receive secure channel identifies the peer by port and MAC address. Swap in the peer's real source address, the example below is just the value from the local manual page, not a discovery mechanism:

$ PEER_PORT='11'
$ PEER_MAC='c6:19:52:8f:e6:a0'
$ sudo ip macsec add "$DEV" rx port "$PEER_PORT" address "$PEER_MAC"
$ sudo ip macsec add "$DEV" rx port "$PEER_PORT" address "$PEER_MAC" sa 0 pn 1 on key 00 "$TX_KEY"
$ sudo ip macsec show dev "$DEV"
Device macsec-test0
    rx port 11 address c6:19:52:8f:e6:a0
        0: PN 1, state on, key 00

In a real two-host setup, the receive key and key identifier have to be coordinated with the peer's transmit configuration. The receive association stays separate from the transmit one even when both sides use the same test key here. Get the peer address, port or key wrong and the config may still be accepted locally, it just will not authenticate any traffic.

5. Inspect without changing anything

Use the device-specific form while troubleshooting:

$ sudo ip macsec show dev "$DEV"
$ ip -d link show dev "$DEV"
$ ip -s link show dev "$DEV"

ip macsec show lists every MACsec device; show dev narrows it to one. The detailed link view confirms parent and attributes, statistics show whether packets are actually moving, though exact counters depend on traffic and kernel support.

The device existing is not proof of working encryption. That also needs a correctly configured peer, matching association details, and traffic that actually exercises the link. The manual frames these commands as debugging and testing tools, and points to 802.1X-2010 with wpa_supplicant for standard key management.

6. Remove the test configuration

$ ip link show dev "$DEV"
$ sudo ip link delete dev "$DEV"
$ ip link show dev "$DEV"
Device "macsec-test0" does not exist.

Deleting the device takes its transmit and receive associations with it. Need to keep a test for later? Leave the device alone and record the values securely instead of deleting it. If you deleted a production device by mistake, stop and follow that system's network recovery procedure rather than repeating cleanup against a guessed name.

Common failure points

• Permission denied. Use sudo for device and association changes. Keep discovery and inspection unprivileged where that works.
• Invalid key. The key must be 128-bit or 256-bit hex, the key identifier a 128-bit hex value. Check the character count without ever printing a real secret.
• Missing peer traffic. Local configuration does not create a peer or negotiate keys. Check the peer's SCI, port, address, cipher and association values.
• Offload confusion. The device starts with offload disabled; the explicit form is sudo ip macsec offload "$DEV" off. phy and mac depend on hardware and driver support, do not enable offload as a guess.
• Extended packet numbers. A device created with cipher gcm-aes-xpn-128 or gcm-aes-xpn-256 needs xpn plus salt and ssci on its associations. Do not mix ordinary pn with an XPN cipher.