DokuWiki

This is an old revision of the document!

====== MACsec explained ======

===== The idea in one paragraph =====

MACsec encrypts **one Ethernet hop** (port to port). It has two parts:

MKA (MACsec Key Agreement) is the control plane. The two ends prove they share a secret, elect one of them as the boss (the Key Server, KS), and that boss hands out the actual traffic key.

MACsec proper is the data plane. Every frame gets encrypted, signed and numbered with that key.

*Keep these apart when troubleshooting.** MKA can look perfectly healthy while the data plane is dropping everything.

===== 1. The keys: three layers, each made from the one above =====

^ Term ^ Plain English ^ Lifetime ^

| **CAK** (Connectivity Association Key) | The master password. It's either pre-shared (configured in a key chain) or comes from 802.1X. It never encrypts traffic itself. | Until   you change the config |

| **CKN** (CAK Name) | The "username" that goes with that password. It's sent in clear text so the peer knows which CAK to use. Both ends must hold the same CKN/CAK pair. | Same as  the CAK |

| **ICK / KEK** | Two keys made automatically from the CAK. The **ICK** signs MKA messages so they can't be forged. The **KEK** encrypts the SAK when the Key Server sends it to the  peer. You never configure them. | Same as the CAK |

| **SAK** (Secure Association Key) | **The key that actually encrypts traffic.** The Key Server generates it at random and delivers it wrapped in the KEK. | One rekey period |

In short: **CKN says which password. The CAK proves who you are. The SAK encrypts the traffic.**

A key chain can hold more than one CKN/CAK pair. That's normally used for hitless CAK rollover. Only one is the live session at a time.

===== 2. Who's who: the identifiers =====

^ Term ^ Plain English ^

| **CA** (Connectivity Association) | The "club" of ports holding the same CAK. On a point-to-point link that's just the two ends. **A CA rebuild means the session is torn down and  rebuilt from scratch.** |

| **SC** (Secure Channel) | **One direction** of traffic. Each sender has its own SC, so a link has two, one per direction. That's why MACsec faults can be one-way only. |

| **SCI** (SC Identifier) | The SC's name tag: the sender's **MAC address (6 bytes) + port ID (2 bytes)** = 8 bytes. |

| **SA** (Secure Association) | One SAK being used on one SC. Each rekey creates a new SA. |

| **AN** (Association Number) | The **slot number** of an SA. It's a 2-bit field, so only **0 to 3**. AN + SCI identifies the SA. Rekey #5 reuses slot 0, #6 reuses slot 1, and so  on. Having 4 slots is what lets the new key overlap the old one during a rekey. |

| **KN** (Key Number) | MKA's running count of SAKs: 1, 2, 3 and upwards. Typically **AN = (KN-1) mod 4**. If KN drops back to 1, the CA was rebuilt. |

| **KS** (Key Server) | The elected boss that generates and distributes SAKs. Lowest ''key-server priority'' wins, with the lowest SCI as tie-break. "Non-KS" in logs means "I'm not  the boss". |

| **MKPDU** | An MKA protocol message. Peers exchange one about every 2 s, and the session dies after about 6 s without one. If a carrier in the path swallows them, MKA never comes  up. |

===== 3. What's added to every frame =====

<code>

DA | SA | SecTAG | encrypted payload | ICV

</code>

SecTAG sits in front of the payload. It carries the AN (which key slot), the PN (which frame number) and optionally the SCI. It adds about 16 bytes.

ICV (Integrity Check Value) is the 16-byte signature. A bad ICV means a wrong key or a tampered frame, and it shows up in the “not valid” counters.

Cipher suite: the algorithm, e.g. aes256-gcm-xpn. Both ends must agree.

===== 4. Packet numbers and replay protection =====

^ Term ^ Plain English ^

| **PN** (Packet Number) | A frame counter, **32 bits**, that **restarts at 1 with every new SAK**. It stops an attacker re-sending a recorded frame. |

| **XPN** (Extended PN) | The same counter at **64 bits**. **Only the low 32 bits go on the wire**, and the receiver works out the upper 32 bits itself. |

| **Replay window** | How far **behind** the highest PN seen a frame may arrive and still be accepted. **0** means strict in-order only, which drops legitimate frames that QoS  queues have reordered. |

| **Lowest acceptable PN** | The highest PN seen minus the window. Anything below it is dropped as **"late"**. |

| **SSCI / salt** | XPN-only extras. They're a compact SCI and a random value from MKA, used to build the encryption nonce. Invisible to you. |

*Why XPN matters:** what matters is packet rate, not link speed. A 32-bit counter allows about 4.3 billion frames per key. At 10G with minimum-size frames that's used up in 5-7 minutes, which forces a rekey long before a typical hourly timer. XPN removes that limit, so it matters at 10G too, not only at 40G+.

===== 5. The knobs you'll actually touch =====

^ Knob ^ Effect ^

| ''rekey-period'' | How often a new SAK is made. Very short periods mean rapid rekeys, and each one is a chance for something to go wrong. |

| ''replay protection window'' | The window size above. On some platforms changing it rebuilds the CA, which means a few seconds of blocked traffic and routing protocol flaps. Treat  it as disruptive. |

| ''key-server priority'' | Decides which end is the boss. |

| ''traffic unprotected drop'' / ''should-secure'' vs ''must-secure'' | What happens to traffic with no live SA. "Drop" or "must" means a blackhole rather than sending in clear  text. |

| ''confidentiality offset'' | Leaves the first 0/30/50 bytes unencrypted (for load balancers that need to see headers). Normally 0. |

===== 6. How a session comes up =====

Both ends send MKPDUs using the CKN. Each checks the other's ICK signature, which proves they have the same CAK. Now they're peers.

They elect the Key Server.

The KS generates a SAK, wraps it with the KEK and sends it.

Both install it in slot AN: the receive side first, then transmit. Traffic is now encrypted, starting from PN 1.

At each rekey: a new SAK goes into the next AN slot, the KN goes up by one, the PN restarts at 1, and the old slot is retired.