path: root/docs/configuration/interfaces/macsec.md

---
lastproofread: '2026-02-13'
---

(macsec-interface)=

# MACsec

MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in
2006\. It enables protocol-independent connectivity between two hosts, providing
data confidentiality, authenticity, and integrity using GCM-AES ciphers. MACsec
operates at the Ethernet layer as a Layer 2 protocol and secures traffic within
Layer 2 networks, including DHCP and ARP requests. It does not compete with
other security solutions, such as IPsec (Layer 3) or TLS (Layer 4), as each
addresses distinct use cases.

## Configuration

### Common interface configuration

```{cmdincludemd} /_include/interface-common-with-dhcp.txt
:var0: macsec
:var1: macsec0
```


### MACsec options

```{cfgcmd} set interfaces macsec \<interface\> security cipher \<gcm-aes-128|gcm-aes-256\>

**Configure the cipher suite for the MACsec interface.**

This configuration parameter is mandatory.
```

```{cfgcmd} set interfaces macsec \<interface\> security encrypt

**Enable encryption on the MACsec interface.**

By default, MACsec interfaces only provide authentication; encryption is
optional.
When enabled, outgoing packets are encrypted using the configured cipher suite.
```

```{cfgcmd} set interfaces macsec \<interface\> source-interface \<physical-source\>

**Configure a physical source interface for the MACsec interface.**

Traffic transmitted through this interface is authenticated and, if configured,
encrypted.
```


#### MACsec key management

**Static** {abbr}`SAK (Secure Authentication Key)` **mode**

In static SAK mode, administrators must manually configure and update SAKs on
each MACsec peer. {abbr}`MKA (MACsec Key Agreement protocol)` cannot be used in
this mode.

```{cfgcmd} set interfaces macsec \<interface\> security static key \<key\>

**Configure the Transmit (TX) SAK for the MACsec interface.**

The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal
string.
```

```{cfgcmd} set interfaces macsec \<interface\> security static peer \<peer\> mac \<mac address\>

**Configure the MAC address associated with the MACsec peer.**
```

```{cfgcmd} set interfaces macsec \<interface\> security static peer \<peer\> key \<key\>

**Configure the RX SAK for traffic from the MACsec peer.**

The key must be a 16-byte (GCM-AES-128) or 64-byte (GCM-AES-256) hexadecimal
string.
```

```{cfgcmd} set interfaces macsec \<interface\> security static peer \<peer\> disable
```

**Dynamic** {abbr}`MKA (MACsec Key Agreement protocol)` **mode**

In this mode, the {abbr}`MKA (MACsec Key Agreement protocol)` protocol is used
to generate, distribute, and update {abbr}`CAKs (MACsec Connectivity
Association Keys)`, and to authenticate MACsec peers.

```{cfgcmd} set interfaces macsec \<interface\> security mka cak \<key\>

**Configure the** {abbr}`CAK (MACsec Connectivity Association Key)` **for the
MACsec interface.**

The {abbr}`CAK (MACsec Connectivity Association Key)` and its {abbr}`CKN
(MACsec Connectivity Association Key Name)` form the pre-shared master key pair
used to authenticate MACsec peers.
```

```{cfgcmd} set interfaces macsec \<interface\> security mka ckn \<key\>

Configure the {abbr}`CKN (MACsec Connectivity Association Key Name)` for the
MACsec interface.
```

```{cfgcmd} set interfaces macsec \<interface\> security mka priority \<priority\>

Configure the MKA key server priority for the MACsec interface.
The peer with the lowest priority is elected as the key server.
```

#### Replay protection

```{cfgcmd} set interfaces macsec \<interface\> security replay-window \<window\>

The replay protection window defines how many out-of-order frames can be
received before they are dropped as a potential replay attack.
The following values are valid:
- ``0``: Any out-of-order frame is immediately dropped.
- ``1-4294967295``: Allows the specified number of out-of-order frames.
```

## Operation

```{opcmd} run generate macsec mka cak \<gcm-aes-128|gcm-aes-256\>

Generate a 128-bit (GCM-AES-128) or 256-bit (GCM-AES-256) {abbr}`MKA (MACsec
Key Agreement protocol)` {abbr}`CAK (MACsec Connectivity Association Key)`.

:::{code-block} none
vyos@vyos:~$ generate macsec mka cak gcm-aes-128
20693b6e08bfa482703a563898c9e3ad
:::
```

```{opcmd} run generate macsec mka ckn

Generate an {abbr}`MKA (MACsec Key Agreement protocol)` {abbr}`CAK (MACsec
Connectivity Association Key)`.

:::{code-block} none
vyos@vyos:~$ generate macsec mka ckn
88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2
:::
```

```{opcmd} show interfaces macsec

Show all MACsec interfaces.

:::{code-block} none
vyos@vyos:~$ show interfaces macsec
17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off
cipher suite: GCM-AES-128, using ICV length 16
TXSC: 005056bfefaa0001 on SA 0
20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off
cipher suite: GCM-AES-128, using ICV length 16
TXSC: 005056bfefaa0001 on SA 0
:::
```

```{opcmd} show interfaces macsec \<interface\>

Show information for a specific MACsec interface.

:::{code-block} none
vyos@vyos:~$ show interfaces macsec macsec1
17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off
cipher suite: GCM-AES-128, using ICV length 16
TXSC: 005056bfefaa0001 on SA 0
:::
```

## Examples

**Site-to-site MACsec with dynamic MKA over an untrusted network**

In the following example, two routers (R1 and R2) are connected via an
untrusted switch, using their `eth1` interfaces as the underlay. The MACsec
interface (`macsec1`) with dynamic MKA encrypts traffic between them.

