ipsec.api

Go to the documentation of this file.

/* Hey Emacs use -*- mode: C -*- */
/*
 * Copyright (c) 2015-2016 Cisco and/or its affiliates.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

option version = "3.0.0";

import "vnet/ip/ip_types.api";
import "vnet/interface_types.api";

/** \brief IPsec: Add/delete Security Policy Database
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param is_add - add SPD if non-zero, else delete
    @param spd_id - SPD instance id (control plane allocated)
*/

autoreply define ipsec_spd_add_del
{
  u32 client_index;
  u32 context;
  u8 is_add;
  u32 spd_id;
};

/** \brief IPsec: Add/delete SPD from interface

    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param is_add - add security mode if non-zero, else delete
    @param sw_if_index - index of the interface
    @param spd_id - SPD instance id to use for lookups
*/


autoreply define ipsec_interface_add_del_spd
{
  u32 client_index;
  u32 context;

  u8 is_add;
  u32 sw_if_index;
  u32 spd_id;
};


enum ipsec_spd_action
{
  /* bypass - no IPsec processing */
  IPSEC_API_SPD_ACTION_BYPASS = 0,
  /* discard - discard packet with ICMP processing */
  IPSEC_API_SPD_ACTION_DISCARD,
  /* resolve - send request to control plane for SA resolving */
  IPSEC_API_SPD_ACTION_RESOLVE,
  /* protect - apply IPsec policy using following parameters */
  IPSEC_API_SPD_ACTION_PROTECT,
};

/** \brief IPsec: Security Policy Database entry

    See RFC 4301, 4.4.1.1 on how to match packet to selectors

    @param spd_id - SPD instance id (control plane allocated)
    @param priority - priority of SPD entry (non-unique value).  Used to order SPD matching - higher priorities match before lower
    @param is_outbound - entry applies to outbound traffic if non-zero, otherwise applies to inbound traffic
    @param remote_address_start - start of remote address range to match
    @param remote_address_stop - end of remote address range to match
    @param local_address_start - start of local address range to match
    @param local_address_stop - end of local address range to match
    @param protocol - protocol type to match [0 means any] otherwise IANA value
    @param remote_port_start - start of remote port range to match ...
    @param remote_port_stop - end of remote port range to match [0 to 65535 means ANY, 65535 to 0 means OPAQUE]
    @param local_port_start - start of local port range to match ...
    @param local_port_stop - end of remote port range to match [0 to 65535 means ANY, 65535 to 0 means OPAQUE]
    @param policy - action to perform on match
    @param sa_id - SAD instance id (control plane allocated)
*/
typedef ipsec_spd_entry
{
  u32 spd_id;
  i32 priority;
  u8 is_outbound;

  u32 sa_id;
  vl_api_ipsec_spd_action_t policy;
  u8 protocol;

  // Selector
  vl_api_address_t remote_address_start;
  vl_api_address_t remote_address_stop;
  vl_api_address_t local_address_start;
  vl_api_address_t local_address_stop;

  u16 remote_port_start;
  u16 remote_port_stop;
  u16 local_port_start;
  u16 local_port_stop;
};

/** \brief IPsec: Add/delete Security Policy Database entry

    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param is_add - add SPD if non-zero, else delete
    @param entry - Description of the entry to add/dell
*/
define ipsec_spd_entry_add_del
{
  u32 client_index;
  u32 context;
  u8 is_add;
  vl_api_ipsec_spd_entry_t entry;
};

/** \brief IPsec: Reply Add/delete Security Policy Database entry

    @param context - sender context, to match reply w/ request
    @param retval - success/fail rutrun code
    @param stat_index - An index for the policy in the stats segment @ /net/ipec/policy
*/
define ipsec_spd_entry_add_del_reply
{
  u32 context;
  i32 retval;
  u32 stat_index;
};

/** \brief Dump IPsec all SPD IDs
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/
define ipsec_spds_dump {
  u32 client_index;
  u32 context;
};

/** \brief Dump IPsec all SPD IDs response
    @param client_index - opaque cookie to identify the sender
    @param spd_id - SPD instance id (control plane allocated)
    @param npolicies - number of policies in SPD
*/
define ipsec_spds_details {
  u32 context;
  u32 spd_id;
  u32 npolicies;
}; 

/** \brief Dump ipsec policy database data
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param spd_id - SPD instance id
    @param sa_id - SA id, optional, set to ~0 to see all policies in SPD
*/
define ipsec_spd_dump {
    u32 client_index;
    u32 context;
    u32 spd_id;
    u32 sa_id;
};

