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