idnits 2.17.1 draft-ietf-anima-grasp-api-01.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 (March 3, 2018) is 2217 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-13 == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-11 == 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: September 4, 2018 Huawei Technologies 6 W. Wang 7 X. Gong 8 BUPT University 9 March 3, 2018 11 Generic Autonomic Signaling Protocol Application Program Interface 12 (GRASP API) 13 draft-ietf-anima-grasp-api-01 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 September 4, 2018. 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 . . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . . . . . . 25 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 value. This value must be used in all 240 subsequent calls. By this mechanism, multiple overlapping sessions 241 can be distinguished, both in the ASA and in the GRASP core. 243 2.3. API definition 245 2.3.1. Parameters and data structures 247 This section describes parameters and data structures uaed in 248 multiple API calls. 250 2.3.1.1. Errorcode 252 All functions in the API have an unsigned 'errorcode' integer as 253 their return value (the first returned value in languages that allow 254 multiple returned parameters). An errorcode of zero indicates 255 success. Any other value indicates failure of some kind. The first 256 three errorcodes have special importance: 258 1. Declined: used to indicate that the other end has sent a GRASP 259 Negotiation End message (M_END) with a Decline option 260 (O_DECLINE). 262 2. No reply: used in non-blocking calls to indicate that the other 263 end has sent no reply so far (see Section 2.2). 265 3. Unspecified error: used when no more specific error code applies. 267 Appendix A gives a full list of currently defined error codes, based 268 on implementation experience. 270 2.3.1.2. Timeout 272 Wherever a 'timeout' parameter appears, it is an integer expressed in 273 milliseconds. If it is zero, the GRASP default timeout 274 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]) will apply. If no 275 response is received before the timeout expires, the call will fail 276 unless otherwise noted. 278 2.3.1.3. Objective 280 An 'objective' parameter is a data structure with the following 281 components: 283 o name (UTF-8 string) - the objective's name 285 o neg (Boolean flag) - True if objective supports negotiation 286 (default False) 288 o synch (Boolean flag) - True if objective supports synchronization 289 (default False) 291 o dry (Boolean flag) - True if objective supports dry-run 292 negotiation (default False) 294 * Note 1: All objectives are assumed to support discovery, so 295 there is no Boolean for that. 297 * Note 2: Only one of 'synch' or 'neg' may be True. 299 * Note 3: 'dry' must not be True unless 'neg' is also True. 301 * Note 4: In a language such as C the preferred implementation 302 may be to represent the Boolean flags as bits in a single byte. 304 o loop_count (integer) - Limit on negotiation steps etc. (default 305 GRASP_DEF_LOOPCT, see [I-D.ietf-anima-grasp]) 307 o value - a specific data structure expressing the value of the 308 objective. The format is language dependent, with the constraint 309 that it can be validly represented in CBOR (default integer = 0). 311 An essential requirement for all language mappings and all 312 implementations is that, regardless of what other options exist 313 for a language-specific represenation of the value, there is 314 always an option to use a CBOR byte string as the value. The API 315 will then wrap this byte string in CBOR Tag 24 for transmission 316 via GRASP, and unwrap it after reception. 318 An example data structure definition for an objective in the C 319 language is: 321 typedef struct { 322 char *name; 323 uint8_t flags; // flag bits as defined by GRASP 324 int loop_count; 325 int value_size; // size of value 326 uint8_t cbor_value[]; // CBOR bytestring of value 327 } objective; 329 An example data structure definition for an objective in the 330 Python language is: 332 class objective: 333 """A GRASP objective""" 334 def __init__(self, name): 335 self.name = name #Unique name, string 336 self.neg = False #True if objective supports negotiation 337 self.dry = False #True if objective supports dry-run neg. 338 self.synch = False #True if objective supports synch 339 self.loop_count = GRASP_DEF_LOOPCT #Default starting value 340 self.value = 0 #Place holder; any valid Python object 342 2.3.1.4. ASA_locator 344 An 'ASA_locator' parameter is a data structure with the following 345 contents: 347 o locator - The actual locator, either an IP address or an ASCII 348 string. 350 o ifi (integer) - The interface identifier index via which this was 351 discovered - probably no use to a normal ASA 353 o expire (system dependent type) - The time on the local system 354 clock when this locator will expire from the cache 356 o is_ipaddress (Boolean) - True if the locator is an IP address 358 o is_fqdn (Boolean) - True if the locator is an FQDN 360 o is_uri (Boolean) - True if the locator is a URI 362 o diverted (Boolean) - True if the locator was discovered via a 363 Divert option 365 o protocol (integer) - Applicable transport protocol (IPPROTO_TCP or 366 IPPROTO_UDP) 368 o port (integer) - Applicable port number 370 2.3.1.5. Tagged_objective 372 A 'tagged_objective' parameter is a data structure with the following 373 contents: 375 o objective - An objective 377 o locator - The ASA_locator associated with the objective, or a null 378 value. 380 2.3.1.6. Asa_nonce 382 In most calls, an 'asa_nonce' parameter is required. It is generated 383 when an ASA registers with GRASP, and any call in which an invalid 384 nonce is presented will fail. It is an up to 32-bit opaque value 385 (for example represented as a uint32_t, depending on the language). 386 It should be unpredictable; a possible implementation is to use the 387 same mechanism that GRASP uses to generate Session IDs 388 [I-D.ietf-anima-grasp]. Another possible implementation is to hash 389 the name of the ASA with a locally defined secret key. 391 2.3.1.7. Session_nonce 393 In some calls, a 'session_nonce' parameter is required. This is an 394 opaque data structure as far as the ASA is concerned, used to 395 identify calls to the API as belonging to a specific GRASP session 396 (see Section 2.2). In fully threaded implementations this parameter 397 might not be needed, but it is included to act as a session handle if 398 necessary. It will also allow GRASP to detect and ignore malicious 399 calls or calls from timed-out sessions. A possible implementation is 400 to form the nonce from the underlying GRASP Session ID and the source 401 address of the session. 403 2.3.2. Registration 405 These functions are used to register an ASA and the objectives that 406 it supports with the GRASP module. If an authorization model is 407 added to GRASP, it would be added here. 409 o register_asa() 411 Input parameter: 413 name of the ASA (UTF-8 string) 415 Return parameters: 417 errorcode (integer) 419 asa_nonce (integer) (if successful) 421 This initialises state in the GRASP module for the calling 422 entity (the ASA). In the case of success, an 'asa_nonce' is 423 returned which the ASA must present in all subsequent calls. 424 In the case of failure, the ASA has not been authorized and 425 cannot operate. 427 o deregister_asa() 428 Input parameters: 430 asa_nonce (integer) 432 name of the ASA (UTF-8 string) 434 Return parameter: 436 errorcode (integer) 438 This removes all state in the GRASP module for the calling 439 entity (the ASA), and deregisters any objectives it has 440 registered. Note that these actions must also happen 441 automatically if an ASA crashes. 443 Note - the ASA name is strictly speaking redundant in this 444 call, but is present for clarity. 446 o register_objective() 448 Input parameters: 450 asa_nonce (integer) 452 objective (structure) 454 ttl (integer - default GRASP_DEF_TIMEOUT) 456 discoverable (Boolean - default False) 458 overlap (Boolean - default False) 460 local (Boolean - default False) 462 Return parameter: 464 errorcode (integer) 466 This registers an objective that this ASA supports and may 467 modify. The 'objective' becomes a candidate for discovery. 468 However, discovery responses should not be enabled until the 469 ASA calls listen_negotiate() or listen_synchronize(), showing 470 that it is able to act as a responder. The ASA may negotiate 471 the objective or send synchronization or flood data. 472 Registration is not needed if the ASA only wants to receive 473 synchronization or flood data for the objective concerned. 475 The 'ttl' parameter is the valid lifetime (time to live) in 476 milliseconds of any discovery response for this objective. The 477 default value should be the GRASP default timeout 478 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]). 480 If the optional parameter 'discoverable' is True, the objective 481 is immediately discoverable. This is intended for objectives 482 that are only defined for GRASP discovery, and which do not 483 support negotiation or synchronization. 485 If the optional parameter 'overlap' is True, more than one ASA 486 may register this objective in the same GRASP instance. 488 If the optional parameter 'local' is True, discovery must 489 return a link-local address. This feature is for objectives 490 that must be restricted to the local link. 492 This call may be repeated for multiple objectives. 494 o deregister_objective() 496 Input parameters: 498 asa_nonce (integer) 500 objective (structure) 502 Return parameter: 504 errorcode (integer) 506 The 'objective' must have been registered by the calling ASA; 507 if not, this call fails. Otherwise, it removes all state in 508 the GRASP module for the given objective. 510 2.3.3. Discovery 512 o discover() 514 Input parameters: 516 asa_nonce (integer) 518 objective (structure) 520 timeout (integer) 522 flush (Boolean - default False) 524 Return parameters: 526 errorcode (integer) 528 locator_list (structure) 530 This returns a list of discovered 'ASA_locator's for the given 531 objective. If the optional parameter 'flush' is True, any 532 locally cached locators for the objective are deleted first. 533 Otherwise, they are returned immediately. If not, GRASP 534 discovery is performed, and all results obtained before the 535 timeout expires are returned. If no results are obtained, an 536 empty list is returned after the timeout. That is not an error 537 condition. 539 Threaded implementation: This should be called in a separate 540 thread if asynchronous operation is required. 542 Event loop implementation: An additional read/write 543 'session_nonce' parameter is used. 545 2.3.4. Negotiation 547 o request_negotiate() 549 Input parameters: 551 asa_nonce (integer) 553 objective (structure) 555 peer (ASA_locator) 557 timeout (integer) 559 Return parameters: 561 errorcode (integer) 563 session_nonce (structure) (if successful) 565 proffered_objective (structure) (if successful) 567 reason (string) (if negotiation declined) 569 This function opens a negotiation session. The 'objective' 570 parameter must include the requested value, and its loop count 571 should be set to a suitable value by the ASA. If not, the 572 GRASP default will apply. 574 Note that a given negotiation session may or may not be a dry- 575 run negotiation; the two modes must not be mixed in a single 576 session. 578 The 'peer' parameter is the target node; it must be an 579 'ASA_locator' as returned by discover(). If the peer is null, 580 GRASP discovery is performed first. 582 If the 'errorcode' return parameter is 0, the negotiation has 583 successfully started. There are then two cases: 585 1. The 'session_nonce' parameter is null. In this case the 586 negotiation has succeeded (the peer has accepted the 587 request). The returned 'proffered_objective' contains the 588 value accepted by the peer. 590 2. The 'session_nonce' parameter is not null. In this case 591 negotiation must continue. The returned 592 'proffered_objective' contains the first value proffered by 593 the negotiation peer. Note that this instance of the 594 objective must be used in the subsequent negotiation call 595 because it also contains the current loop count. The 596 'session_nonce' must be presented in all subsequent 597 negotiation steps. 599 This function must be followed by calls to 'negotiate_step' 600 and/or 'negotiate_wait' and/or 'end_negotiate' until the 601 negotiation ends. 'request_negotiate' may then be called 602 again to start a new negotation. 604 If the 'errorcode' parameter has the value 1 ('declined'), the 605 negotiation has been declined by the peer (M_END and O_DECLINE 606 features of GRASP). The 'reason' string is then available for 607 information and diagnostic use, but it may be a null string. 608 For this and any other error code, an exponential backoff is 609 recommended before any retry. 611 Threaded implementation: This should be called in a separate 612 thread if asynchronous operation is required. 614 Event loop implementation: The 'session_nonce' parameter is 615 used in read/write mode. 617 Special note for the ACP infrastructure ASA: It is likely that 618 this ASA will need to discover and negotiate with its peers in 619 each of its on-link neighbors. It will therefore need to know 620 not only the link-local IP address but also the physical 621 interface and transport port for connecting to each neighbor. 622 One implementation approach to this is to include these details 623 in the 'session_nonce' data structure, which is opaque to 624 normal ASAs. 626 o listen_negotiate() 628 Input parameters: 630 asa_nonce (integer) 632 objective (structure) 634 Return parameters: 636 errorcode (integer) 638 session_nonce (structure) (if successful) 640 requested_objective (structure) (if successful) 642 This function instructs GRASP to listen for negotiation 643 requests for the given 'objective'. It also enables discovery 644 responses for the objective. 646 Threaded implementation: It will block waiting for an incoming 647 request, so should be called in a separate thread if 648 asynchronous operation is required. 650 Event loop implementation: A read/write 'session_nonce' 651 parameter is used. 653 Unless there is an unexpected failure, this call only returns 654 after an incoming negotiation request. When it does so, 655 'requested_objective' contains the first value requested by the 656 negotiation peer. Note that this instance of the objective 657 must be used in the subsequent negotiation call because it also 658 contains the current loop count. The 'session_nonce' must be 659 presented in all subsequent negotiation steps. 661 This function must be followed by calls to 'negotiate_step' 662 and/or 'negotiate_wait' and/or 'end_negotiate' until the 663 negotiation ends. 'listen_negotiate' may then be called again 664 to await a new negotation. 666 If an ASA is capable of handling multiple negotiations 667 simultaneously, it may call 'listen_negotiate' simultaneously 668 from multiple threads. The API and GRASP implementation must 669 support re-entrant use of the listening state and the 670 negotiation calls. Simultaneous sessions will be distinguished 671 by the threads themselves, the GRASP Session IDs, and the 672 underlying unicast transport sockets. 674 o stop_listen_negotiate() 676 Input parameters: 678 asa_nonce (integer) 680 objective (structure) 682 Return parameter: 684 errorcode (integer) 686 Instructs GRASP to stop listening for negotiation requests for 687 the given objective, i.e., cancels 'listen_negotiate'. 689 Threaded implementation: Must be called from a different thread 690 than 'listen_negotiate'. 692 Event loop implementation: no special considerations. 694 o negotiate_step() 696 Input parameters: 698 asa_nonce (integer) 700 session_nonce (structure) 702 objective (structure) 704 timeout (integer) 706 Return parameters: 708 Exactly as for 'request_negotiate' 710 Executes the next negotation step with the peer. The 711 'objective' parameter contains the next value being proffered 712 by the ASA in this step. 714 Threaded implementation: Called in the same thread as the 715 preceding 'request_negotiate' or 'listen_negotiate', with the 716 same value of 'session_nonce'. 718 Event loop implementation: Must use the same value of 719 'session_nonce' returned by the preceding 'request_negotiate' 720 or 'listen_negotiate'. 722 o negotiate_wait() 724 Input parameters: 726 asa_nonce (integer) 728 session_nonce (structure) 730 timeout (integer) 732 Return parameters: 734 errorcode (integer) 736 Delay negotiation session by 'timeout' milliseconds. 738 Threaded implementation: Called in the same thread as the 739 preceding 'request_negotiate' or 'listen_negotiate', with the 740 same value of 'session_nonce'. 742 Event loop implementation: Must use the same value of 743 'session_nonce' returned by the preceding 'request_negotiate' 744 or 'listen_negotiate'. 746 o end_negotiate() 748 Input parameters: 750 asa_nonce (integer) 752 session_nonce (structure) 754 reply (Boolean) 756 reason (UTF-8 string) 758 Return parameters: 760 errorcode (integer) 762 End the negotiation session. 764 'reply' = True for accept (successful negotiation), False for 765 decline (failed negotiation). 767 'reason' = optional string describing reason for decline. 769 Threaded implementation: Called in the same thread as the 770 preceding 'request_negotiate' or 'listen_negotiate', with the 771 same value of 'session_nonce'. 773 Event loop implementation: Must use the same value of 774 'session_nonce' returned by the preceding 'request_negotiate' 775 or 'listen_negotiate'. 777 2.3.5. Synchronization and Flooding 779 o synchronize() 781 Input parameters: 783 asa_nonce (integer) 785 objective (structure) 787 peer (ASA_locator) 789 timeout (integer) 791 Return parameters: 793 errorcode (integer) 795 objective (structure) (if successful) 797 This call requests the synchronized value of the given 798 'objective'. 800 Since this is essentially a read operation, any ASA can do it. 801 Therefore the API checks that the ASA is registered but the 802 objective doesn't need to be registered by the calling ASA. 804 If the objective was already flooded, the flooded value is 805 returned immediately in the 'result' parameter. In this case, 806 the 'source' and 'timeout' are ignored. 808 Otherwise, synchronization with a discovered ASA is performed. 809 The 'peer' parameter is an 'ASA_locator' as returned by 810 discover(). If 'peer' is null, GRASP discovery is performed 811 first. 813 This call should be repeated whenever the latest value is 814 needed. 816 Threaded implementation: Call in a separate thread if 817 asynchronous operation is required. 819 Event loop implementation: An additional read/write 820 'session_nonce' parameter is used. 822 Since this is essentially a read operation, any ASA can use it. 823 Therefore GRASP checks that the calling ASA is registered but 824 the objective doesn't need to be registered by the calling ASA. 826 In the case of failure, an exponential backoff is recommended 827 before retrying. 829 o listen_synchronize() 831 Input parameters: 833 asa_nonce (integer) 835 objective (structure) 837 Return parameters: 839 errorcode (integer) 841 This instructs GRASP to listen for synchronization requests for 842 the given objective, and to respond with the value given in the 843 'objective' parameter. It also enables discovery responses for 844 the objective. 846 This call is non-blocking and may be repeated whenever the 847 value changes. 849 o stop_listen_synchronize() 851 Input parameters: 853 asa_nonce (integer) 855 objective (structure) 857 Return parameters: 859 errorcode (integer) 861 This call instructs GRASP to stop listening for synchronization 862 requests for the given 'objective', i.e. it cancels a previous 863 listen_synchronize. 865 o flood() 867 Input parameters: 869 asa_nonce (integer) 871 ttl (integer) 873 tagged_objective_list (structure) 875 Return parameters: 877 errorcode (integer) 879 This call instructs GRASP to flood the given synchronization 880 objective(s) and their value(s) and associated locator(s) to 881 all GRASP nodes. 883 The 'ttl' parameter is the valid lifetime (time to live) of the 884 flooded data in milliseconds (0 = infinity) 886 The 'tagged_objective_list' parameter is a list of one or more 887 'tagged_objective' couplets. The 'locator' parameter that tags 888 each objective is normally null but may be a valid 889 'ASA_locator'. Infrastructure ASAs needing to flood an 890 {address, protocol, port} 3-tuple with an objective create an 891 ASA_locator object to do so. If the IP address in that locator 892 is the unspecified address ('::') it is replaced by the link- 893 local address of the sending node in each copy of the flood 894 multicast, which will be forced to have a loop count of 1. 895 This feature is for objectives that must be restricted to the 896 local link. 898 The function checks that the ASA registered each objective. 900 This call may be repeated whenever any value changes. 902 o get_flood() 904 Input parameters: 906 asa_nonce (integer) 907 objective (structure) 909 Return parameters: 911 errorcode (integer) 913 tagged_objective_list (structure) (if successful) 915 This call instructs GRASP to return the given synchronization 916 objective if it has been flooded and its lifetime has not 917 expired. 919 Since this is essentially a read operation, any ASA can do it. 920 Therefore the API checks that the ASA is registered but the 921 objective doesn't need to be registered by the calling ASA. 923 The 'tagged_objective_list' parameter is a list of 924 'tagged_objective' couplets, each one being a copy of the 925 flooded objective and a coresponding locator. Thus if the same 926 objective has been flooded by multiple ASAs, the recipient can 927 distinguish the copies. 929 Note that this call is for advanced ASAs. In a simple case, an 930 ASA can simply call synchronize() in order to get a valid 931 flooded objective. 933 o expire_flood() 935 Input parameters: 937 asa_nonce (integer) 939 tagged_objective (structure) 941 Return parameters: 943 errorcode (integer) 945 This is a call that can only be used after a preceding call to 946 get_flood() by an ASA that is capable of deciding that the 947 flooded value is stale or invalid. Use with care. 949 The 'tagged_objective' parameter is the one to be expired. 951 2.3.6. Invalid Message Function 953 o send_invalid() 955 Input parameters: 957 asa_nonce (integer) 959 session_nonce (structure) 961 info (bytes) 963 Return parameters: 965 errorcode (integer) 967 Sends a GRASP Invalid Message (M_INVALID) message, as described 968 in [I-D.ietf-anima-grasp]. Should not be used if 969 end_negotiate() would be sufficient. Note that this message 970 may be used in response to any unicast GRASP message that the 971 receiver cannot interpret correctly. In most cases this 972 message will be generated internally by a GRASP implementation. 974 'info' = optional diagnostic data. May be raw bytes from the 975 invalid message. 977 3. Example Logic Flows 979 TBD 981 (Until this section is written, some Python examples can be found at 982 .) 984 4. Security Considerations 986 Security issues for the GRASP protocol are discussed in 987 [I-D.ietf-anima-grasp]. Authorization of ASAs is a subject for 988 future study. 990 The 'asa_nonce' parameter is used in the API as a first line of 991 defence against a malware process attempting to imitate a 992 legitimately registered ASA. The 'session_nonce' parameter is used 993 in the API as a first line of defence against a malware process 994 attempting to hijack a GRASP session. 996 5. IANA Considerations 998 This document currently makes no request of the IANA. 1000 Open question: Do we need an IANA registry for the error codes? 1002 6. Acknowledgements 1004 Excellent suggestions were made by Michael Richardson and other 1005 participansts in the ANIMA WG. 1007 7. References 1009 7.1. Normative References 1011 [I-D.ietf-anima-grasp] 1012 Bormann, C., Carpenter, B., and B. Liu, "A Generic 1013 Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- 1014 grasp-15 (work in progress), July 2017. 1016 7.2. Informative References 1018 [I-D.ietf-anima-autonomic-control-plane] 1019 Eckert, T., Behringer, M., and S. Bjarnason, "An Autonomic 1020 Control Plane (ACP)", draft-ietf-anima-autonomic-control- 1021 plane-13 (work in progress), December 2017. 1023 [I-D.ietf-anima-bootstrapping-keyinfra] 1024 Pritikin, M., Richardson, M., Behringer, M., Bjarnason, 1025 S., and K. Watsen, "Bootstrapping Remote Secure Key 1026 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 1027 keyinfra-11 (work in progress), February 2018. 1029 [I-D.ietf-anima-reference-model] 1030 Behringer, M., Carpenter, B., Eckert, T., Ciavaglia, L., 1031 and J. Nobre, "A Reference Model for Autonomic 1032 Networking", draft-ietf-anima-reference-model-06 (work in 1033 progress), February 2018. 1035 [I-D.liu-anima-grasp-distribution] 1036 Liu, B., Jiang, S., Xiao, X., Hecker, A., and Z. 1037 Despotovic, "Information Distribution in Autonomic 1038 Networking", draft-liu-anima-grasp-distribution-05 (work 1039 in progress), February 2018. 1041 Appendix A. Error Codes 1043 This Appendix lists the error codes defined so far, with suggested 1044 symbolic names and corresponding descriptive strings in English. It 1045 is expected that complete API implementations will provide for 1046 localisation of these descriptive strings, and that additional error 1047 codes will be needed according to implementation details. 1049 ok 0 "OK" 1050 declined 1 "Declined" 1051 noReply 2 "No reply" 1052 unspec 3 "Unspecified error" 1053 ASAfull 4 "ASA registry full" 1054 dupASA 5 "Duplicate ASA name" 1055 noASA 6 "ASA not registered" 1056 notYourASA 7 "ASA registered but not by you" 1057 notBoth 8 "Objective cannot support both negotiation 1058 and synchronization" 1059 notDry 9 "Dry-run allowed only with negotiation" 1060 notOverlap 10 "Overlap not supported by this implementation" 1061 objFull 11 "Objective registry full" 1062 objReg 12 "Objective already registered" 1063 notYourObj 13 "Objective not registered by this ASA" 1064 notObj 14 "Objective not found" 1065 notNeg 15 "Objective not negotiable" 1066 noSecurity 16 "No security" 1067 noDiscReply 17 "No reply to discovery" 1068 sockErrNegRq 18 "Socket error sending negotiation request" 1069 noSession 19 "No session" 1070 noSocket 20 "No socket" 1071 loopExhausted 21 "Loop count exhausted" 1072 sockErrNegStep 22 "Socket error sending negotiation step" 1073 noPeer 23 "No negotiation peer" 1074 CBORfail 24 "CBOR decode failure" 1075 invalidNeg 25 "Invalid Negotiate message" 1076 invalidEnd 26 "Invalid end message" 1077 noNegReply 27 "No reply to negotiation step" 1078 noValidStep 28 "No valid reply to negotiation step" 1079 sockErrWait 29 "Socket error sending wait message" 1080 sockErrEnd 30 "Socket error sending end message" 1081 IDclash 31 "Incoming request Session ID clash" 1082 notSynch 32 "Not a synchronization objective" 1083 notFloodDisc 33 "Not flooded and no reply to discovery" 1084 sockErrSynRq 34 "Socket error sending synch request" 1085 noListener 35 "No synch listener" 1086 noSynchReply 36 "No reply to synchronization request" 1087 noValidSynch 37 "No valid reply to synchronization request" 1088 invalidLoc 38 "Invalid locator" 1090 Appendix B. Change log [RFC Editor: Please remove] 1092 draft-ietf-anima-grasp-api-01, 2018-03-03: 1094 Editorial updates 1096 draft-ietf-anima-grasp-api-00, 2017-12-23: 1098 WG adoption 1100 Editorial improvements. 1102 draft-liu-anima-grasp-api-06, 2017-11-24: 1104 Improved description of event-loop model. 1106 Changed intended status to Informational. 1108 Editorial improvements. 1110 draft-liu-anima-grasp-api-05, 2017-10-02: 1112 Added send_invalid() 1114 draft-liu-anima-grasp-api-04, 2017-06-30: 1116 Noted that simple nodes might not include the API. 1118 Minor clarifications. 1120 draft-liu-anima-grasp-api-03, 2017-02-13: 1122 Changed error return to integers. 1124 Required all implementations to accept objective values in CBOR. 1126 Added non-blocking alternatives. 1128 draft-liu-anima-grasp-api-02, 2016-12-17: 1130 Updated for draft-ietf-anima-grasp-09 1132 draft-liu-anima-grasp-api-02, 2016-09-30: 1134 Added items for draft-ietf-anima-grasp-07 1136 Editorial corrections 1137 draft-liu-anima-grasp-api-01, 2016-06-24: 1139 Updated for draft-ietf-anima-grasp-05 1141 Editorial corrections 1143 draft-liu-anima-grasp-api-00, 2016-04-04: 1145 Initial version 1147 Authors' Addresses 1149 Brian Carpenter 1150 Department of Computer Science 1151 University of Auckland 1152 PB 92019 1153 Auckland 1142 1154 New Zealand 1156 Email: brian.e.carpenter@gmail.com 1158 Bing Liu (editor) 1159 Huawei Technologies 1160 Q22, Huawei Campus 1161 No.156 Beiqing Road 1162 Hai-Dian District, Beijing 100095 1163 P.R. China 1165 Email: leo.liubing@huawei.com 1167 Wendong Wang 1168 BUPT University 1169 Beijing University of Posts & Telecom. 1170 No.10 Xitucheng Road 1171 Hai-Dian District, Beijing 100876 1172 P.R. China 1174 Email: wdwang@bupt.edu.cn 1175 Xiangyang Gong 1176 BUPT University 1177 Beijing University of Posts & Telecom. 1178 No.10 Xitucheng Road 1179 Hai-Dian District, Beijing 100876 1180 P.R. China 1182 Email: xygong@bupt.edu.cn