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/ipsec/ipsec_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 /** \brief IPsec: Add/delete Security Association Database entry
 184     @param client_index - opaque cookie to identify the sender
 185     @param context - sender context, to match reply w/ request
 186     @param entry - Entry to add or delete
 187  */
 188 define ipsec_sad_entry_add_del
 189 {
 190   u32 client_index;
 191   u32 context;
 192   u8 is_add;
 193   vl_api_ipsec_sad_entry_t entry;
 194 };
 195 define ipsec_sad_entry_add_del_reply
 196 {
 197   u32 context;
 198   i32 retval;
 199   u32 stat_index;
 200 };
 201
 202 /** \brief Add or Update Protection for a tunnel with IPSEC
 203
 204     Tunnel protection directly associates an SA with all packets
 205     ingress and egress on the tunnel. This could also be achieved by
 206     assigning an SPD to the tunnel, but that would incur an unnessccary
 207     SPD entry lookup.
 208
 209     For tunnels the ESP acts on the post-encapsulated packet. So if this
 210     packet:
 211       +---------+------+
 212       | Payload | O-IP |
 213       +---------+------+
 214     where O-IP is the overlay IP addrees that was routed into the tunnel,
 215     the resulting encapsulated packet will be:
 216       +---------+------+------+
 217       | Payload | O-IP | T-IP |
 218       +---------+------+------+
 219     where T-IP is the tunnel's src.dst IP addresses.
 220     If the SAs used for protection are in transport mode then the ESP is
 221     inserted before T-IP, i.e.:
 222       +---------+------+-----+------+
 223       | Payload | O-IP | ESP | T-IP |
 224       +---------+------+-----+------+
 225     If the SAs used for protection are in tunnel mode then another
 226     encapsulation occurs, i.e.:
 227       +---------+------+------+-----+------+
 228       | Payload | O-IP | T-IP | ESP | C-IP |
 229       +---------+------+------+-----+------+
 230     where C-IP are the crypto endpoint IP addresses defined as the tunnel
 231     endpoints in the SA.
 232     The mode for the inbound and outbound SA must be the same.
 233
 234     @param client_index - opaque cookie to identify the sender
 235     @param context - sender context, to match reply w/ request
 236     @param sw_id_index - Tunnel interface to protect
 237     @param nh - The peer/next-hop on the tunnel to which the traffic
 238                 should be protected. For a P2P interface set this to the
 239                 all 0s address.
 240     @param sa_in - The ID [set] of inbound SAs
 241     @param sa_out - The ID of outbound SA
 242 */
 243 typedef ipsec_tunnel_protect
 244 {
 245   vl_api_interface_index_t sw_if_index;
 246   vl_api_address_t nh;
 247   u32 sa_out;
 248   u8 n_sa_in;
 249   u32 sa_in[n_sa_in];
 250 };
 251
 252 autoreply define ipsec_tunnel_protect_update
 253 {
 254   u32 client_index;
 255   u32 context;
 256
 257   vl_api_ipsec_tunnel_protect_t tunnel;
 258 };
 259
 260 autoreply define ipsec_tunnel_protect_del
 261 {
 262   u32 client_index;
 263   u32 context;
 264
 265   vl_api_interface_index_t sw_if_index;
 266   vl_api_address_t nh;
 267 };
 268
 269 /**
 270  * @brief Dump all tunnel protections
 271  */
 272 define ipsec_tunnel_protect_dump
 273 {
 274   u32 client_index;
 275   u32 context;
 276   vl_api_interface_index_t sw_if_index;
 277 };
 278
 279 define ipsec_tunnel_protect_details
 280 {
 281   u32 context;
 282   vl_api_ipsec_tunnel_protect_t tun;
 283 };
 284
 285 /** \brief IPsec: Get SPD interfaces
 286     @param client_index - opaque cookie to identify the sender
 287     @param context - sender context, to match reply w/ request
 288     @param spd_index - SPD index
 289     @param spd_index_valid - if 1 spd_index is used to filter
 290       spd_index's, if 0 no filtering is done
 291 */
 292 define ipsec_spd_interface_dump {
 293     u32 client_index;
 294     u32 context;
 295     u32 spd_index;
 296     u8 spd_index_valid;
 297 };
 298
 299 /** \brief IPsec: SPD interface response
 300     @param context - sender context which was passed in the request
 301     @param spd_index - SPD index
 302     @param sw_if_index - index of the interface
 303 */
 304 define ipsec_spd_interface_details {
 305     u32 context;
 306     u32 spd_index;
 307     u32 sw_if_index;
 308 };
 309
 310 /** \brief Add or delete IPsec tunnel interface
 311
 312     !!DEPRECATED!!
 313          use the tunnel protect APIs instead
 314
 315     @param client_index - opaque cookie to identify the sender
 316     @param context - sender context, to match reply w/ request
 317     @param is_add - add IPsec tunnel interface if nonzero, else delete
 318     @param is_ip6 - tunnel v6 or v4
 319     @param esn - enable extended sequence numbers if nonzero, else disable
 320     @param anti_replay - enable anti replay check if nonzero, else disable
 321     @param local_ip - local IP address
 322     @param remote_ip - IP address of remote IPsec peer
 323     @param local_spi - SPI of outbound IPsec SA
 324     @param remote_spi - SPI of inbound IPsec SA
 325     @param crypto_alg - encryption algorithm ID
 326     @param local_crypto_key_len - length of local crypto key in bytes
 327     @param local_crypto_key - crypto key for outbound IPsec SA
 328     @param remote_crypto_key_len - length of remote crypto key in bytes
 329     @param remote_crypto_key - crypto key for inbound IPsec SA
 330     @param integ_alg - integrity algorithm ID
 331     @param local_integ_key_len - length of local integrity key in bytes
 332     @param local_integ_key - integrity key for outbound IPsec SA
 333     @param remote_integ_key_len - length of remote integrity key in bytes
 334     @param remote_integ_key - integrity key for inbound IPsec SA
 335     @param renumber - intf display name uses a specified instance if != 0
 336     @param show_instance - instance to display for intf if renumber is set
 337     @param udp_encap - enable UDP encapsulation for NAT traversal
 338     @param tx_table_id - the FIB id used after packet encap
 339     @param salt - for use with counter mode ciphers
 340 */
 341 define ipsec_tunnel_if_add_del {
 342   u32 client_index;
 343   u32 context;
 344   u8 is_add;
 345   u8 esn;
 346   u8 anti_replay;
 347   vl_api_address_t local_ip;
 348   vl_api_address_t remote_ip;
 349   u32 local_spi;
 350   u32 remote_spi;
 351   u8 crypto_alg;
 352   u8 local_crypto_key_len;
 353   u8 local_crypto_key[128];
 354   u8 remote_crypto_key_len;
 355   u8 remote_crypto_key[128];
 356   u8 integ_alg;
 357   u8 local_integ_key_len;
 358   u8 local_integ_key[128];
 359   u8 remote_integ_key_len;
 360   u8 remote_integ_key[128];
 361   u8 renumber;
 362   u32 show_instance;
 363   u8 udp_encap;
 364   u32 tx_table_id;
 365   u32 salt;
 366 };
 367
 368 /** \brief Add/delete IPsec tunnel interface response
 369     @param context - sender context, to match reply w/ request
 370     @param retval - return status
 371     @param sw_if_index - sw_if_index of new interface (for successful add)
 372 */
 373 define ipsec_tunnel_if_add_del_reply {
 374   u32 context;
 375   i32 retval;
 376   u32 sw_if_index;
 377 };
 378
 379 /** \brief Dump IPsec security association
 380     @param client_index - opaque cookie to identify the sender
 381     @param context - sender context, to match reply w/ request
 382     @param sa_id - optional ID of an SA to dump, if ~0 dump all SAs in SAD
 383 */
 384 define ipsec_sa_dump {
 385   u32 client_index;
 386   u32 context;
 387   u32 sa_id;
 388 };
 389
 390 /** \brief IPsec security association database response
 391     @param context - sender context which was passed in the request
 392     @param sa_id - SA ID, policy-based SAs >=0, tunnel interface SAs = 0
 393     @param sw_if_index - sw_if_index of tunnel interface, policy-based SAs = ~0
 394     @param spi - security parameter index
 395     @param protocol - IPsec protocol (value from ipsec_protocol_t)
 396     @param crypto_alg - crypto algorithm (value from ipsec_crypto_alg_t)
 397     @param crypto_key_len - length of crypto_key in bytes
 398     @param crypto_key - crypto keying material
 399     @param integ_alg - integrity algorithm (value from ipsec_integ_alg_t)
 400     @param integ_key_len - length of integ_key in bytes
 401     @param integ_key - integrity keying material
 402     @param use_esn - using extended sequence numbers when non-zero
 403     @param use_anti_replay - using anti-replay window when non-zero
 404     @param is_tunnel - IPsec tunnel mode when non-zero, else transport mode
 405     @param is_tunnel_ipv6 - If using tunnel mode, endpoints are IPv6
 406     @param tunnel_src_addr - Tunnel source address if using tunnel mode
 407     @param tunnel_dst_addr - Tunnel destination address is using tunnel mode
 408     @param salt - 4 byte salt
 409     @param seq - current sequence number for outbound
 410     @param seq_hi - high 32 bits of ESN for outbound
 411     @param last_seq - highest sequence number received inbound
 412     @param last_seq_hi - high 32 bits of highest ESN received inbound
 413     @param replay_window - bit map of seq nums received relative to last_seq if using anti-replay
 414     @param total_data_size - total bytes sent or received
 415     @param udp_encap - 1 if UDP encap enabled, 0 otherwise
 416 */
 417 define ipsec_sa_details {
 418   u32 context;
 419   vl_api_ipsec_sad_entry_t entry;
 420
 421   u32 sw_if_index;
 422   u32 salt;
 423   u64 seq_outbound;
 424   u64 last_seq_inbound;
 425   u64 replay_window;
 426
 427   u64 total_data_size;
 428 };
 429
 430 /** \brief Set new SA on IPsec interface
 431
 432     !! DEPRECATED !!
 433
 434     @param client_index - opaque cookie to identify the sender
 435     @param context - sender context, to match reply w/ request
 436     @param sw_if_index - index of tunnel interface
 437     @param sa_id - ID of SA to use
 438     @param is_outbound - 1 if outbound (local) SA, 0 if inbound (remote)
 439 */
 440 autoreply define ipsec_tunnel_if_set_sa {
 441   u32 client_index;
 442   u32 context;
 443   u32 sw_if_index;
 444   u32 sa_id;
 445   u8 is_outbound;
 446 };
 447
 448 /** \brief Dump IPsec backends
 449     @param client_index - opaque cookie to identify the sender
 450     @param context - sender context, to match reply w/ request
 451 */
 452 define ipsec_backend_dump {
 453   u32 client_index;
 454   u32 context;
 455 };
 456
 457 /** \brief IPsec backend details
 458     @param name - name of the backend
 459     @param protocol - IPsec protocol (value from ipsec_protocol_t)
 460     @param index - backend index
 461     @param active - set to 1 if the backend is active, otherwise 0
 462 */
 463 define ipsec_backend_details {
 464   u32 context;
 465   u8 name[128];
 466   vl_api_ipsec_proto_t protocol;
 467   u8 index;
 468   u8 active;
 469 };
 470
 471 /** \brief Select IPsec backend
 472     @param client_index - opaque cookie to identify the sender
 473     @param context - sender context, to match reply w/ request
 474     @param protocol - IPsec protocol (value from ipsec_protocol_t)
 475     @param index - backend index
 476 */
 477 autoreply define ipsec_select_backend {
 478   u32 client_index;
 479   u32 context;
 480   vl_api_ipsec_proto_t protocol;
 481   u8 index;
 482 };
 483
 484 /*
 485  * Local Variables:
 486  * eval: (c-set-style "gnu")
 487  * End:
 488  */
 489