man/man8/ip-xfrm.8

   1 .TH IP\-XFRM 8 "20 Dec 2011" "iproute2" "Linux"
   2 .SH "NAME"
   3 ip-xfrm \- transform configuration
   4 .SH "SYNOPSIS"
   5 .sp
   6 .ad l
   7 .in +8
   8 .ti -8
   9 .B ip
  10 .RI "[ " OPTIONS " ]"
  11 .B xfrm
  12 .RI " { " COMMAND " | "
  13 .BR help " }"
  14 .sp
  15
  16 .ti -8
  17 .B "ip xfrm"
  18 .IR XFRM-OBJECT " { " COMMAND " | "
  19 .BR help " }"
  20 .sp
  21
  22 .ti -8
  23 .IR XFRM-OBJECT " :="
  24 .BR state " | " policy " | " monitor
  25 .sp
  26
  27 .ti -8
  28 .BR "ip xfrm state" " { " add " | " update " } "
  29 .IR ID " [ " ALGO-LIST " ]"
  30 .RB "[ " mode
  31 .IR MODE " ]"
  32 .RB "[ " mark
  33 .I MARK
  34 .RB "[ " mask
  35 .IR MASK " ] ]"
  36 .RB "[ " reqid
  37 .IR REQID " ]"
  38 .RB "[ " seq
  39 .IR SEQ " ]"
  40 .RB "[ " replay-window
  41 .IR SIZE " ]"
  42 .RB "[ " replay-seq
  43 .IR SEQ " ]"
  44 .RB "[ " replay-oseq
  45 .IR SEQ " ]"
  46 .RB "[ " flag
  47 .IR FLAG-LIST " ]"
  48 .RB "[ " sel
  49 .IR SELECTOR " ] [ " LIMIT-LIST " ]"
  50 .RB "[ " encap
  51 .IR ENCAP " ]"
  52 .RB "[ " coa
  53 .IR ADDR "[/" PLEN "] ]"
  54 .RB "[ " ctx
  55 .IR CTX " ]"
  56
  57 .ti -8
  58 .B "ip xfrm state allocspi"
  59 .I ID
  60 .RB "[ " mode
  61 .IR MODE " ]"
  62 .RB "[ " mark
  63 .I MARK
  64 .RB "[ " mask
  65 .IR MASK " ] ]"
  66 .RB "[ " reqid
  67 .IR REQID " ]"
  68 .RB "[ " seq
  69 .IR SEQ " ]"
  70 .RB "[ " min
  71 .I SPI
  72 .B max
  73 .IR SPI " ]"
  74
  75 .ti -8
  76 .BR "ip xfrm state" " { " delete " | " get " } "
  77 .I ID
  78 .RB "[ " mark
  79 .I MARK
  80 .RB "[ " mask
  81 .IR MASK " ] ]"
  82
  83 .ti -8
  84 .BR "ip xfrm state" " { " deleteall " | " list " } ["
  85 .IR ID " ]"
  86 .RB "[ " mode
  87 .IR MODE " ]"
  88 .RB "[ " reqid
  89 .IR REQID " ]"
  90 .RB "[ " flag
  91 .IR FLAG-LIST " ]"
  92
  93 .ti -8
  94 .BR "ip xfrm state flush" " [ " proto
  95 .IR XFRM-PROTO " ]"
  96
  97 .ti -8
  98 .BR "ip xfrm state count"
  99
 100 .ti -8
 101 .IR ID " :="
 102 .RB "[ " src
 103 .IR ADDR " ]"
 104 .RB "[ " dst
 105 .IR ADDR " ]"
 106 .RB "[ " proto
 107 .IR XFRM-PROTO " ]"
 108 .RB "[ " spi
 109 .IR SPI " ]"
 110
 111 .ti -8
 112 .IR XFRM-PROTO " :="
 113 .BR esp " | " ah " | " comp " | " route2 " | " hao
 114
 115 .ti -8
 116 .IR ALGO-LIST " := [ " ALGO-LIST " ] " ALGO
 117
 118 .ti -8
 119 .IR ALGO " :="
 120 .RB "{ " enc " | " auth " } "
 121 .IR ALGO-NAME " " ALGO-KEYMAT " |"
 122 .br
 123 .B auth-trunc
 124 .IR ALGO-NAME " " ALGO-KEYMAT " " ALGO-TRUNC-LEN " |"
 125 .br
 126 .B aead
 127 .IR ALGO-NAME " " ALGO-KEYMAT " " ALGO-ICV-LEN " |"
 128 .br
 129 .B comp
 130 .IR ALGO-NAME
 131
 132 .ti -8
 133 .IR MODE " := "
 134 .BR transport " | " tunnel " | " beet " | " ro " | " in_trigger
 135
 136 .ti -8
 137 .IR FLAG-LIST " := [ " FLAG-LIST " ] " FLAG
 138
 139 .ti -8
 140 .IR FLAG " :="
 141 .BR noecn " | " decap-dscp " | " nopmtudisc " | " wildrecv " | " icmp " | " af-unspec " | " align4
 142
 143 .ti -8
 144 .IR SELECTOR " :="
 145 .RB "[ " src
 146 .IR ADDR "[/" PLEN "] ]"
 147 .RB "[ " dst
 148 .IR ADDR "[/" PLEN "] ]"
 149 .RB "[ " dev
 150 .IR DEV " ]"
 151 .br
 152 .RI "[ " UPSPEC " ]"
 153
 154 .ti -8
 155 .IR UPSPEC " := "
 156 .BR proto " {"
 157 .IR PROTO " |"
 158 .br
 159 .RB "{ " tcp " | " udp " | " sctp " | " dccp " } [ " sport
 160 .IR PORT " ]"
 161 .RB "[ " dport
 162 .IR PORT " ] |"
 163 .br
 164 .RB "{ " icmp " | " ipv6-icmp " | " mobility-header " } [ " type
 165 .IR NUMBER " ]"
 166 .RB "[ " code
 167 .IR NUMBER " ] |"
 168 .br
 169 .BR gre " [ " key
 170 .RI "{ " DOTTED-QUAD " | " NUMBER " } ] }"
 171
 172 .ti -8
 173 .IR LIMIT-LIST " := [ " LIMIT-LIST " ]"
 174 .B limit
 175 .I LIMIT
 176
 177 .ti -8
 178 .IR LIMIT " :="
 179 .RB "{ " time-soft " | " time-hard " | " time-use-soft " | " time-use-hard " }"
 180 .IR "SECONDS" " |"
 181 .br
 182 .RB "{ " byte-soft " | " byte-hard " }"
 183 .IR SIZE " |"
 184 .br
 185 .RB "{ " packet-soft " | " packet-hard " }"
 186 .I COUNT
 187
 188 .ti -8
 189 .IR ENCAP " :="
 190 .RB "{ " espinudp " | " espinudp-nonike " }"
 191 .IR SPORT " " DPORT " " OADDR
 192
 193 .ti -8
 194 .BR "ip xfrm policy" " { " add " | " update " }"
 195 .I SELECTOR
 196 .B dir
 197 .I DIR
 198 .RB "[ " ctx
 199 .IR CTX " ]"
 200 .RB "[ " mark
 201 .I MARK
 202 .RB "[ " mask
 203 .IR MASK " ] ]"
 204 .RB "[ " index
 205 .IR INDEX " ]"
 206 .RB "[ " ptype
 207 .IR PTYPE " ]"
 208 .RB "[ " action
 209 .IR ACTION " ]"
 210 .RB "[ " priority
 211 .IR PRIORITY " ]"
 212 .RB "[ " flag
 213 .IR FLAG-LIST " ]"
 214 .RI "[ " LIMIT-LIST " ] [ " TMPL-LIST " ]"
 215
 216 .ti -8
 217 .BR "ip xfrm policy" " { " delete " | " get " }"
 218 .RI "{ " SELECTOR " | "
 219 .B index
 220 .IR INDEX " }"
 221 .B dir
 222 .I DIR
 223 .RB "[ " ctx
 224 .IR CTX " ]"
 225 .RB "[ " mark
 226 .I MARK
 227 .RB "[ " mask
 228 .IR MASK " ] ]"
 229 .RB "[ " ptype
 230 .IR PTYPE " ]"
 231
 232 .ti -8
 233 .BR "ip xfrm policy" " { " deleteall " | " list " }"
 234 .RI "[ " SELECTOR " ]"
 235 .RB "[ " dir
 236 .IR DIR " ]"
 237 .RB "[ " index
 238 .IR INDEX " ]"
 239 .RB "[ " ptype
 240 .IR PTYPE " ]"
 241 .RB "[ " action
 242 .IR ACTION " ]"
 243 .RB "[ " priority
 244 .IR PRIORITY " ]"
 245
 246 .ti -8
 247 .B "ip xfrm policy flush"
 248 .RB "[ " ptype
 249 .IR PTYPE " ]"
 250
 251 .ti -8
 252 .B "ip xfrm policy count"
 253
 254 .ti -8
 255 .IR SELECTOR " :="
 256 .RB "[ " src
 257 .IR ADDR "[/" PLEN "] ]"
 258 .RB "[ " dst
 259 .IR ADDR "[/" PLEN "] ]"
 260 .RB "[ " dev
 261 .IR DEV " ]"
 262 .RI "[ " UPSPEC " ]"
 263
 264 .ti -8
 265 .IR UPSPEC " := "
 266 .BR proto " {"
 267 .IR PROTO " |"
 268 .br
 269 .RB "{ " tcp " | " udp " | " sctp " | " dccp " } [ " sport
 270 .IR PORT " ]"
 271 .RB "[ " dport
 272 .IR PORT " ] |"
 273 .br
 274 .RB "{ " icmp " | " ipv6-icmp " | " mobility-header " } [ " type
 275 .IR NUMBER " ]"
 276 .RB "[ " code
 277 .IR NUMBER " ] |"
 278 .br
 279 .BR gre " [ " key
 280 .RI "{ " DOTTED-QUAD " | " NUMBER " } ] }"
 281
 282 .ti -8
 283 .IR DIR " := "
 284 .BR in " | " out " | " fwd
 285
 286 .ti -8
 287 .IR PTYPE " := "
 288 .BR main " | " sub
 289
 290 .ti -8
 291 .IR ACTION " := "
 292 .BR allow " | " block
 293
 294 .ti -8
 295 .IR FLAG-LIST " := [ " FLAG-LIST " ] " FLAG
 296
 297 .ti -8
 298 .IR FLAG " :="
 299 .BR localok " | " icmp
 300
 301 .ti -8
 302 .IR LIMIT-LIST " := [ " LIMIT-LIST " ]"
 303 .B limit
 304 .I LIMIT
 305
 306 .ti -8
 307 .IR LIMIT " :="
 308 .RB "{ " time-soft " | " time-hard " | " time-use-soft " | " time-use-hard " }"
 309 .IR "SECONDS" " |"
 310 .br
 311 .RB "{ " byte-soft " | " byte-hard " }"
 312 .IR SIZE " |"
 313 .br
 314 .RB "{ " packet-soft " | " packet-hard " }"
 315 .I COUNT
 316
 317 .ti -8
 318 .IR TMPL-LIST " := [ " TMPL-LIST " ]"
 319 .B tmpl
 320 .I TMPL
 321
 322 .ti -8
 323 .IR TMPL " := " ID
 324 .RB "[ " mode
 325 .IR MODE " ]"
 326 .RB "[ " reqid
 327 .IR REQID " ]"
 328 .RB "[ " level
 329 .IR LEVEL " ]"
 330
 331 .ti -8
 332 .IR ID " :="
 333 .RB "[ " src
 334 .IR ADDR " ]"
 335 .RB "[ " dst
 336 .IR ADDR " ]"
 337 .RB "[ " proto
 338 .IR XFRM-PROTO " ]"
 339 .RB "[ " spi
 340 .IR SPI " ]"
 341
 342 .ti -8
 343 .IR XFRM-PROTO " :="
 344 .BR esp " | " ah " | " comp " | " route2 " | " hao
 345
 346 .ti -8
 347 .IR MODE " := "
 348 .BR transport " | " tunnel " | " beet " | " ro " | " in_trigger
 349
 350 .ti -8
 351 .IR LEVEL " :="
 352 .BR required " | " use
 353
 354 .ti -8
 355 .BR "ip xfrm monitor" " [ " all " |"
 356 .IR LISTofXFRM-OBJECTS " ]"
 357
 358 .in -8
 359 .ad b
 360
 361 .SH DESCRIPTION
 362
 363 xfrm is an IP framework for transforming packets (such as encrypting
 364 their payloads). This framework is used to implement the IPsec protocol
 365 suite (with the
 366 .B state
 367 object operating on the Security Association Database, and the
 368 .B policy
 369 object operating on the Security Policy Database). It is also used for
 370 the IP Payload Compression Protocol and features of Mobile IPv6.
 371
 372 .TS
 373 l l.
 374 ip xfrm state add       add new state into xfrm
 375 ip xfrm state update    update existing state in xfrm
 376 ip xfrm state allocspi  allocate an SPI value
 377 ip xfrm state delete    delete existing state in xfrm
 378 ip xfrm state get       get existing state in xfrm
 379 ip xfrm state deleteall delete all existing state in xfrm
 380 ip xfrm state list      print out the list of existing state in xfrm
 381 ip xfrm state flush     flush all state in xfrm
 382 ip xfrm state count     count all existing state in xfrm
 383 ip xfrm monitor         state monitoring for xfrm objects
 384 .TE
 385
 386 .TP
 387 .IR ID
 388 is specified by a source address, destination address,
 389 .RI "transform protocol " XFRM-PROTO ","
 390 and/or Security Parameter Index
 391 .IR SPI "."
 392 (For IP Payload Compression, the Compression Parameter Index or CPI is used for
 393 .IR SPI ".)"
 394
 395 .TP
 396 .I XFRM-PROTO
 397 specifies a transform protocol:
 398 .RB "IPsec Encapsulating Security Payload (" esp "),"
 399 .RB "IPsec Authentication Header (" ah "),"
 400 .RB "IP Payload Compression (" comp "),"
 401 .RB "Mobile IPv6 Type 2 Routing Header (" route2 "), or"
 402 .RB "Mobile IPv6 Home Address Option (" hao ")."
 403
 404 .TP
 405 .I ALGO-LIST
 406 contains one or more algorithms to use. Each algorithm
 407 .I ALGO
 408 is specified by:
 409 .RS
 410 .IP \[bu]
 411 the algorithm type:
 412 .RB "encryption (" enc "),"
 413 .RB "authentication (" auth " or " auth-trunc "),"
 414 .RB "authenticated encryption with associated data (" aead "), or"
 415 .RB "compression (" comp ")"
 416 .IP \[bu]
 417 the algorithm name
 418 .IR ALGO-NAME
 419 (see below)
 420 .IP \[bu]
 421 .RB "(for all except " comp ")"
 422 the keying material
 423 .IR ALGO-KEYMAT ","
 424 which may include both a key and a salt or nonce value; refer to the
 425 corresponding RFC
 426 .IP \[bu]
 427 .RB "(for " auth-trunc " only)"
 428 the truncation length
 429 .I ALGO-TRUNC-LEN
 430 in bits
 431 .IP \[bu]
 432 .RB "(for " aead " only)"
 433 the Integrity Check Value length
 434 .I ALGO-ICV-LEN
 435 in bits
 436 .RE
 437
 438 .nh
 439 .RS
 440 Encryption algorithms include
 441 .BR ecb(cipher_null) ", " cbc(des) ", " cbc(des3_ede) ", " cbc(cast5) ","
 442 .BR cbc(blowfish) ", " cbc(aes) ", " cbc(serpent) ", " cbc(camellia) ","
 443 .BR cbc(twofish) ", and " rfc3686(ctr(aes)) "."
 444
 445 Authentication algorithms include
 446 .BR digest_null ", " hmac(md5) ", " hmac(sha1) ", " hmac(sha256) ","
 447 .BR hmac(sha384) ", " hmac(sha512) ", " hmac(rmd610) ", and " xcbc(aes) "."
 448
 449 Authenticated encryption with associated data (AEAD) algorithms include
 450 .BR rfc4106(gcm(aes)) ", " rfc4309(ccm(aes)) ", and " rfc4543(gcm(aes)) "."
 451
 452 Compression algorithms include
 453 .BR deflate ", " lzs ", and " lzjh "."
 454 .RE
 455 .hy
 456
 457 .TP
 458 .I MODE
 459 specifies a mode of operation for the transform protocol. IPsec and IP Payload
 460 Compression modes are
 461 .BR transport ", " tunnel ","
 462 and (for IPsec ESP only) Bound End-to-End Tunnel
 463 .RB "(" beet ")."
 464 Mobile IPv6 modes are route optimization
 465 .RB "(" ro ")"
 466 and inbound trigger
 467 .RB "(" in_trigger ")."
 468
 469 .TP
 470 .I FLAG-LIST
 471 contains one or more of the following optional flags:
 472 .BR noecn ", " decap-dscp ", " nopmtudisc ", " wildrecv ", " icmp ", "
 473 .BR af-unspec ", or " align4 "."
 474
 475 .TP
 476 .IR SELECTOR
 477 selects the traffic that will be controlled by the policy, based on the source
 478 address, the destination address, the network device, and/or
 479 .IR UPSPEC "."
 480
 481 .TP
 482 .IR UPSPEC
 483 selects traffic by protocol. For the
 484 .BR tcp ", " udp ", " sctp ", or " dccp
 485 protocols, the source and destination port can optionally be specified.
 486 For the
 487 .BR icmp ", " ipv6-icmp ", or " mobility-header
 488 protocols, the type and code numbers can optionally be specified.
 489 For the
 490 .B gre
 491 protocol, the key can optionally be specified as a dotted-quad or number.
 492 Other protocols can be selected by name or number
 493 .IR PROTO "."
 494
 495 .TP
 496 .I LIMIT-LIST
 497 sets limits in seconds, bytes, or numbers of packets.
 498
 499 .TP
 500 .I ENCAP
 501 encapsulates packets with protocol
 502 .BR espinudp " or " espinudp-nonike ","
 503 .RI "using source port " SPORT ", destination port "  DPORT
 504 .RI ", and original address " OADDR "."
 505 .sp
 506 .TS
 507 l l.
 508 ip xfrm policy add      add a new policy
 509 ip xfrm policy update   update an existing policy
 510 ip xfrm policy delete   delete an existing policy
 511 ip xfrm policy get      get an existing policy
 512 ip xfrm policy deleteall        delete all existing xfrm policies
 513 ip xfrm policy list     print out the list of xfrm policies
 514 ip xfrm policy flush    flush policies
 515 ip xfrm policy count    count existing policies
 516 .TE
 517
 518 .TP
 519 .IR SELECTOR
 520 selects the traffic that will be controlled by the policy, based on the source
 521 address, the destination address, the network device, and/or
 522 .IR UPSPEC "."
 523
 524 .TP
 525 .IR UPSPEC
 526 selects traffic by protocol. For the
 527 .BR tcp ", " udp ", " sctp ", or " dccp
 528 protocols, the source and destination port can optionally be specified.
 529 For the
 530 .BR icmp ", " ipv6-icmp ", or " mobility-header
 531 protocols, the type and code numbers can optionally be specified.
 532 For the
 533 .B gre
 534 protocol, the key can optionally be specified as a dotted-quad or number.
 535 Other protocols can be selected by name or number
 536 .IR PROTO "."
 537
 538 .TP
 539 .I DIR
 540 selects the policy direction as
 541 .BR in ", " out ", or " fwd "."
 542
 543 .TP
 544 .I CTX
 545 sets the security context.
 546
 547 .TP
 548 .I PTYPE
 549 can be
 550 .BR main " (default) or " sub "."
 551
 552 .TP
 553 .I ACTION
 554 can be
 555 .BR allow " (default) or " block "."
 556
 557 .TP
 558 .I PRIORITY
 559 is a number that defaults to zero.
 560
 561 .TP
 562 .I FLAG-LIST
 563 contains one or both of the following optional flags:
 564 .BR local " or " icmp "."
 565
 566 .TP
 567 .I LIMIT-LIST
 568 sets limits in seconds, bytes, or numbers of packets.
 569
 570 .TP
 571 .I TMPL-LIST
 572 is a template list specified using
 573 .IR ID ", " MODE ", " REQID ", and/or " LEVEL ". "
 574
 575 .TP
 576 .IR ID
 577 is specified by a source address, destination address,
 578 .RI "transform protocol " XFRM-PROTO ","
 579 and/or Security Parameter Index
 580 .IR SPI "."
 581 (For IP Payload Compression, the Compression Parameter Index or CPI is used for
 582 .IR SPI ".)"
 583
 584 .TP
 585 .I XFRM-PROTO
 586 specifies a transform protocol:
 587 .RB "IPsec Encapsulating Security Payload (" esp "),"
 588 .RB "IPsec Authentication Header (" ah "),"
 589 .RB "IP Payload Compression (" comp "),"
 590 .RB "Mobile IPv6 Type 2 Routing Header (" route2 "), or"
 591 .RB "Mobile IPv6 Home Address Option (" hao ")."
 592
 593 .TP
 594 .I MODE
 595 specifies a mode of operation for the transform protocol. IPsec and IP Payload
 596 Compression modes are
 597 .BR transport ", " tunnel ","
 598 and (for IPsec ESP only) Bound End-to-End Tunnel
 599 .RB "(" beet ")."
 600 Mobile IPv6 modes are route optimization
 601 .RB "(" ro ")"
 602 and inbound trigger
 603 .RB "(" in_trigger ")."
 604
 605 .TP
 606 .I LEVEL
 607 can be
 608 .BR required " (default) or " use "."
 609
 610 The xfrm objects to monitor can be optionally specified.
 611
 612 .SH AUTHOR
 613 Manpage revised by David Ward <david.ward@ll.mit.edu>