| 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]> |