idnits 2.17.1 draft-liu-anima-grasp-api-05.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 (October 2, 2017) is 2397 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 (-30) exists of draft-ietf-anima-autonomic-control-plane-10 == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-07 == Outdated reference: A later version (-10) exists of draft-ietf-anima-reference-model-04 == 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 (~~), 5 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: April 5, 2018 Huawei Technologies 6 W. Wang 7 X. Gong 8 BUPT University 9 October 2, 2017 11 Generic Autonomic Signaling Protocol Application Program Interface 12 (GRASP API) 13 draft-liu-anima-grasp-api-05 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 https://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 April 5, 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 (https://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 . . . . . . . . . . . . . . . . . . . . 8 62 2.2.3. Discovery . . . . . . . . . . . . . . . . . . . . . . 10 63 2.2.4. Negotiation . . . . . . . . . . . . . . . . . . . . . 11 64 2.2.5. Synchronization and Flooding . . . . . . . . . . . . 15 65 2.2.6. Invalid Message Function . . . . . . . . . . . . . . 18 66 3. Non-threaded Implementations . . . . . . . . . . . . . . . . 19 67 4. Example Logic Flows . . . . . . . . . . . . . . . . . . . . . 19 68 5. Security Considerations . . . . . . . . . . . . . . . . . . . 20 69 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 70 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20 71 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 72 8.1. Normative References . . . . . . . . . . . . . . . . . . 20 73 8.2. Informative References . . . . . . . . . . . . . . . . . 20 74 Appendix A. Error Codes . . . . . . . . . . . . . . . . . . . . 21 75 Appendix B. Change log [RFC Editor: Please remove] . . . . . . . 22 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 78 1. Introduction 80 As defined in [I-D.ietf-anima-reference-model], the Autonomic Service 81 Agent (ASA) is the atomic entity of an autonomic function; and it is 82 instantiated on autonomic nodes. When ASAs communicate with each 83 other, they should use the Generic Autonomic Signaling Protocol 84 (GRASP) [I-D.ietf-anima-grasp]. 86 As the following figure shows, GRASP could contain two major sub- 87 layers. The bottom is the GRASP base protocol module, which is only 88 responsible for sending and receiving GRASP messages and maintaining 89 shared data structures. The upper layer is some extended functions 90 based upon GRASP basic protocol. For example, 91 [I-D.liu-anima-grasp-distribution] describes a possible extended 92 function. 94 It is desirable that ASAs can be designed as portable user-space 95 programs using a portable API. In many operating systems, the GRASP 96 module will therefore be split into two layers, one being a library 97 that provides the API and the other being core code containing common 98 components such as multicast handling and the discovery cache. The 99 details of this are system-dependent. 101 +----+ +----+ 102 |ASAs| |ASAs| 103 +----+ +----+ 104 | | 105 | GRASP Function API | 106 | | 107 +------------------+ |GRASP API 108 | GRASP Extended | | 109 | Function Modules | | 110 +------------------+ | 111 +------------------------------------------+ 112 | GRASP Library | 113 | GRASP Module - - - - - - - - - - - - - -| 114 | GRASP Core | 115 +------------------------------------------+ 117 Both the GRASP base module and the extended function modules should 118 be available to the ASAs. Thus, there needs to be two sub-sets of 119 API. However, since the extended functions are expected to be added 120 in an incremental manner, it is inappropriate to define the function 121 APIs in a single document. This document only defines the base GRASP 122 API. 124 Note that a very simple autonomic node might contain only a single 125 ASA in addition to the autonomic infrastructure components described 126 in [I-D.ietf-anima-bootstrapping-keyinfra] and 127 [I-D.ietf-anima-autonomic-control-plane]. Such a node might directly 128 integrate GRASP in its autonomic code and therefore not require this 129 API to be installed. 131 2. GRASP API for ASA 133 2.1. Design Principles 135 The assumption of this document is that any Autonomic Service Agent 136 (ASA) needs to call a GRASP module that handles protocol details 137 (security, sending and listening for GRASP messages, waiting, caching 138 discovery results, negotiation looping, sending and receiving 139 sychronization data, etc.) but understands nothing about individual 140 objectives. So this is a high level abstract API for use by ASAs. 141 Individual language bindings should be defined in separate documents. 143 An assumption of this API is that ASAs may fall into various classes: 145 o ASAs that only use GRASP for discovery purposes. 147 o ASAs that use GRASP negotiation but only as an initiator (client). 149 o ASAs that use GRASP negotiation but only as a responder. 151 o ASAs that use GRASP negotiation as an initiator or responder. 153 o ASAs that use GRASP synchronization but only as an initiator 154 (recipient). 156 o ASAs that use GRASP synchronization but only as a responder and/or 157 flooder. 159 o ASAs that use GRASP synchronization as an initiator, responder 160 and/or flooder. 162 The API also assumes that one ASA may support multiple objectives. 163 Nothing prevents an ASA from supporting some objectives for 164 synchronization and others for negotiation. 166 The API design assumes that the operating system and programming 167 language provide a convenient mechanism for multi-threaded code. A 168 solution in case this does not apply is described in Section 3. 170 This is a preliminary version. Two particular gaps exist: 172 o Authorization of ASAs is out of scope. 174 o The Rapid mode of GRASP is not supported. 176 2.2. API definition 178 2.2.1. Parameters and data structures 180 This section describes parameters and data structures uaed in 181 multiple API calls. 183 2.2.1.1. Errorcode 185 All functions in the API have an unsigned 'errorcode' integer as 186 their return value (the first returned value in languages that allow 187 multiple returned parameters). An errorcode of zero indicates 188 success. Any other value indicates failure of some kind. The first 189 three errorcodes have special importance: 191 1. Declined: used to indicate that the other end has sent a GRASP 192 Negotiation End message (M_END) with a Decline option 193 (O_DECLINE). 195 2. No reply: used in non-blocking calls to indicate that the other 196 end has sent no reply so far (see Section 3). 198 3. Unspecified error: used when no more specific error code applies. 200 Appendix A gives a full list of currently defined error codes. 202 2.2.1.2. Timeout 204 Wherever a 'timeout' parameter appears, it is an integer expressed in 205 milliseconds. If it is zero, the GRASP default timeout 206 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]) will apply. If no 207 response is received before the timeout expires, the call will fail 208 unless otherwise noted. 210 2.2.1.3. Objective 212 An 'objective' parameter is a data structure with the following 213 components: 215 o name (UTF-8 string) - the objective's name 217 o neg (Boolean) - True if objective supports negotiation (default 218 False) 220 o synch (Boolean) - True if objective supports synchronization 221 (default False) 223 o dry (Boolean) - True if objective also supports dry-run 224 synchronization (default False) 226 * Note 1: All objectives are assumed to support discovery, so 227 there is no Boolean for that. 229 * Note 2: Only one of 'synch' or 'neg' may be True. 231 * Note 3: 'dry' must not be True unless 'neg' is also True. 233 o loop_count (integer) - Limit on negotiation steps etc. (default 234 GRASP_DEF_LOOPCT, see [I-D.ietf-anima-grasp]) 236 o value - a specific data structure expressing the value of the 237 objective. The format is language dependent, with the constraint 238 that it can be validly represented in CBOR (default integer = 0). 240 An essential requirement for all language mappings and all 241 implementations is that, regardless of what other options exist 242 for a language-specific represenation of the value, there is 243 always an option to use a CBOR byte string as the value. The API 244 will then wrap this byte string in CBOR Tag 24 for transmission 245 via GRASP, and unwrap it after reception. 247 An example data structure definition for an objective in the C 248 language is: 250 typedef struct { 251 char *name; 252 bool neg; 253 bool dry; 254 bool synch; 255 int loop_count; 256 int value_size; // size of value 257 uint8_t cbor_value[]; // CBOR bytestring of value 258 } objective; 260 An example data structure definition for an objective in the 261 Python language is: 263 class objective: 264 """A GRASP objective""" 265 def __init__(self, name): 266 self.name = name #Unique name, string 267 self.neg = False #Set True if objective supports negotiation 268 self.dry = False #Set True if objective also supports dry-run negotiation 269 self.synch = False #Set True if objective supports synch 270 self.loop_count = GRASP_DEF_LOOPCT #Default starting value 271 self.value = 0 #Place holder; any valid Python object 273 2.2.1.4. ASA_locator 275 An 'ASA_locator' parameter is a data structure with the following 276 contents: 278 o locator - The actual locator, either an IP address or an ASCII 279 string. 281 o ifi (integer) - The interface identifier index via which this was 282 discovered - probably no use to a normal ASA 284 o expire (system dependent type) - The time on the local system 285 clock when this locator will expire from the cache 287 o is_ipaddress (Boolean) - True if the locator is an IP address 288 o is_fqdn (Boolean) - True if the locator is an FQDN 290 o is_uri (Boolean) - True if the locator is a URI 292 o diverted (Boolean) - True if the locator was discovered via a 293 Divert option 295 o protocol (integer) - Applicable transport protocol (IPPROTO_TCP or 296 IPPROTO_UDP) 298 o port (integer) - Applicable port number 300 2.2.1.5. Tagged_objective 302 A 'tagged_objective' parameter is a data structure with the following 303 contents: 305 o objective - An objective 307 o locator - The ASA_locator associated with the objective, or a null 308 value. 310 2.2.1.6. Asa_nonce 312 In most calls, an 'asa_nonce' parameter is required. It is generated 313 when an ASA registers with GRASP, and any call in which an invalid 314 nonce is presented will fail. It is an up to 32-bit opaque value 315 (for example represented as a uint32_t, depending on the language). 316 It should be unpredictable; a possible implementation is to use the 317 same mechanism that GRASP uses to generate Session IDs 318 [I-D.ietf-anima-grasp]. Another possible implementation is to hash 319 the name of the ASA with a locally defined secret key. 321 2.2.1.7. Session_nonce 323 In some calls, a 'session_nonce' parameter is required. This is an 324 opaque data structure as far as the ASA is concerned, used to 325 identify calls to the API as belonging to a specific GRASP session. 326 In fully threaded implementations this parameter might not be needed, 327 but it is included to act as a session handle if necessary. It will 328 also allow GRASP to detect and ignore malicious calls or calls from 329 timed-out sessions. A possible implementation is to form the nonce 330 from the underlying GRASP Session ID and the source address of the 331 session. 333 2.2.2. Registration 335 These functions are used to register an ASA and the objectives that 336 it supports with the GRASP module. If an authorization model is 337 added to GRASP, it would be added here. 339 o register_asa() 341 Input parameter: 343 name of the ASA (UTF-8 string) 345 Return parameters: 347 errorcode (integer) 349 asa_nonce (integer) (if successful) 351 This initialises state in the GRASP module for the calling 352 entity (the ASA). In the case of success, an 'asa_nonce' is 353 returned which the ASA must present in all subsequent calls. 354 In the case of failure, the ASA has not been authorized and 355 cannot operate. 357 o deregister_asa() 359 Input parameters: 361 asa_nonce (integer) 363 name of the ASA (UTF-8 string) 365 Return parameter: 367 errorcode (integer) 369 This removes all state in the GRASP module for the calling 370 entity (the ASA), and deregisters any objectives it has 371 registered. Note that these actions must also happen 372 automatically if an ASA crashes. 374 Note - the ASA name is strictly speaking redundant in this 375 call, but is present for clarity. 377 o register_objective() 379 Input parameters: 381 asa_nonce (integer) 383 objective (structure) 385 ttl (integer - default GRASP_DEF_TIMEOUT) 387 discoverable (Boolean - default False) 389 overlap (Boolean - default False) 391 local (Boolean - default False) 393 Return parameter: 395 errorcode (integer) 397 This registers an objective that this ASA supports and may 398 modify. The 'objective' becomes a candidate for discovery. 399 However, discovery responses should not be enabled until the 400 ASA calls listen_negotiate() or listen_synchronize(), showing 401 that it is able to act as a responder. The ASA may negotiate 402 the objective or send synchronization or flood data. 403 Registration is not needed if the ASA only wants to receive 404 synchronization or flood data for the objective concerned. 406 The 'ttl' parameter is the valid lifetime (time to live) in 407 milliseconds of any discovery response for this objective. The 408 default value should be the GRASP default timeout 409 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]). 411 If the optional parameter 'discoverable' is True, the objective 412 is immediately discoverable. This is intended for objectives 413 that are only defined for GRASP discovery, and which do not 414 support negotiation or synchronization. 416 If the optional parameter 'overlap' is True, more than one ASA 417 may register this objective in the same GRASP instance. 419 If the optional parameter 'local' is True, discovery must 420 return a link-local address. This feature is for objectives 421 that must be restricted to the local link. 423 This call may be repeated for multiple objectives. 425 o deregister_objective() 427 Input parameters: 429 asa_nonce (integer) 431 objective (structure) 433 Return parameter: 435 errorcode (integer) 437 The 'objective' must have been registered by the calling ASA; 438 if not, this call fails. Otherwise, it removes all state in 439 the GRASP module for the given objective. 441 2.2.3. Discovery 443 o discover() 445 Input parameters: 447 asa_nonce (integer) 449 objective (structure) 451 timeout (integer) 453 flush (Boolean - default False) 455 Return parameters: 457 errorcode (integer) 459 locator_list (structure) 461 This returns a list of discovered 'ASA_locator's for the given 462 objective. If the optional parameter 'flush' is True, any 463 locally cached locators for the objective are deleted first. 464 Otherwise, they are returned immediately. If not, GRASP 465 discovery is performed, and all results obtained before the 466 timeout expires are returned. If no results are obtained, an 467 empty list is returned after the timeout. That is not an error 468 condition. 470 This should be called in a separate thread if asynchronous 471 operation is required. 473 2.2.4. Negotiation 475 o request_negotiate() 477 Input parameters: 479 asa_nonce (integer) 481 objective (structure) 483 peer (ASA_locator) 485 timeout (integer) 487 Return parameters: 489 errorcode (integer) 491 session_nonce (structure) (if successful) 493 proffered_objective (structure) (if successful) 495 reason (string) (if negotiation declined) 497 This function opens a negotiation session. The 'objective' 498 parameter must include the requested value, and its loop count 499 should be set to a suitable value by the ASA. If not, the 500 GRASP default will apply. 502 Note that a given negotiation session may or may not be a dry- 503 run negotiation; the two modes must not be mixed in a single 504 session. 506 The 'peer' parameter is the target node; it must be an 507 'ASA_locator' as returned by discover(). If the peer is null, 508 GRASP discovery is performed first. 510 If the 'errorcode' return parameter is 0, the negotiation has 511 successfully started. There are then two cases: 513 1. The 'session_nonce' parameter is null. In this case the 514 negotiation has succeeded (the peer has accepted the 515 request). The returned 'proffered_objective' contains the 516 value accepted by the peer. 518 2. The 'session_nonce' parameter is not null. In this case 519 negotiation must continue. The returned 520 'proffered_objective' contains the first value proffered by 521 the negotiation peer. Note that this instance of the 522 objective must be used in the subsequent negotiation call 523 because it also contains the current loop count. The 524 'session_nonce' must be presented in all subsequent 525 negotiation steps. 527 This function must be followed by calls to 'negotiate_step' 528 and/or 'negotiate_wait' and/or 'end_negotiate' until the 529 negotiation ends. 'request_negotiate' may then be called 530 again to start a new negotation. 532 If the 'errorcode' parameter has the value 1 ('declined'), the 533 negotiation has been declined by the peer (M_END and O_DECLINE 534 features of GRASP). The 'reason' string is then available for 535 information and diagnostic use, but it may be a null string. 536 For this and any other error code, an exponential backoff is 537 recommended before any retry. 539 This should be called in a separate thread if asynchronous 540 operation is required. 542 Special note for the ACP infrastructure ASA: It is likely that 543 this ASA will need to discover and negotiate with its peers in 544 each of its on-link neighbors. It will therefore need to know 545 not only the link-local IP address but also the physical 546 interface and transport port for connecting to each neighbor. 547 One implementation approach to this is to include these details 548 in the 'session_nonce' data structure, which is opaque to 549 normal ASAs. 551 o listen_negotiate() 553 Input parameters: 555 asa_nonce (integer) 557 objective (structure) 559 Return parameters: 561 errorcode (integer) 563 session_nonce (structure) (if successful) 565 requested_objective (structure) (if successful) 567 This function instructs GRASP to listen for negotiation 568 requests for the given 'objective'. It also enables discovery 569 responses for the objective. It will block waiting for an 570 incoming request, so should be called in a separate thread if 571 asynchronous operation is required. Unless there is an 572 unexpected failure, this call only returns after an incoming 573 negotiation request. When it does so, 'requested_objective' 574 contains the first value requested by the negotiation peer. 575 Note that this instance of the objective must be used in the 576 subsequent negotiation call because it also contains the 577 current loop count. The 'session_nonce' must be presented in 578 all subsequent negotiation steps. 580 This function must be followed by calls to 'negotiate_step' 581 and/or 'negotiate_wait' and/or 'end_negotiate' until the 582 negotiation ends. 'listen_negotiate' may then be called again 583 to await a new negotation. 585 If an ASA is capable of handling multiple negotiations 586 simultaneously, it may call 'listen_negotiate' simultaneously 587 from multiple threads. The API and GRASP implementation must 588 support re-entrant use of the listening state and the 589 negotiation calls. Simultaneous sessions will be distinguished 590 by the threads themselves, the GRASP Session IDs, and the 591 underlying unicast transport sockets. 593 o stop_listen_negotiate() 595 Input parameters: 597 asa_nonce (integer) 599 objective (structure) 601 Return parameter: 603 errorcode (integer) 605 Instructs GRASP to stop listening for negotiation requests for 606 the given objective, i.e., cancels 'listen_negotiate'. Of 607 course, it must be called from a different thread. 609 o negotiate_step() 611 Input parameters: 613 asa_nonce (integer) 615 session_nonce (structure) 616 objective (structure) 618 timeout (integer) 620 Return parameters: 622 Exactly as for 'request_negotiate' 624 Executes the next negotation step with the peer. The 625 'objective' parameter contains the next value being proffered 626 by the ASA in this step. 628 o negotiate_wait() 630 Input parameters: 632 asa_nonce (integer) 634 session_nonce (structure) 636 timeout (integer) 638 Return parameters: 640 errorcode (integer) 642 Delay negotiation session by 'timeout' milliseconds. 644 o end_negotiate() 646 Input parameters: 648 asa_nonce (integer) 650 session_nonce (structure) 652 reply (Boolean) 654 reason (UTF-8 string) 656 Return parameters: 658 errorcode (integer) 660 End the negotiation session. 662 'reply' = True for accept (successful negotiation), False for 663 decline (failed negotiation). 665 'reason' = optional string describing reason for decline. 667 2.2.5. Synchronization and Flooding 669 o synchronize() 671 Input parameters: 673 asa_nonce (integer) 675 objective (structure) 677 peer (ASA_locator) 679 timeout (integer) 681 Return parameters: 683 errorcode (integer) 685 objective (structure) (if successful) 687 This call requests the synchronized value of the given 688 'objective'. 690 Since this is essentially a read operation, any ASA can do it. 691 Therefore the API checks that the ASA is registered but the 692 objective doesn't need to be registered by the calling ASA. 694 If the objective was already flooded, the flooded value is 695 returned immediately in the 'result' parameter. In this case, 696 the 'source' and 'timeout' are ignored. 698 Otherwise, synchronization with a discovered ASA is performed. 699 The 'peer' parameter is an 'ASA_locator' as returned by 700 discover(). If 'peer' is null, GRASP discovery is performed 701 first. 703 This call should be repeated whenever the latest value is 704 needed. 706 Call in a separate thread if asynchronous operation is 707 required. 709 Since this is essentially a read operation, any ASA can use it. 710 Therefore GRASP checks that the calling ASA is registered but 711 the objective doesn't need to be registered by the calling ASA. 713 In the case of failure, an exponential backoff is recommended 714 before retrying. 716 o listen_synchronize() 718 Input parameters: 720 asa_nonce (integer) 722 objective (structure) 724 Return parameters: 726 errorcode (integer) 728 This instructs GRASP to listen for synchronization requests for 729 the given objective, and to respond with the value given in the 730 'objective' parameter. It also enables discovery responses for 731 the objective. 733 This call is non-blocking and may be repeated whenever the 734 value changes. 736 o stop_listen_synchronize() 738 Input parameters: 740 asa_nonce (integer) 742 objective (structure) 744 Return parameters: 746 errorcode (integer) 748 This call instructs GRASP to stop listening for synchronization 749 requests for the given 'objective', i.e. it cancels a previous 750 listen_synchronize. 752 o flood() 754 Input parameters: 756 asa_nonce (integer) 758 ttl (integer) 760 tagged_objective_list (structure) 762 Return parameters: 764 errorcode (integer) 766 This call instructs GRASP to flood the given synchronization 767 objective(s) and their value(s) and associated locator(s) to 768 all GRASP nodes. 770 The 'ttl' parameter is the valid lifetime (time to live) of the 771 flooded data in milliseconds (0 = infinity) 773 The 'tagged_objective_list' parameter is a list of one or more 774 'tagged_objective' couplets. The 'locator' parameter that tags 775 each objective is normally null but may be a valid 776 'ASA_locator'. Infrastructure ASAs needing to flood an 777 {address, protocol, port} 3-tuple with an objective create an 778 ASA_locator object to do so. If the IP address in that locator 779 is the unspecified address ('::') it is replaced by the link- 780 local address of the sending node in each copy of the flood 781 multicast, which will be forced to have a loop count of 1. 782 This feature is for objectives that must be restricted to the 783 local link. 785 The function checks that the ASA registered each objective. 787 This call may be repeated whenever any value changes. 789 o get_flood() 791 Input parameters: 793 asa_nonce (integer) 795 objective (structure) 797 Return parameters: 799 errorcode (integer) 801 tagged_objective_list (structure) (if successful) 803 This call instructs GRASP to return the given synchronization 804 objective if it has been flooded and its lifetime has not 805 expired. 807 Since this is essentially a read operation, any ASA can do it. 808 Therefore the API checks that the ASA is registered but the 809 objective doesn't need to be registered by the calling ASA. 811 The 'tagged_objective_list' parameter is a list of 812 'tagged_objective' couplets, each one being a copy of the 813 flooded objective and a coresponding locator. Thus if the same 814 objective has been flooded by multiple ASAs, the recipient can 815 distinguish the copies. 817 Note that this call is for advanced ASAs. In a simple case, an 818 ASA can simply call synchronize() in order to get a valid 819 flooded objective. 821 o expire_flood() 823 Input parameters: 825 asa_nonce (integer) 827 tagged_objective (structure) 829 Return parameters: 831 errorcode (integer) 833 This is a call that can only be used after a preceding call to 834 get_flood() by an ASA that is capable of deciding that the 835 flooded value is stale or invalid. Use with care. 837 The 'tagged_objective' parameter is the one to be expired. 839 2.2.6. Invalid Message Function 841 o send_invalid() 843 Input parameters: 845 asa_nonce (integer) 847 session_nonce (structure) 849 info (bytes) 851 Return parameters: 853 errorcode (integer) 855 Sends a GRASP Invalid Message (M_INVALID) message, as described 856 in [I-D.ietf-anima-grasp]. Should not be used if 857 end_negotiate() would be sufficient. Note that this message 858 may be used in response to any unicast GRASP message that the 859 receiver cannot interpret correctly. In most cases this 860 message will be generated internally by a GRASP implementation. 862 'info' = optional diagnostic data. May be raw bytes from the 863 invalid message. 865 3. Non-threaded Implementations 867 If an operating system or language does not provide convenient 868 support for multi-threading, ASAs may need to be written using a 869 polling or 'event loop' structure, whereby a main loop supports 870 multiple GRASP sessions in parallel by repeatedly checking each one 871 for a change of state. To facilitate this, an API implementation may 872 provide alternative versions of all the functions that involve 873 blocking and queueing. In the calls, the error code 2 ("noReply") 874 will be returned by each call instead of blocking, until such time as 875 the event for which it is waiting has been queued. Thus, for 876 example, request_negotiate() would return "noReply" instead of 877 waiting until an incoming request or timeout arrived, and an 878 identical call to request_negotiate() would be repeated in the next 879 cycle of the main loop. In the case of negotiations, the 880 session_nonce parameter is used to distinguish sessions from each 881 other, if necessary. 883 The calls to which this mechanism applies are: 885 discover() 887 request_negotiate() 889 negotiate_step() 891 listen_negotiate() 893 synchronize() 895 4. Example Logic Flows 897 TBD 899 (Until this section is written, some Python examples can be found at 900 , 901 , and 902 .) 904 5. Security Considerations 906 Security issues for the GRASP protocol are discussed in 907 [I-D.ietf-anima-grasp]. Authorization of ASAs is a subject for 908 future study. 910 The 'asa_nonce' parameter is used in the API as a first line of 911 defence against a malware process attempting to imitate a 912 legitimately registered ASA. The 'session_nonce' parameter is used 913 in the API as a first line of defence against a malware process 914 attempting to hijack a GRASP session. 916 6. IANA Considerations 918 This does not need IANA assignment. 920 7. Acknowledgements 922 This document was produced using the xml2rfc tool [RFC7749]. 924 Excellent suggestions were made by Michael Richardson. 926 8. References 928 8.1. Normative References 930 [I-D.ietf-anima-grasp] 931 Bormann, C., Carpenter, B., and B. Liu, "A Generic 932 Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- 933 grasp-15 (work in progress), July 2017. 935 8.2. Informative References 937 [I-D.ietf-anima-autonomic-control-plane] 938 Behringer, M., Eckert, T., and S. Bjarnason, "An Autonomic 939 Control Plane (ACP)", draft-ietf-anima-autonomic-control- 940 plane-10 (work in progress), September 2017. 942 [I-D.ietf-anima-bootstrapping-keyinfra] 943 Pritikin, M., Richardson, M., Behringer, M., Bjarnason, 944 S., and K. Watsen, "Bootstrapping Remote Secure Key 945 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 946 keyinfra-07 (work in progress), July 2017. 948 [I-D.ietf-anima-reference-model] 949 Behringer, M., Carpenter, B., Eckert, T., Ciavaglia, L., 950 Pierre, P., Liu, B., Nobre, J., and J. Strassner, "A 951 Reference Model for Autonomic Networking", draft-ietf- 952 anima-reference-model-04 (work in progress), July 2017. 954 [I-D.liu-anima-grasp-distribution] 955 Liu, B. and S. Jiang, "Information Distribution over 956 GRASP", draft-liu-anima-grasp-distribution-04 (work in 957 progress), May 2017. 959 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 960 RFC 7749, DOI 10.17487/RFC7749, February 2016, 961 . 963 Appendix A. Error Codes 965 This Appendix lists the error codes defined so far, with suggested 966 symbolic names and corresponding descriptive strings in English. It 967 is expected that complete API implementations will provide for 968 localisation of these descriptive strings. 970 ok 0 "OK" 971 declined 1 "Declined" 972 noReply 2 "No reply" 973 unspec 3 "Unspecified error" 974 ASAfull 4 "ASA registry full" 975 dupASA 5 "Duplicate ASA name" 976 noASA 6 "ASA not registered" 977 notYourASA 7 "ASA registered but not by you" 978 notBoth 8 "Objective cannot support both negotiation 979 and synchronization" 980 notDry 9 "Dry-run allowed only with negotiation" 981 notOverlap 10 "Overlap not supported by this implementation" 982 objFull 11 "Objective registry full" 983 objReg 12 "Objective already registered" 984 notYourObj 13 "Objective not registered by this ASA" 985 notObj 14 "Objective not found" 986 notNeg 15 "Objective not negotiable" 987 noSecurity 16 "No security" 988 noDiscReply 17 "No reply to discovery" 989 sockErrNegRq 18 "Socket error sending negotiation request" 990 noSession 19 "No session" 991 noSocket 20 "No socket" 992 loopExhausted 21 "Loop count exhausted" 993 sockErrNegStep 22 "Socket error sending negotiation step" 994 noPeer 23 "No negotiation peer" 995 CBORfail 24 "CBOR decode failure" 996 invalidNeg 25 "Invalid Negotiate message" 997 invalidEnd 26 "Invalid end message" 998 noNegReply 27 "No reply to negotiation step" 999 noValidStep 28 "No valid reply to negotiation step" 1000 sockErrWait 29 "Socket error sending wait message" 1001 sockErrEnd 30 "Socket error sending end message" 1002 IDclash 31 "Incoming request Session ID clash" 1003 notSynch 32 "Not a synchronization objective" 1004 notFloodDisc 33 "Not flooded and no reply to discovery" 1005 sockErrSynRq 34 "Socket error sending synch request" 1006 noListener 35 "No synch listener" 1007 noSynchReply 36 "No reply to synchronization request" 1008 noValidSynch 37 "No valid reply to synchronization request" 1009 invalidLoc 38 "Invalid locator" 1011 Appendix B. Change log [RFC Editor: Please remove] 1013 draft-liu-anima-grasp-api-05, 2017-10-02: 1015 Added send_invalid() 1017 draft-liu-anima-grasp-api-04, 2017-06-30: 1019 Noted that simple nodes might not include the API. 1021 Minor clarifications. 1023 draft-liu-anima-grasp-api-03, 2017-02-13: 1025 Changed error return to integers. 1027 Required all implementations to accept objective values in CBOR. 1029 Added non-blocking alternatives. 1031 draft-liu-anima-grasp-api-02, 2016-12-17: 1033 Updated for draft-ietf-anima-grasp-09 1035 draft-liu-anima-grasp-api-02, 2016-09-30: 1037 Added items for draft-ietf-anima-grasp-07 1039 Editorial corrections 1041 draft-liu-anima-grasp-api-01, 2016-06-24: 1043 Updated for draft-ietf-anima-grasp-05 1045 Editorial corrections 1047 draft-liu-anima-grasp-api-00, 2016-04-04: 1049 Initial version 1051 Authors' Addresses 1053 Brian Carpenter 1054 Department of Computer Science 1055 University of Auckland 1056 PB 92019 1057 Auckland 1142 1058 New Zealand 1060 Email: brian.e.carpenter@gmail.com 1061 Bing Liu (editor) 1062 Huawei Technologies 1063 Q22, Huawei Campus 1064 No.156 Beiqing Road 1065 Hai-Dian District, Beijing 100095 1066 P.R. China 1068 Email: leo.liubing@huawei.com 1070 Wendong Wang 1071 BUPT University 1072 Beijing University of Posts & Telecom. 1073 No.10 Xitucheng Road 1074 Hai-Dian District, Beijing 100876 1075 P.R. China 1077 Email: wdwang@bupt.edu.cn 1079 Xiangyang Gong 1080 BUPT University 1081 Beijing University of Posts & Telecom. 1082 No.10 Xitucheng Road 1083 Hai-Dian District, Beijing 100876 1084 P.R. China 1086 Email: xygong@bupt.edu.cn