man/man8/ip-macsec.8

   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" } ] ["
  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 on " | " off " ]"
  68 .br
  69 .IR SCI " := { "
  70 .B sci
  71 .IR <u64> " | "
  72 .BI port
  73 .IR PORT
  74 .BI address " <lladdr> "
  75 }
  76 .br
  77 .IR PORT " := { " 1..2^16-1 " } "
  78
  79
  80 .SH DESCRIPTION
  81 The
  82 .B ip macsec
  83 commands are used to configure transmit secure associations and receive secure channels and their secure associations on a MACsec device created with the
  84 .B ip link add
  85 command using the
  86 .I macsec
  87 type.
  88
  89 .SH EXAMPLES
  90 .PP
  91 .SS Create a MACsec device on link eth0 (offload is disabled by default)
  92 .nf
  93 # ip link add link eth0 macsec0 type macsec port 11 encrypt on
  94 .PP
  95 .SS Configure a secure association on that device
  96 .nf
  97 # ip macsec add macsec0 tx sa 0 pn 1024 on key 01 81818181818181818181818181818181
  98 .PP
  99 .SS Configure a receive channel
 100 .nf
 101 # ip macsec add macsec0 rx port 1234 address c6:19:52:8f:e6:a0
 102 .PP
 103 .SS Configure a receive association
 104 .nf
 105 # ip macsec add macsec0 rx port 1234 address c6:19:52:8f:e6:a0 sa 0 pn 1 on key 00 82828282828282828282828282828282
 106 .PP
 107 .SS Display MACsec configuration
 108 .nf
 109 # ip macsec show
 110 .PP
 111 .SS Configure offloading on an interface
 112 .nf
 113 # ip macsec offload macsec0 phy
 114 .PP
 115 .SS Configure offloading upon MACsec device creation
 116 .nf
 117 # ip link add link eth0 macsec0 type macsec port 11 encrypt on offload mac
 118
 119 .SH NOTES
 120 This tool can be used to configure the 802.1AE keys of the interface. Note that 802.1AE uses GCM-AES
 121 with a initialization vector (IV) derived from the packet number. The same key must not be used
 122 with the same IV more than once. Instead, keys must be frequently regenerated and distibuted.
 123 This tool is thus mostly for debugging and testing, or in combination with a user-space application
 124 that reconfigures the keys. It is wrong to just configure the keys statically and assume them to work
 125 indefinitely. The suggested and standardized way for key management is 802.1X-2010, which is implemented
 126 by wpa_supplicant.
 127
 128 .SH SEE ALSO
 129 .br
 130 .BR ip-link (8)
 131 .BR wpa_supplicant (8)
 132 .SH AUTHOR
 133 Sabrina Dubroca <sd@queasysnail.net>