idnits 2.17.1 draft-ietf-anima-grasp-api-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 21, 2019) is 1916 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-30) exists of draft-ietf-anima-autonomic-control-plane-18 == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-18 == Outdated reference: A later version (-13) exists of draft-liu-anima-grasp-distribution-09 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Carpenter 3 Internet-Draft Univ. of Auckland 4 Intended status: Informational B. Liu, Ed. 5 Expires: July 25, 2019 Huawei Technologies 6 W. Wang 7 X. Gong 8 BUPT University 9 January 21, 2019 11 Generic Autonomic Signaling Protocol Application Program Interface 12 (GRASP API) 13 draft-ietf-anima-grasp-api-03 15 Abstract 17 This document is a conceptual outline of an application programming 18 interface (API) for the Generic Autonomic Signaling Protocol (GRASP). 19 Such an API is needed for Autonomic Service Agents (ASA) calling the 20 GRASP protocol module to exchange autonomic network messages with 21 other ASAs. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on July 25, 2019. 40 Copyright Notice 42 Copyright (c) 2019 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. GRASP API for ASA . . . . . . . . . . . . . . . . . . . . . . 3 59 2.1. Design Principles . . . . . . . . . . . . . . . . . . . . 4 60 2.2. Asynchronous Operations . . . . . . . . . . . . . . . . . 5 61 2.3. API definition . . . . . . . . . . . . . . . . . . . . . 6 62 2.3.1. Parameters and data structures . . . . . . . . . . . 6 63 2.3.2. Registration . . . . . . . . . . . . . . . . . . . . 10 64 2.3.3. Discovery . . . . . . . . . . . . . . . . . . . . . . 12 65 2.3.4. Negotiation . . . . . . . . . . . . . . . . . . . . . 13 66 2.3.5. Synchronization and Flooding . . . . . . . . . . . . 17 67 2.3.6. Invalid Message Function . . . . . . . . . . . . . . 21 68 3. Implementation Status [RFC Editor: please remove] . . . . . . 22 69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 22 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 71 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 72 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 73 7.1. Normative References . . . . . . . . . . . . . . . . . . 22 74 7.2. Informative References . . . . . . . . . . . . . . . . . 22 75 Appendix A. Error Codes . . . . . . . . . . . . . . . . . . . . 23 76 Appendix B. Change log [RFC Editor: Please remove] . . . . . . . 24 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 79 1. Introduction 81 As defined in [I-D.ietf-anima-reference-model], the Autonomic Service 82 Agent (ASA) is the atomic entity of an autonomic function, and it is 83 instantiated on autonomic nodes. When ASAs communicate with each 84 other, they should use the Generic Autonomic Signaling Protocol 85 (GRASP) [I-D.ietf-anima-grasp]. 87 As the following figure shows, a GRASP implementation could contain 88 two major sub-layers. The bottom is the GRASP base protocol module, 89 which is only responsible for sending and receiving GRASP messages 90 and maintaining shared data structures. The upper layer contains 91 some extended functions based upon GRASP basic protocol. For 92 example, [I-D.liu-anima-grasp-distribution] describes a possible 93 extended function. 95 It is desirable that ASAs can be designed as portable user-space 96 programs using a portable API. In many operating systems, the GRASP 97 module will therefore be split into two layers, one being a library 98 that provides the API and the other being core code containing common 99 components such as multicast handling and the discovery cache. The 100 details of this are system-dependent. In particular, the GRASP 101 library might need to communicate with the GRASP core via an inter- 102 process communication (IPC) mechanism. 104 +----+ +----+ 105 |ASAs| |ASAs| 106 +----+ +----+ 107 | | 108 | GRASP Function API | 109 | | 110 +------------------+ |GRASP API 111 | GRASP Extended | | 112 | Function Modules | | 113 +------------------+ | 114 +------------------------------------------+ 115 | GRASP Library | 116 | GRASP Module - - - - - - - - - - - - - -| 117 | GRASP Core | 118 +------------------------------------------+ 120 Both the GRASP library and the extended function modules should be 121 available to the ASAs. Thus, there need to be two sub-sets of API. 122 However, since the extended functions are expected to be added in an 123 incremental manner, it is inappropriate to define all the function 124 APIs in a single document. This document only describes the basic 125 GRASP API. 127 Note that a very simple autonomic node might contain only a single 128 ASA in addition to the autonomic infrastructure components described 129 in [I-D.ietf-anima-bootstrapping-keyinfra] and 130 [I-D.ietf-anima-autonomic-control-plane]. Such a node might directly 131 integrate GRASP in its autonomic code and therefore not require this 132 API to be installed. 134 This document gives a conceptual outline of the API. It is not a 135 formal specification for any particular programming language or 136 operating system, and it is expected that details will be clarified 137 in individual implementations. 139 2. GRASP API for ASA 140 2.1. Design Principles 142 The assumption of this document is that any Autonomic Service Agent 143 (ASA) needs to call a GRASP module that handles protocol details 144 (security, sending and listening for GRASP messages, waiting, caching 145 discovery results, negotiation looping, sending and receiving 146 sychronization data, etc.) but understands nothing about individual 147 objectives. The semantics of objectives are unknown to the GRASP 148 module and are handled only by the ASAs. Thus, this is a high level 149 abstract API for use by ASAs. Individual language bindings should be 150 defined in separate documents. 152 An assumption of this API is that ASAs may fall into various classes: 154 o ASAs that only use GRASP for discovery purposes. 156 o ASAs that use GRASP negotiation but only as an initiator (client). 158 o ASAs that use GRASP negotiation but only as a responder. 160 o ASAs that use GRASP negotiation as an initiator or responder. 162 o ASAs that use GRASP synchronization but only as an initiator 163 (recipient). 165 o ASAs that use GRASP synchronization but only as a responder and/or 166 flooder. 168 o ASAs that use GRASP synchronization as an initiator, responder 169 and/or flooder. 171 The API also assumes that one ASA may support multiple objectives. 172 Nothing prevents an ASA from supporting some objectives for 173 synchronization and others for negotiation. 175 The API design assumes that the operating system and programming 176 language provide a mechanism for simultaneous asynchronous 177 operations. This is discussed in detail in Section 2.2. 179 The functions provided by the API do not map one-to-one onto GRASP 180 messages. Rather, they are intended to offer convenient support for 181 message sequences (such as a discovery request followed by responses 182 from several peers, or a negotiation request followed by various 183 possible responses). 185 This is a preliminary version. A few gaps exist: 187 o Authorization of ASAs is out of scope. 189 o User-supplied explicit locators for an objective are not 190 supported. 192 o The Rapid mode of GRASP is not supported. 194 2.2. Asynchronous Operations 196 GRASP includes asynchronous operations and wait states. Most ASAs 197 will need to support several simultaneous operations; for example an 198 ASA might need to negotiate one objective with a peer while 199 discovering and synchronizing a different objective with a different 200 peer. Alternatively, an ASA which acts as a resource manager might 201 need to run simultaneous negotiations for a given objective with 202 multiple different peers. Thus, both the GRASP core and most ASAs 203 need to support asynchronous operations. Depending on both the 204 operating system and the programming language in use, there are two 205 main techniques for such parallel operations: multi-threading, or a 206 polling or 'event loop' structure. 208 In multi-threading, the operating system and language will provide 209 the necessary support for asynchronous operations, including creation 210 of new threads, context switching between threads, queues, locks, and 211 implicit wait states. In this case, all API calls can be treated 212 naturally as synchronous, even if they include wait states, blocking 213 and queueing. Simultaneous operations will each run in their own 214 threads. For example, the discover() call will not return until 215 discovery results have arrived or a timeout has occurred. If the ASA 216 has other work to do, the discover() call must be in a thread of its 217 own. 219 In an event loop implementation, synchronous blocking calls are not 220 acceptable. Therefore all calls must be non-blocking, and the main 221 loop will support multiple GRASP sessions in parallel by repeatedly 222 checking each one for a change of state. To facilitate this, the API 223 implementation will provide non-blocking versions of all the 224 functions that otherwise involve blocking and queueing. In these 225 calls, a 'noReply' code will be returned by each call instead of 226 blocking, until such time as the event for which it is waiting (or a 227 failure) has occurred. Thus, for example, discover() would return 228 "noReply" instead of waiting until discovery has succeeded or timed 229 out. The discover() call would be repeated in every cycle of the 230 main loop until it completes. A 'session_nonce' parameter (described 231 below) is used to distinguish simultaneous GRASP sessions from each 232 other, so that any number of sessions may proceed in parallel. 234 The following calls involve waiting for a remote operation, so they 235 could use this mechanism: 237 discover() 239 request_negotiate() 241 negotiate_step() 243 listen_negotiate() 245 synchronize() 247 In all these calls, the 'session_nonce' is a read/write parameter. 248 On the first call, it is set to a null value, and the API returns the 249 'noReply' code and a non-null session_nonce value. This value must 250 be used in all subsequent calls for the same session. By this 251 mechanism, multiple overlapping sessions can be distinguished, both 252 in the ASA and in the GRASP core. 254 An additional mechanism that might increase efficiency for event loop 255 implementations is to add a general call, say notify(), which would 256 check the status of all outstanding operations for the calling ASA 257 and return the session_nonce values for all sessions that have 258 changed state. This would eliminate the need for repeated calls to 259 the individual functions returning a "noReply". This call is not 260 described below as the details are likely to be implementation- 261 specific. 263 An implication of the above for all GRASP implementations is that the 264 GRASP core must keep state for each GRASP operation in progress, most 265 likely keyed by the GRASP Session ID and the GRASP source address of 266 the session initiator. Even in a threaded implementation, the GRASP 267 core will need such state internally. The session_nonce parameter 268 exposes this aspect of the implementation. 270 2.3. API definition 272 2.3.1. Parameters and data structures 274 This section describes parameters and data structures uaed in 275 multiple API calls. 277 2.3.1.1. Errorcode 279 All functions in the API have an unsigned 'errorcode' integer as 280 their return value (the first returned value in languages that allow 281 multiple returned parameters). An errorcode of zero indicates 282 success. Any other value indicates failure of some kind. The first 283 three errorcodes have special importance: 285 1. Declined: used to indicate that the other end has sent a GRASP 286 Negotiation End message (M_END) with a Decline option 287 (O_DECLINE). 289 2. No reply: used in non-blocking calls to indicate that the other 290 end has sent no reply so far (see Section 2.2). 292 3. Unspecified error: used when no more specific error code applies. 294 Appendix A gives a full list of currently suggested error codes, 295 based on implementation experience. While there is no absolute 296 requirement for all implementations to use the same error codes, this 297 is highly recommended for portability of applications. 299 2.3.1.2. Timeout 301 Wherever a 'timeout' parameter appears, it is an integer expressed in 302 milliseconds. If it is zero, the GRASP default timeout 303 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]) will apply. If no 304 response is received before the timeout expires, the call will fail 305 unless otherwise noted. 307 2.3.1.3. Objective 309 An 'objective' parameter is a data structure with the following 310 components: 312 o name (UTF-8 string) - the objective's name 314 o neg (Boolean flag) - True if objective supports negotiation 315 (default False) 317 o synch (Boolean flag) - True if objective supports synchronization 318 (default False) 320 o dry (Boolean flag) - True if objective supports dry-run 321 negotiation (default False) 323 * Note 1: All objectives are assumed to support discovery, so 324 there is no Boolean for that. 326 * Note 2: Only one of 'synch' or 'neg' may be True. 328 * Note 3: 'dry' must not be True unless 'neg' is also True. 330 * Note 4: In a language such as C the preferred implementation 331 may be to represent the Boolean flags as bits in a single byte. 333 o loop_count (integer) - Limit on negotiation steps etc. (default 334 GRASP_DEF_LOOPCT, see [I-D.ietf-anima-grasp]) 336 o value - a specific data structure expressing the value of the 337 objective. The format is language dependent, with the constraint 338 that it can be validly represented in CBOR (default integer = 0). 340 An essential requirement for all language mappings and all 341 implementations is that, regardless of what other options exist 342 for a language-specific represenation of the value, there is 343 always an option to use a CBOR byte string as the value. The API 344 will then wrap this byte string in CBOR Tag 24 for transmission 345 via GRASP, and unwrap it after reception. 347 An example data structure definition for an objective in the C 348 language is: 350 typedef struct { 351 char *name; 352 uint8_t flags; // flag bits as defined by GRASP 353 int loop_count; 354 int value_size; // size of value 355 uint8_t cbor_value[]; // CBOR bytestring of value 356 } objective; 358 An example data structure definition for an objective in the 359 Python language is: 361 class objective: 362 """A GRASP objective""" 363 def __init__(self, name): 364 self.name = name #Unique name, string 365 self.neg = False #True if objective supports negotiation 366 self.dry = False #True if objective supports dry-run neg. 367 self.synch = False #True if objective supports synch 368 self.loop_count = GRASP_DEF_LOOPCT #Default starting value 369 self.value = 0 #Place holder; any valid Python object 371 2.3.1.4. ASA_locator 373 An 'ASA_locator' parameter is a data structure with the following 374 contents: 376 o locator - The actual locator, either an IP address or an ASCII 377 string. 379 o ifi (integer) - The interface identifier index via which this was 380 discovered - probably no use to a normal ASA 382 o expire (system dependent type) - The time on the local system 383 clock when this locator will expire from the cache 385 o is_ipaddress (Boolean) - True if the locator is an IP address 387 o is_fqdn (Boolean) - True if the locator is an FQDN 389 o is_uri (Boolean) - True if the locator is a URI 391 o diverted (Boolean) - True if the locator was discovered via a 392 Divert option 394 o protocol (integer) - Applicable transport protocol (IPPROTO_TCP or 395 IPPROTO_UDP) 397 o port (integer) - Applicable port number 399 2.3.1.5. Tagged_objective 401 A 'tagged_objective' parameter is a data structure with the following 402 contents: 404 o objective - An objective 406 o locator - The ASA_locator associated with the objective, or a null 407 value. 409 2.3.1.6. Asa_nonce 411 In most calls, an 'asa_nonce' parameter is required. It is generated 412 when an ASA registers with GRASP, and any call in which an invalid 413 nonce is presented will fail. It is an up to 32-bit opaque value 414 (for example represented as a uint32_t, depending on the language). 415 It should be unpredictable; a possible implementation is to use the 416 same mechanism that GRASP uses to generate Session IDs 417 [I-D.ietf-anima-grasp]. Another possible implementation is to hash 418 the name of the ASA with a locally defined secret key. 420 2.3.1.7. Session_nonce 422 In some calls, a 'session_nonce' parameter is required. This is an 423 opaque data structure as far as the ASA is concerned, used to 424 identify calls to the API as belonging to a specific GRASP session 425 (see Section 2.2). In fully threaded implementations this parameter 426 might not be needed, but it is included to act as a session handle if 427 necessary. It will also allow GRASP to detect and ignore malicious 428 calls or calls from timed-out sessions. A possible implementation is 429 to form the nonce from the underlying GRASP Session ID and the source 430 address of the session. 432 2.3.2. Registration 434 These functions are used to register an ASA and the objectives that 435 it supports with the GRASP module. If an authorization model is 436 added to GRASP, it would also be added at this point in the API. 438 o register_asa() 440 Input parameter: 442 name of the ASA (UTF-8 string) 444 Return parameters: 446 errorcode (integer) 448 asa_nonce (integer) (if successful) 450 This initialises state in the GRASP module for the calling 451 entity (the ASA). In the case of success, an 'asa_nonce' is 452 returned which the ASA must present in all subsequent calls. 453 In the case of failure, the ASA has not been authorized and 454 cannot operate. 456 o deregister_asa() 458 Input parameters: 460 asa_nonce (integer) 462 name of the ASA (UTF-8 string) 464 Return parameter: 466 errorcode (integer) 468 This removes all state in the GRASP module for the calling 469 entity (the ASA), and deregisters any objectives it has 470 registered. Note that these actions must also happen 471 automatically if an ASA crashes. 473 Note - the ASA name is strictly speaking redundant in this 474 call, but is present for clarity. 476 o register_objective() 477 Input parameters: 479 asa_nonce (integer) 481 objective (structure) 483 ttl (integer - default GRASP_DEF_TIMEOUT) 485 discoverable (Boolean - default False) 487 overlap (Boolean - default False) 489 local (Boolean - default False) 491 Return parameter: 493 errorcode (integer) 495 This registers an objective that this ASA supports and may 496 modify. The 'objective' becomes a candidate for discovery. 497 However, discovery responses should not be enabled until the 498 ASA calls listen_negotiate() or listen_synchronize(), showing 499 that it is able to act as a responder. The ASA may negotiate 500 the objective or send synchronization or flood data. 501 Registration is not needed if the ASA only wants to receive 502 synchronization or flood data for the objective concerned. 504 The 'ttl' parameter is the valid lifetime (time to live) in 505 milliseconds of any discovery response for this objective. The 506 default value should be the GRASP default timeout 507 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]). 509 If the parameter 'discoverable' is True, the objective is 510 immediately discoverable. This is intended for objectives that 511 are only defined for GRASP discovery, and which do not support 512 negotiation or synchronization. 514 If the parameter 'overlap' is True, more than one ASA may 515 register this objective in the same GRASP instance. 517 If the parameter 'local' is True, discovery must return a link- 518 local address. This feature is for objectives that must be 519 restricted to the local link. 521 This call may be repeated for multiple objectives. 523 o deregister_objective() 524 Input parameters: 526 asa_nonce (integer) 528 objective (structure) 530 Return parameter: 532 errorcode (integer) 534 The 'objective' must have been registered by the calling ASA; 535 if not, this call fails. Otherwise, it removes all state in 536 the GRASP module for the given objective. 538 2.3.3. Discovery 540 o discover() 542 Input parameters: 544 asa_nonce (integer) 546 objective (structure) 548 timeout (integer) 550 flush (Boolean - default False) 552 Return parameters: 554 errorcode (integer) 556 locator_list (structure) 558 This returns a list of discovered 'ASA_locator's for the given 559 objective. If the parameter 'flush' is True, any locally 560 cached locators for the objective are deleted first. 561 Otherwise, they are returned immediately. If not, GRASP 562 discovery is performed, and all results obtained before the 563 timeout expires are returned. If no results are obtained, an 564 empty list is returned after the timeout. That is not an error 565 condition. 567 Threaded implementation: This should be called in a separate 568 thread if asynchronous operation is required. 570 Event loop implementation: An additional read/write 571 'session_nonce' parameter is used. 573 2.3.4. Negotiation 575 o request_negotiate() 577 Input parameters: 579 asa_nonce (integer) 581 objective (structure) 583 peer (ASA_locator) 585 timeout (integer) 587 Return parameters: 589 errorcode (integer) 591 session_nonce (structure) (if successful) 593 proffered_objective (structure) (if successful) 595 reason (string) (if negotiation declined) 597 This function opens a negotiation session. The 'objective' 598 parameter must include the requested value, and its loop count 599 should be set to a suitable value by the ASA. If not, the 600 GRASP default will apply. 602 Note that a given negotiation session may or may not be a dry- 603 run negotiation; the two modes must not be mixed in a single 604 session. 606 The 'peer' parameter is the target node; it must be an 607 'ASA_locator' as returned by discover(). If the peer is null, 608 GRASP discovery is performed first. 610 If the 'errorcode' return parameter is 0, the negotiation has 611 successfully started. There are then two cases: 613 1. The 'session_nonce' parameter is null. In this case the 614 negotiation has succeeded (the peer has accepted the 615 request). The returned 'proffered_objective' contains the 616 value accepted by the peer. 618 2. The 'session_nonce' parameter is not null. In this case 619 negotiation must continue. The returned 620 'proffered_objective' contains the first value proffered by 621 the negotiation peer. Note that this instance of the 622 objective must be used in the subsequent negotiation call 623 because it also contains the current loop count. The 624 'session_nonce' must be presented in all subsequent 625 negotiation steps. 627 This function must be followed by calls to 'negotiate_step' 628 and/or 'negotiate_wait' and/or 'end_negotiate' until the 629 negotiation ends. 'request_negotiate' may then be called 630 again to start a new negotation. 632 If the 'errorcode' parameter has the value 1 ('declined'), the 633 negotiation has been declined by the peer (M_END and O_DECLINE 634 features of GRASP). The 'reason' string is then available for 635 information and diagnostic use, but it may be a null string. 636 For this and any other error code, an exponential backoff is 637 recommended before any retry. 639 Threaded implementation: This should be called in a separate 640 thread if asynchronous operation is required. 642 Event loop implementation: The 'session_nonce' parameter is 643 used in read/write mode. 645 Special note for the ACP infrastructure ASA: It is likely that 646 this ASA will need to discover and negotiate with its peers in 647 each of its on-link neighbors. It will therefore need to know 648 not only the link-local IP address but also the physical 649 interface and transport port for connecting to each neighbor. 650 One implementation approach to this is to include these details 651 in the 'session_nonce' data structure, which is opaque to 652 normal ASAs. 654 o listen_negotiate() 656 Input parameters: 658 asa_nonce (integer) 660 objective (structure) 662 Return parameters: 664 errorcode (integer) 666 session_nonce (structure) (if successful) 668 requested_objective (structure) (if successful) 670 This function instructs GRASP to listen for negotiation 671 requests for the given 'objective'. It also enables discovery 672 responses for the objective. 674 Threaded implementation: It will block waiting for an incoming 675 request, so should be called in a separate thread if 676 asynchronous operation is required. 678 Event loop implementation: A read/write 'session_nonce' 679 parameter is used. 681 Unless there is an unexpected failure, this call only returns 682 after an incoming negotiation request. When it does so, 683 'requested_objective' contains the first value requested by the 684 negotiation peer. Note that this instance of the objective 685 must be used in the subsequent negotiation call because it also 686 contains the current loop count. The 'session_nonce' must be 687 presented in all subsequent negotiation steps. 689 This function must be followed by calls to 'negotiate_step' 690 and/or 'negotiate_wait' and/or 'end_negotiate' until the 691 negotiation ends. 'listen_negotiate' may then be called again 692 to await a new negotation. 694 If an ASA is capable of handling multiple negotiations 695 simultaneously, it may call 'listen_negotiate' simultaneously 696 from multiple threads. The API and GRASP implementation must 697 support re-entrant use of the listening state and the 698 negotiation calls. Simultaneous sessions will be distinguished 699 by the threads themselves, the GRASP Session IDs, and the 700 underlying unicast transport sockets. 702 o stop_listen_negotiate() 704 Input parameters: 706 asa_nonce (integer) 708 objective (structure) 710 Return parameter: 712 errorcode (integer) 714 Instructs GRASP to stop listening for negotiation requests for 715 the given objective, i.e., cancels 'listen_negotiate'. 717 Threaded implementation: Must be called from a different thread 718 than 'listen_negotiate'. 720 Event loop implementation: no special considerations. 722 o negotiate_step() 724 Input parameters: 726 asa_nonce (integer) 728 session_nonce (structure) 730 objective (structure) 732 timeout (integer) 734 Return parameters: 736 Exactly as for 'request_negotiate' 738 Executes the next negotation step with the peer. The 739 'objective' parameter contains the next value being proffered 740 by the ASA in this step. 742 Threaded implementation: Called in the same thread as the 743 preceding 'request_negotiate' or 'listen_negotiate', with the 744 same value of 'session_nonce'. 746 Event loop implementation: Must use the same value of 747 'session_nonce' returned by the preceding 'request_negotiate' 748 or 'listen_negotiate'. 750 o negotiate_wait() 752 Input parameters: 754 asa_nonce (integer) 756 session_nonce (structure) 758 timeout (integer) 760 Return parameters: 762 errorcode (integer) 764 Delay negotiation session by 'timeout' milliseconds. 766 Threaded implementation: Called in the same thread as the 767 preceding 'request_negotiate' or 'listen_negotiate', with the 768 same value of 'session_nonce'. 770 Event loop implementation: Must use the same value of 771 'session_nonce' returned by the preceding 'request_negotiate' 772 or 'listen_negotiate'. 774 o end_negotiate() 776 Input parameters: 778 asa_nonce (integer) 780 session_nonce (structure) 782 reply (Boolean) 784 reason (UTF-8 string) 786 Return parameters: 788 errorcode (integer) 790 End the negotiation session. 792 'reply' = True for accept (successful negotiation), False for 793 decline (failed negotiation). 795 'reason' = optional string describing reason for decline. 797 Threaded implementation: Called in the same thread as the 798 preceding 'request_negotiate' or 'listen_negotiate', with the 799 same value of 'session_nonce'. 801 Event loop implementation: Must use the same value of 802 'session_nonce' returned by the preceding 'request_negotiate' 803 or 'listen_negotiate'. 805 2.3.5. Synchronization and Flooding 807 o synchronize() 809 Input parameters: 811 asa_nonce (integer) 813 objective (structure) 814 peer (ASA_locator) 816 timeout (integer) 818 Return parameters: 820 errorcode (integer) 822 objective (structure) (if successful) 824 This call requests the synchronized value of the given 825 'objective'. 827 Since this is essentially a read operation, any ASA can do it. 828 Therefore the API checks that the ASA is registered but the 829 objective doesn't need to be registered by the calling ASA. 831 If the objective was already flooded, the flooded value is 832 returned immediately in the 'result' parameter. In this case, 833 the 'source' and 'timeout' are ignored. 835 Otherwise, synchronization with a discovered ASA is performed. 836 The 'peer' parameter is an 'ASA_locator' as returned by 837 discover(). If 'peer' is null, GRASP discovery is performed 838 first. 840 This call should be repeated whenever the latest value is 841 needed. 843 Threaded implementation: Call in a separate thread if 844 asynchronous operation is required. 846 Event loop implementation: An additional read/write 847 'session_nonce' parameter is used. 849 Since this is essentially a read operation, any ASA can use it. 850 Therefore GRASP checks that the calling ASA is registered but 851 the objective doesn't need to be registered by the calling ASA. 853 In the case of failure, an exponential backoff is recommended 854 before retrying. 856 o listen_synchronize() 858 Input parameters: 860 asa_nonce (integer) 861 objective (structure) 863 Return parameters: 865 errorcode (integer) 867 This instructs GRASP to listen for synchronization requests for 868 the given objective, and to respond with the value given in the 869 'objective' parameter. It also enables discovery responses for 870 the objective. 872 This call is non-blocking and may be repeated whenever the 873 value changes. 875 o stop_listen_synchronize() 877 Input parameters: 879 asa_nonce (integer) 881 objective (structure) 883 Return parameters: 885 errorcode (integer) 887 This call instructs GRASP to stop listening for synchronization 888 requests for the given 'objective', i.e. it cancels a previous 889 listen_synchronize. 891 o flood() 893 Input parameters: 895 asa_nonce (integer) 897 ttl (integer) 899 tagged_objective_list (structure) 901 Return parameters: 903 errorcode (integer) 905 This call instructs GRASP to flood the given synchronization 906 objective(s) and their value(s) and associated locator(s) to 907 all GRASP nodes. 909 The 'ttl' parameter is the valid lifetime (time to live) of the 910 flooded data in milliseconds (0 = infinity) 912 The 'tagged_objective_list' parameter is a list of one or more 913 'tagged_objective' couplets. The 'locator' parameter that tags 914 each objective is normally null but may be a valid 915 'ASA_locator'. Infrastructure ASAs needing to flood an 916 {address, protocol, port} 3-tuple with an objective create an 917 ASA_locator object to do so. If the IP address in that locator 918 is the unspecified address ('::') it is replaced by the link- 919 local address of the sending node in each copy of the flood 920 multicast, which will be forced to have a loop count of 1. 921 This feature is for objectives that must be restricted to the 922 local link. 924 The function checks that the ASA registered each objective. 926 This call may be repeated whenever any value changes. 928 o get_flood() 930 Input parameters: 932 asa_nonce (integer) 934 objective (structure) 936 Return parameters: 938 errorcode (integer) 940 tagged_objective_list (structure) (if successful) 942 This call instructs GRASP to return the given synchronization 943 objective if it has been flooded and its lifetime has not 944 expired. 946 Since this is essentially a read operation, any ASA can do it. 947 Therefore the API checks that the ASA is registered but the 948 objective doesn't need to be registered by the calling ASA. 950 The 'tagged_objective_list' parameter is a list of 951 'tagged_objective' couplets, each one being a copy of the 952 flooded objective and a coresponding locator. Thus if the same 953 objective has been flooded by multiple ASAs, the recipient can 954 distinguish the copies. 956 Note that this call is for advanced ASAs. In a simple case, an 957 ASA can simply call synchronize() in order to get a valid 958 flooded objective. 960 o expire_flood() 962 Input parameters: 964 asa_nonce (integer) 966 tagged_objective (structure) 968 Return parameters: 970 errorcode (integer) 972 This is a call that can only be used after a preceding call to 973 get_flood() by an ASA that is capable of deciding that the 974 flooded value is stale or invalid. Use with care. 976 The 'tagged_objective' parameter is the one to be expired. 978 2.3.6. Invalid Message Function 980 o send_invalid() 982 Input parameters: 984 asa_nonce (integer) 986 session_nonce (structure) 988 info (bytes) 990 Return parameters: 992 errorcode (integer) 994 Sends a GRASP Invalid Message (M_INVALID) message, as described 995 in [I-D.ietf-anima-grasp]. Should not be used if 996 end_negotiate() would be sufficient. Note that this message 997 may be used in response to any unicast GRASP message that the 998 receiver cannot interpret correctly. In most cases this 999 message will be generated internally by a GRASP implementation. 1001 'info' = optional diagnostic data. May be raw bytes from the 1002 invalid message. 1004 3. Implementation Status [RFC Editor: please remove] 1006 A prototype open source Python implementation of GRASP, including an 1007 API similar to this document, has been used to verify the concepts 1008 for the threaded model. It may be found at 1009 with associated documentation 1010 and demonstration ASAs. 1012 4. Security Considerations 1014 Security issues for the GRASP protocol are discussed in 1015 [I-D.ietf-anima-grasp]. Authorization of ASAs is a subject for 1016 future study. 1018 The 'asa_nonce' parameter is used in the API as a first line of 1019 defence against a malware process attempting to imitate a 1020 legitimately registered ASA. The 'session_nonce' parameter is used 1021 in the API as a first line of defence against a malware process 1022 attempting to hijack a GRASP session. 1024 5. IANA Considerations 1026 This document currently makes no request of the IANA. 1028 Open question: Do we need an IANA registry for the error codes? 1030 6. Acknowledgements 1032 Excellent suggestions were made by Ignas Bagdonas, Michael Richardson 1033 and other participants in the ANIMA WG. 1035 7. References 1037 7.1. Normative References 1039 [I-D.ietf-anima-grasp] 1040 Bormann, C., Carpenter, B., and B. Liu, "A Generic 1041 Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- 1042 grasp-15 (work in progress), July 2017. 1044 7.2. Informative References 1046 [I-D.ietf-anima-autonomic-control-plane] 1047 Eckert, T., Behringer, M., and S. Bjarnason, "An Autonomic 1048 Control Plane (ACP)", draft-ietf-anima-autonomic-control- 1049 plane-18 (work in progress), August 2018. 1051 [I-D.ietf-anima-bootstrapping-keyinfra] 1052 Pritikin, M., Richardson, M., Behringer, M., Bjarnason, 1053 S., and K. Watsen, "Bootstrapping Remote Secure Key 1054 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 1055 keyinfra-18 (work in progress), January 2019. 1057 [I-D.ietf-anima-reference-model] 1058 Behringer, M., Carpenter, B., Eckert, T., Ciavaglia, L., 1059 and J. Nobre, "A Reference Model for Autonomic 1060 Networking", draft-ietf-anima-reference-model-10 (work in 1061 progress), November 2018. 1063 [I-D.liu-anima-grasp-distribution] 1064 Liu, B., Jiang, S., Xiao, X., Hecker, A., and Z. 1065 Despotovic, "Information Distribution in Autonomic 1066 Networking", draft-liu-anima-grasp-distribution-09 (work 1067 in progress), October 2018. 1069 Appendix A. Error Codes 1071 This Appendix lists the error codes defined so far, with suggested 1072 symbolic names and corresponding descriptive strings in English. It 1073 is expected that complete API implementations will provide for 1074 localisation of these descriptive strings, and that additional error 1075 codes will be needed according to implementation details. 1077 An open issue for these values is whether there is an advantage in 1078 aligning them with existing error codes in the socket API, where the 1079 meanings coincide, and using different values otherwise. This is to 1080 be balanced against the advantage of having a compact and completely 1081 portable set of error codes for GRASP alone. 1083 ok 0 "OK" 1084 declined 1 "Declined" 1085 noReply 2 "No reply" 1086 unspec 3 "Unspecified error" 1087 ASAfull 4 "ASA registry full" 1088 dupASA 5 "Duplicate ASA name" 1089 noASA 6 "ASA not registered" 1090 notYourASA 7 "ASA registered but not by you" 1091 notBoth 8 "Objective cannot support both negotiation 1092 and synchronization" 1093 notDry 9 "Dry-run allowed only with negotiation" 1094 notOverlap 10 "Overlap not supported by this implementation" 1095 objFull 11 "Objective registry full" 1096 objReg 12 "Objective already registered" 1097 notYourObj 13 "Objective not registered by this ASA" 1098 notObj 14 "Objective not found" 1099 notNeg 15 "Objective not negotiable" 1100 noSecurity 16 "No security" 1101 noDiscReply 17 "No reply to discovery" 1102 sockErrNegRq 18 "Socket error sending negotiation request" 1103 noSession 19 "No session" 1104 noSocket 20 "No socket" 1105 loopExhausted 21 "Loop count exhausted" 1106 sockErrNegStep 22 "Socket error sending negotiation step" 1107 noPeer 23 "No negotiation peer" 1108 CBORfail 24 "CBOR decode failure" 1109 invalidNeg 25 "Invalid Negotiate message" 1110 invalidEnd 26 "Invalid end message" 1111 noNegReply 27 "No reply to negotiation step" 1112 noValidStep 28 "No valid reply to negotiation step" 1113 sockErrWait 29 "Socket error sending wait message" 1114 sockErrEnd 30 "Socket error sending end message" 1115 IDclash 31 "Incoming request Session ID clash" 1116 notSynch 32 "Not a synchronization objective" 1117 notFloodDisc 33 "Not flooded and no reply to discovery" 1118 sockErrSynRq 34 "Socket error sending synch request" 1119 noListener 35 "No synch listener" 1120 noSynchReply 36 "No reply to synchronization request" 1121 noValidSynch 37 "No valid reply to synchronization request" 1122 invalidLoc 38 "Invalid locator" 1124 Appendix B. Change log [RFC Editor: Please remove] 1126 draft-ietf-anima-grasp-api-03, 2019-01-21: 1128 Replaced empty "logic flows" section by "implementation status". 1130 Minor clarifications. 1132 Editorial improvements. 1134 draft-ietf-anima-grasp-api-02, 2018-06-30: 1136 Additional suggestion for event-loop API. 1138 Discussion of error code values. 1140 draft-ietf-anima-grasp-api-01, 2018-03-03: 1142 Editorial updates 1144 draft-ietf-anima-grasp-api-00, 2017-12-23: 1146 WG adoption 1148 Editorial improvements. 1150 draft-liu-anima-grasp-api-06, 2017-11-24: 1152 Improved description of event-loop model. 1154 Changed intended status to Informational. 1156 Editorial improvements. 1158 draft-liu-anima-grasp-api-05, 2017-10-02: 1160 Added send_invalid() 1162 draft-liu-anima-grasp-api-04, 2017-06-30: 1164 Noted that simple nodes might not include the API. 1166 Minor clarifications. 1168 draft-liu-anima-grasp-api-03, 2017-02-13: 1170 Changed error return to integers. 1172 Required all implementations to accept objective values in CBOR. 1174 Added non-blocking alternatives. 1176 draft-liu-anima-grasp-api-02, 2016-12-17: 1178 Updated for draft-ietf-anima-grasp-09 1179 draft-liu-anima-grasp-api-02, 2016-09-30: 1181 Added items for draft-ietf-anima-grasp-07 1183 Editorial corrections 1185 draft-liu-anima-grasp-api-01, 2016-06-24: 1187 Updated for draft-ietf-anima-grasp-05 1189 Editorial corrections 1191 draft-liu-anima-grasp-api-00, 2016-04-04: 1193 Initial version 1195 Authors' Addresses 1197 Brian Carpenter 1198 Department of Computer Science 1199 University of Auckland 1200 PB 92019 1201 Auckland 1142 1202 New Zealand 1204 Email: brian.e.carpenter@gmail.com 1206 Bing Liu (editor) 1207 Huawei Technologies 1208 Q14, Huawei Campus 1209 No.156 Beiqing Road 1210 Hai-Dian District, Beijing 100095 1211 P.R. China 1213 Email: leo.liubing@huawei.com 1215 Wendong Wang 1216 BUPT University 1217 Beijing University of Posts & Telecom. 1218 No.10 Xitucheng Road 1219 Hai-Dian District, Beijing 100876 1220 P.R. China 1222 Email: wdwang@bupt.edu.cn 1223 Xiangyang Gong 1224 BUPT University 1225 Beijing University of Posts & Telecom. 1226 No.10 Xitucheng Road 1227 Hai-Dian District, Beijing 100876 1228 P.R. China 1230 Email: xygong@bupt.edu.cn