idnits 2.17.1 draft-liu-anima-grasp-api-04.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 12 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 30, 2017) is 2463 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-13 == Outdated reference: A later version (-30) exists of draft-ietf-anima-autonomic-control-plane-06 == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-06 == Outdated reference: A later version (-10) exists of draft-ietf-anima-reference-model-03 == Outdated reference: A later version (-13) exists of draft-liu-anima-grasp-distribution-04 -- Obsolete informational reference (is this intentional?): RFC 7749 (Obsoleted by RFC 7991) Summary: 1 error (**), 0 flaws (~~), 6 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: January 1, 2018 Huawei Technologies 6 W. Wang 7 X. Gong 8 BUPT University 9 June 30, 2017 11 Generic Autonomic Signaling Protocol Application Program Interface 12 (GRASP API) 13 draft-liu-anima-grasp-api-04 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 January 1, 2018. 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 . . . . . . . . . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . . . . . . 19 67 5. Security Considerations . . . . . . . . . . . . . . . . . . . 19 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 . . . . . . . . . . . . . . . . . . . . 20 74 Appendix B. Change log [RFC Editor: Please remove] . . . . . . . 21 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 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 Note that a very simple autonomic node might contain only a single 124 ASA in addition to the autonomic infrastructure components described 125 in [I-D.ietf-anima-bootstrapping-keyinfra] and 126 [I-D.ietf-anima-autonomic-control-plane]. Such a node might directly 127 integrate GRASP in its autonomic code and therefore not require this 128 API to be installed. 130 2. GRASP API for ASA 132 2.1. Design Principles 134 The assumption of this document is that any Autonomic Service Agent 135 (ASA) needs to call a GRASP module that handles protocol details 136 (security, sending and listening for GRASP messages, waiting, caching 137 discovery results, negotiation looping, sending and receiving 138 sychronization data, etc.) but understands nothing about individual 139 objectives. So this is a high level abstract API for use by ASAs. 140 Individual language bindings should be defined in separate documents. 142 An assumption of this API is that ASAs may fall into various classes: 144 o ASAs that only use GRASP for discovery purposes. 146 o ASAs that use GRASP negotiation but only as an initiator (client). 148 o ASAs that use GRASP negotiation but only as a responder. 150 o ASAs that use GRASP negotiation as an initiator or responder. 152 o ASAs that use GRASP synchronization but only as an initiator 153 (recipient). 155 o ASAs that use GRASP synchronization but only as a responder and/or 156 flooder. 158 o ASAs that use GRASP synchronization as an initiator, responder 159 and/or flooder. 161 The API also assumes that one ASA may support multiple objectives. 162 Nothing prevents an ASA from supporting some objectives for 163 synchronization and others for negotiation. 165 The API design assumes that the operating system and programming 166 language provide a convenient mechanism for multi-threaded code. A 167 solution in case this does not apply is described in Section 3. 169 This is a preliminary version. Two particular gaps exist: 171 o Authorization of ASAs is out of scope. 173 o The Rapid mode of GRASP is not supported. 175 2.2. API definition 177 2.2.1. Parameters and data structures 179 This section describes parameters and data structures uaed in 180 multiple API calls. 182 2.2.1.1. Errorcode 184 All functions in the API have an unsigned 'errorcode' integer as 185 their return value (the first returned value in languages that allow 186 multiple returned parameters). An errorcode of zero indicates 187 success. Any other value indicates failure of some kind. The first 188 three errorcodes have special importance: 190 1. Declined: used to indicate that the other end has sent a GRASP 191 Negotiation End message (M_END) with a Decline option 192 (O_DECLINE). 194 2. No reply: used in non-blocking calls to indicate that the other 195 end has sent no reply so far (see Section 3). 197 3. Unspecified error: used when no more specific error code applies. 199 Appendix A gives a full list of currently defined error codes. 201 2.2.1.2. Timeout 203 Wherever a 'timeout' parameter appears, it is an integer expressed in 204 milliseconds. If it is zero, the GRASP default timeout 205 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]) will apply. If no 206 response is received before the timeout expires, the call will fail 207 unless otherwise noted. 209 2.2.1.3. Objective 211 An 'objective' parameter is a data structure with the following 212 components: 214 o name (UTF-8 string) - the objective's name 216 o neg (Boolean) - True if objective supports negotiation (default 217 False) 219 o synch (Boolean) - True if objective supports synchronization 220 (default False) 222 o dry (Boolean) - True if objective also supports dry-run 223 synchronization (default False) 225 * Note 1: All objectives are assumed to support discovery, so 226 there is no Boolean for that. 228 * Note 2: Only one of 'synch' or 'neg' may be True. 230 * Note 3: 'dry' must not be True unless 'neg' is also True. 232 o loop_count (integer) - Limit on negotiation steps etc. (default 233 GRASP_DEF_LOOPCT, see [I-D.ietf-anima-grasp]) 235 o value - a specific data structure expressing the value of the 236 objective. The format is language dependent, with the constraint 237 that it can be validly represented in CBOR (default integer = 0). 239 An essential requirement for all language mappings and all 240 implementations is that, regardless of what other options exist 241 for a language-specific represenation of the value, there is 242 always an option to use a CBOR byte string as the value. The API 243 will then wrap this byte string in CBOR Tag 24 for transmission 244 via GRASP, and unwrap it after reception. 246 An example data structure definition for an objective in the C 247 language is: 249 typedef struct { 250 char *name; 251 bool neg; 252 bool dry; 253 bool synch; 254 int loop_count; 255 int value_size; // size of value 256 uint8_t cbor_value[]; // CBOR bytestring of value 257 } objective; 259 An example data structure definition for an objective in the 260 Python language is: 262 class objective: 263 """A GRASP objective""" 264 def __init__(self, name): 265 self.name = name #Unique name, string 266 self.neg = False #Set True if objective supports negotiation 267 self.dry = False #Set True if objective also supports dry-run negotiation 268 self.synch = False #Set True if objective supports synch 269 self.loop_count = GRASP_DEF_LOOPCT #Default starting value 270 self.value = 0 #Place holder; any valid Python object 272 2.2.1.4. ASA_locator 274 An 'ASA_locator' parameter is a data structure with the following 275 contents: 277 o locator - The actual locator, either an IP address or an ASCII 278 string. 280 o ifi (integer) - The interface identifier index via which this was 281 discovered - probably no use to a normal ASA 283 o expire (system dependent type) - The time on the local system 284 clock when this locator will expire from the cache 286 o is_ipaddress (Boolean) - True if the locator is an IP address 288 o is_fqdn (Boolean) - True if the locator is an FQDN 289 o is_uri (Boolean) - True if the locator is a URI 291 o diverted (Boolean) - True if the locator was discovered via a 292 Divert option 294 o protocol (integer) - Applicable transport protocol (IPPROTO_TCP or 295 IPPROTO_UDP) 297 o port (integer) - Applicable port number 299 2.2.1.5. Tagged_objective 301 A 'tagged_objective' parameter is a data structure with the following 302 contents: 304 o objective - An objective 306 o locator - The ASA_locator associated with the objective, or a null 307 value. 309 2.2.1.6. Asa_nonce 311 In most calls, an 'asa_nonce' parameter is required. It is generated 312 when an ASA registers with GRASP, and any call in which an invalid 313 nonce is presented will fail. It is an up to 32-bit opaque value 314 (for example represented as a uint32_t, depending on the language). 315 It should be unpredictable; a possible implementation is to use the 316 same mechanism that GRASP uses to generate Session IDs 317 [I-D.ietf-anima-grasp]. Another possible implementation is to hash 318 the name of the ASA with a locally defined secret key. 320 2.2.1.7. Session_nonce 322 In some calls, a 'session_nonce' parameter is required. This is an 323 opaque data structure as far as the ASA is concerned, used to 324 identify calls to the API as belonging to a specific GRASP session. 325 In fully threaded implementations this parameter might not be needed, 326 but it is included to act as a session handle if necessary. It will 327 also allow GRASP to detect and ignore malicious calls or calls from 328 timed-out sessions. A possible implementation is to form the nonce 329 from the underlying GRASP Session ID and the source address of the 330 session. 332 2.2.2. Registration 334 These functions are used to register an ASA and the objectives that 335 it supports with the GRASP module. If an authorization model is 336 added to GRASP, it would be added here. 338 o register_asa() 340 Input parameter: 342 name of the ASA (UTF-8 string) 344 Return parameters: 346 errorcode (integer) 348 asa_nonce (integer) (if successful) 350 This initialises state in the GRASP module for the calling 351 entity (the ASA). In the case of success, an 'asa_nonce' is 352 returned which the ASA must present in all subsequent calls. 353 In the case of failure, the ASA has not been authorized and 354 cannot operate. 356 o deregister_asa() 358 Input parameters: 360 asa_nonce (integer) 362 name of the ASA (UTF-8 string) 364 Return parameter: 366 errorcode (integer) 368 This removes all state in the GRASP module for the calling 369 entity (the ASA), and deregisters any objectives it has 370 registered. Note that these actions must also happen 371 automatically if an ASA crashes. 373 Note - the ASA name is strictly speaking redundant in this 374 call, but is present for clarity. 376 o register_objective() 378 Input parameters: 380 asa_nonce (integer) 382 objective (structure) 384 ttl (integer - default GRASP_DEF_TIMEOUT) 385 discoverable (Boolean - default False) 387 overlap (Boolean - default False) 389 local (Boolean - default False) 391 Return parameter: 393 errorcode (integer) 395 This registers an objective that this ASA supports and may 396 modify. The 'objective' becomes a candidate for discovery. 397 However, discovery responses should not be enabled until the 398 ASA calls listen_negotiate() or listen_synchronize(), showing 399 that it is able to act as a responder. The ASA may negotiate 400 the objective or send synchronization or flood data. 401 Registration is not needed if the ASA only wants to receive 402 synchronization or flood data for the objective concerned. 404 The 'ttl' parameter is the valid lifetime (time to live) in 405 milliseconds of any discovery response for this objective. The 406 default value should be the GRASP default timeout 407 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]). 409 If the optional parameter 'discoverable' is True, the objective 410 is immediately discoverable. This is intended for objectives 411 that are only defined for GRASP discovery, and which do not 412 support negotiation or synchronization. 414 If the optional parameter 'overlap' is True, more than one ASA 415 may register this objective in the same GRASP instance. 417 If the optional parameter 'local' is True, discovery must 418 return a link-local address. This feature is for objectives 419 that must be restricted to the local link. 421 This call may be repeated for multiple objectives. 423 o deregister_objective() 425 Input parameters: 427 asa_nonce (integer) 429 objective (structure) 431 Return parameter: 433 errorcode (integer) 435 The 'objective' must have been registered by the calling ASA; 436 if not, this call fails. Otherwise, it removes all state in 437 the GRASP module for the given objective. 439 2.2.3. Discovery 441 o discover() 443 Input parameters: 445 asa_nonce (integer) 447 objective (structure) 449 timeout (integer) 451 flush (Boolean - default False) 453 Return parameters: 455 errorcode (integer) 457 locator_list (structure) 459 This returns a list of discovered 'ASA_locator's for the given 460 objective. If the optional parameter 'flush' is True, any 461 locally cached locators for the objective are deleted first. 462 Otherwise, they are returned immediately. If not, GRASP 463 discovery is performed, and all results obtained before the 464 timeout expires are returned. If no results are obtained, an 465 empty list is returned after the timeout. That is not an error 466 condition. 468 This should be called in a separate thread if asynchronous 469 operation is required. 471 2.2.4. Negotiation 473 o request_negotiate() 475 Input parameters: 477 asa_nonce (integer) 479 objective (structure) 480 peer (ASA_locator) 482 timeout (integer) 484 Return parameters: 486 errorcode (integer) 488 session_nonce (structure) (if successful) 490 proffered_objective (structure) (if successful) 492 reason (string) (if negotiation declined) 494 This function opens a negotiation session. The 'objective' 495 parameter must include the requested value, and its loop count 496 should be set to a suitable value by the ASA. If not, the 497 GRASP default will apply. 499 Note that a given negotiation session may or may not be a dry- 500 run negotiation; the two modes must not be mixed in a single 501 session. 503 The 'peer' parameter is the target node; it must be an 504 'ASA_locator' as returned by discover(). If the peer is null, 505 GRASP discovery is performed first. 507 If the 'errorcode' return parameter is 0, the negotiation has 508 successfully started. There are then two cases: 510 1. The 'session_nonce' parameter is null. In this case the 511 negotiation has succeeded (the peer has accepted the 512 request). The returned 'proffered_objective' contains the 513 value accepted by the peer. 515 2. The 'session_nonce' parameter is not null. In this case 516 negotiation must continue. The returned 517 'proffered_objective' contains the first value proffered by 518 the negotiation peer. Note that this instance of the 519 objective must be used in the subsequent negotiation call 520 because it also contains the current loop count. The 521 'session_nonce' must be presented in all subsequent 522 negotiation steps. 524 This function must be followed by calls to 'negotiate_step' 525 and/or 'negotiate_wait' and/or 'end_negotiate' until the 526 negotiation ends. 'request_negotiate' may then be called 527 again to start a new negotation. 529 If the 'errorcode' parameter has the value 1 ('declined'), the 530 negotiation has been declined by the peer (M_END and O_DECLINE 531 features of GRASP). The 'reason' string is then available for 532 information and diagnostic use, but it may be a null string. 533 For this and any other error code, an exponential backoff is 534 recommended before any retry. 536 This should be called in a separate thread if asynchronous 537 operation is required. 539 Special note for the ACP infrastructure ASA: It is likely that 540 this ASA will need to discover and negotiate with its peers in 541 each of its on-link neighbors. It will therefore need to know 542 not only the link-local IP address but also the physical 543 interface and transport port for connecting to each neighbor. 544 One implementation approach to this is to include these details 545 in the 'session_nonce' data structure, which is opaque to 546 normal ASAs. 548 o listen_negotiate() 550 Input parameters: 552 asa_nonce (integer) 554 objective (structure) 556 Return parameters: 558 errorcode (integer) 560 session_nonce (structure) (if successful) 562 requested_objective (structure) (if successful) 564 This function instructs GRASP to listen for negotiation 565 requests for the given 'objective'. It also enables discovery 566 responses for the objective. It will block waiting for an 567 incoming request, so should be called in a separate thread if 568 asynchronous operation is required. Unless there is an 569 unexpected failure, this call only returns after an incoming 570 negotiation request. When it does so, 'requested_objective' 571 contains the first value requested by the negotiation peer. 572 Note that this instance of the objective must be used in the 573 subsequent negotiation call because it also contains the 574 current loop count. The 'session_nonce' must be presented in 575 all subsequent negotiation steps. 577 This function must be followed by calls to 'negotiate_step' 578 and/or 'negotiate_wait' and/or 'end_negotiate' until the 579 negotiation ends. 'listen_negotiate' may then be called again 580 to await a new negotation. 582 If an ASA is capable of handling multiple negotiations 583 simultaneously, it may call 'listen_negotiate' simultaneously 584 from multiple threads. The API and GRASP implementation must 585 support re-entrant use of the listening state and the 586 negotiation calls. Simultaneous sessions will be distinguished 587 by the threads themselves, the GRASP Session IDs, and the 588 underlying unicast transport sockets. 590 o stop_listen_negotiate() 592 Input parameters: 594 asa_nonce (integer) 596 objective (structure) 598 Return parameter: 600 errorcode (integer) 602 Instructs GRASP to stop listening for negotiation requests for 603 the given objective, i.e., cancels 'listen_negotiate'. Of 604 course, it must be called from a different thread. 606 o negotiate_step() 608 Input parameters: 610 asa_nonce (integer) 612 session_nonce (structure) 614 objective (structure) 616 timeout (integer) 618 Return parameters: 620 Exactly as for 'request_negotiate' 622 Executes the next negotation step with the peer. The 623 'objective' parameter contains the next value being proffered 624 by the ASA in this step. 626 o negotiate_wait() 628 Input parameters: 630 asa_nonce (integer) 632 session_nonce (structure) 634 timeout (integer) 636 Return parameters: 638 errorcode (integer) 640 Delay negotiation session by 'timeout' milliseconds. 642 o end_negotiate() 644 Input parameters: 646 asa_nonce (integer) 648 session_nonce (structure) 650 reply (Boolean) 652 reason (UTF-8 string) 654 Return parameters: 656 errorcode (integer) 658 End the negotiation session. 660 'reply' = True for accept (successful negotiation), False for 661 decline (failed negotiation). 663 'reason' = optional string describing reason for decline. 665 2.2.5. Synchronization and Flooding 667 o synchronize() 669 Input parameters: 671 asa_nonce (integer) 673 objective (structure) 674 peer (ASA_locator) 676 timeout (integer) 678 Return parameters: 680 errorcode (integer) 682 objective (structure) (if successful) 684 This call requests the synchronized value of the given 685 'objective'. 687 Since this is essentially a read operation, any ASA can do it. 688 Therefore the API checks that the ASA is registered but the 689 objective doesn't need to be registered by the calling ASA. 691 If the objective was already flooded, the flooded value is 692 returned immediately in the 'result' parameter. In this case, 693 the 'source' and 'timeout' are ignored. 695 Otherwise, synchronization with a discovered ASA is performed. 696 The 'peer' parameter is an 'ASA_locator' as returned by 697 discover(). If 'peer' is null, GRASP discovery is performed 698 first. 700 This call should be repeated whenever the latest value is 701 needed. 703 Call in a separate thread if asynchronous operation is 704 required. 706 Since this is essentially a read operation, any ASA can use it. 707 Therefore GRASP checks that the calling ASA is registered but 708 the objective doesn't need to be registered by the calling ASA. 710 In the case of failure, an exponential backoff is recommended 711 before retrying. 713 o listen_synchronize() 715 Input parameters: 717 asa_nonce (integer) 719 objective (structure) 721 Return parameters: 723 errorcode (integer) 725 This instructs GRASP to listen for synchronization requests for 726 the given objective, and to respond with the value given in the 727 'objective' parameter. It also enables discovery responses for 728 the objective. 730 This call is non-blocking and may be repeated whenever the 731 value changes. 733 o stop_listen_synchronize() 735 Input parameters: 737 asa_nonce (integer) 739 objective (structure) 741 Return parameters: 743 errorcode (integer) 745 This call instructs GRASP to stop listening for synchronization 746 requests for the given 'objective', i.e. it cancels a previous 747 listen_synchronize. 749 o flood() 751 Input parameters: 753 asa_nonce (integer) 755 ttl (integer) 757 tagged_objective_list (structure) 759 Return parameters: 761 errorcode (integer) 763 This call instructs GRASP to flood the given synchronization 764 objective(s) and their value(s) and associated locator(s) to 765 all GRASP nodes. 767 The 'ttl' parameter is the valid lifetime (time to live) of the 768 flooded data in milliseconds (0 = infinity) 769 The 'tagged_objective_list' parameter is a list of one or more 770 'tagged_objective' couplets. The 'locator' parameter that tags 771 each objective is normally null but may be a valid 772 'ASA_locator'. Infrastructure ASAs needing to flood an 773 {address, protocol, port} 3-tuple with an objective create an 774 ASA_locator object to do so. If the IP address in that locator 775 is the unspecified address ('::') it is replaced by the link- 776 local address of the sending node in each copy of the flood 777 multicast, which will be forced to have a loop count of 1. 778 This feature is for objectives that must be restricted to the 779 local link. 781 The function checks that the ASA registered each objective. 783 This call may be repeated whenever any value changes. 785 o get_flood() 787 Input parameters: 789 asa_nonce (integer) 791 objective (structure) 793 Return parameters: 795 errorcode (integer) 797 tagged_objective_list (structure) (if successful) 799 This call instructs GRASP to return the given synchronization 800 objective if it has been flooded and its lifetime has not 801 expired. 803 Since this is essentially a read operation, any ASA can do it. 804 Therefore the API checks that the ASA is registered but the 805 objective doesn't need to be registered by the calling ASA. 807 The 'tagged_objective_list' parameter is a list of 808 'tagged_objective' couplets, each one being a copy of the 809 flooded objective and a coresponding locator. Thus if the same 810 objective has been flooded by multiple ASAs, the recipient can 811 distinguish the copies. 813 Note that this call is for advanced ASAs. In a simple case, an 814 ASA can simply call synchronize() in order to get a valid 815 flooded objective. 817 o expire_flood() 819 Input parameters: 821 asa_nonce (integer) 823 tagged_objective (structure) 825 Return parameters: 827 errorcode (integer) 829 This is a call that can only be used after a preceding call to 830 get_flood() by an ASA that is capable of deciding that the 831 flooded value is stale or invalid. Use with care. 833 The 'tagged_objective' parameter is the one to be expired. 835 3. Non-threaded Implementations 837 If an operating system or language does not provide convenient 838 support for multi-threading, ASAs may need to be written using a 839 polling or 'event loop' structure, whereby a main loop supports 840 multiple GRASP sessions in parallel by repeatedly checking each one 841 for a change of state. To facilitate this, an API implementation may 842 provide alternative versions of all the functions that involve 843 blocking and queueing. In the calls, the error code 2 ("noReply") 844 will be returned by each call instead of blocking, until such time as 845 the event for which it is waiting has been queued. Thus, for 846 example, request_negotiate() would return "noReply" instead of 847 waiting until an incoming request or timeout arrived, and an 848 identical call to request_negotiate() would be repeated in the next 849 cycle of the main loop. In the case of negotiations, the 850 session_nonce parameter is used to distinguish sessions from each 851 other, if necessary. 853 The calls to which this mechanism applies are: 855 discover() 857 request_negotiate() 859 negotiate_step() 861 listen_negotiate() 863 synchronize() 865 4. Example Logic Flows 867 TBD 869 (Until this section is written, some Python examples can be found at 870 , 871 , and 872 .) 874 5. Security Considerations 876 Security issues for the GRASP protocol are discussed in 877 [I-D.ietf-anima-grasp]. Authorization of ASAs is a subject for 878 future study. 880 The 'asa_nonce' parameter is used in the API as a first line of 881 defence against a malware process attempting to imitate a 882 legitimately registered ASA. The 'session_nonce' parameter is used 883 in the API as a first line of defence against a malware process 884 attempting to hijack a GRASP session. 886 6. IANA Considerations 888 This does not need IANA assignment. 890 7. Acknowledgements 892 This document was produced using the xml2rfc tool [RFC7749]. 894 Excellent suggestions were made by Michael Richardson. 896 8. References 898 8.1. Normative References 900 [I-D.ietf-anima-grasp] 901 Bormann, C., Carpenter, B., and B. Liu, "A Generic 902 Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- 903 grasp-13 (work in progress), June 2017. 905 8.2. Informative References 907 [I-D.ietf-anima-autonomic-control-plane] 908 Behringer, M., Eckert, T., and S. Bjarnason, "An Autonomic 909 Control Plane", draft-ietf-anima-autonomic-control- 910 plane-06 (work in progress), March 2017. 912 [I-D.ietf-anima-bootstrapping-keyinfra] 913 Pritikin, M., Richardson, M., Behringer, M., Bjarnason, 914 S., and K. Watsen, "Bootstrapping Remote Secure Key 915 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 916 keyinfra-06 (work in progress), May 2017. 918 [I-D.ietf-anima-reference-model] 919 Behringer, M., Carpenter, B., Eckert, T., Ciavaglia, L., 920 Pierre, P., Liu, B., Nobre, J., and J. Strassner, "A 921 Reference Model for Autonomic Networking", draft-ietf- 922 anima-reference-model-03 (work in progress), March 2017. 924 [I-D.liu-anima-grasp-distribution] 925 Liu, B. and S. Jiang, "Information Distribution over 926 GRASP", draft-liu-anima-grasp-distribution-04 (work in 927 progress), May 2017. 929 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 930 RFC 7749, DOI 10.17487/RFC7749, February 2016, 931 . 933 Appendix A. Error Codes 935 This Appendix lists the error codes defined so far, with suggested 936 symbolic names and corresponding descriptive strings in English. It 937 is expected that complete API implementations will provide for 938 localisation of these descriptive strings. 940 ok 0 "OK" 941 declined 1 "Declined" 942 noReply 2 "No reply" 943 unspec 3 "Unspecified error" 944 ASAfull 4 "ASA registry full" 945 dupASA 5 "Duplicate ASA name" 946 noASA 6 "ASA not registered" 947 notYourASA 7 "ASA registered but not by you" 948 notBoth 8 "Objective cannot support both negotiation 949 and synchronization" 950 notDry 9 "Dry-run allowed only with negotiation" 951 notOverlap 10 "Overlap not supported by this implementation" 952 objFull 11 "Objective registry full" 953 objReg 12 "Objective already registered" 954 notYourObj 13 "Objective not registered by this ASA" 955 notObj 14 "Objective not found" 956 notNeg 15 "Objective not negotiable" 957 noSecurity 16 "No security" 958 noDiscReply 17 "No reply to discovery" 959 sockErrNegRq 18 "Socket error sending negotiation request" 960 noSession 19 "No session" 961 noSocket 20 "No socket" 962 loopExhausted 21 "Loop count exhausted" 963 sockErrNegStep 22 "Socket error sending negotiation step" 964 noPeer 23 "No negotiation peer" 965 CBORfail 24 "CBOR decode failure" 966 invalidNeg 25 "Invalid Negotiate message" 967 invalidEnd 26 "Invalid end message" 968 noNegReply 27 "No reply to negotiation step" 969 noValidStep 28 "No valid reply to negotiation step" 970 sockErrWait 29 "Socket error sending wait message" 971 sockErrEnd 30 "Socket error sending end message" 972 IDclash 31 "Incoming request Session ID clash" 973 notSynch 32 "Not a synchronization objective" 974 notFloodDisc 33 "Not flooded and no reply to discovery" 975 sockErrSynRq 34 "Socket error sending synch request" 976 noListener 35 "No synch listener" 977 noSynchReply 36 "No reply to synchronization request" 978 noValidSynch 37 "No valid reply to synchronization request" 979 invalidLoc 38 "Invalid locator" 981 Appendix B. Change log [RFC Editor: Please remove] 983 draft-liu-anima-grasp-api-04, 2017-06-30: 985 Noted that simple nodes might not include the API. 987 Minor clarifications. 989 draft-liu-anima-grasp-api-03, 2017-02-13: 991 Changed error return to integers. 993 Required all implementations to accept objective values in CBOR. 995 Added non-blocking alternatives. 997 draft-liu-anima-grasp-api-02, 2016-12-17: 999 Updated for draft-ietf-anima-grasp-09 1001 draft-liu-anima-grasp-api-02, 2016-09-30: 1003 Added items for draft-ietf-anima-grasp-07 1005 Editorial corrections 1007 draft-liu-anima-grasp-api-01, 2016-06-24: 1009 Updated for draft-ietf-anima-grasp-05 1011 Editorial corrections 1013 draft-liu-anima-grasp-api-00, 2016-04-04: 1015 Initial version 1017 Authors' Addresses 1019 Brian Carpenter 1020 Department of Computer Science 1021 University of Auckland 1022 PB 92019 1023 Auckland 1142 1024 New Zealand 1026 Email: brian.e.carpenter@gmail.com 1028 Bing Liu (editor) 1029 Huawei Technologies 1030 Q22, Huawei Campus 1031 No.156 Beiqing Road 1032 Hai-Dian District, Beijing 100095 1033 P.R. China 1035 Email: leo.liubing@huawei.com 1036 Wendong Wang 1037 BUPT University 1038 Beijing University of Posts & Telecom. 1039 No.10 Xitucheng Road 1040 Hai-Dian District, Beijing 100876 1041 P.R. China 1043 Email: wdwang@bupt.edu.cn 1045 Xiangyang Gong 1046 BUPT University 1047 Beijing University of Posts & Telecom. 1048 No.10 Xitucheng Road 1049 Hai-Dian District, Beijing 100876 1050 P.R. China 1052 Email: xygong@bupt.edu.cn