idnits 2.17.1 draft-ietf-anima-grasp-api-02.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 (June 30, 2018) is 2127 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-16 == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-16 == Outdated reference: A later version (-10) exists of draft-ietf-anima-reference-model-06 == Outdated reference: A later version (-13) exists of draft-liu-anima-grasp-distribution-05 Summary: 0 errors (**), 0 flaws (~~), 5 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: January 1, 2019 Huawei Technologies 6 W. Wang 7 X. Gong 8 BUPT University 9 June 30, 2018 11 Generic Autonomic Signaling Protocol Application Program Interface 12 (GRASP API) 13 draft-ietf-anima-grasp-api-02 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 January 1, 2019. 40 Copyright Notice 42 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . 9 64 2.3.3. Discovery . . . . . . . . . . . . . . . . . . . . . . 12 65 2.3.4. Negotiation . . . . . . . . . . . . . . . . . . . . . 12 66 2.3.5. Synchronization and Flooding . . . . . . . . . . . . 17 67 2.3.6. Invalid Message Function . . . . . . . . . . . . . . 21 68 3. Example Logic Flows . . . . . . . . . . . . . . . . . . . . . 21 69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 21 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 the function APIs 124 in a single document. This document only describes the base GRASP 125 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 This is a preliminary version. A few gaps exist: 181 o Authorization of ASAs is out of scope. 183 o User-supplied explicit locators for an objective are not 184 supported. 186 o The Rapid mode of GRASP is not supported. 188 2.2. Asynchronous Operations 190 GRASP includes asynchronous operations and wait states. Most ASAs 191 will need to support several simultaneous operations; for example an 192 ASA might need to negotiate one objective with a peer while 193 discovering and synchronizing a different objective with a different 194 peer. Alternatively, an ASA which acts as a resource manager might 195 need to run simultaneous negotiations for a given objective with 196 multiple different peers. Thus, both the GRASP core and most ASAs 197 need to support asynchronous operations. Depending on both the 198 operating system and the programming language in use, there are two 199 main techniques for such parallel operations: multi-threading, or a 200 polling or 'event loop' structure. 202 In multi-threading, the operating system and language will provide 203 the necessary support for asynchronous operations, including creation 204 of new threads, context switching between threads, queues, locks, and 205 implicit wait states. In this case, all API calls can be treated 206 naturally as synchronous, even if they include wait states, blocking 207 and queueing. Simultaneous operations will each run in their own 208 threads. 210 In an event loop implementation, synchronous blocking calls are not 211 acceptable. Therefore all calls must be non-blocking, and the main 212 loop will support multiple GRASP sessions in parallel by repeatedly 213 checking each one for a change of state. To facilitate this, the API 214 implementation will provide non-blocking versions of all the 215 functions that otherwise involve blocking and queueing. In these 216 calls, a 'noReply' code will be returned by each call instead of 217 blocking, until such time as the event for which it is waiting (or a 218 failure) has occurred. Thus, for example, discover() would return 219 "noReply" instead of waiting until discovery has succeeded or timed 220 out. The discover() call would be repeated in every cycle of the 221 main loop until it completes. A 'session_nonce' parameter (described 222 below) is used to distinguish simultaneous GRASP sessions from each 223 other, so that any number of sessions may proceed in parallel. 225 The following calls involve waiting for a remote operation, so they 226 could use this mechanism: 228 discover() 230 request_negotiate() 232 negotiate_step() 234 listen_negotiate() 235 synchronize() 237 In all these calls, the 'session_nonce' is a read/write parameter. 238 On the first call, it is set to a null value, and the API returns the 239 'noReply' code and a non-null session_nonce value. This value must 240 be used in all subsequent calls for the same session. By this 241 mechanism, multiple overlapping sessions can be distinguished, both 242 in the ASA and in the GRASP core. 244 An additional mechanism that might increase efficiency for event loop 245 implementations is to add a general call, say notify(), which would 246 check the status of all outstanding operations for the calling ASA 247 and return the session_nonce values for all sessions that have 248 changed state. This would eliminate the need for repeated calls to 249 the individual functions returning a "noReply". This call is not 250 described below as the details are likely to be implementation- 251 specific. 253 2.3. API definition 255 2.3.1. Parameters and data structures 257 This section describes parameters and data structures uaed in 258 multiple API calls. 260 2.3.1.1. Errorcode 262 All functions in the API have an unsigned 'errorcode' integer as 263 their return value (the first returned value in languages that allow 264 multiple returned parameters). An errorcode of zero indicates 265 success. Any other value indicates failure of some kind. The first 266 three errorcodes have special importance: 268 1. Declined: used to indicate that the other end has sent a GRASP 269 Negotiation End message (M_END) with a Decline option 270 (O_DECLINE). 272 2. No reply: used in non-blocking calls to indicate that the other 273 end has sent no reply so far (see Section 2.2). 275 3. Unspecified error: used when no more specific error code applies. 277 Appendix A gives a full list of currently defined error codes, based 278 on implementation experience. 280 2.3.1.2. Timeout 282 Wherever a 'timeout' parameter appears, it is an integer expressed in 283 milliseconds. If it is zero, the GRASP default timeout 284 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]) will apply. If no 285 response is received before the timeout expires, the call will fail 286 unless otherwise noted. 288 2.3.1.3. Objective 290 An 'objective' parameter is a data structure with the following 291 components: 293 o name (UTF-8 string) - the objective's name 295 o neg (Boolean flag) - True if objective supports negotiation 296 (default False) 298 o synch (Boolean flag) - True if objective supports synchronization 299 (default False) 301 o dry (Boolean flag) - True if objective supports dry-run 302 negotiation (default False) 304 * Note 1: All objectives are assumed to support discovery, so 305 there is no Boolean for that. 307 * Note 2: Only one of 'synch' or 'neg' may be True. 309 * Note 3: 'dry' must not be True unless 'neg' is also True. 311 * Note 4: In a language such as C the preferred implementation 312 may be to represent the Boolean flags as bits in a single byte. 314 o loop_count (integer) - Limit on negotiation steps etc. (default 315 GRASP_DEF_LOOPCT, see [I-D.ietf-anima-grasp]) 317 o value - a specific data structure expressing the value of the 318 objective. The format is language dependent, with the constraint 319 that it can be validly represented in CBOR (default integer = 0). 321 An essential requirement for all language mappings and all 322 implementations is that, regardless of what other options exist 323 for a language-specific represenation of the value, there is 324 always an option to use a CBOR byte string as the value. The API 325 will then wrap this byte string in CBOR Tag 24 for transmission 326 via GRASP, and unwrap it after reception. 328 An example data structure definition for an objective in the C 329 language is: 331 typedef struct { 332 char *name; 333 uint8_t flags; // flag bits as defined by GRASP 334 int loop_count; 335 int value_size; // size of value 336 uint8_t cbor_value[]; // CBOR bytestring of value 337 } objective; 339 An example data structure definition for an objective in the 340 Python language is: 342 class objective: 343 """A GRASP objective""" 344 def __init__(self, name): 345 self.name = name #Unique name, string 346 self.neg = False #True if objective supports negotiation 347 self.dry = False #True if objective supports dry-run neg. 348 self.synch = False #True if objective supports synch 349 self.loop_count = GRASP_DEF_LOOPCT #Default starting value 350 self.value = 0 #Place holder; any valid Python object 352 2.3.1.4. ASA_locator 354 An 'ASA_locator' parameter is a data structure with the following 355 contents: 357 o locator - The actual locator, either an IP address or an ASCII 358 string. 360 o ifi (integer) - The interface identifier index via which this was 361 discovered - probably no use to a normal ASA 363 o expire (system dependent type) - The time on the local system 364 clock when this locator will expire from the cache 366 o is_ipaddress (Boolean) - True if the locator is an IP address 368 o is_fqdn (Boolean) - True if the locator is an FQDN 370 o is_uri (Boolean) - True if the locator is a URI 372 o diverted (Boolean) - True if the locator was discovered via a 373 Divert option 375 o protocol (integer) - Applicable transport protocol (IPPROTO_TCP or 376 IPPROTO_UDP) 378 o port (integer) - Applicable port number 380 2.3.1.5. Tagged_objective 382 A 'tagged_objective' parameter is a data structure with the following 383 contents: 385 o objective - An objective 387 o locator - The ASA_locator associated with the objective, or a null 388 value. 390 2.3.1.6. Asa_nonce 392 In most calls, an 'asa_nonce' parameter is required. It is generated 393 when an ASA registers with GRASP, and any call in which an invalid 394 nonce is presented will fail. It is an up to 32-bit opaque value 395 (for example represented as a uint32_t, depending on the language). 396 It should be unpredictable; a possible implementation is to use the 397 same mechanism that GRASP uses to generate Session IDs 398 [I-D.ietf-anima-grasp]. Another possible implementation is to hash 399 the name of the ASA with a locally defined secret key. 401 2.3.1.7. Session_nonce 403 In some calls, a 'session_nonce' parameter is required. This is an 404 opaque data structure as far as the ASA is concerned, used to 405 identify calls to the API as belonging to a specific GRASP session 406 (see Section 2.2). In fully threaded implementations this parameter 407 might not be needed, but it is included to act as a session handle if 408 necessary. It will also allow GRASP to detect and ignore malicious 409 calls or calls from timed-out sessions. A possible implementation is 410 to form the nonce from the underlying GRASP Session ID and the source 411 address of the session. 413 2.3.2. Registration 415 These functions are used to register an ASA and the objectives that 416 it supports with the GRASP module. If an authorization model is 417 added to GRASP, it would be added here. 419 o register_asa() 421 Input parameter: 423 name of the ASA (UTF-8 string) 425 Return parameters: 427 errorcode (integer) 429 asa_nonce (integer) (if successful) 431 This initialises state in the GRASP module for the calling 432 entity (the ASA). In the case of success, an 'asa_nonce' is 433 returned which the ASA must present in all subsequent calls. 434 In the case of failure, the ASA has not been authorized and 435 cannot operate. 437 o deregister_asa() 439 Input parameters: 441 asa_nonce (integer) 443 name of the ASA (UTF-8 string) 445 Return parameter: 447 errorcode (integer) 449 This removes all state in the GRASP module for the calling 450 entity (the ASA), and deregisters any objectives it has 451 registered. Note that these actions must also happen 452 automatically if an ASA crashes. 454 Note - the ASA name is strictly speaking redundant in this 455 call, but is present for clarity. 457 o register_objective() 459 Input parameters: 461 asa_nonce (integer) 463 objective (structure) 465 ttl (integer - default GRASP_DEF_TIMEOUT) 467 discoverable (Boolean - default False) 469 overlap (Boolean - default False) 470 local (Boolean - default False) 472 Return parameter: 474 errorcode (integer) 476 This registers an objective that this ASA supports and may 477 modify. The 'objective' becomes a candidate for discovery. 478 However, discovery responses should not be enabled until the 479 ASA calls listen_negotiate() or listen_synchronize(), showing 480 that it is able to act as a responder. The ASA may negotiate 481 the objective or send synchronization or flood data. 482 Registration is not needed if the ASA only wants to receive 483 synchronization or flood data for the objective concerned. 485 The 'ttl' parameter is the valid lifetime (time to live) in 486 milliseconds of any discovery response for this objective. The 487 default value should be the GRASP default timeout 488 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]). 490 If the optional parameter 'discoverable' is True, the objective 491 is immediately discoverable. This is intended for objectives 492 that are only defined for GRASP discovery, and which do not 493 support negotiation or synchronization. 495 If the optional parameter 'overlap' is True, more than one ASA 496 may register this objective in the same GRASP instance. 498 If the optional parameter 'local' is True, discovery must 499 return a link-local address. This feature is for objectives 500 that must be restricted to the local link. 502 This call may be repeated for multiple objectives. 504 o deregister_objective() 506 Input parameters: 508 asa_nonce (integer) 510 objective (structure) 512 Return parameter: 514 errorcode (integer) 516 The 'objective' must have been registered by the calling ASA; 517 if not, this call fails. Otherwise, it removes all state in 518 the GRASP module for the given objective. 520 2.3.3. Discovery 522 o discover() 524 Input parameters: 526 asa_nonce (integer) 528 objective (structure) 530 timeout (integer) 532 flush (Boolean - default False) 534 Return parameters: 536 errorcode (integer) 538 locator_list (structure) 540 This returns a list of discovered 'ASA_locator's for the given 541 objective. If the optional parameter 'flush' is True, any 542 locally cached locators for the objective are deleted first. 543 Otherwise, they are returned immediately. If not, GRASP 544 discovery is performed, and all results obtained before the 545 timeout expires are returned. If no results are obtained, an 546 empty list is returned after the timeout. That is not an error 547 condition. 549 Threaded implementation: This should be called in a separate 550 thread if asynchronous operation is required. 552 Event loop implementation: An additional read/write 553 'session_nonce' parameter is used. 555 2.3.4. Negotiation 557 o request_negotiate() 559 Input parameters: 561 asa_nonce (integer) 563 objective (structure) 564 peer (ASA_locator) 566 timeout (integer) 568 Return parameters: 570 errorcode (integer) 572 session_nonce (structure) (if successful) 574 proffered_objective (structure) (if successful) 576 reason (string) (if negotiation declined) 578 This function opens a negotiation session. The 'objective' 579 parameter must include the requested value, and its loop count 580 should be set to a suitable value by the ASA. If not, the 581 GRASP default will apply. 583 Note that a given negotiation session may or may not be a dry- 584 run negotiation; the two modes must not be mixed in a single 585 session. 587 The 'peer' parameter is the target node; it must be an 588 'ASA_locator' as returned by discover(). If the peer is null, 589 GRASP discovery is performed first. 591 If the 'errorcode' return parameter is 0, the negotiation has 592 successfully started. There are then two cases: 594 1. The 'session_nonce' parameter is null. In this case the 595 negotiation has succeeded (the peer has accepted the 596 request). The returned 'proffered_objective' contains the 597 value accepted by the peer. 599 2. The 'session_nonce' parameter is not null. In this case 600 negotiation must continue. The returned 601 'proffered_objective' contains the first value proffered by 602 the negotiation peer. Note that this instance of the 603 objective must be used in the subsequent negotiation call 604 because it also contains the current loop count. The 605 'session_nonce' must be presented in all subsequent 606 negotiation steps. 608 This function must be followed by calls to 'negotiate_step' 609 and/or 'negotiate_wait' and/or 'end_negotiate' until the 610 negotiation ends. 'request_negotiate' may then be called 611 again to start a new negotation. 613 If the 'errorcode' parameter has the value 1 ('declined'), the 614 negotiation has been declined by the peer (M_END and O_DECLINE 615 features of GRASP). The 'reason' string is then available for 616 information and diagnostic use, but it may be a null string. 617 For this and any other error code, an exponential backoff is 618 recommended before any retry. 620 Threaded implementation: This should be called in a separate 621 thread if asynchronous operation is required. 623 Event loop implementation: The 'session_nonce' parameter is 624 used in read/write mode. 626 Special note for the ACP infrastructure ASA: It is likely that 627 this ASA will need to discover and negotiate with its peers in 628 each of its on-link neighbors. It will therefore need to know 629 not only the link-local IP address but also the physical 630 interface and transport port for connecting to each neighbor. 631 One implementation approach to this is to include these details 632 in the 'session_nonce' data structure, which is opaque to 633 normal ASAs. 635 o listen_negotiate() 637 Input parameters: 639 asa_nonce (integer) 641 objective (structure) 643 Return parameters: 645 errorcode (integer) 647 session_nonce (structure) (if successful) 649 requested_objective (structure) (if successful) 651 This function instructs GRASP to listen for negotiation 652 requests for the given 'objective'. It also enables discovery 653 responses for the objective. 655 Threaded implementation: It will block waiting for an incoming 656 request, so should be called in a separate thread if 657 asynchronous operation is required. 659 Event loop implementation: A read/write 'session_nonce' 660 parameter is used. 662 Unless there is an unexpected failure, this call only returns 663 after an incoming negotiation request. When it does so, 664 'requested_objective' contains the first value requested by the 665 negotiation peer. Note that this instance of the objective 666 must be used in the subsequent negotiation call because it also 667 contains the current loop count. The 'session_nonce' must be 668 presented in all subsequent negotiation steps. 670 This function must be followed by calls to 'negotiate_step' 671 and/or 'negotiate_wait' and/or 'end_negotiate' until the 672 negotiation ends. 'listen_negotiate' may then be called again 673 to await a new negotation. 675 If an ASA is capable of handling multiple negotiations 676 simultaneously, it may call 'listen_negotiate' simultaneously 677 from multiple threads. The API and GRASP implementation must 678 support re-entrant use of the listening state and the 679 negotiation calls. Simultaneous sessions will be distinguished 680 by the threads themselves, the GRASP Session IDs, and the 681 underlying unicast transport sockets. 683 o stop_listen_negotiate() 685 Input parameters: 687 asa_nonce (integer) 689 objective (structure) 691 Return parameter: 693 errorcode (integer) 695 Instructs GRASP to stop listening for negotiation requests for 696 the given objective, i.e., cancels 'listen_negotiate'. 698 Threaded implementation: Must be called from a different thread 699 than 'listen_negotiate'. 701 Event loop implementation: no special considerations. 703 o negotiate_step() 705 Input parameters: 707 asa_nonce (integer) 709 session_nonce (structure) 710 objective (structure) 712 timeout (integer) 714 Return parameters: 716 Exactly as for 'request_negotiate' 718 Executes the next negotation step with the peer. The 719 'objective' parameter contains the next value being proffered 720 by the ASA in this step. 722 Threaded implementation: Called in the same thread as the 723 preceding 'request_negotiate' or 'listen_negotiate', with the 724 same value of 'session_nonce'. 726 Event loop implementation: Must use the same value of 727 'session_nonce' returned by the preceding 'request_negotiate' 728 or 'listen_negotiate'. 730 o negotiate_wait() 732 Input parameters: 734 asa_nonce (integer) 736 session_nonce (structure) 738 timeout (integer) 740 Return parameters: 742 errorcode (integer) 744 Delay negotiation session by 'timeout' milliseconds. 746 Threaded implementation: Called in the same thread as the 747 preceding 'request_negotiate' or 'listen_negotiate', with the 748 same value of 'session_nonce'. 750 Event loop implementation: Must use the same value of 751 'session_nonce' returned by the preceding 'request_negotiate' 752 or 'listen_negotiate'. 754 o end_negotiate() 756 Input parameters: 758 asa_nonce (integer) 760 session_nonce (structure) 762 reply (Boolean) 764 reason (UTF-8 string) 766 Return parameters: 768 errorcode (integer) 770 End the negotiation session. 772 'reply' = True for accept (successful negotiation), False for 773 decline (failed negotiation). 775 'reason' = optional string describing reason for decline. 777 Threaded implementation: Called in the same thread as the 778 preceding 'request_negotiate' or 'listen_negotiate', with the 779 same value of 'session_nonce'. 781 Event loop implementation: Must use the same value of 782 'session_nonce' returned by the preceding 'request_negotiate' 783 or 'listen_negotiate'. 785 2.3.5. Synchronization and Flooding 787 o synchronize() 789 Input parameters: 791 asa_nonce (integer) 793 objective (structure) 795 peer (ASA_locator) 797 timeout (integer) 799 Return parameters: 801 errorcode (integer) 803 objective (structure) (if successful) 805 This call requests the synchronized value of the given 806 'objective'. 808 Since this is essentially a read operation, any ASA can do it. 809 Therefore the API checks that the ASA is registered but the 810 objective doesn't need to be registered by the calling ASA. 812 If the objective was already flooded, the flooded value is 813 returned immediately in the 'result' parameter. In this case, 814 the 'source' and 'timeout' are ignored. 816 Otherwise, synchronization with a discovered ASA is performed. 817 The 'peer' parameter is an 'ASA_locator' as returned by 818 discover(). If 'peer' is null, GRASP discovery is performed 819 first. 821 This call should be repeated whenever the latest value is 822 needed. 824 Threaded implementation: Call in a separate thread if 825 asynchronous operation is required. 827 Event loop implementation: An additional read/write 828 'session_nonce' parameter is used. 830 Since this is essentially a read operation, any ASA can use it. 831 Therefore GRASP checks that the calling ASA is registered but 832 the objective doesn't need to be registered by the calling ASA. 834 In the case of failure, an exponential backoff is recommended 835 before retrying. 837 o listen_synchronize() 839 Input parameters: 841 asa_nonce (integer) 843 objective (structure) 845 Return parameters: 847 errorcode (integer) 849 This instructs GRASP to listen for synchronization requests for 850 the given objective, and to respond with the value given in the 851 'objective' parameter. It also enables discovery responses for 852 the objective. 854 This call is non-blocking and may be repeated whenever the 855 value changes. 857 o stop_listen_synchronize() 859 Input parameters: 861 asa_nonce (integer) 863 objective (structure) 865 Return parameters: 867 errorcode (integer) 869 This call instructs GRASP to stop listening for synchronization 870 requests for the given 'objective', i.e. it cancels a previous 871 listen_synchronize. 873 o flood() 875 Input parameters: 877 asa_nonce (integer) 879 ttl (integer) 881 tagged_objective_list (structure) 883 Return parameters: 885 errorcode (integer) 887 This call instructs GRASP to flood the given synchronization 888 objective(s) and their value(s) and associated locator(s) to 889 all GRASP nodes. 891 The 'ttl' parameter is the valid lifetime (time to live) of the 892 flooded data in milliseconds (0 = infinity) 894 The 'tagged_objective_list' parameter is a list of one or more 895 'tagged_objective' couplets. The 'locator' parameter that tags 896 each objective is normally null but may be a valid 897 'ASA_locator'. Infrastructure ASAs needing to flood an 898 {address, protocol, port} 3-tuple with an objective create an 899 ASA_locator object to do so. If the IP address in that locator 900 is the unspecified address ('::') it is replaced by the link- 901 local address of the sending node in each copy of the flood 902 multicast, which will be forced to have a loop count of 1. 903 This feature is for objectives that must be restricted to the 904 local link. 906 The function checks that the ASA registered each objective. 908 This call may be repeated whenever any value changes. 910 o get_flood() 912 Input parameters: 914 asa_nonce (integer) 916 objective (structure) 918 Return parameters: 920 errorcode (integer) 922 tagged_objective_list (structure) (if successful) 924 This call instructs GRASP to return the given synchronization 925 objective if it has been flooded and its lifetime has not 926 expired. 928 Since this is essentially a read operation, any ASA can do it. 929 Therefore the API checks that the ASA is registered but the 930 objective doesn't need to be registered by the calling ASA. 932 The 'tagged_objective_list' parameter is a list of 933 'tagged_objective' couplets, each one being a copy of the 934 flooded objective and a coresponding locator. Thus if the same 935 objective has been flooded by multiple ASAs, the recipient can 936 distinguish the copies. 938 Note that this call is for advanced ASAs. In a simple case, an 939 ASA can simply call synchronize() in order to get a valid 940 flooded objective. 942 o expire_flood() 944 Input parameters: 946 asa_nonce (integer) 948 tagged_objective (structure) 950 Return parameters: 952 errorcode (integer) 954 This is a call that can only be used after a preceding call to 955 get_flood() by an ASA that is capable of deciding that the 956 flooded value is stale or invalid. Use with care. 958 The 'tagged_objective' parameter is the one to be expired. 960 2.3.6. Invalid Message Function 962 o send_invalid() 964 Input parameters: 966 asa_nonce (integer) 968 session_nonce (structure) 970 info (bytes) 972 Return parameters: 974 errorcode (integer) 976 Sends a GRASP Invalid Message (M_INVALID) message, as described 977 in [I-D.ietf-anima-grasp]. Should not be used if 978 end_negotiate() would be sufficient. Note that this message 979 may be used in response to any unicast GRASP message that the 980 receiver cannot interpret correctly. In most cases this 981 message will be generated internally by a GRASP implementation. 983 'info' = optional diagnostic data. May be raw bytes from the 984 invalid message. 986 3. Example Logic Flows 988 TBD 990 (Until this section is written, some Python examples can be found at 991 .) 993 4. Security Considerations 995 Security issues for the GRASP protocol are discussed in 996 [I-D.ietf-anima-grasp]. Authorization of ASAs is a subject for 997 future study. 999 The 'asa_nonce' parameter is used in the API as a first line of 1000 defence against a malware process attempting to imitate a 1001 legitimately registered ASA. The 'session_nonce' parameter is used 1002 in the API as a first line of defence against a malware process 1003 attempting to hijack a GRASP session. 1005 5. IANA Considerations 1007 This document currently makes no request of the IANA. 1009 Open question: Do we need an IANA registry for the error codes? 1011 6. Acknowledgements 1013 Excellent suggestions were made by Ignas Bagdonas, Michael Richardson 1014 and other participants in the ANIMA WG. 1016 7. References 1018 7.1. Normative References 1020 [I-D.ietf-anima-grasp] 1021 Bormann, C., Carpenter, B., and B. Liu, "A Generic 1022 Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- 1023 grasp-15 (work in progress), July 2017. 1025 7.2. Informative References 1027 [I-D.ietf-anima-autonomic-control-plane] 1028 Eckert, T., Behringer, M., and S. Bjarnason, "An Autonomic 1029 Control Plane (ACP)", draft-ietf-anima-autonomic-control- 1030 plane-16 (work in progress), June 2018. 1032 [I-D.ietf-anima-bootstrapping-keyinfra] 1033 Pritikin, M., Richardson, M., Behringer, M., Bjarnason, 1034 S., and K. Watsen, "Bootstrapping Remote Secure Key 1035 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 1036 keyinfra-16 (work in progress), June 2018. 1038 [I-D.ietf-anima-reference-model] 1039 Behringer, M., Carpenter, B., Eckert, T., Ciavaglia, L., 1040 and J. Nobre, "A Reference Model for Autonomic 1041 Networking", draft-ietf-anima-reference-model-06 (work in 1042 progress), February 2018. 1044 [I-D.liu-anima-grasp-distribution] 1045 Liu, B., Jiang, S., Xiao, X., Hecker, A., and Z. 1046 Despotovic, "Information Distribution in Autonomic 1047 Networking", draft-liu-anima-grasp-distribution-05 (work 1048 in progress), February 2018. 1050 Appendix A. Error Codes 1052 This Appendix lists the error codes defined so far, with suggested 1053 symbolic names and corresponding descriptive strings in English. It 1054 is expected that complete API implementations will provide for 1055 localisation of these descriptive strings, and that additional error 1056 codes will be needed according to implementation details. 1058 An open issue for these values is whether there is an advantage in 1059 aligning them with existing error codes in the socket API, where the 1060 meanings coincide, and using different values otherwise. This is to 1061 be balanced against the advantage of having a compact and completely 1062 portable set of error codes for GRASP alone. 1064 ok 0 "OK" 1065 declined 1 "Declined" 1066 noReply 2 "No reply" 1067 unspec 3 "Unspecified error" 1068 ASAfull 4 "ASA registry full" 1069 dupASA 5 "Duplicate ASA name" 1070 noASA 6 "ASA not registered" 1071 notYourASA 7 "ASA registered but not by you" 1072 notBoth 8 "Objective cannot support both negotiation 1073 and synchronization" 1074 notDry 9 "Dry-run allowed only with negotiation" 1075 notOverlap 10 "Overlap not supported by this implementation" 1076 objFull 11 "Objective registry full" 1077 objReg 12 "Objective already registered" 1078 notYourObj 13 "Objective not registered by this ASA" 1079 notObj 14 "Objective not found" 1080 notNeg 15 "Objective not negotiable" 1081 noSecurity 16 "No security" 1082 noDiscReply 17 "No reply to discovery" 1083 sockErrNegRq 18 "Socket error sending negotiation request" 1084 noSession 19 "No session" 1085 noSocket 20 "No socket" 1086 loopExhausted 21 "Loop count exhausted" 1087 sockErrNegStep 22 "Socket error sending negotiation step" 1088 noPeer 23 "No negotiation peer" 1089 CBORfail 24 "CBOR decode failure" 1090 invalidNeg 25 "Invalid Negotiate message" 1091 invalidEnd 26 "Invalid end message" 1092 noNegReply 27 "No reply to negotiation step" 1093 noValidStep 28 "No valid reply to negotiation step" 1094 sockErrWait 29 "Socket error sending wait message" 1095 sockErrEnd 30 "Socket error sending end message" 1096 IDclash 31 "Incoming request Session ID clash" 1097 notSynch 32 "Not a synchronization objective" 1098 notFloodDisc 33 "Not flooded and no reply to discovery" 1099 sockErrSynRq 34 "Socket error sending synch request" 1100 noListener 35 "No synch listener" 1101 noSynchReply 36 "No reply to synchronization request" 1102 noValidSynch 37 "No valid reply to synchronization request" 1103 invalidLoc 38 "Invalid locator" 1105 Appendix B. Change log [RFC Editor: Please remove] 1107 draft-ietf-anima-grasp-api-02, 2018-06-30: 1109 Additional suggestion for event-loop API. 1111 Discussion of error code values. 1113 draft-ietf-anima-grasp-api-01, 2018-03-03: 1115 Editorial updates 1117 draft-ietf-anima-grasp-api-00, 2017-12-23: 1119 WG adoption 1121 Editorial improvements. 1123 draft-liu-anima-grasp-api-06, 2017-11-24: 1125 Improved description of event-loop model. 1127 Changed intended status to Informational. 1129 Editorial improvements. 1131 draft-liu-anima-grasp-api-05, 2017-10-02: 1133 Added send_invalid() 1135 draft-liu-anima-grasp-api-04, 2017-06-30: 1137 Noted that simple nodes might not include the API. 1139 Minor clarifications. 1141 draft-liu-anima-grasp-api-03, 2017-02-13: 1143 Changed error return to integers. 1145 Required all implementations to accept objective values in CBOR. 1147 Added non-blocking alternatives. 1149 draft-liu-anima-grasp-api-02, 2016-12-17: 1151 Updated for draft-ietf-anima-grasp-09 1153 draft-liu-anima-grasp-api-02, 2016-09-30: 1155 Added items for draft-ietf-anima-grasp-07 1157 Editorial corrections 1159 draft-liu-anima-grasp-api-01, 2016-06-24: 1161 Updated for draft-ietf-anima-grasp-05 1163 Editorial corrections 1165 draft-liu-anima-grasp-api-00, 2016-04-04: 1167 Initial version 1169 Authors' Addresses 1171 Brian Carpenter 1172 Department of Computer Science 1173 University of Auckland 1174 PB 92019 1175 Auckland 1142 1176 New Zealand 1178 Email: brian.e.carpenter@gmail.com 1180 Bing Liu (editor) 1181 Huawei Technologies 1182 Q22, Huawei Campus 1183 No.156 Beiqing Road 1184 Hai-Dian District, Beijing 100095 1185 P.R. China 1187 Email: leo.liubing@huawei.com 1189 Wendong Wang 1190 BUPT University 1191 Beijing University of Posts & Telecom. 1192 No.10 Xitucheng Road 1193 Hai-Dian District, Beijing 100876 1194 P.R. China 1196 Email: wdwang@bupt.edu.cn 1198 Xiangyang Gong 1199 BUPT University 1200 Beijing University of Posts & Telecom. 1201 No.10 Xitucheng Road 1202 Hai-Dian District, Beijing 100876 1203 P.R. China 1205 Email: xygong@bupt.edu.cn