idnits 2.17.1 draft-liu-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 (February 13, 2017) is 2629 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-15) exists of draft-ietf-anima-grasp-09 == Outdated reference: A later version (-10) exists of draft-ietf-anima-reference-model-02 == Outdated reference: A later version (-13) exists of draft-liu-anima-grasp-distribution-03 -- Obsolete informational reference (is this intentional?): RFC 7749 (Obsoleted by RFC 7991) Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). 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: Standards Track B. Liu, Ed. 5 Expires: August 17, 2017 Huawei Technologies 6 W. Wang 7 X. Gong 8 BUPT University 9 February 13, 2017 11 Generic Autonomic Signaling Protocol Application Program Interface 12 (GRASP API) 13 draft-liu-anima-grasp-api-03 15 Abstract 17 This document specifies the application programming interface (API) 18 of the Generic Autonomic Signaling Protocol (GRASP). The API is used 19 for Autonomic Service Agents (ASA) calling the GRASP protocol module 20 to exchange autonomic network messages with other ASAs. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on August 17, 2017. 39 Copyright Notice 41 Copyright (c) 2017 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. GRASP API for ASA . . . . . . . . . . . . . . . . . . . . . . 3 58 2.1. Design Principles . . . . . . . . . . . . . . . . . . . . 3 59 2.2. API definition . . . . . . . . . . . . . . . . . . . . . 4 60 2.2.1. Parameters and data structures . . . . . . . . . . . 4 61 2.2.2. Registration . . . . . . . . . . . . . . . . . . . . 7 62 2.2.3. Discovery . . . . . . . . . . . . . . . . . . . . . . 9 63 2.2.4. Negotiation . . . . . . . . . . . . . . . . . . . . . 10 64 2.2.5. Synchronization and Flooding . . . . . . . . . . . . 14 65 3. Non-threaded Implementations . . . . . . . . . . . . . . . . 18 66 4. Example Logic Flows . . . . . . . . . . . . . . . . . . . . . 18 67 5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 68 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 69 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 70 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 71 8.1. Normative References . . . . . . . . . . . . . . . . . . 19 72 8.2. Informative References . . . . . . . . . . . . . . . . . 19 73 Appendix A. Error Codes . . . . . . . . . . . . . . . . . . . . 19 74 Appendix B. Change log [RFC Editor: Please remove] . . . . . . . 20 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 77 1. Introduction 79 As defined in [I-D.ietf-anima-reference-model], the Autonomic Service 80 Agent (ASA) is the atomic entity of an autonomic function; and it is 81 instantiated on autonomic nodes. When ASAs communicate with each 82 other, they should use the Generic Autonomic Signaling Protocol 83 (GRASP) [I-D.ietf-anima-grasp]. 85 As the following figure shows, GRASP could contain two major sub- 86 layers. The bottom is the GRASP base protocol module, which is only 87 responsible for sending and receiving GRASP messages and maintaining 88 shared data structures. The upper layer is some extended functions 89 based upon GRASP basic protocol. For example, 90 [I-D.liu-anima-grasp-distribution] describes a possible extended 91 function. 93 It is desirable that ASAs can be designed as portable user-space 94 programs using a portable API. In many operating systems, the GRASP 95 module will therefore be split into two layers, one being a library 96 that provides the API and the other being core code containing common 97 components such as multicast handling and the discovery cache. The 98 details of this are system-dependent. 100 +----+ +----+ 101 |ASAs| |ASAs| 102 +----+ +----+ 103 | | 104 | GRASP Function API | 105 | | 106 +------------------+ |GRASP API 107 | GRASP Extended | | 108 | Function Modules | | 109 +------------------+ | 110 +------------------------------------------+ 111 | GRASP Library | 112 | GRASP Module - - - - - - - - - - - - - -| 113 | GRASP Core | 114 +------------------------------------------+ 116 Both the GRASP base module and the extended function modules should 117 be available to the ASAs. Thus, there needs to be two sub-sets of 118 API. However, since the extended functions are expected to be added 119 in an incremental manner, it is inappropriate to define the function 120 APIs in a single document. This document only defines the base GRASP 121 API. 123 2. GRASP API for ASA 125 2.1. Design Principles 127 The assumption of this document is that any Autonomic Service Agent 128 (ASA) needs to call a GRASP module that handles protocol details 129 (security, sending and listening for GRASP messages, waiting, caching 130 discovery results, negotiation looping, sending and receiving 131 sychronization data, etc.) but understands nothing about individual 132 objectives. So this is a high level abstract API for use by ASAs. 133 Individual language bindings should be defined in separate documents. 135 An assumption of this API is that ASAs may fall into various classes: 137 o ASAs that only use GRASP for discovery purposes. 139 o ASAs that use GRASP negotiation but only as an initiator (client). 141 o ASAs that use GRASP negotiation but only as a responder. 143 o ASAs that use GRASP negotiation as an initiator or responder. 145 o ASAs that use GRASP synchronization but only as an initiator 146 (recipient). 148 o ASAs that use GRASP synchronization but only as a responder and/or 149 flooder. 151 o ASAs that use GRASP synchronization as an initiator, responder 152 and/or flooder. 154 The API also assumes that one ASA may support multiple objectives. 155 Nothing prevents an ASA from supporting some objectives for 156 synchronization and others for negotiation. 158 The API design assumes that the operating system and programming 159 language provide a convenient mechanism for multi-threaded code. A 160 solution in case this does not apply is described in Section 3. 162 This is a preliminary version. Two particular gaps exist: 164 o Authorization of ASAs is out of scope. 166 o The Rapid mode of GRASP is not supported. 168 2.2. API definition 170 2.2.1. Parameters and data structures 172 This section describes parameters and data structures uaed in 173 multiple API calls. 175 2.2.1.1. Errorcode 177 All functions in the API have an unsigned 'errorcode' integer as 178 their return value (the first returned value in languages that allow 179 multiple returned parameters). An errorcode of zero indicates 180 success. Any other value indicates failure of some kind. The first 181 three errorcodes have special importance: 183 1. Declined: used to indicate that the other end has sent a GRASP 184 Negotiation End message (M_END) with a Decline option 185 (O_DECLINE). 187 2. No reply: used in non-blocking calls to indicate that the other 188 end has sent no reply so far (see Section 3). 190 3. Unspecified error: used when no more specific error code applies. 192 Appendix A gives a full list of currently defined error codes. 194 2.2.1.2. Timeout 196 Wherever a 'timeout' parameter appears, it is an integer expressed in 197 milliseconds. If it is zero, the GRASP default timeout 198 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]) will apply. If no 199 response is received before the timeout expires, the call will fail 200 unless otherwise noted. 202 2.2.1.3. Objective 204 An 'objective' parameter is a data structure with the following 205 components: 207 o name (UTF-8 string) - the objective's name 209 o neg (Boolean) - True if objective supports negotiation (default 210 False) 212 o synch (Boolean) - True if objective supports synchronization 213 (default False) 215 o dry (Boolean) - True if objective also supports dry-run 216 synchronization (default False) 218 * Note 1: All objectives are assumed to support discovery, so 219 there is no Boolean for that. 221 * Note 2: Only one of 'synch' or 'neg' may be True. 223 * Note 3: 'dry' must not be True unless 'neg' is also True. 225 o loop_count (integer) - Limit on negotiation steps etc. (default 226 GRASP_DEF_LOOPCT, see [I-D.ietf-anima-grasp]) 228 o value - a specific data structure expressing the value of the 229 objective. The format is language dependent, with the constraint 230 that it can be validly represented in CBOR (default integer = 0). 232 An essential requirement for all language mappings and all 233 implementations is that, regardless of what other options exist 234 for a language-specific represenation of the value, there is 235 always an option to use a CBOR byte string as the value. The API 236 will then wrap this byte string in CBOR Tag 24 for transmission 237 via GRASP, and unwrap it after reception. 239 An example data structure definition for an objective in the C 240 language is: 242 typedef struct { 243 char *name; 244 bool neg; 245 bool dry; 246 bool synch; 247 int loop_count; 248 int value_size; // size of value 249 uint8_t cbor_value[]; // CBOR bytestring of value 250 } objective; 252 2.2.1.4. ASA_locator 254 An 'ASA_locator' parameter is a data structure with the following 255 contents: 257 o locator - The actual locator, either an IP address or an ASCII 258 string. 260 o ifi (integer) - The interface identifier index via which this was 261 discovered - probably no use to a normal ASA 263 o expire (system dependent type) - The time on the local system 264 clock when this locator will expire from the cache 266 o is_ipaddress (Boolean) - True if the locator is an IP address 268 o is_fqdn (Boolean) - True if the locator is an FQDN 270 o is_uri (Boolean) - True if the locator is a URI 272 o diverted (Boolean) - True if the locator was discovered via a 273 Divert option 275 o protocol (integer) - Applicable transport protocol (IPPROTO_TCP or 276 IPPROTO_UDP) 278 o port (integer) - Applicable port number 280 2.2.1.5. Tagged_objective 282 A 'tagged_objective' parameter is a data structure with the following 283 contents: 285 o objective - An objective 287 o locator - The ASA_locator associated with the objective, or a null 288 value. 290 2.2.1.6. Asa_nonce 292 In most calls, an 'asa_nonce' parameter is required. It is generated 293 when an ASA registers with GRASP, and any call in which an invalid 294 nonce is presented will fail. It is an up to 32-bit opaque value 295 (for example represented as a uint32_t, depending on the language). 296 It should be unpredictable; a possible implementation is to use the 297 same mechanism that GRASP uses to generate Session IDs 298 [I-D.ietf-anima-grasp]. Another possible implementation is to hash 299 the name of the ASA with a locally defined secret key. 301 2.2.1.7. Session_nonce 303 In some calls, a 'session_nonce' parameter is required. This is an 304 opaque data structure as far as the ASA is concerned, used to 305 identify calls to the API as belonging to a specific GRASP session. 306 In fully threaded implementations this parameter might not be needed, 307 but it is included to act as a session handle if necessary. It will 308 also allow GRASP to detect and ignore malicious calls or calls from 309 timed-out sessions. A possible implementation is to form the nonce 310 from the underlying GRASP Session ID and the source address of the 311 session. 313 2.2.2. Registration 315 These functions are used to register an ASA and the objectives that 316 it supports with the GRASP module. If an authorization model is 317 added to GRASP, it would be added here. 319 o register_asa() 321 Input parameter: 323 name of the ASA (UTF-8 string) 325 Return parameters: 327 errorcode (integer) 329 asa_nonce (integer) (if successful) 331 This initialises state in the GRASP module for the calling 332 entity (the ASA). In the case of success, an 'asa_nonce' is 333 returned which the ASA must present in all subsequent calls. 334 In the case of failure, the ASA has not been authorized and 335 cannot operate. 337 o deregister_asa() 338 Input parameters: 340 asa_nonce (integer) 342 name of the ASA (UTF-8 string) 344 Return parameter: 346 errorcode (integer) 348 This removes all state in the GRASP module for the calling 349 entity (the ASA), and deregisters any objectives it has 350 registered. Note that these actions must also happen 351 automatically if an ASA crashes. 353 Note - the ASA name is strictly speaking redundant in this 354 call, but is present for clarity. 356 o register_objective() 358 Input parameters: 360 asa_nonce (integer) 362 objective (structure) 364 ttl (integer - default GRASP_DEF_TIMEOUT) 366 discoverable (Boolean - default False) 368 overlap (Boolean - default False) 370 local (Boolean - default False) 372 Return parameter: 374 errorcode (integer) 376 This registers an objective that this ASA supports and may 377 modify. The 'objective' becomes a candidate for discovery. 378 However, discovery responses should not be enabled until the 379 ASA calls listen_negotiate() or listen_synchronize(), showing 380 that it is able to act as a responder. The ASA may negotiate 381 the objective or send synchronization or flood data. 382 Registration is not needed if the ASA only wants to receive 383 synchronization or flood data for the objective concerned. 385 The 'ttl' parameter is the valid lifetime (time to live) in 386 milliseconds of any discovery response for this objective. The 387 default value should be the GRASP default timeout 388 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]). 390 If the optional parameter 'discoverable' is True, the objective 391 is immediately discoverable. This is intended for objectives 392 that are only defined for GRASP discovery, and which do not 393 support negotiation or synchronization. 395 If the optional parameter 'overlap' is True, more than one ASA 396 may register this objective in the same GRASP instance. 398 If the optional parameter 'local' is True, discovery must 399 return a link-local address. This feature is for objectives 400 that must be restricted to the local link. 402 This call may be repeated for multiple objectives. 404 o deregister_objective() 406 Input parameters: 408 asa_nonce (integer) 410 objective (structure) 412 Return parameter: 414 errorcode (integer) 416 The 'objective' must have been registered by the calling ASA; 417 if not, this call fails. Otherwise, it removes all state in 418 the GRASP module for the given objective. 420 2.2.3. Discovery 422 o discover() 424 Input parameters: 426 asa_nonce (integer) 428 objective (structure) 430 timeout (integer) 432 flush (Boolean - default False) 434 Return parameters: 436 errorcode (integer) 438 locator_list (structure) 440 This returns a list of discovered 'ASA_locator's for the given 441 objective. If the optional parameter 'flush' is True, any 442 locally cached locators for the objective are deleted first. 443 Otherwise, they are returned immediately. If not, GRASP 444 discovery is performed, and all results obtained before the 445 timeout expires are returned. If no results are obtained, an 446 empty list is returned after the timeout. That is not an error 447 condition. 449 This should be called in a separate thread if asynchronous 450 operation is required. 452 2.2.4. Negotiation 454 o request_negotiate() 456 Input parameters: 458 asa_nonce (integer) 460 objective (structure) 462 peer (ASA_locator) 464 timeout (integer) 466 Return parameters: 468 errorcode (integer) 470 session_nonce (structure) (if successful) 472 proffered_objective (structure) (if successful) 474 reason (string) (if negotiation declined) 476 This function opens a negotiation session. The 'objective' 477 parameter must include the requested value, and its loop count 478 should be set to a suitable value by the ASA. If not, the 479 GRASP default will apply. 481 Note that a given negotiation session may or may not be a dry- 482 run negotiation; the two modes must not be mixed in a single 483 session. 485 The 'peer' parameter is the target node; it must be an 486 'ASA_locator' as returned by discover(). If the peer is null, 487 GRASP discovery is performed first. 489 If the 'errorcode' return parameter is 0, the negotiation has 490 successfully started. There are then two cases: 492 1. The 'session_nonce' parameter is null. In this case the 493 negotiation has succeeded (the peer has accepted the 494 request). The returned 'proffered_objective' contains the 495 value accepted by the peer. 497 2. The 'session_nonce' parameter is not null. In this case 498 negotiation must continue. The returned 499 'proffered_objective' contains the first value proffered by 500 the negotiation peer. Note that this instance of the 501 objective must be used in the subsequent negotiation call 502 because it also contains the current loop count. The 503 'session_nonce' must be presented in all subsequent 504 negotiation steps. 506 This function must be followed by calls to 'negotiate_step' 507 and/or 'negotiate_wait' and/or 'end_negotiate' until the 508 negotiation ends. 'request_negotiate' may then be called 509 again to start a new negotation. 511 If the 'errorcode' parameter has the value 1 ('declined'), the 512 negotiation has been declined by the peer (M_END and O_DECLINE 513 features of GRASP). The 'reason' string is then available for 514 information and diagnostic use, but it may be a null string. 515 For this and any other error code, an exponential backoff is 516 recommended before any retry. 518 This should be called in a separate thread if asynchronous 519 operation is required. 521 Special note for the ACP infrastructure ASA: It is likely that 522 this ASA will need to discover and negotiate with its peers in 523 each of its on-link neighbors. It will therefore need to know 524 not only the link-local IP address but also the physical 525 interface and transport port for connecting to each neighbor. 526 One implementation approach to this is to include these details 527 in the 'session_nonce' data structure, which is opaque to 528 normal ASAs. 530 o listen_negotiate() 532 Input parameters: 534 asa_nonce (integer) 536 objective (structure) 538 Return parameters: 540 errorcode (integer) 542 session_nonce (structure) (if successful) 544 requested_objective (structure) (if successful) 546 This function instructs GRASP to listen for negotiation 547 requests for the given 'objective'. It also enables discovery 548 responses for the objective. It will block waiting for an 549 incoming request, so should be called in a separate thread if 550 asynchronous operation is required. Unless there is an 551 unexpected failure, this call only returns after an incoming 552 negotiation request. When it does so, 'requested_objective' 553 contains the first value requested by the negotiation peer. 554 Note that this instance of the objective must be used in the 555 subsequent negotiation call because it also contains the 556 current loop count. The 'session_nonce' must be presented in 557 all subsequent negotiation steps. 559 This function must be followed by calls to 'negotiate_step' 560 and/or 'negotiate_wait' and/or 'end_negotiate' until the 561 negotiation ends. 'listen_negotiate' may then be called again 562 to await a new negotation. 564 If an ASA is capable of handling multiple negotiations 565 simultaneously, it may call 'listen_negotiate' simultaneously 566 from multiple threads. The API and GRASP implementation must 567 support re-entrant use of the listening state and the 568 negotiation calls. Simultaneous sessions will be distinguished 569 by the threads themselves, the GRASP Session IDs, and the 570 underlying unicast transport sockets. 572 o stop_listen_negotiate() 574 Input parameters: 576 asa_nonce (integer) 577 objective (structure) 579 Return parameter: 581 errorcode (integer) 583 Instructs GRASP to stop listening for negotiation requests for 584 the given objective, i.e., cancels 'listen_negotiate'. Of 585 course, it must be called from a different thread. 587 o negotiate_step() 589 Input parameters: 591 asa_nonce (integer) 593 session_nonce (structure) 595 objective (structure) 597 timeout (integer) 599 Return parameters: 601 Exactly as for 'request_negotiate' 603 Executes the next negotation step with the peer. The 604 'objective' parameter contains the next value being proffered 605 by the ASA in this step. 607 o negotiate_wait() 609 Input parameters: 611 asa_nonce (integer) 613 session_nonce (structure) 615 timeout (integer) 617 Return parameters: 619 errorcode (integer) 621 Delay negotiation session by 'timeout' milliseconds. 623 o end_negotiate() 624 Input parameters: 626 asa_nonce (integer) 628 session_nonce (structure) 630 reply (Boolean) 632 reason (UTF-8 string) 634 Return parameters: 636 errorcode (integer) 638 End the negotiation session. 640 'reply' = True for accept (successful negotiation), False for 641 decline (failed negotiation). 643 'reason' = optional string describing reason for decline. 645 2.2.5. Synchronization and Flooding 647 o synchronize() 649 Input parameters: 651 asa_nonce (integer) 653 objective (structure) 655 peer (ASA_locator) 657 timeout (integer) 659 Return parameters: 661 errorcode (integer) 663 objective (structure) (if successful) 665 This call requests the synchronized value of the given 666 'objective'. 668 Since this is essentially a read operation, any ASA can do it. 669 Therefore the API checks that the ASA is registered but the 670 objective doesn't need to be registered by the calling ASA. 672 If the objective was already flooded, the flooded value is 673 returned immediately in the 'result' parameter. In this case, 674 the 'source' and 'timeout' are ignored. 676 Otherwise, synchronization with a discovered ASA is performed. 677 The 'peer' parameter is an 'ASA_locator' as returned by 678 discover(). If 'peer' is null, GRASP discovery is performed 679 first. 681 This call should be repeated whenever the latest value is 682 needed. 684 Call in a separate thread if asynchronous operation is 685 required. 687 Since this is essentially a read operation, any ASA can use it. 688 Therefore GRASP checks that the calling ASA is registered but 689 the objective doesn't need to be registered by the calling ASA. 691 In the case of failure, an exponential backoff is recommended 692 before retrying. 694 o listen_synchronize() 696 Input parameters: 698 asa_nonce (integer) 700 objective (structure) 702 Return parameters: 704 errorcode (integer) 706 This instructs GRASP to listen for synchronization requests for 707 the given objective, and to respond with the value given in the 708 'objective' parameter. It also enables discovery responses for 709 the objective. 711 This call is non-blocking and may be repeated whenever the 712 value changes. 714 o stop_listen_synchronize() 716 Input parameters: 718 asa_nonce (integer) 719 objective (structure) 721 Return parameters: 723 errorcode (integer) 725 This call instructs GRASP to stop listening for synchronization 726 requests for the given 'objective', i.e. it cancels a previous 727 listen_synchronize. 729 o flood() 731 Input parameters: 733 asa_nonce (integer) 735 ttl (integer) 737 tagged_objective_list (structure) 739 Return parameters: 741 errorcode (integer) 743 This call instructs GRASP to flood the given synchronization 744 objective(s) and their value(s) and associated locator(s) to 745 all GRASP nodes. 747 The 'ttl' parameter is the valid lifetime (time to live) of the 748 flooded data in milliseconds (0 = infinity) 750 The 'tagged_objective_list' parameter is a list of one or more 751 'tagged_objective' couplets. The 'locator' parameter that tags 752 each objective is normally null but may be a valid 753 'ASA_locator'. Infrastructure ASAs needing to flood an 754 {address, protocol, port} 3-tuple with an objective create an 755 ASA_locator object to do so. If the IP address in that locator 756 is the unspecified address ('::') it is replaced by the link- 757 local address of the sending node in each copy of the flood 758 multicast, which will be forced to have a loop count of 1. 759 This feature is for objectives that must be restricted to the 760 local link. 762 The function checks that the ASA registered each objective. 764 This call may be repeated whenever any value changes. 766 o get_flood() 767 Input parameters: 769 asa_nonce (integer) 771 objective (structure) 773 Return parameters: 775 errorcode (integer) 777 tagged_objective_list (structure) (if successful) 779 This call instructs GRASP to return the given synchronization 780 objective if it has been flooded and its lifetime has not 781 expired. 783 Since this is essentially a read operation, any ASA can do it. 784 Therefore the API checks that the ASA is registered but the 785 objective doesn't need to be registered by the calling ASA. 787 The 'tagged_objective_list' parameter is a list of 788 'tagged_objective' couplets, each one being a copy of the 789 flooded objective and a coresponding locator. Thus if the same 790 objective has been flooded by multiple ASAs, the recipient can 791 distinguish the copies. 793 Note that this call is for advanced ASAs. In a simple case, an 794 ASA can simply call synchronize() in order to get a valid 795 flooded objective. 797 o expire_flood() 799 Input parameters: 801 asa_nonce (integer) 803 tagged_objective (structure) 805 Return parameters: 807 errorcode (integer) 809 This is a call that can only be used after a preceding call to 810 get_flood() by an ASA that is capable of deciding that the 811 flooded value is stale or invalid. Use with care. 813 The 'tagged_objective' parameter is the one to be expired. 815 3. Non-threaded Implementations 817 If an operating system or language does not provide convenient 818 support for multi-threading, ASAs may need to be written using a 819 polling or 'event loop' structure, whereby a main loop supports 820 multiple GRASP sessions in parallel by repeatedly checking each one 821 for a change of state. To facilitate this, an API implementation may 822 provide alternative versions of all the functions that involve 823 blocking and queueing. In the calls, the error code 2 ("noReply") 824 will be returned by each call instead of blocking, until such time as 825 the event for which it is waiting has been queued. Thus, for 826 example, request_negotiate would return "noReply" instead of waiting 827 until an incoming request or timeout arrived. The calls to which 828 this applies are: 830 discover() 832 request_negotiate() 834 negotiate_step() 836 synchronize() 838 listen_negotiate() 840 4. Example Logic Flows 842 TBD 844 (Until this section is written, some Python examples can be found at 845 , 846 , and 847 .) 849 5. Security Considerations 851 Security issues for the GRASP protocol are discussed in 852 [I-D.ietf-anima-grasp]. Authorization of ASAs is a subject for 853 future study. 855 The 'asa_nonce' parameter is used in the API as a first line of 856 defence against a malware process attempting to imitate a 857 legitimately registered ASA. The 'session_nonce' parameter is used 858 in the API as a first line of defence against a malware process 859 attempting to hijack a GRASP session. 861 6. IANA Considerations 863 This does not need IANA assignment. 865 7. Acknowledgements 867 This document was produced using the xml2rfc tool [RFC7749]. 869 Excellent suggestions were made by Michael Richardson. 871 8. References 873 8.1. Normative References 875 [I-D.ietf-anima-grasp] 876 Bormann, C., Carpenter, B., and B. Liu, "A Generic 877 Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- 878 grasp-09 (work in progress), December 2016. 880 8.2. Informative References 882 [I-D.ietf-anima-reference-model] 883 Behringer, M., Carpenter, B., Eckert, T., Ciavaglia, L., 884 Pierre, P., Liu, B., Nobre, J., and J. Strassner, "A 885 Reference Model for Autonomic Networking", draft-ietf- 886 anima-reference-model-02 (work in progress), July 2016. 888 [I-D.liu-anima-grasp-distribution] 889 Liu, B. and S. Jiang, "Information Distribution over 890 GRASP", draft-liu-anima-grasp-distribution-03 (work in 891 progress), October 2016. 893 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 894 RFC 7749, DOI 10.17487/RFC7749, February 2016, 895 . 897 Appendix A. Error Codes 899 This Appendix lists the error codes defined so far, with suggested 900 symbolic names and corresponding descriptive strings in English. It 901 is expected that complete API implementations will provide for 902 localisation of these descriptive strings. 904 ok 0 "OK" 905 declined 1 "Declined" 906 noReply 2 "No reply" 907 unspec 3 "Unspecified error" 908 ASAfull 4 "ASA registry full" 909 dupASA 5 "Duplicate ASA name" 910 noASA 6 "ASA not registered" 911 notYourASA 7 "ASA registered but not by you" 912 notBoth 8 "Objective cannot support both negotiation 913 and synchronization" 914 notDry 9 "Dry-run allowed only with negotiation" 915 notOverlap 10 "Overlap not supported by this implementation" 916 objFull 11 "Objective registry full" 917 objReg 12 "Objective already registered" 918 notYourObj 13 "Objective not registered by this ASA" 919 notObj 14 "Objective not found" 920 notNeg 15 "Objective not negotiable" 921 noSecurity 16 "No security" 922 noDiscReply 17 "No reply to discovery" 923 sockErrNegRq 18 "Socket error sending negotiation request" 924 noSession 19 "No session" 925 noSocket 20 "No socket" 926 loopExhausted 21 "Loop count exhausted" 927 sockErrNegStep 22 "Socket error sending negotiation step" 928 noPeer 23 "No negotiation peer" 929 CBORfail 24 "CBOR decode failure" 930 invalidNeg 25 "Invalid Negotiate message" 931 invalidEnd 26 "Invalid end message" 932 noNegReply 27 "No reply to negotiation step" 933 noValidStep 28 "No valid reply to negotiation step" 934 sockErrWait 29 "Socket error sending wait message" 935 sockErrEnd 30 "Socket error sending end message" 936 IDclash 31 "Incoming request Session ID clash" 937 notSynch 32 "Not a synchronization objective" 938 notFloodDisc 33 "Not flooded and no reply to discovery" 939 sockErrSynRq 34 "Socket error sending synch request" 940 noListener 35 "No synch listener" 941 noSynchReply 36 "No reply to synchronization request" 942 noValidSynch 37 "No valid reply to synchronization request" 943 invalidLoc 38 "Invalid locator" 945 Appendix B. Change log [RFC Editor: Please remove] 947 draft-liu-anima-grasp-api-03, 2017-02-13: 949 Changed error return to integers. 951 Required all implementations to accept objective values in CBOR. 953 Added non-blocking alternatives. 955 draft-liu-anima-grasp-api-02, 2016-12-17: 957 Updated for draft-ietf-anima-grasp-09 959 draft-liu-anima-grasp-api-02, 2016-09-30: 961 Added items for draft-ietf-anima-grasp-07 963 Editorial corrections 965 draft-liu-anima-grasp-api-01, 2016-06-24: 967 Updated for draft-ietf-anima-grasp-05 969 Editorial corrections 971 draft-liu-anima-grasp-api-00, 2016-04-04: 973 Initial version 975 Authors' Addresses 977 Brian Carpenter 978 Department of Computer Science 979 University of Auckland 980 PB 92019 981 Auckland 1142 982 New Zealand 984 Email: brian.e.carpenter@gmail.com 986 Bing Liu (editor) 987 Huawei Technologies 988 Q22, Huawei Campus 989 No.156 Beiqing Road 990 Hai-Dian District, Beijing 100095 991 P.R. China 993 Email: leo.liubing@huawei.com 994 Wendong Wang 995 BUPT University 996 Beijing University of Posts & Telecom. 997 No.10 Xitucheng Road 998 Hai-Dian District, Beijing 100876 999 P.R. China 1001 Email: wdwang@bupt.edu.cn 1003 Xiangyang Gong 1004 BUPT University 1005 Beijing University of Posts & Telecom. 1006 No.10 Xitucheng Road 1007 Hai-Dian District, Beijing 100876 1008 P.R. China 1010 Email: xygong@bupt.edu.cn