/** \brief IPsec policy database response
    @param context - sender context which was passed in the request
    €param entry - The SPD entry.
    @param bytes - byte count of packets matching this policy
    @param packets - count of packets matching this policy
*/
define ipsec_spd_details {
    u32 context;
    vl_api_ipsec_spd_entry_t entry;
};

/*
 * @brief Support cryptographic algorithms
 */
enum ipsec_crypto_alg
{
  IPSEC_API_CRYPTO_ALG_NONE = 0,
  IPSEC_API_CRYPTO_ALG_AES_CBC_128,
  IPSEC_API_CRYPTO_ALG_AES_CBC_192,
  IPSEC_API_CRYPTO_ALG_AES_CBC_256,
  IPSEC_API_CRYPTO_ALG_AES_CTR_128,
  IPSEC_API_CRYPTO_ALG_AES_CTR_192,
  IPSEC_API_CRYPTO_ALG_AES_CTR_256,
  IPSEC_API_CRYPTO_ALG_AES_GCM_128,
  IPSEC_API_CRYPTO_ALG_AES_GCM_192,
  IPSEC_API_CRYPTO_ALG_AES_GCM_256,
  IPSEC_API_CRYPTO_ALG_DES_CBC,
  IPSEC_API_CRYPTO_ALG_3DES_CBC,
};

/*
 * @brief Supported Integrity Algorithms
 */
enum ipsec_integ_alg
{
  IPSEC_API_INTEG_ALG_NONE = 0,
  /* RFC2403 */
  IPSEC_API_INTEG_ALG_MD5_96,
  /* RFC2404 */
  IPSEC_API_INTEG_ALG_SHA1_96,
  /* draft-ietf-ipsec-ciph-sha-256-00 */
  IPSEC_API_INTEG_ALG_SHA_256_96,
  /* RFC4868 */
  IPSEC_API_INTEG_ALG_SHA_256_128,
  /* RFC4868 */
  IPSEC_API_INTEG_ALG_SHA_384_192,
  /* RFC4868 */
  IPSEC_API_INTEG_ALG_SHA_512_256,
};

enum ipsec_sad_flags
{
  IPSEC_API_SAD_FLAG_NONE = 0,
  /* Enable extended sequence numbers */
  IPSEC_API_SAD_FLAG_USE_ESN = 0x01,
  /* Enable Anti-replay */
  IPSEC_API_SAD_FLAG_USE_ANTI_REPLAY = 0x02,
  /* IPsec tunnel mode if non-zero, else transport mode */
  IPSEC_API_SAD_FLAG_IS_TUNNEL = 0x04,
  /* IPsec tunnel mode is IPv6 if non-zero,
   *  else IPv4 tunnel only valid if is_tunnel is non-zero */
  IPSEC_API_SAD_FLAG_IS_TUNNEL_V6 = 0x08,
  /* enable UDP encapsulation for NAT traversal */
  IPSEC_API_SAD_FLAG_UDP_ENCAP = 0x10,
  /* IPsec SA is for inbound traffic */
  IPSEC_API_SAD_FLAG_IS_INBOUND = 0x40,
};

enum ipsec_proto
{
  IPSEC_API_PROTO_ESP,
  IPSEC_API_PROTO_AH,
};

typedef key
{
  /* the length of the key */
  u8 length;
  /* The data for the key */
  u8 data[128];
};

/** \brief IPsec: Security Association Database entry
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param is_add - add SAD entry if non-zero, else delete
    @param sad_id - sad id
    @param spi - security parameter index
    @param protocol - 0 = AH, 1 = ESP
    @param crypto_algorithm - a supported crypto algorithm
    @param crypto_key - crypto keying material
    @param integrity_algorithm - one of the supported algorithms
    @param integrity_key - integrity keying material
    @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
    @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
    @param tx_table_id - the FIB id used for encapsulated packets
    @param salt - for use with counter mode ciphers
 */
typedef ipsec_sad_entry
{
  u32 sad_id;

  u32 spi;

  vl_api_ipsec_proto_t protocol;

  vl_api_ipsec_crypto_alg_t crypto_algorithm;
  vl_api_key_t crypto_key;

  vl_api_ipsec_integ_alg_t integrity_algorithm;
  vl_api_key_t integrity_key;

  vl_api_ipsec_sad_flags_t flags;

  vl_api_address_t tunnel_src;
  vl_api_address_t tunnel_dst;
  u32 tx_table_id;
  u32 salt;
};

/** \brief IPsec: Add/delete Security Association Database entry
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param entry - Entry to add or delete
 */
