idnits 2.17.1 draft-liu-anima-grasp-api-06.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 3 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 (November 24, 2017) is 2345 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC7749' is defined on line 1034, but no explicit reference was found in the text == Outdated reference: A later version (-30) exists of draft-ietf-anima-autonomic-control-plane-12 == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-09 == Outdated reference: A later version (-10) exists of draft-ietf-anima-reference-model-05 == 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: Informational B. Liu, Ed. 5 Expires: May 28, 2018 Huawei Technologies 6 W. Wang 7 X. Gong 8 BUPT University 9 November 24, 2017 11 Generic Autonomic Signaling Protocol Application Program Interface 12 (GRASP API) 13 draft-liu-anima-grasp-api-06 15 Abstract 17 This document is a conceptual outline of the application programming 18 interface (API) of the Generic Autonomic Signaling Protocol (GRASP). 19 Such an API is needed for Autonomic Service Agents (ASA) calling the 20 GRASP protocol module to exchange autonomic network messages with 21 other ASAs. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on May 28, 2018. 40 Copyright Notice 42 Copyright (c) 2017 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. GRASP API for ASA . . . . . . . . . . . . . . . . . . . . . . 3 59 2.1. Design Principles . . . . . . . . . . . . . . . . . . . . 3 60 2.2. Asynchronous Operations . . . . . . . . . . . . . . . . . 4 61 2.3. API definition . . . . . . . . . . . . . . . . . . . . . 6 62 2.3.1. Parameters and data structures . . . . . . . . . . . 6 63 2.3.2. Registration . . . . . . . . . . . . . . . . . . . . 9 64 2.3.3. Discovery . . . . . . . . . . . . . . . . . . . . . . 11 65 2.3.4. Negotiation . . . . . . . . . . . . . . . . . . . . . 12 66 2.3.5. Synchronization and Flooding . . . . . . . . . . . . 17 67 2.3.6. Invalid Message Function . . . . . . . . . . . . . . 20 68 3. Example Logic Flows . . . . . . . . . . . . . . . . . . . . . 21 69 4. Security Considerations . . . . . . . . . . . . . . . . . . . 21 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 71 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 72 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 73 7.1. Normative References . . . . . . . . . . . . . . . . . . 21 74 7.2. Informative References . . . . . . . . . . . . . . . . . 22 75 Appendix A. Error Codes . . . . . . . . . . . . . . . . . . . . 22 76 Appendix B. Change log [RFC Editor: Please remove] . . . . . . . 23 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 79 1. Introduction 81 As defined in [I-D.ietf-anima-reference-model], the Autonomic Service 82 Agent (ASA) is the atomic entity of an autonomic function; and it is 83 instantiated on autonomic nodes. When ASAs communicate with each 84 other, they should use the Generic Autonomic Signaling Protocol 85 (GRASP) [I-D.ietf-anima-grasp]. 87 As the following figure shows, GRASP could contain two major sub- 88 layers. The bottom is the GRASP base protocol module, which is only 89 responsible for sending and receiving GRASP messages and maintaining 90 shared data structures. The upper layer is some extended functions 91 based upon GRASP basic protocol. For example, 92 [I-D.liu-anima-grasp-distribution] describes a possible extended 93 function. 95 It is desirable that ASAs can be designed as portable user-space 96 programs using a portable API. In many operating systems, the GRASP 97 module will therefore be split into two layers, one being a library 98 that provides the API and the other being core code containing common 99 components such as multicast handling and the discovery cache. The 100 details of this are system-dependent. In particular, the GRASP 101 library might need to communicate with the GRASP core via an inter- 102 process communication (IPC) mechanism. 104 +----+ +----+ 105 |ASAs| |ASAs| 106 +----+ +----+ 107 | | 108 | GRASP Function API | 109 | | 110 +------------------+ |GRASP API 111 | GRASP Extended | | 112 | Function Modules | | 113 +------------------+ | 114 +------------------------------------------+ 115 | GRASP Library | 116 | GRASP Module - - - - - - - - - - - - - -| 117 | GRASP Core | 118 +------------------------------------------+ 120 Both the GRASP library and the extended function modules should be 121 available to the ASAs. Thus, there needs to be two sub-sets of API. 122 However, since the extended functions are expected to be added in an 123 incremental manner, it is inappropriate to define the function APIs 124 in a single document. This document only defines the base GRASP API. 126 Note that a very simple autonomic node might contain only a single 127 ASA in addition to the autonomic infrastructure components described 128 in [I-D.ietf-anima-bootstrapping-keyinfra] and 129 [I-D.ietf-anima-autonomic-control-plane]. Such a node might directly 130 integrate GRASP in its autonomic code and therefore not require this 131 API to be installed. 133 This document gives a conceptual outline of the API. It is not a 134 formal specification for any particular programming language or 135 operating system, and it is expected that details will be clarified 136 in individual implementations. 138 2. GRASP API for ASA 140 2.1. Design Principles 142 The assumption of this document is that any Autonomic Service Agent 143 (ASA) needs to call a GRASP module that handles protocol details 144 (security, sending and listening for GRASP messages, waiting, caching 145 discovery results, negotiation looping, sending and receiving 146 sychronization data, etc.) but understands nothing about individual 147 objectives. So this is a high level abstract API for use by ASAs. 148 Individual language bindings should be defined in separate documents. 150 An assumption of this API is that ASAs may fall into various classes: 152 o ASAs that only use GRASP for discovery purposes. 154 o ASAs that use GRASP negotiation but only as an initiator (client). 156 o ASAs that use GRASP negotiation but only as a responder. 158 o ASAs that use GRASP negotiation as an initiator or responder. 160 o ASAs that use GRASP synchronization but only as an initiator 161 (recipient). 163 o ASAs that use GRASP synchronization but only as a responder and/or 164 flooder. 166 o ASAs that use GRASP synchronization as an initiator, responder 167 and/or flooder. 169 The API also assumes that one ASA may support multiple objectives. 170 Nothing prevents an ASA from supporting some objectives for 171 synchronization and others for negotiation. 173 The API design assumes that the operating system and programming 174 language provide a mechanism for simultaneous asynchronous 175 operations. This is discussed in detail in Section 2.2. 177 This is a preliminary version. A few gaps exist: 179 o Authorization of ASAs is out of scope. 181 o User-supplied explicit locators for an objective are not 182 supported. 184 o The Rapid mode of GRASP is not supported. 186 2.2. Asynchronous Operations 188 GRASP includes asynchronous operations and wait states. Most ASAs 189 will need to support several simultaneous operations; for example an 190 ASA might need to negotiate one objective with a peer while 191 discovering and synchronizing a different objective with a different 192 peer. Alternatively, an ASA which acts as a resource manager might 193 need to run simultaneous negotiations for a given objective with 194 multiple different peers. Thus, both the GRASP core and most ASAs 195 need to support asynchronous operations. Depending on both the 196 operating system and the programming language in use, there are two 197 main techniques for such parallel operations: multi-threading, or a 198 polling or 'event loop' structure. 200 In multi-threading, the operating system and language will provide 201 the necessary support for asynchronous operations, including creation 202 of new threads, context switching between threads, queues, locks, and 203 implicit wait states. In this case, all API calls can be treated 204 naturally as synchronous, even if they include wait states, blocking 205 and queueing. 207 In an event loop implementation, synchronous blocking calls are not 208 acceptable. Therefore all calls must be non-blocking, and the main 209 loop will support multiple GRASP sessions in parallel by repeatedly 210 checking each one for a change of state. To facilitate this, the API 211 implementation will provide non-blocking versions of all the 212 functions that otherwise involve blocking and queueing. In these 213 calls, a 'noReply' code will be returned by each call instead of 214 blocking, until such time as the event for which it is waiting has 215 occurred. Thus, for example, discover() would return "noReply" 216 instead of waiting until discovery has succeeded or timed out. The 217 discover() call would be repeated in every cycle of the main loop 218 until it completes. A 'session_nonce' parameter (described below) is 219 used to distinguish simultaneous GRASP sessions from each other, so 220 that any number of sessions may proceed in parallel. 222 The following calls involve waiting for a remote operation, so they 223 use this mechanism: 225 discover() 227 request_negotiate() 229 negotiate_step() 231 listen_negotiate() 233 synchronize() 235 In all these calls, the 'session_nonce' is a read/write parameter. 236 On the first call, it is set to a null value, and the API returns the 237 'noReply' code and a non-null value. This value must be used in all 238 subsequent calls. By this mechanism, multiple overlapping sessions 239 can be distinguished. 241 2.3. API definition 243 2.3.1. Parameters and data structures 245 This section describes parameters and data structures uaed in 246 multiple API calls. 248 2.3.1.1. Errorcode 250 All functions in the API have an unsigned 'errorcode' integer as 251 their return value (the first returned value in languages that allow 252 multiple returned parameters). An errorcode of zero indicates 253 success. Any other value indicates failure of some kind. The first 254 three errorcodes have special importance: 256 1. Declined: used to indicate that the other end has sent a GRASP 257 Negotiation End message (M_END) with a Decline option 258 (O_DECLINE). 260 2. No reply: used in non-blocking calls to indicate that the other 261 end has sent no reply so far (see Section 2.2). 263 3. Unspecified error: used when no more specific error code applies. 265 Appendix A gives a full list of currently defined error codes. 267 2.3.1.2. Timeout 269 Wherever a 'timeout' parameter appears, it is an integer expressed in 270 milliseconds. If it is zero, the GRASP default timeout 271 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]) will apply. If no 272 response is received before the timeout expires, the call will fail 273 unless otherwise noted. 275 2.3.1.3. Objective 277 An 'objective' parameter is a data structure with the following 278 components: 280 o name (UTF-8 string) - the objective's name 282 o neg (Boolean flag) - True if objective supports negotiation 283 (default False) 285 o synch (Boolean flag) - True if objective supports synchronization 286 (default False) 288 o dry (Boolean flag) - True if objective supports dry-run 289 synchronization (default False) 291 * Note 1: All objectives are assumed to support discovery, so 292 there is no Boolean for that. 294 * Note 2: Only one of 'synch' or 'neg' may be True. 296 * Note 3: 'dry' must not be True unless 'neg' is also True. 298 o loop_count (integer) - Limit on negotiation steps etc. (default 299 GRASP_DEF_LOOPCT, see [I-D.ietf-anima-grasp]) 301 o value - a specific data structure expressing the value of the 302 objective. The format is language dependent, with the constraint 303 that it can be validly represented in CBOR (default integer = 0). 305 An essential requirement for all language mappings and all 306 implementations is that, regardless of what other options exist 307 for a language-specific represenation of the value, there is 308 always an option to use a CBOR byte string as the value. The API 309 will then wrap this byte string in CBOR Tag 24 for transmission 310 via GRASP, and unwrap it after reception. 312 An example data structure definition for an objective in the C 313 language is: 315 typedef struct { 316 char *name; 317 uint8_t flags; // flag bits as defined by GRASP 318 int loop_count; 319 int value_size; // size of value 320 uint8_t cbor_value[]; // CBOR bytestring of value 321 } objective; 323 An example data structure definition for an objective in the 324 Python language is: 326 class objective: 327 """A GRASP objective""" 328 def __init__(self, name): 329 self.name = name #Unique name, string 330 self.neg = False #True if objective supports negotiation 331 self.dry = False #True if objective supports dry-run negotiation 332 self.synch = False #True if objective supports synch 333 self.loop_count = GRASP_DEF_LOOPCT #Default starting value 334 self.value = 0 #Place holder; any valid Python object 336 2.3.1.4. ASA_locator 338 An 'ASA_locator' parameter is a data structure with the following 339 contents: 341 o locator - The actual locator, either an IP address or an ASCII 342 string. 344 o ifi (integer) - The interface identifier index via which this was 345 discovered - probably no use to a normal ASA 347 o expire (system dependent type) - The time on the local system 348 clock when this locator will expire from the cache 350 o is_ipaddress (Boolean) - True if the locator is an IP address 352 o is_fqdn (Boolean) - True if the locator is an FQDN 354 o is_uri (Boolean) - True if the locator is a URI 356 o diverted (Boolean) - True if the locator was discovered via a 357 Divert option 359 o protocol (integer) - Applicable transport protocol (IPPROTO_TCP or 360 IPPROTO_UDP) 362 o port (integer) - Applicable port number 364 2.3.1.5. Tagged_objective 366 A 'tagged_objective' parameter is a data structure with the following 367 contents: 369 o objective - An objective 371 o locator - The ASA_locator associated with the objective, or a null 372 value. 374 2.3.1.6. Asa_nonce 376 In most calls, an 'asa_nonce' parameter is required. It is generated 377 when an ASA registers with GRASP, and any call in which an invalid 378 nonce is presented will fail. It is an up to 32-bit opaque value 379 (for example represented as a uint32_t, depending on the language). 380 It should be unpredictable; a possible implementation is to use the 381 same mechanism that GRASP uses to generate Session IDs 382 [I-D.ietf-anima-grasp]. Another possible implementation is to hash 383 the name of the ASA with a locally defined secret key. 385 2.3.1.7. Session_nonce 387 In some calls, a 'session_nonce' parameter is required. This is an 388 opaque data structure as far as the ASA is concerned, used to 389 identify calls to the API as belonging to a specific GRASP session 390 (see Section 2.2). In fully threaded implementations this parameter 391 might not be needed, but it is included to act as a session handle if 392 necessary. It will also allow GRASP to detect and ignore malicious 393 calls or calls from timed-out sessions. A possible implementation is 394 to form the nonce from the underlying GRASP Session ID and the source 395 address of the session. 397 2.3.2. Registration 399 These functions are used to register an ASA and the objectives that 400 it supports with the GRASP module. If an authorization model is 401 added to GRASP, it would be added here. 403 o register_asa() 405 Input parameter: 407 name of the ASA (UTF-8 string) 409 Return parameters: 411 errorcode (integer) 413 asa_nonce (integer) (if successful) 415 This initialises state in the GRASP module for the calling 416 entity (the ASA). In the case of success, an 'asa_nonce' is 417 returned which the ASA must present in all subsequent calls. 418 In the case of failure, the ASA has not been authorized and 419 cannot operate. 421 o deregister_asa() 423 Input parameters: 425 asa_nonce (integer) 427 name of the ASA (UTF-8 string) 429 Return parameter: 431 errorcode (integer) 433 This removes all state in the GRASP module for the calling 434 entity (the ASA), and deregisters any objectives it has 435 registered. Note that these actions must also happen 436 automatically if an ASA crashes. 438 Note - the ASA name is strictly speaking redundant in this 439 call, but is present for clarity. 441 o register_objective() 443 Input parameters: 445 asa_nonce (integer) 447 objective (structure) 449 ttl (integer - default GRASP_DEF_TIMEOUT) 451 discoverable (Boolean - default False) 453 overlap (Boolean - default False) 455 local (Boolean - default False) 457 Return parameter: 459 errorcode (integer) 461 This registers an objective that this ASA supports and may 462 modify. The 'objective' becomes a candidate for discovery. 463 However, discovery responses should not be enabled until the 464 ASA calls listen_negotiate() or listen_synchronize(), showing 465 that it is able to act as a responder. The ASA may negotiate 466 the objective or send synchronization or flood data. 467 Registration is not needed if the ASA only wants to receive 468 synchronization or flood data for the objective concerned. 470 The 'ttl' parameter is the valid lifetime (time to live) in 471 milliseconds of any discovery response for this objective. The 472 default value should be the GRASP default timeout 473 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]). 475 If the optional parameter 'discoverable' is True, the objective 476 is immediately discoverable. This is intended for objectives 477 that are only defined for GRASP discovery, and which do not 478 support negotiation or synchronization. 480 If the optional parameter 'overlap' is True, more than one ASA 481 may register this objective in the same GRASP instance. 483 If the optional parameter 'local' is True, discovery must 484 return a link-local address. This feature is for objectives 485 that must be restricted to the local link. 487 This call may be repeated for multiple objectives. 489 o deregister_objective() 491 Input parameters: 493 asa_nonce (integer) 495 objective (structure) 497 Return parameter: 499 errorcode (integer) 501 The 'objective' must have been registered by the calling ASA; 502 if not, this call fails. Otherwise, it removes all state in 503 the GRASP module for the given objective. 505 2.3.3. Discovery 507 o discover() 509 Input parameters: 511 asa_nonce (integer) 513 objective (structure) 515 timeout (integer) 517 flush (Boolean - default False) 519 Return parameters: 521 errorcode (integer) 523 locator_list (structure) 525 This returns a list of discovered 'ASA_locator's for the given 526 objective. If the optional parameter 'flush' is True, any 527 locally cached locators for the objective are deleted first. 529 Otherwise, they are returned immediately. If not, GRASP 530 discovery is performed, and all results obtained before the 531 timeout expires are returned. If no results are obtained, an 532 empty list is returned after the timeout. That is not an error 533 condition. 535 Threaded implementation: This should be called in a separate 536 thread if asynchronous operation is required. 538 Event loop implementation: An additional read/write 539 'session_nonce' parameter is used. 541 2.3.4. Negotiation 543 o request_negotiate() 545 Input parameters: 547 asa_nonce (integer) 549 objective (structure) 551 peer (ASA_locator) 553 timeout (integer) 555 Return parameters: 557 errorcode (integer) 559 session_nonce (structure) (if successful) 561 proffered_objective (structure) (if successful) 563 reason (string) (if negotiation declined) 565 This function opens a negotiation session. The 'objective' 566 parameter must include the requested value, and its loop count 567 should be set to a suitable value by the ASA. If not, the 568 GRASP default will apply. 570 Note that a given negotiation session may or may not be a dry- 571 run negotiation; the two modes must not be mixed in a single 572 session. 574 The 'peer' parameter is the target node; it must be an 575 'ASA_locator' as returned by discover(). If the peer is null, 576 GRASP discovery is performed first. 578 If the 'errorcode' return parameter is 0, the negotiation has 579 successfully started. There are then two cases: 581 1. The 'session_nonce' parameter is null. In this case the 582 negotiation has succeeded (the peer has accepted the 583 request). The returned 'proffered_objective' contains the 584 value accepted by the peer. 586 2. The 'session_nonce' parameter is not null. In this case 587 negotiation must continue. The returned 588 'proffered_objective' contains the first value proffered by 589 the negotiation peer. Note that this instance of the 590 objective must be used in the subsequent negotiation call 591 because it also contains the current loop count. The 592 'session_nonce' must be presented in all subsequent 593 negotiation steps. 595 This function must be followed by calls to 'negotiate_step' 596 and/or 'negotiate_wait' and/or 'end_negotiate' until the 597 negotiation ends. 'request_negotiate' may then be called 598 again to start a new negotation. 600 If the 'errorcode' parameter has the value 1 ('declined'), the 601 negotiation has been declined by the peer (M_END and O_DECLINE 602 features of GRASP). The 'reason' string is then available for 603 information and diagnostic use, but it may be a null string. 604 For this and any other error code, an exponential backoff is 605 recommended before any retry. 607 Threaded implementation: This should be called in a separate 608 thread if asynchronous operation is required. 610 Event loop implementation: The 'session_nonce' parameter is 611 used in read/write mode. 613 Special note for the ACP infrastructure ASA: It is likely that 614 this ASA will need to discover and negotiate with its peers in 615 each of its on-link neighbors. It will therefore need to know 616 not only the link-local IP address but also the physical 617 interface and transport port for connecting to each neighbor. 618 One implementation approach to this is to include these details 619 in the 'session_nonce' data structure, which is opaque to 620 normal ASAs. 622 o listen_negotiate() 624 Input parameters: 626 asa_nonce (integer) 628 objective (structure) 630 Return parameters: 632 errorcode (integer) 634 session_nonce (structure) (if successful) 636 requested_objective (structure) (if successful) 638 This function instructs GRASP to listen for negotiation 639 requests for the given 'objective'. It also enables discovery 640 responses for the objective. 642 Threaded implementation: It will block waiting for an incoming 643 request, so should be called in a separate thread if 644 asynchronous operation is required. 646 Event loop implementation: A read/write 'session_nonce' 647 parameter is used. 649 Unless there is an unexpected failure, this call only returns 650 after an incoming negotiation request. When it does so, 651 'requested_objective' contains the first value requested by the 652 negotiation peer. Note that this instance of the objective 653 must be used in the subsequent negotiation call because it also 654 contains the current loop count. The 'session_nonce' must be 655 presented in all subsequent negotiation steps. 657 This function must be followed by calls to 'negotiate_step' 658 and/or 'negotiate_wait' and/or 'end_negotiate' until the 659 negotiation ends. 'listen_negotiate' may then be called again 660 to await a new negotation. 662 If an ASA is capable of handling multiple negotiations 663 simultaneously, it may call 'listen_negotiate' simultaneously 664 from multiple threads. The API and GRASP implementation must 665 support re-entrant use of the listening state and the 666 negotiation calls. Simultaneous sessions will be distinguished 667 by the threads themselves, the GRASP Session IDs, and the 668 underlying unicast transport sockets. 670 o stop_listen_negotiate() 672 Input parameters: 674 asa_nonce (integer) 676 objective (structure) 678 Return parameter: 680 errorcode (integer) 682 Instructs GRASP to stop listening for negotiation requests for 683 the given objective, i.e., cancels 'listen_negotiate'. 685 Threaded implementation: Must be called from a different thread 686 than 'listen_negotiate'. 688 Event loop implementation: no special considerations. 690 o negotiate_step() 692 Input parameters: 694 asa_nonce (integer) 696 session_nonce (structure) 698 objective (structure) 700 timeout (integer) 702 Return parameters: 704 Exactly as for 'request_negotiate' 706 Executes the next negotation step with the peer. The 707 'objective' parameter contains the next value being proffered 708 by the ASA in this step. 710 Threaded implementation: Called in the same thread as the 711 preceding 'request_negotiate' or 'listen_negotiate', with the 712 same value of 'session_nonce'. 714 Event loop implementation: Must use the same value of 715 'session_nonce' returned by the preceding 'request_negotiate' 716 or 'listen_negotiate'. 718 o negotiate_wait() 720 Input parameters: 722 asa_nonce (integer) 724 session_nonce (structure) 726 timeout (integer) 728 Return parameters: 730 errorcode (integer) 732 Delay negotiation session by 'timeout' milliseconds. 734 Threaded implementation: Called in the same thread as the 735 preceding 'request_negotiate' or 'listen_negotiate', with the 736 same value of 'session_nonce'. 738 Event loop implementation: Must use the same value of 739 'session_nonce' returned by the preceding 'request_negotiate' 740 or 'listen_negotiate'. 742 o end_negotiate() 744 Input parameters: 746 asa_nonce (integer) 748 session_nonce (structure) 750 reply (Boolean) 752 reason (UTF-8 string) 754 Return parameters: 756 errorcode (integer) 758 End the negotiation session. 760 'reply' = True for accept (successful negotiation), False for 761 decline (failed negotiation). 763 'reason' = optional string describing reason for decline. 765 Threaded implementation: Called in the same thread as the 766 preceding 'request_negotiate' or 'listen_negotiate', with the 767 same value of 'session_nonce'. 769 Event loop implementation: Must use the same value of 770 'session_nonce' returned by the preceding 'request_negotiate' 771 or 'listen_negotiate'. 773 2.3.5. Synchronization and Flooding 775 o synchronize() 777 Input parameters: 779 asa_nonce (integer) 781 objective (structure) 783 peer (ASA_locator) 785 timeout (integer) 787 Return parameters: 789 errorcode (integer) 791 objective (structure) (if successful) 793 This call requests the synchronized value of the given 794 'objective'. 796 Since this is essentially a read operation, any ASA can do it. 797 Therefore the API checks that the ASA is registered but the 798 objective doesn't need to be registered by the calling ASA. 800 If the objective was already flooded, the flooded value is 801 returned immediately in the 'result' parameter. In this case, 802 the 'source' and 'timeout' are ignored. 804 Otherwise, synchronization with a discovered ASA is performed. 805 The 'peer' parameter is an 'ASA_locator' as returned by 806 discover(). If 'peer' is null, GRASP discovery is performed 807 first. 809 This call should be repeated whenever the latest value is 810 needed. 812 Threaded implementation: Call in a separate thread if 813 asynchronous operation is required. 815 Event loop implementation: An additional read/write 816 'session_nonce' parameter is used. 818 Since this is essentially a read operation, any ASA can use it. 819 Therefore GRASP checks that the calling ASA is registered but 820 the objective doesn't need to be registered by the calling ASA. 822 In the case of failure, an exponential backoff is recommended 823 before retrying. 825 o listen_synchronize() 827 Input parameters: 829 asa_nonce (integer) 831 objective (structure) 833 Return parameters: 835 errorcode (integer) 837 This instructs GRASP to listen for synchronization requests for 838 the given objective, and to respond with the value given in the 839 'objective' parameter. It also enables discovery responses for 840 the objective. 842 This call is non-blocking and may be repeated whenever the 843 value changes. 845 o stop_listen_synchronize() 847 Input parameters: 849 asa_nonce (integer) 851 objective (structure) 853 Return parameters: 855 errorcode (integer) 857 This call instructs GRASP to stop listening for synchronization 858 requests for the given 'objective', i.e. it cancels a previous 859 listen_synchronize. 861 o flood() 863 Input parameters: 865 asa_nonce (integer) 866 ttl (integer) 868 tagged_objective_list (structure) 870 Return parameters: 872 errorcode (integer) 874 This call instructs GRASP to flood the given synchronization 875 objective(s) and their value(s) and associated locator(s) to 876 all GRASP nodes. 878 The 'ttl' parameter is the valid lifetime (time to live) of the 879 flooded data in milliseconds (0 = infinity) 881 The 'tagged_objective_list' parameter is a list of one or more 882 'tagged_objective' couplets. The 'locator' parameter that tags 883 each objective is normally null but may be a valid 884 'ASA_locator'. Infrastructure ASAs needing to flood an 885 {address, protocol, port} 3-tuple with an objective create an 886 ASA_locator object to do so. If the IP address in that locator 887 is the unspecified address ('::') it is replaced by the link- 888 local address of the sending node in each copy of the flood 889 multicast, which will be forced to have a loop count of 1. 890 This feature is for objectives that must be restricted to the 891 local link. 893 The function checks that the ASA registered each objective. 895 This call may be repeated whenever any value changes. 897 o get_flood() 899 Input parameters: 901 asa_nonce (integer) 903 objective (structure) 905 Return parameters: 907 errorcode (integer) 909 tagged_objective_list (structure) (if successful) 911 This call instructs GRASP to return the given synchronization 912 objective if it has been flooded and its lifetime has not 913 expired. 915 Since this is essentially a read operation, any ASA can do it. 916 Therefore the API checks that the ASA is registered but the 917 objective doesn't need to be registered by the calling ASA. 919 The 'tagged_objective_list' parameter is a list of 920 'tagged_objective' couplets, each one being a copy of the 921 flooded objective and a coresponding locator. Thus if the same 922 objective has been flooded by multiple ASAs, the recipient can 923 distinguish the copies. 925 Note that this call is for advanced ASAs. In a simple case, an 926 ASA can simply call synchronize() in order to get a valid 927 flooded objective. 929 o expire_flood() 931 Input parameters: 933 asa_nonce (integer) 935 tagged_objective (structure) 937 Return parameters: 939 errorcode (integer) 941 This is a call that can only be used after a preceding call to 942 get_flood() by an ASA that is capable of deciding that the 943 flooded value is stale or invalid. Use with care. 945 The 'tagged_objective' parameter is the one to be expired. 947 2.3.6. Invalid Message Function 949 o send_invalid() 951 Input parameters: 953 asa_nonce (integer) 955 session_nonce (structure) 957 info (bytes) 959 Return parameters: 961 errorcode (integer) 963 Sends a GRASP Invalid Message (M_INVALID) message, as described 964 in [I-D.ietf-anima-grasp]. Should not be used if 965 end_negotiate() would be sufficient. Note that this message 966 may be used in response to any unicast GRASP message that the 967 receiver cannot interpret correctly. In most cases this 968 message will be generated internally by a GRASP implementation. 970 'info' = optional diagnostic data. May be raw bytes from the 971 invalid message. 973 3. Example Logic Flows 975 TBD 977 (Until this section is written, some Python examples can be found at 978 .) 980 4. Security Considerations 982 Security issues for the GRASP protocol are discussed in 983 [I-D.ietf-anima-grasp]. Authorization of ASAs is a subject for 984 future study. 986 The 'asa_nonce' parameter is used in the API as a first line of 987 defence against a malware process attempting to imitate a 988 legitimately registered ASA. The 'session_nonce' parameter is used 989 in the API as a first line of defence against a malware process 990 attempting to hijack a GRASP session. 992 5. IANA Considerations 994 This document does not need IANA assignments. 996 6. Acknowledgements 998 Excellent suggestions were made by Michael Richardson and other 999 participansts in the ANIMA WG. 1001 7. References 1003 7.1. Normative References 1005 [I-D.ietf-anima-grasp] 1006 Bormann, C., Carpenter, B., and B. Liu, "A Generic 1007 Autonomic Signaling Protocol (GRASP)", draft-ietf-anima- 1008 grasp-15 (work in progress), July 2017. 1010 7.2. Informative References 1012 [I-D.ietf-anima-autonomic-control-plane] 1013 Behringer, M., Eckert, T., and S. Bjarnason, "An Autonomic 1014 Control Plane (ACP)", draft-ietf-anima-autonomic-control- 1015 plane-12 (work in progress), October 2017. 1017 [I-D.ietf-anima-bootstrapping-keyinfra] 1018 Pritikin, M., Richardson, M., Behringer, M., Bjarnason, 1019 S., and K. Watsen, "Bootstrapping Remote Secure Key 1020 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 1021 keyinfra-09 (work in progress), October 2017. 1023 [I-D.ietf-anima-reference-model] 1024 Behringer, M., Carpenter, B., Eckert, T., Ciavaglia, L., 1025 Pierre, P., Liu, B., Nobre, J., and J. Strassner, "A 1026 Reference Model for Autonomic Networking", draft-ietf- 1027 anima-reference-model-05 (work in progress), October 2017. 1029 [I-D.liu-anima-grasp-distribution] 1030 Liu, B. and S. Jiang, "Information Distribution over 1031 GRASP", draft-liu-anima-grasp-distribution-04 (work in 1032 progress), May 2017. 1034 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 1035 RFC 7749, DOI 10.17487/RFC7749, February 2016, 1036 . 1038 Appendix A. Error Codes 1040 This Appendix lists the error codes defined so far, with suggested 1041 symbolic names and corresponding descriptive strings in English. It 1042 is expected that complete API implementations will provide for 1043 localisation of these descriptive strings. 1045 ok 0 "OK" 1046 declined 1 "Declined" 1047 noReply 2 "No reply" 1048 unspec 3 "Unspecified error" 1049 ASAfull 4 "ASA registry full" 1050 dupASA 5 "Duplicate ASA name" 1051 noASA 6 "ASA not registered" 1052 notYourASA 7 "ASA registered but not by you" 1053 notBoth 8 "Objective cannot support both negotiation 1054 and synchronization" 1055 notDry 9 "Dry-run allowed only with negotiation" 1056 notOverlap 10 "Overlap not supported by this implementation" 1057 objFull 11 "Objective registry full" 1058 objReg 12 "Objective already registered" 1059 notYourObj 13 "Objective not registered by this ASA" 1060 notObj 14 "Objective not found" 1061 notNeg 15 "Objective not negotiable" 1062 noSecurity 16 "No security" 1063 noDiscReply 17 "No reply to discovery" 1064 sockErrNegRq 18 "Socket error sending negotiation request" 1065 noSession 19 "No session" 1066 noSocket 20 "No socket" 1067 loopExhausted 21 "Loop count exhausted" 1068 sockErrNegStep 22 "Socket error sending negotiation step" 1069 noPeer 23 "No negotiation peer" 1070 CBORfail 24 "CBOR decode failure" 1071 invalidNeg 25 "Invalid Negotiate message" 1072 invalidEnd 26 "Invalid end message" 1073 noNegReply 27 "No reply to negotiation step" 1074 noValidStep 28 "No valid reply to negotiation step" 1075 sockErrWait 29 "Socket error sending wait message" 1076 sockErrEnd 30 "Socket error sending end message" 1077 IDclash 31 "Incoming request Session ID clash" 1078 notSynch 32 "Not a synchronization objective" 1079 notFloodDisc 33 "Not flooded and no reply to discovery" 1080 sockErrSynRq 34 "Socket error sending synch request" 1081 noListener 35 "No synch listener" 1082 noSynchReply 36 "No reply to synchronization request" 1083 noValidSynch 37 "No valid reply to synchronization request" 1084 invalidLoc 38 "Invalid locator" 1086 Appendix B. Change log [RFC Editor: Please remove] 1088 draft-liu-anima-grasp-api-06, 2017-11-24: 1090 Improved description of event-loop model. 1092 Changed intended status to Informational. 1094 Editorial improvements. 1096 draft-liu-anima-grasp-api-05, 2017-10-02: 1098 Added send_invalid() 1100 draft-liu-anima-grasp-api-04, 2017-06-30: 1102 Noted that simple nodes might not include the API. 1104 Minor clarifications. 1106 draft-liu-anima-grasp-api-03, 2017-02-13: 1108 Changed error return to integers. 1110 Required all implementations to accept objective values in CBOR. 1112 Added non-blocking alternatives. 1114 draft-liu-anima-grasp-api-02, 2016-12-17: 1116 Updated for draft-ietf-anima-grasp-09 1118 draft-liu-anima-grasp-api-02, 2016-09-30: 1120 Added items for draft-ietf-anima-grasp-07 1122 Editorial corrections 1124 draft-liu-anima-grasp-api-01, 2016-06-24: 1126 Updated for draft-ietf-anima-grasp-05 1128 Editorial corrections 1130 draft-liu-anima-grasp-api-00, 2016-04-04: 1132 Initial version 1134 Authors' Addresses 1135 Brian Carpenter 1136 Department of Computer Science 1137 University of Auckland 1138 PB 92019 1139 Auckland 1142 1140 New Zealand 1142 Email: brian.e.carpenter@gmail.com 1144 Bing Liu (editor) 1145 Huawei Technologies 1146 Q22, Huawei Campus 1147 No.156 Beiqing Road 1148 Hai-Dian District, Beijing 100095 1149 P.R. China 1151 Email: leo.liubing@huawei.com 1153 Wendong Wang 1154 BUPT University 1155 Beijing University of Posts & Telecom. 1156 No.10 Xitucheng Road 1157 Hai-Dian District, Beijing 100876 1158 P.R. China 1160 Email: wdwang@bupt.edu.cn 1162 Xiangyang Gong 1163 BUPT University 1164 Beijing University of Posts & Telecom. 1165 No.10 Xitucheng Road 1166 Hai-Dian District, Beijing 100876 1167 P.R. China 1169 Email: xygong@bupt.edu.cn