src/vnet/ipsec/ipsec.api

   1 /* Hey Emacs use -*- mode: C -*- */
   2 /*
   3  * Copyright (c) 2015-2016 Cisco and/or its affiliates.
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 option version = "3.0.0";
  18
  19 import "vnet/ip/ip_types.api";
  20 import "vnet/interface_types.api";
  21
  22 /** \brief IPsec: Add/delete Security Policy Database
  23     @param client_index - opaque cookie to identify the sender
  24     @param context - sender context, to match reply w/ request
  25     @param is_add - add SPD if non-zero, else delete
  26     @param spd_id - SPD instance id (control plane allocated)
  27 */
  28
  29 autoreply define ipsec_spd_add_del
  30 {
  31   u32 client_index;
  32   u32 context;
  33   u8 is_add;
  34   u32 spd_id;
  35 };
  36
  37 /** \brief IPsec: Add/delete SPD from interface
  38
  39     @param client_index - opaque cookie to identify the sender
  40     @param context - sender context, to match reply w/ request
  41     @param is_add - add security mode if non-zero, else delete
  42     @param sw_if_index - index of the interface
  43     @param spd_id - SPD instance id to use for lookups
  44 */
  45
  46
  47 autoreply define ipsec_interface_add_del_spd
  48 {
  49   u32 client_index;
  50   u32 context;
  51
  52   u8 is_add;
  53   u32 sw_if_index;
  54   u32 spd_id;
  55 };
  56
  57
  58 enum ipsec_spd_action
  59 {
  60   /* bypass - no IPsec processing */
  61   IPSEC_API_SPD_ACTION_BYPASS = 0,
  62   /* discard - discard packet with ICMP processing */
  63   IPSEC_API_SPD_ACTION_DISCARD,
  64   /* resolve - send request to control plane for SA resolving */
  65   IPSEC_API_SPD_ACTION_RESOLVE,
  66   /* protect - apply IPsec policy using following parameters */
  67   IPSEC_API_SPD_ACTION_PROTECT,
  68 };
  69
  70 /** \brief IPsec: Security Policy Database entry
  71
  72     See RFC 4301, 4.4.1.1 on how to match packet to selectors
  73
  74     @param spd_id - SPD instance id (control plane allocated)
  75     @param priority - priority of SPD entry (non-unique value).  Used to order SPD matching - higher priorities match before lower
  76     @param is_outbound - entry applies to outbound traffic if non-zero, otherwise applies to inbound traffic
  77     @param remote_address_start - start of remote address range to match
  78     @param remote_address_stop - end of remote address range to match
  79     @param local_address_start - start of local address range to match
  80     @param local_address_stop - end of local address range to match
  81     @param protocol - protocol type to match [0 means any] otherwise IANA value
  82     @param remote_port_start - start of remote port range to match ...
  83     @param remote_port_stop - end of remote port range to match [0 to 65535 means ANY, 65535 to 0 means OPAQUE]
  84     @param local_port_start - start of local port range to match ...
  85     @param local_port_stop - end of remote port range to match [0 to 65535 means ANY, 65535 to 0 means OPAQUE]
  86     @param policy - action to perform on match
  87     @param sa_id - SAD instance id (control plane allocated)
  88 */
  89 typedef ipsec_spd_entry
  90 {
  91   u32 spd_id;
  92   i32 priority;
  93   u8 is_outbound;
  94
  95   u32 sa_id;
  96   vl_api_ipsec_spd_action_t policy;
  97   u8 protocol;
  98
  99   // Selector
 100   vl_api_address_t remote_address_start;
 101   vl_api_address_t remote_address_stop;
 102   vl_api_address_t local_address_start;
 103   vl_api_address_t local_address_stop;
 104
 105   u16 remote_port_start;
 106   u16 remote_port_stop;
 107   u16 local_port_start;
 108   u16 local_port_stop;
 109 };
 110
 111 /** \brief IPsec: Add/delete Security Policy Database entry
 112
 113     @param client_index - opaque cookie to identify the sender
 114     @param context - sender context, to match reply w/ request
 115     @param is_add - add SPD if non-zero, else delete
 116     @param entry - Description of the entry to add/dell
 117 */
 118 define ipsec_spd_entry_add_del
 119 {
 120   u32 client_index;
 121   u32 context;
 122   u8 is_add;
 123   vl_api_ipsec_spd_entry_t entry;
 124 };
 125
 126 /** \brief IPsec: Reply Add/delete Security Policy Database entry
 127
 128     @param context - sender context, to match reply w/ request
 129     @param retval - success/fail rutrun code
 130     @param stat_index - An index for the policy in the stats segment @ /net/ipec/policy
 131 */
 132 define ipsec_spd_entry_add_del_reply
 133 {
 134   u32 context;
 135   i32 retval;
 136   u32 stat_index;
 137 };
 138
 139 /** \brief Dump IPsec all SPD IDs
 140     @param client_index - opaque cookie to identify the sender
 141     @param context - sender context, to match reply w/ request
 142 */
 143 define ipsec_spds_dump {
 144   u32 client_index;
 145   u32 context;
 146 };
 147
 148 /** \brief Dump IPsec all SPD IDs response
 149     @param client_index - opaque cookie to identify the sender
 150     @param spd_id - SPD instance id (control plane allocated)
 151     @param npolicies - number of policies in SPD
 152 */
 153 define ipsec_spds_details {
 154   u32 context;
 155   u32 spd_id;
 156   u32 npolicies;
 157 };
 158
 159 /** \brief Dump ipsec policy database data
 160     @param client_index - opaque cookie to identify the sender
 161     @param context - sender context, to match reply w/ request
 162     @param spd_id - SPD instance id
 163     @param sa_id - SA id, optional, set to ~0 to see all policies in SPD
 164 */
 165 define ipsec_spd_dump {
 166     u32 client_index;
 167     u32 context;
 168     u32 spd_id;
 169     u32 sa_id;
 170 };
 171
 172 /** \brief IPsec policy database response
 173     @param context - sender context which was passed in the request
 174     €param entry - The SPD entry.
 175     @param bytes - byte count of packets matching this policy
 176     @param packets - count of packets matching this policy
 177 */
 178 define ipsec_spd_details {
 179     u32 context;
 180     vl_api_ipsec_spd_entry_t entry;
 181 };
 182
 183 /*
 184  * @brief Support cryptographic algorithms
 185  */
 186 enum ipsec_crypto_alg
 187 {
 188   IPSEC_API_CRYPTO_ALG_NONE = 0,
 189   IPSEC_API_CRYPTO_ALG_AES_CBC_128,
 190   IPSEC_API_CRYPTO_ALG_AES_CBC_192,
 191   IPSEC_API_CRYPTO_ALG_AES_CBC_256,
 192   IPSEC_API_CRYPTO_ALG_AES_CTR_128,
 193   IPSEC_API_CRYPTO_ALG_AES_CTR_192,
 194   IPSEC_API_CRYPTO_ALG_AES_CTR_256,
 195   IPSEC_API_CRYPTO_ALG_AES_GCM_128,
 196   IPSEC_API_CRYPTO_ALG_AES_GCM_192,
 197   IPSEC_API_CRYPTO_ALG_AES_GCM_256,
 198   IPSEC_API_CRYPTO_ALG_DES_CBC,
 199   IPSEC_API_CRYPTO_ALG_3DES_CBC,
 200 };
 201
 202 /*
 203  * @brief Supported Integrity Algorithms
 204  */
 205 enum ipsec_integ_alg
 206 {
 207   IPSEC_API_INTEG_ALG_NONE = 0,
 208   /* RFC2403 */
 209   IPSEC_API_INTEG_ALG_MD5_96,
 210   /* RFC2404 */
 211   IPSEC_API_INTEG_ALG_SHA1_96,
 212   /* draft-ietf-ipsec-ciph-sha-256-00 */
 213   IPSEC_API_INTEG_ALG_SHA_256_96,
 214   /* RFC4868 */
 215   IPSEC_API_INTEG_ALG_SHA_256_128,
 216   /* RFC4868 */
 217   IPSEC_API_INTEG_ALG_SHA_384_192,
 218   /* RFC4868 */
 219   IPSEC_API_INTEG_ALG_SHA_512_256,
 220 };
 221
 222 enum ipsec_sad_flags
 223 {
 224   IPSEC_API_SAD_FLAG_NONE = 0,
 225   /* Enable extended sequence numbers */
 226   IPSEC_API_SAD_FLAG_USE_ESN = 0x01,
 227   /* Enable Anti-replay */
 228   IPSEC_API_SAD_FLAG_USE_ANTI_REPLAY = 0x02,
 229   /* IPsec tunnel mode if non-zero, else transport mode */
 230   IPSEC_API_SAD_FLAG_IS_TUNNEL = 0x04,
 231   /* IPsec tunnel mode is IPv6 if non-zero,
 232    *  else IPv4 tunnel only valid if is_tunnel is non-zero */
 233   IPSEC_API_SAD_FLAG_IS_TUNNEL_V6 = 0x08,
 234   /* enable UDP encapsulation for NAT traversal */
 235   IPSEC_API_SAD_FLAG_UDP_ENCAP = 0x10,
 236 };
 237
 238 enum ipsec_proto
 239 {
 240   IPSEC_API_PROTO_ESP,
 241   IPSEC_API_PROTO_AH,
 242 };
 243
 244 typedef key
 245 {
 246   /* the length of the key */
 247   u8 length;
 248   /* The data for the key */
 249   u8 data[128];
 250 };
 251
 252 /** \brief IPsec: Security Association Database entry
 253     @param client_index - opaque cookie to identify the sender
 254     @param context - sender context, to match reply w/ request
 255     @param is_add - add SAD entry if non-zero, else delete
 256     @param sad_id - sad id
 257     @param spi - security parameter index
 258     @param protocol - 0 = AH, 1 = ESP
 259     @param crypto_algorithm - a supported crypto algorithm
 260     @param crypto_key - crypto keying material
 261     @param integrity_algorithm - one of the supported algorithms
 262     @param integrity_key - integrity keying material
 263     @param tunnel_src_address - IPsec tunnel source address IPv6 if is_tunnel_ipv6 is non-zero, else IPv4. Only valid if is_tunnel is non-zero
 264     @param tunnel_dst_address - IPsec tunnel destination address IPv6 if is_tunnel_ipv6 is non-zero, else IPv4. Only valid if is_tunnel is non-zero
 265     @param tx_table_id - the FIB id used for encapsulated packets
 266     @param salt - for use with counter mode ciphers
 267  */
 268 typedef ipsec_sad_entry
 269 {
 270   u32 sad_id;
 271
 272   u32 spi;
 273
 274   vl_api_ipsec_proto_t protocol;
 275
 276   vl_api_ipsec_crypto_alg_t crypto_algorithm;
 277   vl_api_key_t crypto_key;
 278
 279   vl_api_ipsec_integ_alg_t integrity_algorithm;
 280   vl_api_key_t integrity_key;
 281
 282   vl_api_ipsec_sad_flags_t flags;
 283
 284   vl_api_address_t tunnel_src;
 285   vl_api_address_t tunnel_dst;
 286   u32 tx_table_id;
 287   u32 salt;
 288 };
 289
 290 /** \brief IPsec: Add/delete Security Association Database entry
 291     @param client_index - opaque cookie to identify the sender
 292     @param context - sender context, to match reply w/ request
 293     @param entry - Entry to add or delete
 294  */
 295 define ipsec_sad_entry_add_del
 296 {
 297   u32 client_index;
 298   u32 context;
 299   u8 is_add;
 300   vl_api_ipsec_sad_entry_t entry;
 301 };
 302 define ipsec_sad_entry_add_del_reply
 303 {
 304   u32 context;
 305   i32 retval;
 306   u32 stat_index;
 307 };
 308
 309 /** \brief Add or Update Protection for a tunnel with IPSEC
 310
 311     Tunnel protection directly associates an SA with all packets
 312     ingress and egress on the tunnel. This could also be achieved by
 313     assigning an SPD to the tunnel, but that would incur an unnessccary
 314     SPD entry lookup.
 315
 316     For tunnels the ESP acts on the post-encapsulated packet. So if this
 317     packet:
 318       +---------+------+
 319       | Payload | O-IP |
 320       +---------+------+
 321     where O-IP is the overlay IP addrees that was routed into the tunnel,
 322     the resulting encapsulated packet will be:
 323       +---------+------+------+
 324       | Payload | O-IP | T-IP |
 325       +---------+------+------+
 326     where T-IP is the tunnel's src.dst IP addresses.
 327     If the SAs used for protection are in transport mode then the ESP is
 328     inserted before T-IP, i.e.:
 329       +---------+------+-----+------+
 330       | Payload | O-IP | ESP | T-IP |
 331       +---------+------+-----+------+
 332     If the SAs used for protection are in tunnel mode then another
 333     encapsulation occurs, i.e.:
 334       +---------+------+------+-----+------+
 335       | Payload | O-IP | T-IP | ESP | C-IP |
 336       +---------+------+------+-----+------+
 337     where C-IP are the crypto endpoint IP addresses defined as the tunnel
 338     endpoints in the SA.
 339     The mode for the inbound and outbound SA must be the same.
 340
 341     @param client_index - opaque cookie to identify the sender
 342     @param context - sender context, to match reply w/ request
 343     @param sw_id_index - Tunnel interface to protect
 344     @param sa_in - The ID [set] of inbound SAs
 345     @param sa_out - The ID of outbound SA
 346 */
 347 typedef ipsec_tunnel_protect
 348 {
 349   vl_api_interface_index_t sw_if_index;
 350   u32 sa_out;
 351   u8 n_sa_in;
 352   u32 sa_in[n_sa_in];
 353 };
 354
 355 autoreply define ipsec_tunnel_protect_update
 356 {
 357   u32 client_index;
 358   u32 context;
 359
 360   vl_api_ipsec_tunnel_protect_t tunnel;
 361 };
 362
 363 autoreply define ipsec_tunnel_protect_del
 364 {
 365   u32 client_index;
 366   u32 context;
 367
 368   vl_api_interface_index_t sw_if_index;
 369 };
 370
 371 /**
 372  * @brief Dump all tunnel protections
 373  */
 374 define ipsec_tunnel_protect_dump
 375 {
 376   u32 client_index;
 377   u32 context;
 378   vl_api_interface_index_t sw_if_index;
 379 };
 380
 381 define ipsec_tunnel_protect_details
 382 {
 383   u32 context;
 384   vl_api_ipsec_tunnel_protect_t tun;
 385 };
 386
 387 /** \brief IPsec: Get SPD interfaces
 388     @param client_index - opaque cookie to identify the sender
 389     @param context - sender context, to match reply w/ request
 390     @param spd_index - SPD index
 391     @param spd_index_valid - if 1 spd_index is used to filter
 392       spd_index's, if 0 no filtering is done
 393 */
 394 define ipsec_spd_interface_dump {
 395     u32 client_index;
 396     u32 context;
 397     u32 spd_index;
 398     u8 spd_index_valid;
 399 };
 400
 401 /** \brief IPsec: SPD interface response
 402     @param context - sender context which was passed in the request
 403     @param spd_index - SPD index
 404     @param sw_if_index - index of the interface
 405 */
 406 define ipsec_spd_interface_details {
 407     u32 context;
 408     u32 spd_index;
 409     u32 sw_if_index;
 410 };
 411
 412 /** \brief Add or delete IPsec tunnel interface
 413
 414     !!DEPRECATED!!
 415          use the tunnel protect APIs instead
 416
 417     @param client_index - opaque cookie to identify the sender
 418     @param context - sender context, to match reply w/ request
 419     @param is_add - add IPsec tunnel interface if nonzero, else delete
 420     @param is_ip6 - tunnel v6 or v4
 421     @param esn - enable extended sequence numbers if nonzero, else disable
 422     @param anti_replay - enable anti replay check if nonzero, else disable
 423     @param local_ip - local IP address
 424     @param remote_ip - IP address of remote IPsec peer
 425     @param local_spi - SPI of outbound IPsec SA
 426     @param remote_spi - SPI of inbound IPsec SA
 427     @param crypto_alg - encryption algorithm ID
 428     @param local_crypto_key_len - length of local crypto key in bytes
 429     @param local_crypto_key - crypto key for outbound IPsec SA
 430     @param remote_crypto_key_len - length of remote crypto key in bytes
 431     @param remote_crypto_key - crypto key for inbound IPsec SA
 432     @param integ_alg - integrity algorithm ID
 433     @param local_integ_key_len - length of local integrity key in bytes
 434     @param local_integ_key - integrity key for outbound IPsec SA
 435     @param remote_integ_key_len - length of remote integrity key in bytes
 436     @param remote_integ_key - integrity key for inbound IPsec SA
 437     @param renumber - intf display name uses a specified instance if != 0
 438     @param show_instance - instance to display for intf if renumber is set
 439     @param udp_encap - enable UDP encapsulation for NAT traversal
 440     @param tx_table_id - the FIB id used after packet encap
 441     @param salt - for use with counter mode ciphers
 442 */
 443 define ipsec_tunnel_if_add_del {
 444   u32 client_index;
 445   u32 context;
 446   u8 is_add;
 447   u8 esn;
 448   u8 anti_replay;
 449   vl_api_address_t local_ip;
 450   vl_api_address_t remote_ip;
 451   u32 local_spi;
 452   u32 remote_spi;
 453   u8 crypto_alg;
 454   u8 local_crypto_key_len;
 455   u8 local_crypto_key[128];
 456   u8 remote_crypto_key_len;
 457   u8 remote_crypto_key[128];
 458   u8 integ_alg;
 459   u8 local_integ_key_len;
 460   u8 local_integ_key[128];
 461   u8 remote_integ_key_len;
 462   u8 remote_integ_key[128];
 463   u8 renumber;
 464   u32 show_instance;
 465   u8 udp_encap;
 466   u32 tx_table_id;
 467   u32 salt;
 468 };
 469
 470 /** \brief Add/delete IPsec tunnel interface response
 471     @param context - sender context, to match reply w/ request
 472     @param retval - return status
 473     @param sw_if_index - sw_if_index of new interface (for successful add)
 474 */
 475 define ipsec_tunnel_if_add_del_reply {
 476   u32 context;
 477   i32 retval;
 478   u32 sw_if_index;
 479 };
 480
 481 /** \brief Dump IPsec security association
 482     @param client_index - opaque cookie to identify the sender
 483     @param context - sender context, to match reply w/ request
 484     @param sa_id - optional ID of an SA to dump, if ~0 dump all SAs in SAD
 485 */
 486 define ipsec_sa_dump {
 487   u32 client_index;
 488   u32 context;
 489   u32 sa_id;
 490 };
 491
 492 /** \brief IPsec security association database response
 493     @param context - sender context which was passed in the request
 494     @param sa_id - SA ID, policy-based SAs >=0, tunnel interface SAs = 0
 495     @param sw_if_index - sw_if_index of tunnel interface, policy-based SAs = ~0
 496     @param spi - security parameter index
 497     @param protocol - IPsec protocol (value from ipsec_protocol_t)
 498     @param crypto_alg - crypto algorithm (value from ipsec_crypto_alg_t)
 499     @param crypto_key_len - length of crypto_key in bytes
 500     @param crypto_key - crypto keying material
 501     @param integ_alg - integrity algorithm (value from ipsec_integ_alg_t)
 502     @param integ_key_len - length of integ_key in bytes
 503     @param integ_key - integrity keying material
 504     @param use_esn - using extended sequence numbers when non-zero
 505     @param use_anti_replay - using anti-replay window when non-zero
 506     @param is_tunnel - IPsec tunnel mode when non-zero, else transport mode
 507     @param is_tunnel_ipv6 - If using tunnel mode, endpoints are IPv6
 508     @param tunnel_src_addr - Tunnel source address if using tunnel mode
 509     @param tunnel_dst_addr - Tunnel destination address is using tunnel mode
 510     @param salt - 4 byte salt
 511     @param seq - current sequence number for outbound
 512     @param seq_hi - high 32 bits of ESN for outbound
 513     @param last_seq - highest sequence number received inbound
 514     @param last_seq_hi - high 32 bits of highest ESN received inbound
 515     @param replay_window - bit map of seq nums received relative to last_seq if using anti-replay
 516     @param total_data_size - total bytes sent or received
 517     @param udp_encap - 1 if UDP encap enabled, 0 otherwise
 518 */
 519 define ipsec_sa_details {
 520   u32 context;
 521   vl_api_ipsec_sad_entry_t entry;
 522
 523   u32 sw_if_index;
 524   u32 salt;
 525   u64 seq_outbound;
 526   u64 last_seq_inbound;
 527   u64 replay_window;
 528
 529   u64 total_data_size;
 530 };
 531
 532 /** \brief Set new SA on IPsec interface
 533
 534     !! DEPRECATED !!
 535
 536     @param client_index - opaque cookie to identify the sender
 537     @param context - sender context, to match reply w/ request
 538     @param sw_if_index - index of tunnel interface
 539     @param sa_id - ID of SA to use
 540     @param is_outbound - 1 if outbound (local) SA, 0 if inbound (remote)
 541 */
 542 autoreply define ipsec_tunnel_if_set_sa {
 543   u32 client_index;
 544   u32 context;
 545   u32 sw_if_index;
 546   u32 sa_id;
 547   u8 is_outbound;
 548 };
 549
 550 /** \brief Dump IPsec backends
 551     @param client_index - opaque cookie to identify the sender
 552     @param context - sender context, to match reply w/ request
 553 */
 554 define ipsec_backend_dump {
 555   u32 client_index;
 556   u32 context;
 557 };
 558
 559 /** \brief IPsec backend details
 560     @param name - name of the backend
 561     @param protocol - IPsec protocol (value from ipsec_protocol_t)
 562     @param index - backend index
 563     @param active - set to 1 if the backend is active, otherwise 0
 564 */
 565 define ipsec_backend_details {
 566   u32 context;
 567   u8 name[128];
 568   vl_api_ipsec_proto_t protocol;
 569   u8 index;
 570   u8 active;
 571 };
 572
 573 /** \brief Select IPsec backend
 574     @param client_index - opaque cookie to identify the sender
 575     @param context - sender context, to match reply w/ request
 576     @param protocol - IPsec protocol (value from ipsec_protocol_t)
 577     @param index - backend index
 578 */
 579 autoreply define ipsec_select_backend {
 580   u32 client_index;
 581   u32 context;
 582   vl_api_ipsec_proto_t protocol;
 583   u8 index;
 584 };
 585
 586 /*
 587  * Local Variables:
 588  * eval: (c-set-style "gnu")
 589  * End:
 590  */
 591