src/vnet/session/session.api

   1 /*
   2  * Copyright (c) 2015-2019 Cisco and/or its affiliates.
   3  * Licensed under the Apache License, Version 2.0 (the "License");
   4  * you may not use this file except in compliance with the License.
   5  * You may obtain a copy of the License at:
   6  *
   7  *     http://www.apache.org/licenses/LICENSE-2.0
   8  *
   9  * Unless required by applicable law or agreed to in writing, software
  10  * distributed under the License is distributed on an "AS IS" BASIS,
  11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12  * See the License for the specific language governing permissions and
  13  * limitations under the License.
  14  */
  15
  16 option version = "2.0.0";
  17
  18 import "vnet/interface_types.api";
  19 import "vnet/ip/ip_types.api";
  20
  21
  22 enum transport_proto : u8
  23 {
  24         TRANSPORT_PROTO_API_TCP,
  25         TRANSPORT_PROTO_API_UDP,
  26         TRANSPORT_PROTO_API_NONE,
  27         TRANSPORT_PROTO_API_TLS,
  28         TRANSPORT_PROTO_API_UDPC,
  29         TRANSPORT_PROTO_API_QUIC,
  30 };
  31
  32 /** \brief client->vpp, attach application to session layer
  33         ### WILL BE DEPRECATED POST 20.01 ###
  34     @param client_index - opaque cookie to identify the sender
  35     @param context - sender context, to match reply w/ request
  36     @param initial_segment_size - size of the initial shm segment to be
  37                                                           allocated
  38     @param options - segment size, fifo sizes, etc.
  39     @param namespace_id - string
  40 */
  41  define application_attach {
  42     u32 client_index;
  43     u32 context;
  44     u32 initial_segment_size;
  45     u64 options[17];
  46     string namespace_id[];
  47  };
  48
  49  /** \brief Application attach reply
  50         ### WILL BE DEPRECATED POST 20.01 ###
  51     @param context - sender context, to match reply w/ request
  52     @param retval - return code for the request
  53     @param app_event_queue_address - vpp event queue address or 0 if this
  54                                          connection shouldn't send events
  55     @param n_fds - number of fds exchanged
  56     @param fd_flags - set of flags that indicate which fds are to be expected
  57                                   over the socket (set only if socket transport available)
  58     @param segment_size - size of first shm segment
  59     @param app_index - index of the newly created app
  60     @param segment_handle - handle for segment
  61     @param segment_name - name of segment client needs to attach to
  62 */
  63 define application_attach_reply {
  64     u32 context;
  65     i32 retval;
  66     u64 app_event_queue_address;
  67     u8 n_fds;
  68     u8 fd_flags;
  69     u32 segment_size;
  70     u32 app_index;
  71     u64 segment_handle;
  72     string segment_name[];
  73 };
  74
  75 /** \brief Application attach to session layer
  76     @param client_index - opaque cookie to identify the sender
  77     @param context - sender context, to match reply w/ request
  78     @param options - segment size, fifo sizes, etc.
  79     @param namespace_id - string
  80 */
  81  define app_attach {
  82     u32 client_index;
  83     u32 context;
  84     u64 options[17];
  85     string namespace_id[];
  86  };
  87
  88  /** \brief Application attach reply
  89     @param context - sender context, to match reply w/ request
  90     @param retval - return code for the request
  91     @param app_mq - app message queue
  92     @param vpp_ctrl_mq - vpp message queue for control events that should
  93                                          be handled in main thread, i.e., bind/connect
  94     @param vpp_ctrl_mq_thread_index - thread index of the ctrl mq
  95     @param app_index - index of the newly created app
  96     @param n_fds - number of fds exchanged
  97     @param fd_flags - set of flags that indicate which fds are to be expected
  98                                   over the socket (set only if socket transport available)
  99     @param segment_size - size of first shm segment
 100     @param segment_handle - handle for segment
 101     @param segment_name - name of segment client needs to attach to
 102 */
 103 define app_attach_reply {
 104     u32 context;
 105     i32 retval;
 106     u64 app_mq;
 107     u64 vpp_ctrl_mq;
 108     u8 vpp_ctrl_mq_thread;
 109     u32 app_index;
 110     u8 n_fds;
 111     u8 fd_flags;
 112     u32 segment_size;
 113     u64 segment_handle;
 114     string segment_name[];
 115 };
 116
 117 /** \brief Add certificate and key
 118     @param client_index - opaque cookie to identify the sender
 119     @param context - sender context, to match reply w/ request
 120     @param engine - crypto engine
 121     @param cert_len - cert length (comes first)
 122     @param certkey_len - cert and key length
 123     @param certkey - cert & key data (due to API limitation)
 124 */
 125 define app_add_cert_key_pair {
 126     u32 client_index;
 127     u32 context;
 128     u16 cert_len;
 129     u16 certkey_len;
 130     u8 certkey[certkey_len];
 131 };
 132
 133 /** \brief Add certificate and key
 134     @param context - sender context, to match reply w/ request
 135     @param retval - return code for the request
 136     @param index - index in certificate store
 137 */
 138 define app_add_cert_key_pair_reply {
 139     u32 context;
 140     i32 retval;
 141     u32 index;
 142 };
 143
 144 /** \brief Delete certificate and key
 145     @param client_index - opaque cookie to identify the sender
 146     @param context - sender context, to match reply w/ request
 147     @param index - index in certificate store
 148 */
 149 autoreply define app_del_cert_key_pair {
 150     u32 client_index;
 151     u32 context;
 152     u32 index;
 153 };
 154
 155 /** \brief Application add TLS certificate
 156         ### WILL BE DEPRECATED POST 20.01 ###
 157     @param client_index - opaque cookie to identify the sender
 158     @param context - sender context, to match reply w/ request
 159     @param cert_len - certificate length
 160     @param cert - certificate as a string
 161 */
 162 autoreply define application_tls_cert_add {
 163     u32 client_index;
 164     u32 context;
 165     u32 app_index;
 166     u16 cert_len;
 167     u8 cert[cert_len];
 168 };
 169
 170 /** \brief Application add TLS key
 171         ### WILL BE DEPRECATED POST 20.01 ###
 172     @param client_index - opaque cookie to identify the sender
 173     @param context - sender context, to match reply w/ request
 174     @param key_len - certificate length
 175     @param key - PEM encoded key as a string
 176 */
 177 autoreply define application_tls_key_add {
 178     u32 client_index;
 179     u32 context;
 180     u32 app_index;
 181     u16 key_len;
 182     u8 key[key_len];
 183 };
 184
 185  /** \brief client->vpp, attach application to session layer
 186         ### WILL BE DEPRECATED POST 20.01 ###
 187     @param client_index - opaque cookie to identify the sender
 188     @param context - sender context, to match reply w/ request
 189 */
 190 autoreply define application_detach {
 191     u32 client_index;
 192     u32 context;
 193  };
 194
 195 /** \brief vpp->client, please map an additional shared memory segment
 196         ### WILL BE DEPRECATED POST 20.01 ###
 197     @param client_index - opaque cookie to identify the sender
 198     @param context - sender context, to match reply w/ request
 199         @param fd_flags - set of flags that indicate which, if any, fds are
 200                                           to be expected over the socket. This is set only if
 201                                           socket transport available
 202     @param segment_size - size of the segment to be mapped
 203     @param segment_name - name of the segment to be mapped
 204     @param segment_handle - unique identifier for segment
 205 */
 206 autoreply define map_another_segment {
 207     u32 client_index;
 208     u32 context;
 209     u8 fd_flags;
 210     u32 segment_size;
 211     string segment_name[128];
 212     u64 segment_handle;
 213 };
 214
 215 /** \brief vpp->client unmap shared memory segment
 216         ### WILL BE DEPRECATED POST 20.01 ###
 217     @param client_index - opaque cookie to identify the sender
 218     @param context - sender context, to match reply w/ request
 219     @param segment_name - segment name
 220     @param segment_handle - handle of the segment to be unmapped
 221 */
 222 autoreply define unmap_segment {
 223     u32 client_index;
 224     u32 context;
 225     u64 segment_handle;
 226 };
 227
 228  /** \brief Bind to a given URI
 229         ### WILL BE DEPRECATED POST 20.01 ###
 230     @param client_index - opaque cookie to identify the sender
 231     @param context - sender context, to match reply w/ request
 232     @param accept_cookie - sender accept cookie, to identify this bind flavor
 233     @param uri - a URI, e.g. "tcp://0.0.0.0/0/80" [ipv4]
 234                  "tcp://::/0/80" [ipv6] etc.
 235     @param options - socket options, fifo sizes, etc.
 236 */
 237 autoreply define bind_uri {
 238   u32 client_index;
 239   u32 context;
 240   u32 accept_cookie;
 241   u8 uri[128];
 242 };
 243
 244 /** \brief Unbind a given URI
 245         ### WILL BE DEPRECATED POST 20.01 ###
 246     @param client_index - opaque cookie to identify the sender
 247     @param context - sender context, to match reply w/ request
 248     @param uri - a URI, e.g. "tcp://0.0.0.0/0/80" [ipv4]
 249                  "tcp://::/0/80" [ipv6], etc.
 250     @param options - socket options, fifo sizes, etc.
 251 */
 252 autoreply define unbind_uri {
 253   u32 client_index;
 254   u32 context;
 255   u8 uri[128];
 256 };
 257
 258 /** \brief Connect to a given URI
 259         ### WILL BE DEPRECATED POST 20.01 ###
 260     @param client_index - opaque cookie to identify the sender
 261     @param context - sender context, to match reply w/ request
 262     @param client_queue_address - binary API client queue address. Used by
 263                                                           local server when connect was redirected.
 264     @param options - socket options, fifo sizes, etc. passed by vpp to the
 265                                  server when redirecting connects
 266     @param uri - a URI, e.g. "tcp4://0.0.0.0/0/80"
 267                  "tcp6://::/0/80" [ipv6], etc.
 268 */
 269 autoreply define connect_uri {
 270   u32 client_index;
 271   u32 context;
 272   u64 client_queue_address;
 273   u64 options[16];
 274   u8 uri[128];
 275 };
 276
 277 /** \brief bidirectional disconnect API
 278         ### WILL BE DEPRECATED POST 20.01 ###
 279     @param client_index - opaque cookie to identify the sender
 280                           client to vpp direction only
 281     @param context - sender context, to match reply w/ request
 282     @param handle - session handle obtained from accept/connect
 283 */
 284 define disconnect_session {
 285   u32 client_index;
 286   u32 context;
 287   u64 handle;
 288 };
 289
 290 /** \brief bidirectional disconnect reply API
 291         ### WILL BE DEPRECATED POST 20.01 ###
 292     @param client_index - opaque cookie to identify the sender
 293                           client to vpp direction only
 294     @param context - sender context, to match reply w/ request
 295     @param retval - return code for the request
 296     @param handle - session handle
 297 */
 298 define disconnect_session_reply {
 299   u32 context;
 300   i32 retval;
 301   u64 handle;
 302 };
 303
 304 /** \brief Bind to an ip:port pair for a given transport protocol
 305         ### WILL BE DEPRECATED POST 20.01 ###
 306     @param client_index - opaque cookie to identify the sender
 307     @param context - sender context, to match reply w/ request
 308     @param wrk_index - index of worker requesting the bind
 309     @param vrf - bind namespace
 310     @param ip - ip address
 311     @param port - port
 312     @param proto - protocol 0 - TCP 1 - UDP
 313     @param options - socket options, fifo sizes, etc.
 314 */
 315 autoreply define bind_sock {
 316   u32 client_index;
 317   u32 context;
 318   u32 wrk_index;
 319   u32 vrf;
 320   vl_api_address_t ip;
 321   u16 port;
 322   vl_api_transport_proto_t proto;
 323   u64 options[16];
 324 };
 325
 326 /** \brief Unbind
 327         ### WILL BE DEPRECATED POST 20.01 ###s
 328     @param client_index - opaque cookie to identify the sender
 329     @param context - sender context, to match reply w/ request
 330     @param wrk_index - index of worker requesting the bind
 331     @param handle - bind handle obtained from bind reply
 332 */
 333 autoreply define unbind_sock {
 334   u32 client_index;
 335   u32 context;
 336   u32 wrk_index;
 337   u64 handle;
 338 };
 339
 340 /** \brief Connect to a remote peer
 341         ### WILL BE DEPRECATED POST 20.01 ###
 342     @param client_index - opaque cookie to identify the sender
 343     @param context - sender context, to match reply w/ request
 344     @param wrk_index - worker that requests the connect
 345     @param client_queue_address - client's API queue address. Non-zero when
 346                                   used to perform redirects
 347     @param options - socket options, fifo sizes, etc. when doing redirects
 348     @param vrf - connection namespace
 349     @param ip - ip address
 350     @param port - port
 351     @param proto - protocol 0 - TCP 1 - UDP
 352     @param hostname-len - length of hostname
 353     @param hostname - destination's hostname. If present, used by protocols
 354                                           like tls.
 355     @param parent_handle - handle of parent session (e.g. for opening quic streams).
 356 */
 357 autoreply define connect_sock {
 358   u32 client_index;
 359   u32 context;
 360   u32 wrk_index;
 361   u64 client_queue_address;
 362   u64 options[16];
 363   u32 vrf;
 364   vl_api_address_t ip;
 365   u16 port;
 366   vl_api_transport_proto_t proto;
 367   u64 parent_handle;
 368   string hostname[];
 369 };
 370
 371 /** \brief ask app to add a new cut-through registration
 372         ### WILL BE DEPRECATED POST 20.01 ###
 373     @param client_index - opaque cookie to identify the sender
 374                           client to vpp direction only
 375     @param context - sender context, to match reply w/ request
 376     @param evt_q_address - address of the mq in ssvm segment
 377     @param peer_evt_q_address - address of peer's mq in ssvm segment
 378     @param wrk_index - index of worker to receive the registration
 379     @param n_fds - number of fds exchanged
 380     @param fd_flags - flag indicating the fds that will be exchanged over
 381                                   api socket
 382 */
 383 autoreply define app_cut_through_registration_add
 384 {
 385   u32 client_index;
 386   u32 context;
 387   u64 evt_q_address;
 388   u64 peer_evt_q_address;
 389   u32 wrk_index;
 390   u8 n_fds;
 391   u8 fd_flags;
 392 };
 393
 394 /** \brief add/del application worker
 395     @param client_index - opaque cookie to identify the sender
 396                           client to vpp direction only
 397     @param context - sender context, to match reply w/ request
 398     @param app_index - application index
 399     @param wrk_index - worker index, if a delete
 400     @param is_add - set if an add
 401 */
 402 define app_worker_add_del
 403 {
 404   u32 client_index;
 405   u32 context;
 406   u32 app_index;
 407   u32 wrk_index;
 408   bool is_add [default=true];
 409 };
 410
 411 /** \brief Reply for app worker add/del
 412     @param context - returned sender context, to match reply w/ request
 413     @param retval - return code
 414     @param wrk_index - worker index, if add
 415     @param app_event_queue_address - vpp event queue address of new worker
 416     @param n_fds - number of fds exchanged
 417     @param fd_flags - set of flags that indicate which fds are to be expected
 418                                   over the socket (set only if socket transport available)
 419     @param segment_handle - handle for segment
 420     @param is_add - add if non zero, else delete
 421     @param segment_name - name of segment client needs to attach to
 422 */
 423 define app_worker_add_del_reply
 424 {
 425   u32 context;
 426   i32 retval;
 427   u32 wrk_index;
 428   u64 app_event_queue_address;
 429   u8 n_fds;
 430   u8 fd_flags;
 431   u64 segment_handle;
 432   bool is_add [default=true];
 433   string segment_name[];
 434 };
 435
 436 /** \brief enable/disable session layer
 437     @param client_index - opaque cookie to identify the sender
 438                           client to vpp direction only
 439     @param context - sender context, to match reply w/ request
 440     @param is_enable - disable session layer if 0, enable otherwise
 441 */
 442 autoreply define session_enable_disable {
 443   u32 client_index;
 444   u32 context;
 445   bool is_enable [default=true];
 446 };
 447
 448 /** \brief add/del application namespace
 449     @param client_index - opaque cookie to identify the sender
 450                           client to vpp direction only
 451     @param context - sender context, to match reply w/ request
 452     @param secret - secret shared between app and vpp
 453     @param sw_if_index - local interface that "supports" namespace. Set to
 454                          ~0 if no preference
 455     @param ip4_fib_id - id of ip4 fib that "supports" the namespace. Ignored
 456                         if sw_if_index set.
 457     @param ip6_fib_id - id of ip6 fib that "supports" the namespace. Ignored
 458                         if sw_if_index set.
 459     @param namespace_id - namespace id
 460 */
 461 define app_namespace_add_del {
 462   u32 client_index;
 463   u32 context;
 464   u64 secret;
 465   vl_api_interface_index_t sw_if_index;
 466   u32 ip4_fib_id;
 467   u32 ip6_fib_id;
 468   string namespace_id[];
 469 };
 470
 471 /** \brief Reply for app namespace add/del
 472     @param context - returned sender context, to match reply w/ request
 473     @param retval - return code
 474     @param appns_index - app namespace index
 475 */
 476 define app_namespace_add_del_reply
 477 {
 478   u32 context;
 479   i32 retval;
 480   u32 appns_index;
 481 };
 482
 483 enum session_rule_scope {
 484         SESSION_RULE_SCOPE_API_GLOBAL = 0,
 485         SESSION_RULE_SCOPE_API_LOCAL = 1,
 486         SESSION_RULE_SCOPE_API_BOTH = 2,
 487 };
 488
 489 /** \brief add/del session rule
 490     @param client_index - opaque cookie to identify the sender
 491                           client to vpp direction only
 492     @param context - sender context, to match reply w/ request
 493     @param transport_proto - transport protocol
 494     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 495     @param lcl_ip - local ip
 496     @param lcl_plen - local prefix length
 497     @param rmt_ip - remote ip
 498     @param rmt_ple - remote prefix length
 499     @param lcl_port - local port
 500     @param rmt_port - remote port
 501     @param action_index - the only action defined now is forward to
 502                           application with index action_index
 503     @param is_add - flag to indicate if add or del
 504     @param appns_index - application namespace where rule is to be applied to
 505     @param scope - enum that indicates scope of the rule: global or local.
 506                    If 0, default is global, 1 is global 2 is local, 3 is both
 507     @param tag - tag
 508 */
 509 autoreply define session_rule_add_del {
 510   u32 client_index;
 511   u32 context;
 512   vl_api_transport_proto_t transport_proto;
 513   vl_api_prefix_t lcl;
 514   vl_api_prefix_t rmt;
 515   u16 lcl_port;
 516   u16 rmt_port;
 517   u32 action_index;
 518   bool is_add [default=true];
 519   u32 appns_index;
 520   vl_api_session_rule_scope_t scope;
 521   string tag[64];
 522 };
 523
 524 /** \brief Dump session rules
 525     @param client_index - opaque cookie to identify the sender
 526     @param context - sender context, to match reply w/ request
 527  */
 528 define session_rules_dump
 529 {
 530   u32 client_index;
 531   u32 context;
 532 };
 533
 534 /** \brief Session rules details
 535     @param context - sender context, to match reply w/ request
 536     @param transport_proto - transport protocol
 537     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 538     @param lcl_ip - local ip
 539     @param lcl_plen - local prefix length
 540     @param rmt_ip - remote ip
 541     @param rmt_ple - remote prefix length
 542     @param lcl_port - local port
 543     @param rmt_port - remote port
 544     @param action_index - the only action defined now is forward to
 545                           application with index action_index
 546     @param appns_index - application namespace where rule is to be applied to
 547     @param scope - enum that indicates scope of the rule: global or local.
 548                    If 0, default is global, 1 is global 2 is local, 3 is both
 549     @param tag - tag
 550   */
 551 define session_rules_details
 552 {
 553   u32 context;
 554   vl_api_transport_proto_t transport_proto;
 555   vl_api_prefix_t lcl;
 556   vl_api_prefix_t rmt;
 557   u16 lcl_port;
 558   u16 rmt_port;
 559   u32 action_index;
 560   u32 appns_index;
 561   vl_api_session_rule_scope_t scope;
 562   string tag[64];
 563 };
 564
 565 /*
 566  * Local Variables:
 567  * eval: (c-set-style "gnu")
 568  * End:
 569  */