Debian Codegraph @

upstream/debian-unstable/man8/ip-macsec.8

raw
1 .TH IP\-MACSEC 8 "07 Mar 2016" "iproute" "Linux"
2 .SH NAME
3 ip-macsec \- MACsec device configuration
4 .SH "SYNOPSIS"
5 .BI "ip link add link " DEVICE " name " NAME " type macsec "
6 [ [
7 .BI address " <lladdr>"
8 ]
9 .BI port " PORT"
10 |
11 .BI sci " <u64>"
12 ] [
13 .BR cipher " { " default " | " gcm-aes-128 " | " gcm-aes-256 " | " gcm-aes-xpn-128 " | " gcm-aes-xpn-256 " } ] ["
14 .BI icvlen " ICVLEN"
15 ] [
16 .BR encrypt " { " on " | " off " } ] ["
17 .BR send_sci " { " on " | " off " } ] ["
18 .BR end_station " { " on " | " off " } ] ["
19 .BR scb " { " on " | " off " } ] ["
20 .BR protect " { " on " | " off " } ] ["
21 .BR replay " { " on " | " off " } ] ["
22 .BI window " WINDOW"
23 ] [
24 .BR validate " { " strict " | " check " | " disabled " } ] ["
25 .BI encodingsa " SA"
26 ] [
27 .BR offload " { " off " | " phy " | " mac " }"
28 ]
29
30 .BI "ip macsec add " DEV " tx sa"
31 .RI "{ " 0..3 " } [ " OPTS " ]"
32 .BI key " ID KEY"
33 .br
34 .BI "ip macsec set " DEV " tx sa"
35 .RI "{ " 0..3 " } [ " OPTS " ]"
36 .br
37 .BI "ip macsec del " DEV " tx sa"
38 .RI "{ " 0..3 " }"
39
40 .BI "ip macsec add " DEV " rx " SCI
41 .RB [ " on " | " off " ]
42 .br
43 .BI "ip macsec set " DEV " rx " SCI
44 .RB [ " on " | " off " ]
45 .br
46 .BI "ip macsec del " DEV " rx " SCI
47
48 .BI "ip macsec add " DEV " rx " SCI " sa"
49 .RI "{ " 0..3 " } [ " OPTS " ]"
50 .BI key " ID KEY"
51 .br
52 .BI "ip macsec set " DEV " rx " SCI " sa"
53 .RI "{ " 0..3 " } [ " OPTS " ]"
54 .br
55 .BI "ip macsec del " DEV " rx " SCI " sa"
56 .RI "{ " 0..3 " }"
57
58 .BI "ip macsec offload " DEV
59 .RB "{ " off " | " phy " | " mac " }"
60
61 .B ip macsec show
62 .RI [ " DEV " ]
63
64 .IR OPTS " := [ "
65 .BR pn " { "
66 .IR 1..2^32-1 " } |"
67 .BR xpn " { "
68 .IR 1..2^64-1 " } ] ["
69 .B salt
70 .IR SALT " ] ["
71 .B ssci
72 .IR <u32> " ] ["
73 .BR on " | " off " ]"
74 .br
75 .IR SCI " := { "
76 .B sci
77 .IR <u64> " | "
78 .BI port
79 .IR PORT
80 .BI address " <lladdr> "
81 }
82 .br
83 .IR PORT " := { " 1..2^16-1 " } "
84 .br
85 .IR SALT " := 96-bit hex string "
86
87
88 .SH DESCRIPTION
89 The
90 .B ip macsec
91 commands are used to configure transmit secure associations and receive secure channels and their secure associations on a MACsec device created with the
92 .B ip link add
93 command using the
94 .I macsec
95 type.
96
97 .SH EXAMPLES
98 .PP
99 .SS Create a MACsec device on link eth0 (offload is disabled by default)
100 .nf
101 # ip link add link eth0 macsec0 type macsec port 11 encrypt on
102 .PP
103 .SS Configure a secure association on that device
104 .nf
105 # ip macsec add macsec0 tx sa 0 pn 1024 on key 01 81818181818181818181818181818181
106 .PP
107 .SS Configure a receive channel
108 .nf
109 # ip macsec add macsec0 rx port 1234 address c6:19:52:8f:e6:a0
110 .PP
111 .SS Configure a receive association
112 .nf
113 # ip macsec add macsec0 rx port 1234 address c6:19:52:8f:e6:a0 sa 0 pn 1 on key 00 82828282828282828282828282828282
114 .PP
115 .SS Display MACsec configuration
116 .nf
117 # ip macsec show
118 .PP
119 .SS Configure offloading on an interface
120 .nf
121 # ip macsec offload macsec0 phy
122 .PP
123 .SS Configure offloading upon MACsec device creation
124 .nf
125 # ip link add link eth0 macsec0 type macsec port 11 encrypt on offload mac
126
127 .SH EXTENDED PACKET NUMBER EXAMPLES
128 .PP
129 .SS Create a MACsec device on link eth0 with enabled extended packet number (offload is disabled by default)
130 .nf
131 # ip link add link eth0 macsec0 type macsec port 11 encrypt on cipher gcm-aes-xpn-128
132 .PP
133 .SS Configure a secure association on that device
134 .nf
135 # ip macsec add macsec0 tx sa 0 xpn 1024 on salt 838383838383838383838383 ssci 123 key 01 81818181818181818181818181818181
136 .PP
137 .SS Configure a receive channel
138 .nf
139 # ip macsec add macsec0 rx port 11 address c6:19:52:8f:e6:a0
140 .PP
141 .SS Configure a receive association
142 .nf
143 # ip macsec add macsec0 rx port 11 address c6:19:52:8f:e6:a0 sa 0 xpn 1 on salt 838383838383838383838383 ssci 123 key 00 82828282828282828282828282828282
144 .PP
145 .SS Display MACsec configuration
146 .nf
147 # ip macsec show
148 .PP
149
150 .SH NOTES
151 This tool can be used to configure the 802.1AE keys of the interface. Note that 802.1AE uses GCM-AES
152 with a initialization vector (IV) derived from the packet number. The same key must not be used
153 with the same IV more than once. Instead, keys must be frequently regenerated and distributed.
154 This tool is thus mostly for debugging and testing, or in combination with a user-space application
155 that reconfigures the keys. It is wrong to just configure the keys statically and assume them to work
156 indefinitely. The suggested and standardized way for key management is 802.1X-2010, which is implemented
157 by wpa_supplicant.
158
159 .SH EXTENDED PACKET NUMBER NOTES
160 Passing cipher
161 .B gcm-aes-xpn-128
162 or
163 .B gcm-aes-xpn-256
164 to
165 .B ip link add
166 command using the
167 .I macsec
168 type requires using the keyword
169 .B 'xpn'
170 instead of
171 .B 'pn'
172 in addition to providing a salt using the
173 .B 'salt'
174 keyword and ssci using the
175 .B 'ssci'
176 keyword when using the
177 .B ip macsec
178 command.
179
180
181 .SH SEE ALSO
182 .br
183 .BR ip-link (8)
184 .BR wpa_supplicant (8)
185 .SH AUTHOR
186 Sabrina Dubroca <[email protected]>