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