define ipsec_sad_entry_add_del
{
  u32 client_index;
  u32 context;
  u8 is_add;
  vl_api_ipsec_sad_entry_t entry;
};
define ipsec_sad_entry_add_del_reply
{
  u32 context;
  i32 retval;
  u32 stat_index;
};

/** \brief Add or Update Protection for a tunnel with IPSEC

    Tunnel protection directly associates an SA with all packets
    ingress and egress on the tunnel. This could also be achieved by
    assigning an SPD to the tunnel, but that would incur an unnessccary
    SPD entry lookup.

    For tunnels the ESP acts on the post-encapsulated packet. So if this
    packet:
      +---------+------+
      | Payload | O-IP |
      +---------+------+
    where O-IP is the overlay IP addrees that was routed into the tunnel,
    the resulting encapsulated packet will be:
      +---------+------+------+
      | Payload | O-IP | T-IP |
      +---------+------+------+
    where T-IP is the tunnel's src.dst IP addresses.
    If the SAs used for protection are in transport mode then the ESP is
    inserted before T-IP, i.e.:
      +---------+------+-----+------+
      | Payload | O-IP | ESP | T-IP |
      +---------+------+-----+------+
    If the SAs used for protection are in tunnel mode then another
    encapsulation occurs, i.e.:
      +---------+------+------+-----+------+
      | Payload | O-IP | T-IP | ESP | C-IP |
      +---------+------+------+-----+------+
    where C-IP are the crypto endpoint IP addresses defined as the tunnel
    endpoints in the SA.
    The mode for the inbound and outbound SA must be the same.

    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_id_index - Tunnel interface to protect
    @param sa_in - The ID [set] of inbound SAs
    @param sa_out - The ID of outbound SA
*/
typedef ipsec_tunnel_protect
{
  vl_api_interface_index_t sw_if_index;
  u32 sa_out;
  u8 n_sa_in;
  u32 sa_in[n_sa_in];
};

autoreply define ipsec_tunnel_protect_update
{
  u32 client_index;
  u32 context;

  vl_api_ipsec_tunnel_protect_t tunnel;
};

autoreply define ipsec_tunnel_protect_del
{
  u32 client_index;
  u32 context;

  vl_api_interface_index_t sw_if_index;
};

define ipsec_tunnel_protect_dump
{
  u32 client_index;
  u32 context;
  vl_api_interface_index_t sw_if_index;
};

define ipsec_tunnel_protect_details
{
  u32 context;
  vl_api_ipsec_tunnel_protect_t tun;
};

/** \brief IPsec: Get SPD interfaces
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param spd_index - SPD index
    @param spd_index_valid - if 1 spd_index is used to filter
      spd_index's, if 0 no filtering is done
*/
define ipsec_spd_interface_dump {
    u32 client_index;
    u32 context;
    u32 spd_index;
    u8 spd_index_valid;
};

/** \brief IPsec: SPD interface response
    @param context - sender context which was passed in the request
    @param spd_index - SPD index
    @param sw_if_index - index of the interface
*/
define ipsec_spd_interface_details {
    u32 context;
    u32 spd_index;
    u32 sw_if_index;
};

/** \brief Add or delete IPsec tunnel interface
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param is_add - add IPsec tunnel interface if nonzero, else delete
    @param is_ip6 - tunnel v6 or v4
    @param esn - enable extended sequence numbers if nonzero, else disable
    @param anti_replay - enable anti replay check if nonzero, else disable
    @param local_ip - local IP address
    @param remote_ip - IP address of remote IPsec peer
    @param local_spi - SPI of outbound IPsec SA
    @param remote_spi - SPI of inbound IPsec SA
    @param crypto_alg - encryption algorithm ID
    @param local_crypto_key_len - length of local crypto key in bytes
    @param local_crypto_key - crypto key for outbound IPsec SA
    @param remote_crypto_key_len - length of remote crypto key in bytes
    @param remote_crypto_key - crypto key for inbound IPsec SA
    @param integ_alg - integrity algorithm ID
    @param local_integ_key_len - length of local integrity key in bytes
    @param local_integ_key - integrity key for outbound IPsec SA
    @param remote_integ_key_len - length of remote integrity key in bytes
    @param remote_integ_key - integrity key for inbound IPsec SA
    @param renumber - intf display name uses a specified instance if != 0
    @param show_instance - instance to display for intf if renumber is set
    @param udp_encap - enable UDP encapsulation for NAT traversal
    @param tx_table_id - the FIB id used after packet encap
    @param salt - for use with counter mode ciphers
*/
define ipsec_tunnel_if_add_del {
  u32 client_index;
  u32 context;
  u8 is_add;
  u8 esn;
  u8 anti_replay;
  vl_api_address_t local_ip;
  vl_api_address_t remote_ip;
  u32 local_spi;
  u32 remote_spi;
  u8 crypto_alg;
  u8 local_crypto_key_len;
  u8 local_crypto_key[128];
  u8 remote_crypto_key_len;
  u8 remote_crypto_key[128];
  u8 integ_alg;
  u8 local_integ_key_len;
  u8 local_integ_key[128];
  u8 remote_integ_key_len;
  u8 remote_integ_key[128];
  u8 renumber;
  u32 show_instance;
  u8 udp_encap;
  u32 tx_table_id;
  u32 salt;
};

