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[16];
  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[16];
  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     @param client_index - opaque cookie to identify the sender
 191     @param context - sender context, to match reply w/ request
 192         @param fd_flags - set of flags that indicate which, if any, fds are
 193                                           to be expected over the socket. This is set only if
 194                                           socket transport available
 195     @param segment_size - size of the segment to be mapped
 196     @param segment_name - name of the segment to be mapped
 197     @param segment_handle - unique identifier for segment
 198 */
 199 autoreply define map_another_segment {
 200     u32 client_index;
 201     u32 context;
 202     u8 fd_flags;
 203     u32 segment_size;
 204     u8 segment_name[128];
 205     u64 segment_handle;
 206 };
 207
 208 /** \brief vpp->client unmap shared memory segment
 209     @param client_index - opaque cookie to identify the sender
 210     @param context - sender context, to match reply w/ request
 211     @param segment_name - segment name
 212     @param segment_handle - handle of the segment to be unmapped
 213 */
 214 autoreply define unmap_segment {
 215     u32 client_index;
 216     u32 context;
 217     u64 segment_handle;
 218 };
 219
 220  /** \brief Bind to a given URI
 221         ### WILL BE DEPRECATED POST 20.01 ###
 222     @param client_index - opaque cookie to identify the sender
 223     @param context - sender context, to match reply w/ request
 224     @param accept_cookie - sender accept cookie, to identify this bind flavor
 225     @param uri - a URI, e.g. "tcp://0.0.0.0/0/80" [ipv4]
 226                  "tcp://::/0/80" [ipv6] etc.
 227     @param options - socket options, fifo sizes, etc.
 228 */
 229 autoreply define bind_uri {
 230   u32 client_index;
 231   u32 context;
 232   u32 accept_cookie;
 233   u8 uri[128];
 234 };
 235
 236 /** \brief Unbind a given URI
 237         ### WILL BE DEPRECATED POST 20.01 ###
 238     @param client_index - opaque cookie to identify the sender
 239     @param context - sender context, to match reply w/ request
 240     @param uri - a URI, e.g. "tcp://0.0.0.0/0/80" [ipv4]
 241                  "tcp://::/0/80" [ipv6], etc.
 242     @param options - socket options, fifo sizes, etc.
 243 */
 244 autoreply define unbind_uri {
 245   u32 client_index;
 246   u32 context;
 247   u8 uri[128];
 248 };
 249
 250 /** \brief Connect to a given URI
 251         ### WILL BE DEPRECATED POST 20.01 ###
 252     @param client_index - opaque cookie to identify the sender
 253     @param context - sender context, to match reply w/ request
 254     @param client_queue_address - binary API client queue address. Used by
 255                                                           local server when connect was redirected.
 256     @param options - socket options, fifo sizes, etc. passed by vpp to the
 257                                  server when redirecting connects
 258     @param uri - a URI, e.g. "tcp4://0.0.0.0/0/80"
 259                  "tcp6://::/0/80" [ipv6], etc.
 260 */
 261 autoreply define connect_uri {
 262   u32 client_index;
 263   u32 context;
 264   u64 client_queue_address;
 265   u64 options[16];
 266   u8 uri[128];
 267 };
 268
 269 /** \brief bidirectional disconnect API
 270         ### WILL BE DEPRECATED POST 20.01 ###
 271     @param client_index - opaque cookie to identify the sender
 272                           client to vpp direction only
 273     @param context - sender context, to match reply w/ request
 274     @param handle - session handle obtained from accept/connect
 275 */
 276 define disconnect_session {
 277   u32 client_index;
 278   u32 context;
 279   u64 handle;
 280 };
 281
 282 /** \brief bidirectional disconnect reply API
 283         ### WILL BE DEPRECATED POST 20.01 ###
 284     @param client_index - opaque cookie to identify the sender
 285                           client to vpp direction only
 286     @param context - sender context, to match reply w/ request
 287     @param retval - return code for the request
 288     @param handle - session handle
 289 */
 290 define disconnect_session_reply {
 291   u32 context;
 292   i32 retval;
 293   u64 handle;
 294 };
 295
 296 /** \brief Bind to an ip:port pair for a given transport protocol
 297         ### WILL BE DEPRECATED POST 20.01 ###
 298     @param client_index - opaque cookie to identify the sender
 299     @param context - sender context, to match reply w/ request
 300     @param wrk_index - index of worker requesting the bind
 301     @param vrf - bind namespace
 302     @param is_ip4 - flag that is 1 if ip address family is IPv4
 303     @param ip - ip address
 304     @param port - port
 305     @param proto - protocol 0 - TCP 1 - UDP
 306     @param options - socket options, fifo sizes, etc.
 307 */
 308 autoreply define bind_sock {
 309   u32 client_index;
 310   u32 context;
 311   u32 wrk_index;
 312   u32 vrf;
 313   u8 is_ip4;
 314   u8 ip[16];
 315   u16 port;
 316   u8 proto;
 317   u64 options[16];
 318 };
 319
 320 /** \brief Unbind
 321         ### WILL BE DEPRECATED POST 20.01 ###s
 322     @param client_index - opaque cookie to identify the sender
 323     @param context - sender context, to match reply w/ request
 324     @param wrk_index - index of worker requesting the bind
 325     @param handle - bind handle obtained from bind reply
 326 */
 327 autoreply define unbind_sock {
 328   u32 client_index;
 329   u32 context;
 330   u32 wrk_index;
 331   u64 handle;
 332 };
 333
 334 /** \brief Connect to a remote peer
 335         ### WILL BE DEPRECATED POST 20.01 ###
 336     @param client_index - opaque cookie to identify the sender
 337     @param context - sender context, to match reply w/ request
 338     @param wrk_index - worker that requests the connect
 339     @param client_queue_address - client's API queue address. Non-zero when
 340                                   used to perform redirects
 341     @param options - socket options, fifo sizes, etc. when doing redirects
 342     @param vrf - connection namespace
 343     @param is_ip4 - flag that is 1 if ip address family is IPv4
 344     @param ip - ip address
 345     @param port - port
 346     @param proto - protocol 0 - TCP 1 - UDP
 347     @param hostname-len - length of hostname
 348     @param hostname - destination's hostname. If present, used by protocols
 349                                           like tls.
 350     @param parent_handle - handle of parent session (e.g. for opening quic streams).
 351 */
 352 autoreply define connect_sock {
 353   u32 client_index;
 354   u32 context;
 355   u32 wrk_index;
 356   u64 client_queue_address;
 357   u64 options[16];
 358   u32 vrf;
 359   u8 is_ip4;
 360   u8 ip[16];
 361   u16 port;
 362   u8 proto;
 363   u64 parent_handle;
 364   u8 hostname_len;
 365   u8 hostname[hostname_len];
 366 };
 367
 368 /** \brief ask app to add a new cut-through registration
 369         ### WILL BE DEPRECATED POST 20.01 ###
 370     @param client_index - opaque cookie to identify the sender
 371                           client to vpp direction only
 372     @param context - sender context, to match reply w/ request
 373     @param evt_q_address - address of the mq in ssvm segment
 374     @param peer_evt_q_address - address of peer's mq in ssvm segment
 375     @param wrk_index - index of worker to receive the registration
 376     @param n_fds - number of fds exchanged
 377     @param fd_flags - flag indicating the fds that will be exchanged over
 378                                   api socket
 379 */
 380 autoreply define app_cut_through_registration_add
 381 {
 382   u32 client_index;
 383   u32 context;
 384   u64 evt_q_address;
 385   u64 peer_evt_q_address;
 386   u32 wrk_index;
 387   u8 n_fds;
 388   u8 fd_flags;
 389 };
 390
 391 /** \brief add/del application worker
 392     @param client_index - opaque cookie to identify the sender
 393                           client to vpp direction only
 394     @param context - sender context, to match reply w/ request
 395     @param app_index - application index
 396     @param wrk_index - worker index, if a delete
 397     @param is_add - set if an add
 398 */
 399 define app_worker_add_del
 400 {
 401   u32 client_index;
 402   u32 context;
 403   u32 app_index;
 404   u32 wrk_index;
 405   u8 is_add;
 406 };
 407
 408 /** \brief Reply for app worker add/del
 409     @param context - returned sender context, to match reply w/ request
 410     @param retval - return code
 411     @param wrk_index - worker index, if add
 412     @param app_event_queue_address - vpp event queue address of new worker
 413     @param n_fds - number of fds exchanged
 414     @param fd_flags - set of flags that indicate which fds are to be expected
 415                                   over the socket (set only if socket transport available)
 416     @param segment_name_length - length of segment name
 417     @param segment_name - name of segment client needs to attach to
 418     @param segment_handle - handle for segment
 419 */
 420 define app_worker_add_del_reply
 421 {
 422   u32 context;
 423   i32 retval;
 424   u32 wrk_index;
 425   u64 app_event_queue_address;
 426   u8 n_fds;
 427   u8 fd_flags;
 428   u8 segment_name_length;
 429   u8 segment_name[128];
 430   u64 segment_handle;
 431   u8 is_add;
 432 };
 433
 434 /** \brief enable/disable session layer
 435     @param client_index - opaque cookie to identify the sender
 436                           client to vpp direction only
 437     @param context - sender context, to match reply w/ request
 438     @param is_enable - disable session layer if 0, enable otherwise
 439 */
 440 autoreply define session_enable_disable {
 441   u32 client_index;
 442   u32 context;
 443   u8 is_enable;
 444 };
 445
 446 /** \brief add/del application namespace
 447     @param client_index - opaque cookie to identify the sender
 448                           client to vpp direction only
 449     @param context - sender context, to match reply w/ request
 450     @param secret - secret shared between app and vpp
 451     @param sw_if_index - local interface that "supports" namespace. Set to
 452                          ~0 if no preference
 453     @param ip4_fib_id - id of ip4 fib that "supports" the namespace. Ignored
 454                         if sw_if_index set.
 455     @param ip6_fib_id - id of ip6 fib that "supports" the namespace. Ignored
 456                         if sw_if_index set.
 457     @param namespace_id_len - length of namespace id lower
 458     @param namespace_id - namespace id
 459 */
 460 define app_namespace_add_del {
 461   u32 client_index;
 462   u32 context;
 463   u64 secret;
 464   u32 sw_if_index;
 465   u32 ip4_fib_id;
 466   u32 ip6_fib_id;
 467   u8 namespace_id_len;
 468   u8 namespace_id[64];
 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 /** \brief add/del session rule
 484     @param client_index - opaque cookie to identify the sender
 485                           client to vpp direction only
 486     @param context - sender context, to match reply w/ request
 487     @param transport_proto - transport protocol (0 - tcp 1 - udp)
 488     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 489     @param lcl_ip - local ip
 490     @param lcl_plen - local prefix length
 491     @param rmt_ip - remote ip
 492     @param rmt_ple - remote prefix length
 493     @param lcl_port - local port
 494     @param rmt_port - remote port
 495     @param action_index - the only action defined now is forward to
 496                           application with index action_index
 497     @param is_add - flag to indicate if add or del
 498     @param appns_index - application namespace where rule is to be applied to
 499     @param scope - flag that indicates scope of the rule: global or local.
 500                    If 0, default is global, 1 is global 2 is local, 3 is both
 501 */
 502 autoreply define session_rule_add_del {
 503   u32 client_index;
 504   u32 context;
 505   u8 transport_proto;
 506   u8 is_ip4;
 507   u8 lcl_ip[16];
 508   u8 lcl_plen;
 509   u8 rmt_ip[16];
 510   u8 rmt_plen;
 511   u16 lcl_port;
 512   u16 rmt_port;
 513   u32 action_index;
 514   u8 is_add;
 515   u32 appns_index;
 516   u8 scope;
 517   u8 tag[64];
 518 };
 519
 520 /** \brief Dump session rules
 521     @param client_index - opaque cookie to identify the sender
 522     @param context - sender context, to match reply w/ request
 523  */
 524 define session_rules_dump
 525 {
 526   u32 client_index;
 527   u32 context;
 528 };
 529
 530 /** \brief Session rules details
 531     @param context - sender context, to match reply w/ request
 532     @param transport_proto - transport protocol (0 - tcp 1 - udp)
 533     @param is_ip4 - flag to indicate if ip addresses are ip4 or 6
 534     @param lcl_ip - local ip
 535     @param lcl_plen - local prefix length
 536     @param rmt_ip - remote ip
 537     @param rmt_ple - remote prefix length
 538     @param lcl_port - local port
 539     @param rmt_port - remote port
 540     @param action_index - the only action defined now is forward to
 541                           application with index action_index
 542     @param appns_index - application namespace where rule is to be applied to
 543     @param scope - flag that indicates scope of the rule: global or local.
 544                    If 0, default is global, 1 is global 2 is local, 3 is both
 545   */
 546 define session_rules_details
 547 {
 548   u32 context;
 549   u8 transport_proto;
 550   u8 is_ip4;
 551   u8 lcl_ip[16];
 552   u8 lcl_plen;
 553   u8 rmt_ip[16];
 554   u8 rmt_plen;
 555   u16 lcl_port;
 556   u16 rmt_port;
 557   u32 action_index;
 558   u32 appns_index;
 559   u8 scope;
 560   u8 tag[64];
 561 };
 562
 563 /*
 564  * Local Variables:
 565  * eval: (c-set-style "gnu")
 566  * End:
 567  */