Topology details:
- R1 IP addresses: `192.0.2.1/24` and `2001:db8::1/64`.
- R2 IP addresses: `192.0.2.2/24` and `2001:db8::2/64`.

**R1**

```none
set interfaces macsec macsec1 address '192.0.2.1/24'
set interfaces macsec macsec1 address '2001:db8::1/64'
set interfaces macsec macsec1 security cipher 'gcm-aes-128'
set interfaces macsec macsec1 security encrypt
set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4'
set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836'
set interfaces macsec macsec1 source-interface 'eth1'
```

**R2**

```none
set interfaces macsec macsec1 address '192.0.2.2/24'
set interfaces macsec macsec1 address '2001:db8::2/64'
set interfaces macsec macsec1 security cipher 'gcm-aes-128'
set interfaces macsec macsec1 security encrypt
set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4'
set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836'
set interfaces macsec macsec1 source-interface 'eth1'
```

Pinging (IPv6) the other host and intercepting traffic on `eth1` confirm that
the content is encrypted.

```none
17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150:
        0x0000:  2c00 0000 000a 0050 56bf efaa 0001 d9fb  ,......PV.......
        0x0010:  920a 8b8d 68ed 9609 29dd e767 25a4 4466  ....h...)..g%.Df
        0x0020:  5293 487b 9990 8517 3b15 22c7 ea5c ac83  R.H{....;."..\..
        0x0030:  4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09  Ln...C..,NiN....
        0x0040:  0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb  .w]S.u..T..Z.f..
        0x0050:  c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b  ..n#..m.2..X...;
        0x0060:  4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669  M..X...../..1..i
        0x0070:  e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e  .:.8.b..(Wj.....
        0x0080:  6b30 92a5 7ccc 720b                      k0..|.r.
```

Disabling encryption on the MACsec interface by removing the `security
encrypt` option shows the unencrypted but authenticated content.

```none
17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150:
        0x0000:  2000 0000 0009 0050 56bf efaa 0001 86dd  .......PV.......
        0x0010:  6009 86f3 0040 3a40 2001 0db8 0000 0000  `....@:@........
        0x0020:  0000 0000 0000 0001 2001 0db8 0000 0000  ................
        0x0030:  0000 0000 0000 0002 8100 d977 0f30 0003  ...........w.0..
        0x0040:  1ca0 c65e 0000 0000 8d93 0b00 0000 0000  ...^............
        0x0050:  1011 1213 1415 1617 1819 1a1b 1c1d 1e1f  ................
        0x0060:  2021 2223 2425 2627 2829 2a2b 2c2d 2e2f  .!"#$%&'()*+,-./
        0x0070:  3031 3233 3435 3637 87d5 eed3 3a39 d52b  01234567....:9.+
        0x0080:  a282 c842 5254 ef28                      ...BRT.(
```

**Site-to-site MACsec with static SAK over an untrusted network**

This example uses the same topology as above, but applies static SAK mode to
the MACsec interface configuration.

**R1**

```none
set interfaces macsec macsec1 address '192.0.2.1/24'
set interfaces macsec macsec1 address '2001:db8::1/64'
set interfaces macsec macsec1 security cipher 'gcm-aes-128'
set interfaces macsec macsec1 security encrypt
set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02
set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
set interfaces macsec macsec1 source-interface 'eth1'
```

**R2**

```none
set interfaces macsec macsec1 address '192.0.2.2/24'
set interfaces macsec macsec1 address '2001:db8::2/64'
set interfaces macsec macsec1 security cipher 'gcm-aes-128'
set interfaces macsec macsec1 security encrypt
set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
set interfaces macsec macsec1 security static peer R1 mac 00:11:22:33:44:01
set interfaces macsec macsec1 security static peer R1 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
set interfaces macsec macsec1 source-interface 'eth1'
```

## MACsec over WAN

MACsec offers an alternative to traditional tunneling solutions by securing
Layer 2 with integrity, origin authentication, and optional encryption.

While typically deployed between hosts and access switches, MACsec can also
secure traffic over a WAN. In the following example, we combine VXLAN (for
transport) and MACsec (for security) to create a secure tunnel between two
sites.

**R1 MACsec01**

```none
set interfaces macsec macsec1 address '192.0.2.1/24'
set interfaces macsec macsec1 address '2001:db8::1/64'
set interfaces macsec macsec1 security cipher 'gcm-aes-128'
set interfaces macsec macsec1 security encrypt
set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
set interfaces macsec macsec1 security static peer SEC02 key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
set interfaces macsec macsec1 security static peer SEC02 mac '00:11:22:33:44:02'
set interfaces macsec macsec1 source-interface 'vxlan1'
set interfaces vxlan vxlan1 mac '00:11:22:33:44:01'
set interfaces vxlan vxlan1 remote '10.1.3.3'
set interfaces vxlan vxlan1 source-address '172.16.100.1'
set interfaces vxlan vxlan1 vni '10'
set protocols static route 10.1.3.3/32 next-hop 172.16.100.2
```

**R2 MACsec02**

```none
set interfaces macsec macsec1 address '192.0.2.2/24'
set interfaces macsec macsec1 address '2001:db8::2/64'
set interfaces macsec macsec1 security cipher 'gcm-aes-128'
set interfaces macsec macsec1 security encrypt
set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
set interfaces macsec macsec1 security static peer SEC01 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
set interfaces macsec macsec1 security static peer SEC01 mac '00:11:22:33:44:01'
set interfaces macsec macsec1 source-interface 'vxlan1'
set interfaces vxlan vxlan1 mac '00:11:22:33:44:02'
set interfaces vxlan vxlan1 remote '10.1.2.2'
set interfaces vxlan vxlan1 source-address '172.16.100.2'
set interfaces vxlan vxlan1 vni '10'
set protocols static route 10.1.2.2/32 next-hop 172.16.100.1
```