/** \brief Add/delete IPsec tunnel interface response
    @param context - sender context, to match reply w/ request
    @param retval - return status
    @param sw_if_index - sw_if_index of new interface (for successful add)
*/
define ipsec_tunnel_if_add_del_reply {
  u32 context;
  i32 retval;
  u32 sw_if_index;
};

/** \brief Dump IPsec security association
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sa_id - optional ID of an SA to dump, if ~0 dump all SAs in SAD
*/
define ipsec_sa_dump {
  u32 client_index;
  u32 context;
  u32 sa_id;
};

/** \brief IPsec security association database response
    @param context - sender context which was passed in the request
    @param sa_id - SA ID, policy-based SAs >=0, tunnel interface SAs = 0 
    @param sw_if_index - sw_if_index of tunnel interface, policy-based SAs = ~0
    @param spi - security parameter index
    @param protocol - IPsec protocol (value from ipsec_protocol_t)
    @param crypto_alg - crypto algorithm (value from ipsec_crypto_alg_t)
    @param crypto_key_len - length of crypto_key in bytes
    @param crypto_key - crypto keying material
    @param integ_alg - integrity algorithm (value from ipsec_integ_alg_t)
    @param integ_key_len - length of integ_key in bytes
    @param integ_key - integrity keying material
    @param use_esn - using extended sequence numbers when non-zero
    @param use_anti_replay - using anti-replay window when non-zero
    @param is_tunnel - IPsec tunnel mode when non-zero, else transport mode
    @param is_tunnel_ipv6 - If using tunnel mode, endpoints are IPv6
    @param tunnel_src_addr - Tunnel source address if using tunnel mode
    @param tunnel_dst_addr - Tunnel destination address is using tunnel mode
    @param salt - 4 byte salt 
    @param seq - current sequence number for outbound
    @param seq_hi - high 32 bits of ESN for outbound 
    @param last_seq - highest sequence number received inbound
    @param last_seq_hi - high 32 bits of highest ESN received inbound
    @param replay_window - bit map of seq nums received relative to last_seq if using anti-replay
    @param total_data_size - total bytes sent or received
    @param udp_encap - 1 if UDP encap enabled, 0 otherwise
*/
define ipsec_sa_details {
  u32 context;
  vl_api_ipsec_sad_entry_t entry;

  u32 sw_if_index;
  u32 salt;
  u64 seq_outbound;
  u64 last_seq_inbound;
  u64 replay_window;

  u64 total_data_size;
};

/** \brief Set new SA on IPsec interface
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param sw_if_index - index of tunnel interface
    @param sa_id - ID of SA to use
    @param is_outbound - 1 if outbound (local) SA, 0 if inbound (remote)
*/
autoreply define ipsec_tunnel_if_set_sa {
  u32 client_index;
  u32 context;
  u32 sw_if_index;
  u32 sa_id;
  u8 is_outbound;
};

/** \brief Dump IPsec backends
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
*/
define ipsec_backend_dump {
  u32 client_index;
  u32 context;
};

/** \brief IPsec backend details
    @param name - name of the backend
    @param protocol - IPsec protocol (value from ipsec_protocol_t)
    @param index - backend index
    @param active - set to 1 if the backend is active, otherwise 0
*/
define ipsec_backend_details {
  u32 context;
  u8 name[128];
  vl_api_ipsec_proto_t protocol;
  u8 index;
  u8 active;
};

/** \brief Select IPsec backend
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param protocol - IPsec protocol (value from ipsec_protocol_t)
    @param index - backend index
*/
autoreply define ipsec_select_backend {
  u32 client_index;
  u32 context;
  vl_api_ipsec_proto_t protocol;
  u8 index;
};

/*
 * Local Variables:
 * eval: (c-set-style "gnu")
 * End:
 */