MACsec
A cable can be tapped, and a frame can be changed or sent twice. MACsec signs every frame and numbers it. See the tag go in, and the window that stops a replay.
You Will Be Able To
- Name the parts of a protected frame and the fields of the SecTAG.
- Say what the ICV covers and what encryption hides.
- Explain secure channels, secure associations and the packet number.
- Follow the receive checks in order, and tell which count each outcome adds to.
- Lesson
- P11.46
- Time
- 45 min
- Runs on
- Your browser
- Check
- 5 questions
Someone taps the cable between two switches. Now every frame can be read, changed, or recorded and sent again.
MACsec stops all three, between two ports that share a key.
- Neutral
- Data
- Before
Two addresses and the User Data, which starts with the EtherType.
- The addresses stay
A switch must still read them.
- A tag goes in
The SecTAG names the key and carries a packet number.
- The data
The User Data, as it was or encrypted.
- A check value
The ICV covers addresses, tag and data. The MAC adds a new FCS.
Read the diagram as text
- Addresses: 12 octets
- User Data: 48 octets here
- Addresses: unchanged
- SecTAG: 8 or 16 octets
- Secure Data: plain or encrypted
- ICV: 16 octets, over all three
- Addresses → Addresses
- User Data → Secure Data: through the cipher
- Secure Data → ICV
- SecTAG → Secure Data
After IEEE Std 802.1AE-2018 Figure 9-1. Bench run: 60 octets became 92.
What MACsec Protects
MACsec is IEEE 802.1AE. It sits just above the MAC of a port.
| Service | Meaning | By |
|---|---|---|
| Integrity | a changed frame is noticed | the ICV |
| Origin | only a holder of the key can have sent it | the ICV |
| Confidentiality (optional) | the User Data cannot be read on the line | encryption |
| Replay protection | a frame that is sent again is refused | the packet number |
IEEE Std 802.1AE-2018 6.9.
The keys come from key agreement: MKA of IEEE 802.1X, software outside this lesson.
Channels and Associations
- Neutral
- I/O
- Channel / handshake
- Transaction / TLM
- Structure
- A secure channel
A secure channel (SC) runs one way, from one sender.
- One for each sender
B has its own. Each channel has an identifier, the SCI.
- A secure association
An SA is one key on a channel, with its packet numbers.
- Changing the key
A new SA with another association number takes over.
Read the diagram as text
- SA, AN 0: a key and its packet numbers
- SA, AN 1: the next key
- Station A: SecY and key agreement
- SC of A: SCI: address of A, port
- Station B: SecY and key agreement
- SC of B: SCI: address of B, port
- Station A → SC of A: sends on
- SC of A → Station B: A to B
- Station B → SC of B: sends on
- SC of B → Station A: B to A
- SC of A → SA, AN 0: uses
- SA, AN 0 → SA, AN 1: then
After IEEE Std 802.1AE-2018 Figure 7-3.
The SCI of a channel has 64 bits: the sender's MAC address and a 16-bit port number (7.1.2).
The key of an SA is the SAK. The 2-bit association number (AN) tells the SAs of a channel apart (9.6).
A receiver holds two SAs for each channel: the one in use and the next.
The SecTAG, Field by Field
| Octets of the SecTAG | Field | Holds |
|---|---|---|
| 1 and 2 | MACsec EtherType | 88-E5 |
| 3, bits 8 to 3 | TCI | six flag bits |
| 3, bits 2 and 1 | AN | the association number, 0 to 3 |
| 4, bits 6 to 1 | SL | the short length; bits 8 and 7 are 0 |
| 5 to 8 | PN | the packet number, 32 bits |
| 9 to 16 | SCI | optional: 6 octets of address, 2 of port number |
IEEE Std 802.1AE-2018 Figure 9-2. Bit 8 is the top bit of an octet.
The tag starts with its own EtherType (Table 9-1). The original one now opens the Secure Data.
Without the SCI the tag has 8 octets. With it, 16.
Between two stations the SCI can be left out: the receiver knows it from key agreement (9.9).
The Flag Bits
| Bit of octet 3 | Name | Set when |
|---|---|---|
| 8 | V | never: the version is 0 |
| 7 | ES | the SCI is the source address with port number 1 |
| 6 | SC | the SCI is in the tag |
| 5 | SCB | an EPON single copy broadcast channel |
| 4 | E | the User Data is encrypted |
| 3 | C | the Secure Data is not the plain User Data, or the ICV is not 16 octets |
| 2 and 1 | AN | the association number |
IEEE Std 802.1AE-2018 9.5 and 9.6.
ES and SCB save the 8 octets of the SCI. With either one set, SC is clear.
E and C both clear: plain data and a 16-octet ICV. Both set: encrypted data.
E set with C clear is reserved. Such a frame is discarded (10.6).
| SCI in the tag | useES | useSCB | Confidential | Octet 3 | SecTAG |
|---|---|---|---|---|---|
| yes | no | no | no | 00100000 | 16 octets |
| no | yes | no | no | 01000000 | 8 octets |
| no | no | yes | no | 00010000 | 8 octets |
| no | yes | yes | no | 01010000 | 8 octets |
| no | no | no | no | 00000000 | 8 octets |
| yes | no | no | yes | 00101100 | 16 octets |
| no | no | no | yes | 00001100 | 8 octets |
Bench run of eth_macsec, AN 0. Rows 1 to 4 are columns of Table 10-1.
Short Frames and the Growth of a Frame
Ethernet pads a short frame, and the receiver must still find the ICV.
So the Short Length (SL) gives the size of the Secure Data if it is below 48 octets, else 0 (9.7).
| User Data | SCI in the tag | SL | Frame before | Frame after | Growth |
|---|---|---|---|---|---|
| 2 octets | yes | 2 | 14 octets | 46 octets | 32 octets |
| 47 octets | yes | 47 | 59 octets | 91 octets | 32 octets |
| 48 octets | yes | 0 | 60 octets | 92 octets | 32 octets |
| 49 octets | yes | 0 | 61 octets | 93 octets | 32 octets |
| 100 octets | yes | 0 | 112 octets | 144 octets | 32 octets |
| 1,500 octets | yes | 0 | 1,512 octets | 1,544 octets | 32 octets |
| 47 octets | no | 47 | 59 octets | 83 octets | 24 octets |
| 100 octets | no | 0 | 112 octets | 136 octets | 24 octets |
Bench run of eth_macsec, integrity only, sizes without the FCS.
The frame grows by 32 octets with the SCI, and by 24 without.
A frame near the size limit may become too large. If the port cannot send it, it is discarded (8.3 NOTE 1).
What Is Checked and What Is Hidden
The ICV covers both addresses, the whole SecTAG and the data (9.11, 8.3).
Encryption hides the User Data only. The addresses and the tag stay readable.
In the bench, integrity only changed 0 of 48 data octets. Confidentiality changed 48 of 48.
An older option, the confidentiality offset, leaves the first 30 or 50 data octets readable (10.7.25).
It let early hardware see the IP header. The XPN cipher suites do not have it.
The Cipher, and Our Stand-In
The default cipher suite is GCM-AES-128 (14.5).
| Input of GCM | Integrity only | With confidentiality |
|---|---|---|
| K, the key | the SAK, 128 bits | the SAK, 128 bits |
| IV, 96 bits | the SCI, then the PN | the SCI, then the PN |
| A, checked only | both addresses, the SecTAG, the User Data | both addresses, the SecTAG |
| P, encrypted and checked | nothing | the User Data |
| T, the tag GCM returns | the ICV, 16 octets | the ICV, 16 octets |
IEEE Std 802.1AE-2018 14.5. The names are those of NIST SP 800-38D.
The SCI goes into the IV even when the tag does not carry it.
This bench has no AES. Its check value comes from toy_icv, a small mixing function of ours.
It takes the same inputs: key, SCI, PN and every octet. It gives no security at all.
It only shows what the ICV covers.
| What changed on the way | Does the ICV still fit? |
|---|---|
| nothing | yes |
| one bit of the destination address | no |
| one bit of the source address | no |
| one bit of the TCI | no |
| one bit of the PN | no |
| one bit of the SCI in the tag | no |
| one bit of the data | no |
| one bit of the ICV | no |
| the receiver has another key | no |
| no SCI in the tag, and the receiver expects another channel | no |
Bench run of eth_macsec with its stand-in check value. This is not AES.
A Packet Number Never Repeats Under One Key
The sender puts nextPN into the tag and adds 1 (10.5.2).
A PN is never 0 and never used twice with one key (14.1). GCM breaks if an IV repeats.
So the port stops sending when the 32-bit PN runs out.
In the bench the PN ffffffff was the last one. The third frame was not sent.
Key agreement asks for a fresh key long before: at PN 0xC000 0000 (8.2.7).
At 100 Gb/s, frames of 64 octets use up a 32-bit PN in about 29 seconds.
Extended packet numbering (XPN) makes the PN 64 bits.
The tag still carries 32 bits. The receiver takes the upper half from its lowest acceptable PN (10.6.2).
| PN field in the tag | Lowest acceptable PN | PN the receiver uses |
|---|---|---|
| 0x2A2B 5051 | 0x0000 0007 1234 DEF0 | 0x0000 0007 2A2B 5051 |
| 0x2A2B 5051 | 0x0000 0007 8234 DEF0 | 0x0000 0008 2A2B 5051 |
| 0x9A2B 5051 | 0x0000 0007 8234 DEF0 | 0x0000 0007 9A2B 5051 |
| 0x9A2B 5051 | 0x0000 0007 2234 DEF0 | 0x0000 0007 9A2B 5051 |
Bench run of xpn_recover on the four examples of Table 10-2.
With XPN the IV is built from a short channel number (SSCI) and a salt (14.7).
The Receive Checks, in Order
A receiver checks the tag (9.12) and finds the SA from SCI and AN (10.6.1). Then come these tests.
| Order | Test | The frame is | Count |
|---|---|---|---|
| 1 | replayProtect is on and the PN is below the lowest acceptable PN | discarded | InPktsLate |
| 2 | the frame is not valid, and validateFrames is Strict or the C bit is set | discarded | InPktsNotValid |
| 3 | the frame is not valid, and validateFrames is Check | delivered | InPktsInvalid |
| 4 | the PN is below the lowest acceptable PN | delivered | InPktsDelayed |
| 5 | the frame is not valid | delivered | InPktsUnchecked |
| 6 | none of these | delivered | InPktsOK |
IEEE Std 802.1AE-2018 10.6.2 to 10.6.5, Figure 10-4. The first test that holds decides.
Valid means: the cipher was asked, and the ICV fits.
Three controls steer this: validateFrames, replayProtect and replayWindow (10.7.8).
A late frame counts as late, whatever its ICV says.
The standard makes the late test before and after the cipher. Our model makes it once.
The Replay Window
An SA keeps nextPN and the lowest acceptable PN (10.7.14).
A valid frame with a PN of nextPN or more sets nextPN to that PN plus 1 (10.6.5).
The lowest acceptable PN follows at nextPN minus replayWindow. It never goes down.
- Frame 0
A new SA. PN 1 and PN 2 come in order.
- Frame 2
PN 5 jumps ahead: nextPN 6, lowest acceptable PN 6 − 3 = 3.
- Frame 3
PN 3 and then PN 4 are inside the window: delivered.
- Frame 5
PN 5 again, also inside the window: delivered twice.
- Frame 6
PN 9 moves the lowest acceptable PN to 7.
- Frame 7
PN 6 and then PN 5 are below it: discarded, InPktsLate.
- Frame 9
PN 9 again is accepted.
Bench run of a private model: Strict, replayProtect on, replayWindow 3.
A window of 0 means strict order: a frame that was overtaken is lost.
Inside a window, a copy of a frame is accepted (10.4).
| PN | Window 0 | Window 3 | replayProtect off |
|---|---|---|---|
| 1 | OK | OK | OK |
| 2 | OK | OK | OK |
| 5 | OK | OK | OK |
| 3 | Late | OK | Delayed |
| 4 | Late | OK | Delayed |
| 5 | Late | OK | Delayed |
| 9 | OK | OK | OK |
| 6 | Late | Late | Delayed |
| 5 | Late | Late | Delayed |
| 9 | Late | OK | Delayed |
| 10 | OK | OK | OK |
Bench run of a private model: one stream of valid frames. Late is discarded, Delayed is delivered.
With replayProtect off, old frames are only counted.
Key agreement may raise both numbers of an SA. It can never lower them (10.7.15).
Only a Valid Frame Moves the Window
An attacker sends a frame with a huge PN and a wrong ICV.
If that moved nextPN, every real frame after it would be late.
So only a valid frame moves nextPN (10.6.5).
| validateFrames | PN 1 | PN 4,000,000,000 with a wrong ICV | nextPN after it | PN 2 |
|---|---|---|---|---|
| Strict | OK | NotValid | 2 | OK |
| Check | OK | Invalid | 2 | OK |
| Disabled | Unchecked | Unchecked | 1 | Unchecked |
Bench run of a private model: replayProtect on, window 0.
In Disabled no frame is valid, so nextPN never moves.
Strict, Check and Disabled
validateFrames lets an operator bring MACsec up step by step (10.4).
| validateFrames | ICV fits | ICV wrong, C clear | ICV wrong, C set |
|---|---|---|---|
| Strict | OK, delivered | NotValid, discarded | NotValid, discarded |
| Check | OK, delivered | Invalid, delivered | NotValid, discarded |
| Disabled | Unchecked, delivered | Unchecked, delivered | NotValid, discarded |
Bench run of a private model, for a frame in order.
| validateFrames | A tagged frame that is not valid | A frame without a SecTAG |
|---|---|---|
| Strict (default) | discarded | discarded, InPktsNoTag |
| Check | counted and delivered, unless C is set | delivered, InPktsUntagged |
| Disabled | the cipher is not asked: no frame is valid | delivered, InPktsUntagged |
| Null | not looked at: every frame is delivered as it came | delivered as it came |
IEEE Std 802.1AE-2018 10.6, 10.7.8 and Figure 10-4.
A frame with the C bit set is of no use without the cipher. If it is not valid, it is always discarded.
Try It
eth_macsec is the transmit side of one secure channel, with a stand-in for the cipher.
load builds the frame to protect: two addresses, a type and 46 data octets. That is 60 octets.
protect puts the SecTAG after the source address and the ICV at the end: 92 octets.
The tag reads 88 e5, then 20: the SC bit alone. The SL is 0, because the Secure Data has 48 octets.
Then the PN, 1, in four octets, and the SCI in eight.
tag_check runs the tests of 9.12 that need no key. validate is the receiver's check of the ICV.
The last two lines flip one bit of the data. The check value no longer fits.
The check value is not AES. The receive checks with the replay window are the practice problem.
Set m.include_sci = 0 before protect. Predict the two frame sizes and the third octet of the tag.
before: 60 octets after: 92 octets SecTAG: 88 e5 20 00 00 00 00 01 02 00 00 00 00 01 00 01 TCI and AN 00100000, SL 0, PN 1 Secure Data from octet 28, ICV from octet 76 receiver: tag check 0, ICV fits 1 one bit changed: ICV fits 0Read included file: hs_pkg.sv
`timescale 1ns/1ns
// hs_pkg.sv: shared pure functions, and the bench random generator (read-only).
package hs_pkg;
// xorshift32 (Marsaglia 2003): a linear generator over GF(2), period 2^32 - 1. A zero state is
// replaced by 1, because zero maps to itself.
function automatic [31:0] xs32(input [31:0] s);
reg [31:0] x;
x = (s == 32'd0) ? 32'd1 : s;
x = x ^ (x << 13); x = x ^ (x >> 17); x = x ^ (x << 5);
return x;
endfunction
// A Fibonacci PRBS generator x^n + x^m + 1 (PRBS7: 7,6; PRBS9: 9,5; PRBS15: 15,14; PRBS23: 23,18;
// PRBS31: 31,28). The output bit is s[n-1]; the next state shifts the feedback into bit 0.
function automatic [31:0] prbs_next(input [31:0] s, input int n, input int m);
reg fb;
fb = s[n-1] ^ s[m-1];
return ((s << 1) | {31'd0, fb}) & ((n == 32) ? 32'hffffffff : ((32'd1 << n) - 32'd1));
endfunction
function automatic int ones(input [63:0] v);
int n; n = 0;
for (int i = 0; i < 64; i++) n += v[i];
return n;
endfunction
// GF(16) with x^4 + x + 1, and GF(1024) with x^10 + x^3 + 1: shift-and-add multiply, no tables.
function automatic [3:0] gf16_mul(input [3:0] a, input [3:0] b);
reg [3:0] p, x; p = 4'd0; x = a;
for (int i = 0; i < 4; i++) begin
if (b[i]) p = p ^ x;
x = x[3] ? ({x[2:0], 1'b0} ^ 4'b0011) : {x[2:0], 1'b0};
end
return p;
endfunction
function automatic [3:0] gf16_pow(input int e); // alpha^e, alpha = x
reg [3:0] p; int k; p = 4'd1; k = e % 15; if (k < 0) k += 15;
for (int i = 0; i < k; i++) p = gf16_mul(p, 4'd2);
return p;
endfunction
function automatic int gf16_log(input [3:0] a); // -1 for 0
reg [3:0] p; p = 4'd1;
if (a == 4'd0) return -1;
for (int i = 0; i < 15; i++) begin if (p == a) return i; p = gf16_mul(p, 4'd2); end
return -1;
endfunction
function automatic [9:0] gf1024_mul(input [9:0] a, input [9:0] b);
reg [9:0] p, x; p = 10'd0; x = a;
for (int i = 0; i < 10; i++) begin
if (b[i]) p = p ^ x;
x = x[9] ? ({x[8:0], 1'b0} ^ 10'b0000001001) : {x[8:0], 1'b0};
end
return p;
endfunction
function automatic [9:0] gf1024_pow(input int e);
reg [9:0] p; int k; p = 10'd1; k = e % 1023; if (k < 0) k += 1023;
for (int i = 0; i < k; i++) p = gf1024_mul(p, 10'd2);
return p;
endfunction
endpackage
// hs_rng: the bench's random numbers. Same seed, same numbers, on every engine.
module hs_rng;
int unsigned s = 32'h2545f491;
function automatic void seed(input int unsigned v); s = (v == 0) ? 32'd1 : v; endfunction
function automatic int unsigned next(); s = hs_pkg::xs32(s); return s; endfunction
function automatic int below(input int n); s = hs_pkg::xs32(s); return (n <= 0) ? 0 : int'(s % n); endfunction
function automatic bit bit1(); s = hs_pkg::xs32(s); return s[16]; endfunction
function automatic bit chance_ppm(input int ppm); s = hs_pkg::xs32(s); return (s % 1000000) < ppm; endfunction
function automatic [7:0] byte8(); s = hs_pkg::xs32(s); return s[23:16]; endfunction
endmodule
Read included file: hs_code.sv
`timescale 1ns/1ns
// hs_code.sv: line codes, CRCs and scramblers (read-only).
// ---------------------------------------------------------------------------------------------
// hs_8b10b: 8b/10b encoder and decoder with running disparity and the 12 K codes.
// code[9:0] = {a,b,c,d,e,i,f,g,h,j}; bit a (code[9]) goes on the wire first. rd: 0 = RD-, 1 = RD+.
// encode(d, k, rd_in) -> {rd_out, code[9:0]} (11 bits)
// decode(code, rd_in) -> {rd_out, disp_err, code_err, k, d[7:0]} (12 bits)
// enc(d, k) / dec(code): the same, with the running disparity kept in rd_tx / rd_rx
// A K request for a byte that is not one of the 12 K codes is encoded as data and counted in bad_k.
// Decoder: code_err = the code is in neither column of the table; disp_err = it is a valid code
// only in the other column. rd_out follows the sub-block rule on the received bits.
// Faults: no_rd (always the RD- column), a7_never (never the alternate D.x.A7),
// keep_rd_on_unbalanced (the 4b sub-block is chosen with the disparity from before the 6b one),
// no_balanced_flip (D.07 and D.x.3 keep their RD- form at RD+), dec_no_disp_check.
module hs_8b10b;
bit no_rd = 0, a7_never = 0, keep_rd_on_unbalanced = 0, no_balanced_flip = 0, dec_no_disp_check = 0;
bit trace = 0;
bit rd_tx = 0, rd_rx = 0;
int bad_k = 0, symbols = 0, code_errs = 0, disp_errs = 0;
bit last_k = 0, last_code_err = 0, last_disp_err = 0;
bit valid_m [0:1023]; bit valid_p [0:1023]; bit [8:0] kd [0:1023]; bit built = 0;
function automatic [5:0] t6(input [4:0] x); // 5b/6b, RD- column, abcdei
case (x)
5'd0: return 6'b100111; 5'd1: return 6'b011101; 5'd2: return 6'b101101; 5'd3: return 6'b110001;
5'd4: return 6'b110101; 5'd5: return 6'b101001; 5'd6: return 6'b011001; 5'd7: return 6'b111000;
5'd8: return 6'b111001; 5'd9: return 6'b100101; 5'd10: return 6'b010101; 5'd11: return 6'b110100;
5'd12: return 6'b001101; 5'd13: return 6'b101100; 5'd14: return 6'b011100; 5'd15: return 6'b010111;
5'd16: return 6'b011011; 5'd17: return 6'b100011; 5'd18: return 6'b010011; 5'd19: return 6'b110010;
5'd20: return 6'b001011; 5'd21: return 6'b101010; 5'd22: return 6'b011010; 5'd23: return 6'b111010;
5'd24: return 6'b110011; 5'd25: return 6'b100110; 5'd26: return 6'b010110; 5'd27: return 6'b110110;
5'd28: return 6'b001110; 5'd29: return 6'b101110; 5'd30: return 6'b011110; default: return 6'b101011;
endcase
endfunction
function automatic [3:0] t4d(input [2:0] y); // 3b/4b data, RD- column, fghj (y = 7 is P7)
case (y)
3'd0: return 4'b1011; 3'd1: return 4'b1001; 3'd2: return 4'b0101; 3'd3: return 4'b1100;
3'd4: return 4'b1101; 3'd5: return 4'b1010; 3'd6: return 4'b0110; default: return 4'b1110;
endcase
endfunction
function automatic [3:0] t4k(input [2:0] y); // 3b/4b for K codes, RD- form before the flip
case (y)
3'd0: return 4'b1011; 3'd1: return 4'b0110; 3'd2: return 4'b1010; 3'd3: return 4'b1100;
3'd4: return 4'b1101; 3'd5: return 4'b0101; 3'd6: return 4'b1001; default: return 4'b0111;
endcase
endfunction
function automatic bit k_ok(input [7:0] d);
return d[4:0] == 5'd28 || d == 8'hf7 || d == 8'hfb || d == 8'hfd || d == 8'hfe;
endfunction
function automatic int n6(input [5:0] v); return v[0] + v[1] + v[2] + v[3] + v[4] + v[5]; endfunction
function automatic int n4(input [3:0] v); return v[0] + v[1] + v[2] + v[3]; endfunction
// running disparity at the end of a sub-block (more ones: +; more zeros: -; 000111 and 0011: +; 111000 and 1100: -)
function automatic bit rd6(input [5:0] v, input bit rd);
return (n6(v) > 3) ? 1'b1 : (n6(v) < 3) ? 1'b0 : (v == 6'b000111) ? 1'b1 : (v == 6'b111000) ? 1'b0 : rd;
endfunction
function automatic bit rd4(input [3:0] v, input bit rd);
return (n4(v) > 2) ? 1'b1 : (n4(v) < 2) ? 1'b0 : (v == 4'b0011) ? 1'b1 : (v == 4'b1100) ? 1'b0 : rd;
endfunction
// faults: [0] no_rd [1] a7_never [2] keep_rd_on_unbalanced [3] no_balanced_flip
function automatic [10:0] core(input [7:0] d, input bit k, input bit rd_in, input [3:0] f);
reg [5:0] six; reg [3:0] four; reg rd0, r6, rd1, a7, kk; reg [4:0] x; reg [2:0] y; int o6, o4;
x = d[4:0]; y = d[7:5]; kk = k && k_ok(d); rd0 = f[0] ? 1'b0 : rd_in;
six = (kk && x == 5'd28) ? 6'b001111 : t6(x); o6 = n6(six);
if (rd0 && (o6 != 3 || (six == 6'b111000 && !f[3]))) begin six = ~six; o6 = 6 - o6; end
r6 = (o6 > 3) ? 1'b1 : (o6 < 3) ? 1'b0 : (six == 6'b000111) ? 1'b1 : (six == 6'b111000) ? 1'b0 : rd0;
rd1 = f[2] ? rd0 : r6;
if (kk) begin
four = t4k(y); if (rd1) four = ~four;
end else begin
a7 = (y == 3'd7) && !f[1] && ((!rd1 && (x == 5'd17 || x == 5'd18 || x == 5'd20)) || (rd1 && (x == 5'd11 || x == 5'd13 || x == 5'd14)));
four = a7 ? 4'b0111 : t4d(y);
if (rd1 && (n4(four) != 2 || (four == 4'b1100 && !f[3]))) four = ~four;
end
o4 = n4(four);
return {(o4 > 2) ? 1'b1 : (o4 < 2) ? 1'b0 : (four == 4'b0011) ? 1'b1 : (four == 4'b1100) ? 1'b0 : r6, six, four};
endfunction
function automatic [10:0] encode(input [7:0] d, input bit k, input bit rd_in);
if (k && !k_ok(d)) bad_k++;
return core(d, k, rd_in, {no_balanced_flip, keep_rd_on_unbalanced, a7_never, no_rd});
endfunction
function automatic void build();
reg [10:0] c;
for (int i = 0; i < 1024; i++) begin valid_m[i] = 0; valid_p[i] = 0; kd[i] = 9'd0; end
for (int i = 0; i < 268; i++) begin
reg [7:0] d; reg k;
if (i < 256) begin d = i[7:0]; k = 0; end
else begin k = 1; d = (i < 264) ? {3'(i - 256), 5'd28} : (i == 264) ? 8'hf7 : (i == 265) ? 8'hfb : (i == 266) ? 8'hfd : 8'hfe; end
c = core(d, k, 1'b0, 4'd0); valid_m[c[9:0]] = 1; kd[c[9:0]] = {k, d};
c = core(d, k, 1'b1, 4'd0); valid_p[c[9:0]] = 1; kd[c[9:0]] = {k, d};
end
built = 1;
endfunction
function automatic [11:0] decode(input [9:0] code, input bit rd_in);
reg here, there, ce, de, r;
if (!built) build();
here = rd_in ? valid_p[code] : valid_m[code];
there = rd_in ? valid_m[code] : valid_p[code];
ce = !(here || there); de = !ce && !here && !dec_no_disp_check;
r = rd4(code[3:0], rd6(code[9:4], rd_in));
return {r, de, ce, ce ? 9'd0 : kd[code]};
endfunction
function automatic [9:0] enc(input [7:0] d, input bit k);
reg [10:0] r; r = encode(d, k, rd_tx); rd_tx = r[10];
if (trace) $display("s%0d TX %s%0d.%0d code=%b rd=%s", symbols, (k && k_ok(d)) ? "K" : "D", d[4:0], d[7:5], r[9:0], r[10] ? "+" : "-");
symbols++;
return r[9:0];
endfunction
function automatic [8:0] dec(input [9:0] code);
reg [11:0] r; r = decode(code, rd_rx); rd_rx = r[11];
last_disp_err = r[10]; last_code_err = r[9]; last_k = r[8];
if (r[9]) code_errs++; if (r[10]) disp_errs++;
if (trace && (r[9] || r[10])) $display("RX %b %s", code, r[9] ? "code error" : "disparity error");
return r[8:0];
endfunction
function automatic bit comma7(input [6:0] w); return w == 7'b0011111 || w == 7'b1100000; endfunction
endmodule
// ---------------------------------------------------------------------------------------------
// hs_crc: a CRC of 1 to 32 bits with any polynomial, seed, bit order and final inversion.
// The register shifts left; the polynomial omits the x^width term. The field is sent register bit
// width-1 first (USB 2.0, USB 3.2 and Ethernet all send it this way).
// use_crc32(), use_crc16_usb2(), use_crc5_usb2(), use_crc16_usb3(): parameter sets
// reset(), crc_bit(b), crc_byte(v), crc_bits(v, n), field(), field_bit(i), check_value(), crc_residue_ok()
// Faults: msb_first (bytes enter MSB first), no_invert (the field is not complemented), seed_zero.
module hs_crc;
int width = 32;
bit [31:0] poly = 32'h04c11db7, seed = 32'hffffffff, residue = 32'hc704dd7b;
bit lsb_first = 1, invert = 1;
bit msb_first = 0, no_invert = 0, seed_zero = 0;
bit [31:0] r = 32'hffffffff;
function automatic [31:0] mask(); return (width >= 32) ? 32'hffffffff : ((32'd1 << width) - 32'd1); endfunction
function automatic void reset(); r = seed_zero ? 32'd0 : (seed & mask()); endfunction
function automatic void set(input int w, input [31:0] p, input [31:0] s, input [31:0] res, input bit lsb, input bit inv);
width = w; poly = p; seed = s; residue = res; lsb_first = lsb; invert = inv; reset();
endfunction
function automatic void use_crc32(); set(32, 32'h04c11db7, 32'hffffffff, 32'hc704dd7b, 1, 1); endfunction
function automatic void use_crc16_usb2(); set(16, 32'h8005, 32'hffff, 32'h800d, 1, 1); endfunction
function automatic void use_crc5_usb2(); set(5, 32'h05, 32'h1f, 32'h0c, 1, 1); endfunction
function automatic void use_crc16_usb3(); set(16, 32'h100b, 32'hffff, 32'hf6aa, 1, 1); endfunction
function automatic void crc_bit(input bit b);
reg fb; fb = b ^ r[width - 1];
r = ((r << 1) ^ (fb ? poly : 32'd0)) & mask();
endfunction
function automatic void crc_byte(input [7:0] v);
for (int i = 0; i < 8; i++) crc_bit(v[(lsb_first ^ msb_first) ? i : 7 - i]);
endfunction
function automatic void crc_bits(input [31:0] v, input int n); // n bits of v, bit 0 first
for (int i = 0; i < n; i++) crc_bit(v[i]);
endfunction
function automatic [31:0] field(); return (invert && !no_invert) ? (~r & mask()) : r; endfunction
function automatic bit field_bit(input int i); reg [31:0] f; f = field(); return f[width - 1 - i]; endfunction
// the usual published "check" number: the field with its first-sent bit read as bit 0
function automatic [31:0] check_value();
reg [31:0] f, o; f = field(); o = 32'd0;
for (int i = 0; i < width; i++) o[i] = f[width - 1 - i];
return lsb_first ? o : f;
endfunction
function automatic bit crc_residue_ok(); return r == (residue & mask()); endfunction
endmodule
// ---------------------------------------------------------------------------------------------
// hs_scr: additive (frame-synchronous) and multiplicative (self-synchronising) scramblers.
// poly holds the coefficients: bit k is x^k; the +1 term is always used (taps() sets bit 0); len is the degree.
// Additive: a Galois LFSR. The key bit is s[len-1]; each step shifts left and adds the low terms of
// the polynomial when the key bit is 1. The data never enters the register.
// Multiplicative: the line bit is the data bit XOR the register bits at the polynomial's terms;
// the scrambler shifts its own output in, the descrambler shifts the received line bit in.
// scr_add(len, poly, seed), scr_mul(len, poly), use_usb3_gen1(), use_x58(), use_x23_usb3() (see its note)
// scr_bit(b), dscr_bit(b), scr_byte(v), dscr_byte(v) (bit 0 first), scr_reset(), scr_hold() (a skip
// symbol: no step), scr_unscrambled() (a symbol sent in the clear: 8 steps, data untouched)
// Faults: advance_on_skip (scr_hold steps the LFSR 8 times), no_reset (scr_reset does nothing),
// wrong_tap (the lowest term x^k becomes x^(k+1)), seed_zero (scr_reset loads 0).
module hs_scr;
bit mult = 0; int len = 16;
bit [63:0] poly = 64'h10039, seed = 64'hffff;
bit advance_on_skip = 0, no_reset = 0, wrong_tap = 0, seed_zero = 0;
bit [63:0] s = 64'hffff;
int steps = 0;
function automatic [63:0] lmask(); return (len >= 64) ? 64'hffffffffffffffff : ((64'd1 << len) - 64'd1); endfunction
function automatic [63:0] taps();
reg [63:0] p; int k; p = poly | 64'd1; k = 1;
if (wrong_tap) begin
while (k < len && !p[k]) k++;
if (k < len) begin p[k] = 1'b0; p[k + 1] = 1'b1; end
end
return p;
endfunction
function automatic void load(); s = (seed_zero ? 64'd0 : seed) & lmask(); endfunction
function automatic void scr_add(input int n, input [63:0] p, input [63:0] sd); mult = 0; len = n; poly = p; seed = sd; s = sd & lmask(); endfunction
function automatic void scr_mul(input int n, input [63:0] p); mult = 1; len = n; poly = p; seed = 64'd0; s = 64'd0; endfunction
function automatic void use_usb3_gen1(); scr_add(16, 64'h10039, 64'hffff); endfunction // x^16 + x^5 + x^4 + x^3 + 1, seed FFFFh
function automatic void use_x58(); scr_mul(58, (64'd1 << 58) | (64'd1 << 39) | 64'd1); endfunction // x^58 + x^39 + 1
// USB 3.2 Gen 2 (§6.3.2.3) polynomial x^23 + x^21 + x^16 + x^8 + x^5 + x^2 + 1 with seed 1DBFBCh. Only the
// polynomial and seed are the specification's: the register form here is this library's Galois form, and
// the reset and bypass rules of §6.3.2.3 are not modelled, so do not quote its key stream as USB's.
function automatic void use_x23_usb3(); scr_add(23, (64'd1 << 23) | (64'd1 << 21) | (64'd1 << 16) | (64'd1 << 8) | (64'd1 << 5) | (64'd1 << 2) | 64'd1, 64'h1dbfbc); endfunction
function automatic void scr_reset(); if (!no_reset) load(); endfunction
function automatic bit key(); return s[len - 1]; endfunction
function automatic void step();
reg kb; kb = s[len - 1];
s = ((s << 1) & lmask()) ^ (kb ? (taps() & lmask()) : 64'd0);
steps++;
endfunction
// the XOR of the register bits at the polynomial's terms x^1..x^len (bit k-1 of the register for x^k)
function automatic bit fbx(input [63:0] st); return ^(st & (taps() >> 1) & lmask()); endfunction
function automatic bit scr_bit(input bit b);
reg o;
if (!mult) begin o = b ^ s[len - 1]; step(); end
else begin o = b ^ fbx(s); s = ((s << 1) | {63'd0, o}) & lmask(); steps++; end
return o;
endfunction
function automatic bit dscr_bit(input bit b);
reg o;
if (!mult) begin o = b ^ s[len - 1]; step(); end
else begin o = b ^ fbx(s); s = ((s << 1) | {63'd0, b}) & lmask(); steps++; end
return o;
endfunction
function automatic [7:0] scr_byte(input [7:0] v);
reg [7:0] o; for (int i = 0; i < 8; i++) o[i] = scr_bit(v[i]); return o;
endfunction
function automatic [7:0] dscr_byte(input [7:0] v);
reg [7:0] o; for (int i = 0; i < 8; i++) o[i] = dscr_bit(v[i]); return o;
endfunction
// a skip symbol passes unscrambled and the LFSR holds
function automatic void scr_hold(); if (advance_on_skip && !mult) for (int i = 0; i < 8; i++) step(); endfunction
// another symbol that is sent unscrambled (a K code other than COM and SKP): the LFSR still steps 8 times
function automatic void scr_unscrambled(); if (!mult) for (int i = 0; i < 8; i++) step(); endfunction
endmodule
Read included file: eth_macsec.sv
`timescale 1ns/1ns
// eth_macsec.sv: MACsec framing (read-only). A bench model after IEEE Std 802.1AE-2018 Clauses 9, 10.5 and 14.
//
// THE CIPHER HERE IS A STAND-IN. toy_start, toy_octet and toy_stream are a small mixing function of this bench.
// They are NOT GCM-AES and they give no security at all. They take the inputs the real cipher takes (key, IV,
// the octets that are only checked, the octets that are hidden), so the framing around them is the real one.
// eth_macsec: the transmit side of one secure channel, and a receiver's look at the result.
// user[i], n_user the frame to protect: DA, SA, then the user data (no FCS)
// load(da, sa, type, len) fills user[] with len data octets that count up from 0
// sci, an, sak, next_pn channel identifier, association number, key, the next packet number
// include_sci, use_es, use_scb how the SecTAG names the channel (10.5.3)
// confidential 1: the user data is hidden as well (E and C set)
// protect() -> mpdu[0..n_mpdu-1]: DA, SA, SecTAG, Secure Data, ICV. 0: the PN has run out
// tci_an(...), short_len(n) octets 3 and 4 of the SecTAG
// tag_check() the checks of 9.12 on mpdu[] that need no key: 0 if all pass
// validate() the receiver's toy check of mpdu[]: 1 if the ICV fits. plain[] is the user data
// xpn_recover(field, lowest) a 64-bit PN from its 32 low bits (10.6.2)
module eth_macsec;
localparam bit [15:0] ETHERTYPE = 16'h88e5; // Table 9-1
bit [7:0] user [0:2047]; int n_user = 0;
bit [7:0] mpdu [0:2047]; int n_mpdu = 0;
bit [7:0] plain [0:2047]; int n_plain = 0;
bit [63:0] sci = 0; bit [1:0] an = 0; bit [127:0] sak = 0;
bit [32:0] next_pn = 33'd1; // nextPN: one more bit than the PN, so 2^32 can be seen
bit include_sci = 1, use_es = 0, use_scb = 0, confidential = 0;
int n_tag = 0, n_secure = 0;
// what validate() read from the tag
bit [31:0] rx_pn = 0; bit [1:0] rx_an = 0; bit rx_es = 0, rx_sc = 0, rx_scb = 0, rx_e = 0, rx_c = 0; int rx_sl = 0;
// the toy cipher's state
bit [31:0] mix [0:3]; bit [31:0] ks = 0;
function automatic void load(input [47:0] d, input [47:0] s, input [15:0] t, input int len);
for (int i = 0; i < 6; i++) begin user[i] = d[47 - 8*i -: 8]; user[6 + i] = s[47 - 8*i -: 8]; end
user[12] = t[15:8]; user[13] = t[7:0];
for (int i = 0; i < len; i++) user[14 + i] = i[7:0];
n_user = 14 + len;
endfunction
// Octet 3 of the SecTAG (Figure 9-4): bit 8 is the version, then ES, SC, SCB, E and C; bits 2 and 1 are the AN.
function automatic [7:0] tci_an(input bit v, input bit es, input bit sc, input bit scb, input bit e, input bit c, input [1:0] a);
return {v, es, sc, scb, e, c, a};
endfunction
// Octet 4 (9.7): the number of Secure Data octets if that is below 48, else 0. Bits 8 and 7 are 0.
function automatic [7:0] short_len(input int secure_octets);
if (secure_octets < 48) return secure_octets[7:0];
return 8'd0;
endfunction
// ---- the stand-in for GCM-AES: NOT a cipher ----
function automatic void toy_start(input [127:0] key, input [95:0] iv);
mix[0] = key[31:0] ^ iv[31:0]; mix[1] = key[63:32] ^ iv[63:32];
mix[2] = key[95:64] ^ iv[95:64]; mix[3] = key[127:96] ^ 32'h746f7921;
ks = hs_pkg::xs32(key[31:0] ^ key[95:64] ^ iv[31:0] ^ iv[95:64]);
endfunction
function automatic void toy_octet(input [7:0] o); // one more octet into the check value
mix[0] = hs_pkg::xs32(mix[0] ^ {24'd0, o});
mix[1] = hs_pkg::xs32(mix[1] + mix[0]);
mix[2] = hs_pkg::xs32(mix[2] ^ mix[1]);
mix[3] = hs_pkg::xs32(mix[3] + mix[2]);
endfunction
function automatic [7:0] toy_stream(); // one octet of "key stream"
ks = hs_pkg::xs32(ks);
return ks[15:8];
endfunction
function automatic [7:0] toy_icv(input int k); // octet k of the 16-octet check value
reg [127:0] t;
t = {mix[3], mix[2], mix[1], mix[0]};
return t[127 - 8*k -: 8];
endfunction
// Secure frame generation (10.5), for the frame in user[].
function automatic bit protect();
int k, nd; reg [31:0] pn; bit sc; reg [7:0] o;
if (next_pn == 33'd0 || next_pn[32]) return 1'b0; // 10.5.2: no PN is left for this key
pn = next_pn[31:0]; next_pn = next_pn + 33'd1;
sc = include_sci; nd = n_user - 12;
for (int i = 0; i < 12; i++) mpdu[i] = user[i]; // the addresses stay where they are
mpdu[12] = ETHERTYPE[15:8]; mpdu[13] = ETHERTYPE[7:0];
mpdu[14] = tci_an(1'b0, use_es && !sc, sc, use_scb && !sc, confidential, confidential, an);
mpdu[15] = short_len(nd);
for (int i = 0; i < 4; i++) mpdu[16 + i] = pn[31 - 8*i -: 8];
if (sc) for (int i = 0; i < 8; i++) mpdu[20 + i] = sci[63 - 8*i -: 8];
n_tag = sc ? 16 : 8; n_secure = nd; k = 12 + n_tag;
toy_start(sak, {sci, pn}); // the IV: the SCI, then the PN (14.5)
for (int i = 0; i < k; i++) toy_octet(mpdu[i]); // checked, not hidden: DA, SA, SecTAG
for (int i = 0; i < nd; i++) begin
o = user[12 + i];
if (confidential) o = o ^ toy_stream(); // hidden: the user data
mpdu[k + i] = o; toy_octet(o);
end
for (int i = 0; i < 16; i++) mpdu[k + nd + i] = toy_icv(i);
n_mpdu = k + nd + 16;
return 1'b1;
endfunction
// The checks of 9.12 that need no key, for a 16-octet ICV. 0: all pass. Else the letter of the item, a = 1.
function automatic int tag_check();
int body, sl; bit c, sc;
body = n_mpdu - 12; // the MPDU: all that follows the addresses
if (body < 17) return 1;
if (mpdu[12] != ETHERTYPE[15:8] || mpdu[13] != ETHERTYPE[7:0]) return 2;
if (mpdu[14][7]) return 3;
if ((mpdu[14][6] || mpdu[14][4]) && mpdu[14][5]) return 4;
if (mpdu[15][7:6] != 2'b00) return 5;
c = mpdu[14][2]; sc = mpdu[14][5]; sl = mpdu[15][5:0];
if (sl != 0 && body != (sc ? 32 : 24) + sl) return c ? (sc ? 9 : 8) : (sc ? 7 : 6);
if (sl == 0 && body < (sc ? 32 : 24) + 48) return c ? (sc ? 9 : 8) : (sc ? 7 : 6);
return 0;
endfunction
// The receiver's toy check. It reads the tag, works the check value out again and compares.
function automatic bit validate();
int k, nd; bit same; reg [63:0] s; reg [7:0] o;
rx_es = mpdu[14][6]; rx_sc = mpdu[14][5]; rx_scb = mpdu[14][4]; rx_e = mpdu[14][3]; rx_c = mpdu[14][2];
rx_an = mpdu[14][1:0]; rx_sl = mpdu[15][5:0];
rx_pn = {mpdu[16], mpdu[17], mpdu[18], mpdu[19]};
s = sci; // known from key agreement
if (rx_sc) s = {mpdu[20], mpdu[21], mpdu[22], mpdu[23], mpdu[24], mpdu[25], mpdu[26], mpdu[27]};
k = 12 + (rx_sc ? 16 : 8); nd = n_mpdu - k - 16;
toy_start(sak, {s, rx_pn});
for (int i = 0; i < k; i++) toy_octet(mpdu[i]);
for (int i = 0; i < 12; i++) plain[i] = mpdu[i];
for (int i = 0; i < nd; i++) begin
o = mpdu[k + i]; toy_octet(o);
if (rx_e) o = o ^ toy_stream();
plain[12 + i] = o;
end
n_plain = 12 + nd; same = 1'b1;
for (int i = 0; i < 16; i++) if (mpdu[k + nd + i] != toy_icv(i)) same = 1'b0;
return same;
endfunction
// Extended packet numbering (10.6.2): the tag carries the 32 low bits. The 32 high bits are those of the lowest
// acceptable PN, or one more if its bit 31 is set and bit 31 of the field is not.
function automatic [63:0] xpn_recover(input [31:0] field, input [63:0] lowest);
reg [31:0] high;
high = lowest[63:32];
if (lowest[31] && !field[31]) high = high + 32'd1;
return {high, field};
endfunction
endmodule
Check Yourself
Common Mistakes
Wrong Let any frame with a high PN move nextPN.
A forged frame would push the window past every real frame.
Fix Move nextPN only on a frame that the cipher has found valid.
Wrong Keep nextPN in 32 bits.
After the PN 0xFFFF FFFF, nextPN is 2^32. In 32 bits that is 0.
Fix Give nextPN one more bit than the PN.
Wrong Expect a replay window to stop every copy.
Inside the window a second copy of a frame is accepted.
Fix Use a window of 0 where the network keeps the order.
Wrong Count a late frame with a wrong ICV as not valid.
The replay check comes first, and a frame adds to one count only.
Fix Count it as InPktsLate.
Remember
- A protected frame is: addresses, SecTAG, Secure Data, ICV. It grows by 24 or 32 octets.
- The SecTAG holds EtherType 88-E5, six flag bits, the AN, the SL, a 32-bit PN and an optional SCI.
- The ICV covers addresses, tag and data. Encryption hides the User Data only.
- A PN is never reused with a key. The receiver refuses a PN below its lowest acceptable PN.
- Only a valid frame moves nextPN. Each received frame adds to exactly one count.