idnits 2.17.1 draft-ietf-anima-grasp-api-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (4 January 2021) is 1207 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-07) exists of draft-ietf-anima-asa-guidelines-00 == Outdated reference: A later version (-11) exists of draft-ietf-anima-grasp-distribution-01 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. E. Carpenter 3 Internet-Draft Univ. of Auckland 4 Intended status: Informational B. Liu, Ed. 5 Expires: 8 July 2021 Huawei Technologies 6 W. Wang 7 X. Gong 8 BUPT University 9 4 January 2021 11 Generic Autonomic Signaling Protocol Application Program Interface 12 (GRASP API) 13 draft-ietf-anima-grasp-api-10 15 Abstract 17 This document is a conceptual outline of an application programming 18 interface (API) for the Generic Autonomic Signaling Protocol (GRASP). 19 Such an API is needed for Autonomic Service Agents (ASA) calling the 20 GRASP protocol module to exchange autonomic network messages with 21 other ASAs. Since GRASP is designed to support asynchronous 22 operations, the API will need to be adapted according to the support 23 for asynchronicity in various programming languages and operating 24 systems. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on 8 July 2021. 43 Copyright Notice 45 Copyright (c) 2021 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Simplified BSD License text 54 as described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. GRASP API for ASA . . . . . . . . . . . . . . . . . . . . . . 5 61 2.1. Design Assumptions . . . . . . . . . . . . . . . . . . . 5 62 2.2. Asynchronous Operations . . . . . . . . . . . . . . . . . 6 63 2.2.1. Alternative Asynchronous Mechanisms . . . . . . . . . 6 64 2.2.2. Multiple Negotiation Scenario . . . . . . . . . . . . 7 65 2.2.3. Overlapping Sessions and Operations . . . . . . . . . 8 66 2.2.4. Session Termination . . . . . . . . . . . . . . . . . 9 67 2.3. API definition . . . . . . . . . . . . . . . . . . . . . 9 68 2.3.1. Overview of Functions . . . . . . . . . . . . . . . . 9 69 2.3.2. Parameters and data structures . . . . . . . . . . . 10 70 2.3.3. Registration . . . . . . . . . . . . . . . . . . . . 15 71 2.3.4. Discovery . . . . . . . . . . . . . . . . . . . . . . 17 72 2.3.5. Negotiation . . . . . . . . . . . . . . . . . . . . . 19 73 2.3.6. Synchronization and Flooding . . . . . . . . . . . . 26 74 2.3.7. Invalid Message Function . . . . . . . . . . . . . . 31 75 3. Implementation Status [RFC Editor: please remove] . . . . . . 31 76 4. Security Considerations . . . . . . . . . . . . . . . . . . . 31 77 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 78 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 33 79 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 80 7.1. Normative References . . . . . . . . . . . . . . . . . . 33 81 7.2. Informative References . . . . . . . . . . . . . . . . . 33 82 Appendix A. Error Codes . . . . . . . . . . . . . . . . . . . . 34 83 Appendix B. Change log [RFC Editor: Please remove] . . . . . . . 36 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 86 1. Introduction 88 As defined in [I-D.ietf-anima-reference-model], the Autonomic Service 89 Agent (ASA) is the atomic entity of an autonomic function, and it is 90 instantiated on autonomic nodes. These nodes are members of a secure 91 Autonomic Control Plane (ACP) such as defined by 92 [I-D.ietf-anima-autonomic-control-plane]. 94 When ASAs communicate with each other, they should use the Generic 95 Autonomic Signaling Protocol (GRASP) [I-D.ietf-anima-grasp]. GRASP 96 relies on the message confidentiality and integrity provided by the 97 ACP, with the consequence that all nodes in a given autonomic network 98 share the same trust boundary, i.e., the boundary of the ACP. Nodes 99 that have not successfully joined the ACP cannot send, receive or 100 intercept GRASP messages via the ACP, and cannot usurp ACP addresses. 101 An ASA runs in an ACP node and therefore benefits from the node's 102 security properties when transmitting over the ACP, i.e., message 103 integrity, message confidentiality and the fact that unauthorized 104 nodes cannot join the ACP. All ASAs within a given autonomic network 105 therefore trust each other's messages. For these reasons, the API 106 defined in this document has no explicit security features. 108 An important feature of GRASP is the concept of a GRASP objective. 109 This is a data structure encoded, like all GRASP messages, in CBOR 110 [RFC8949]. Its main contents are a name and a value, explained at 111 more length in the 'Terminology' section of [I-D.ietf-anima-grasp]. 112 When an objective is passed from one ASA to another using GRASP, its 113 value is either conveyed in one direction (by a process of 114 synchronization or flooding), or negotiated bilaterally. The 115 semantics of the value are opaque to GRASP and therefore to the API. 116 Each objective must be accurately specified in a dedicated 117 specification, as discussed in the 'Objective Options' section of 118 [I-D.ietf-anima-grasp]. In particular, the specification will define 119 the syntax and semantics of the value of the objective, whether and 120 how it supports a negotiation process, whether it supports a dry run 121 mode, and any other details needed for interoperability. The use of 122 CBOR, with CDDL [RFC8610] as the data definition language, allows the 123 value to be passed between ASAs regardless of the programming 124 languages in use. Data storage and consistency during negotiation 125 are the responsibility of the ASAs involved. Additionally, GRASP 126 needs to cache the latest values of objectives that are received by 127 flooding. 129 As Figure 1 shows, a GRASP implementation could contain several sub- 130 layers. The bottom layer is the GRASP base protocol module, which is 131 only responsible for sending and receiving GRASP messages and 132 maintaining shared data structures. Above that is the basic API 133 described in this document. The upper layer contains some extended 134 API functions based upon GRASP basic protocol. For example, 135 [I-D.ietf-anima-grasp-distribution] describes a possible extended 136 function. 138 +--------------+ +--------------+ 139 | ASAs | | ASAs | 140 +--------------+ +--------------+ 141 | | | 142 | +------------------+ | 143 | | GRASP Extended | | 144 | | Function API | | 145 | +------------------+ | 146 | | | 147 +------------------------------------------+ 148 | Basic GRASP API Library | 149 +------------------------------------------+ 150 | 151 IPC or system call 152 | 153 +------------------------------------------+ 154 | GRASP Core | 155 | (functions, data structures, daemon(s)) | 156 +------------------------------------------+ 158 Figure 1: Software layout 160 Multiple ASAs in a single node will share the same instance of GRASP, 161 much as multiple applications share a single TCP/IP stack. This 162 aspect is hidden from individual ASAs by the API, and is not further 163 discussed here. 165 It is desirable that ASAs can be designed as portable user-space 166 programs using a system-independent API. In many implementations, 167 the GRASP code will therefore be split between user space and kernel 168 space. In user space, library functions provide the API and 169 communicate directly with ASAs. In kernel space is a daemon, or a 170 set of sub-services, providing GRASP core functions that are 171 independent of specific ASAs, such as multicast handling and 172 relaying, and common data structures such as the discovery cache. 173 The GRASP API library would need to communicate with the GRASP core 174 via an inter-process communication (IPC) or system call mechanism. 175 The details of this are system-dependent. 177 Both the GRASP library and the extended function modules should be 178 available to the ASAs. However, since the extended functions are 179 expected to be added in an incremental manner, they will be the 180 subject of future documents. This document only describes the basic 181 GRASP API. 183 The functions provided by the API do not map one-to-one onto GRASP 184 messages. Rather, they are intended to offer convenient support for 185 message sequences (such as a discovery request followed by responses 186 from several peers, or a negotiation request followed by various 187 possible responses). This choice was made to assist ASA programmers 188 in writing code based on their application requirements rather than 189 needing to understand protocol details. 191 Note that a simple autonomic node might contain very few ASAs in 192 addition to the autonomic infrastructure components described in 193 [I-D.ietf-anima-bootstrapping-keyinfra] and 194 [I-D.ietf-anima-autonomic-control-plane]. Such a node might directly 195 integrate a GRASP protocol stack in its code and therefore not 196 require this API to be installed. However, the programmer would then 197 need a deeper understanding of the GRASP protocol than is needed to 198 use the API. 200 This document gives a conceptual outline of the API. It is not a 201 formal specification for any particular programming language or 202 operating system, and it is expected that details will be clarified 203 in individual implementations. 205 2. GRASP API for ASA 207 2.1. Design Assumptions 209 The assumption of this document is that an Autonomic Service Agent 210 (ASA) needs to call a separate GRASP implementation. The latter 211 handles protocol details (security, sending and listening for GRASP 212 messages, waiting, caching discovery results, negotiation looping, 213 sending and receiving sychronization data, etc.) but understands 214 nothing about individual GRASP objectives (Section 2.10 of 215 [I-D.ietf-anima-grasp]). The semantics of objectives are unknown to 216 the GRASP protocol and are handled only by the ASAs. Thus, this is 217 an abstract API for use by ASAs. Individual language bindings should 218 be defined in separate documents. 220 Different ASAs may make different use of GRASP features, such as: 222 * Use GRASP only for discovery purposes. 224 * Use GRASP negotiation but only as an initiator (client). 226 * Use GRASP negotiation but only as a responder. 228 * Use GRASP negotiation as an initiator or responder. 230 * Use GRASP synchronization but only as an initiator (recipient). 232 * Use GRASP synchronization but only as a responder and/or flooder. 234 * Use GRASP synchronization as an initiator, responder and/or 235 flooder. 237 The API also assumes that one ASA may support multiple objectives. 238 Nothing prevents an ASA from supporting some objectives for 239 synchronization and others for negotiation. 241 The API design assumes that the operating system and programming 242 language provide a mechanism for simultaneous asynchronous 243 operations. This is discussed in detail in Section 2.2. 245 A few items are out of scope in this version, since practical 246 experience is required before including them: 248 * Authorization of ASAs is not defined as part of GRASP and is a 249 subject for future study. 251 * User-supplied explicit locators for an objective are not 252 supported. The GRASP core will supply the locator, using the IP 253 address of the node concerned. 255 * The Rapid mode of GRASP (Section 2.5.4 of [I-D.ietf-anima-grasp]) 256 is not supported. 258 2.2. Asynchronous Operations 260 GRASP depends on asynchronous operations and wait states, and some of 261 its messages are not idempotent, meaning that repeating a message may 262 cause repeated changes of state in the recipient ASA. Many ASAs will 263 need to support several concurrent operations; for example an ASA 264 might need to negotiate one objective with a peer while discovering 265 and synchronizing a different objective with a different peer. 266 Alternatively, an ASA which acts as a resource manager might need to 267 run simultaneous negotiations for a given objective with multiple 268 different peers. Such an ASA will probably need to support 269 uninterruptible atomic changes to its internal data structures, using 270 a mechanism provided by the operating system and programming language 271 in use. 273 2.2.1. Alternative Asynchronous Mechanisms 275 Thus, some ASAs need to support asynchronous operations, and 276 therefore the GRASP core must do so. Depending on both the operating 277 system and the programming language in use, there are various 278 techniques for such parallel operations, three of which we consider 279 here: multi-threading, an event loop structure using polling, and an 280 event loop structure using callback functions. 282 1. In multi-threading, the operating system and language will 283 provide the necessary support for asynchronous operations, 284 including creation of new threads, context switching between 285 threads, queues, locks, and implicit wait states. In this case, 286 API calls can be treated as simple synchronous function calls 287 within their own thread, even if the function includes wait 288 states, blocking and queueing. Concurrent operations will each 289 run in their own threads. For example, the discover() call may 290 not return until discovery results have arrived or a timeout has 291 occurred. If the ASA has other work to do, the discover() call 292 must be in a thread of its own. 294 2. In an event loop implementation with polling, blocking calls are 295 not acceptable. Therefore all calls must be non-blocking, and 296 the main loop could support multiple GRASP sessions in parallel 297 by repeatedly polling each one for a change of state. To 298 facilitate this, the API implementation would provide non- 299 blocking versions of all the functions that otherwise involve 300 blocking and queueing. In these calls, a 'noReply' code will be 301 returned by each call instead of blocking, until such time as the 302 event for which it is waiting (or a failure) has occurred. Thus, 303 for example, discover() would return 'noReply' instead of waiting 304 until discovery has succeeded or timed out. The discover() call 305 would be repeated in every cycle of the main loop until it 306 completes. Effectively, it becomes a polling call. 308 3. It was noted earlier that some GRASP messages are not idempotent; 309 in particular this applies to each step in a negotiation session 310 - sending the same message twice might produce unintended side 311 effects. This is not affected by event loop polling: repeating a 312 call after a 'noReply' does not repeat a message; it simply 313 checks whether a reply has been received. 315 4. In an event loop implementation with callbacks, the ASA 316 programmer would provide a callback function for each 317 asynchronous operation. This would be called asynchronously when 318 a reply is received or a failure such as a timeout occurs. 320 2.2.2. Multiple Negotiation Scenario 322 The design of GRASP allows the following scenario. Consider an ASA 323 "A" that acts as a resource allocator for some objective. An ASA "B" 324 launches a negotiation with "A" to obtain or release a quantity of 325 the resource. While this negotatition is under way, "B" chooses to 326 launch a second simultaneous negotiation with "A" for a different 327 quantity of the same resource. "A" must therefore conduct two 328 separate negotiation sessions at the same time with the same peer, 329 and must not mix them up. 331 Note that ASAs could be designed to avoid such a scenario, i.e. 332 restricted to exactly one negotiation session at a time for a given 333 objective, but this would be a voluntary restriction not required by 334 the GRASP protocol. In fact it is an assumption of GRASP that any 335 ASA managing a resource may need to conduct multiple parallel 336 negotiations, possibly with the same peer. Communication patterns 337 could be very complex, with a group of ASAs overlapping negotiations 338 among themselves, as described in [I-D.ciavaglia-anima-coordination]. 339 Therefore, the API design allows for such scenarios. 341 In the callback model, for the scenario just described, the ASAs "A" 342 and "B" will each provide two instances of the callback function, one 343 for each session. For this reason, each ASA must be able to 344 distinguish the two sessions, and the peer's IP address is not 345 sufficient for this. It is also not safe to rely on transport port 346 numbers for this, since future variants of GRASP might use shared 347 ports rather than a separate port per session. Hence the GRASP 348 design includes a session identifier. Thus, when necessary, a 349 session handle (see next section) is used in the API to distinguish 350 simultaneous GRASP sessions from each other, so that any number of 351 sessions may proceed asynchronously in parallel. 353 2.2.3. Overlapping Sessions and Operations 355 A GRASP session consists of a finite sequence of messages (for 356 discovery, synchronization, or negotiation) between two ASAs. It is 357 uniquely identified on the wire by a pseudo-random session identifier 358 plus the IP address of the initiator of the session. Further details 359 are given in the section 'Session Identifier' of 360 [I-D.ietf-anima-grasp]. 362 On the first call in a new GRASP session, the API returns a 363 'session_handle' handle that uniquely identifies the session within 364 the API, so that multiple overlapping sessions can be distinguished. 365 A likely implementation is to form the handle from the underlying 366 GRASP Session ID and IP address. This handle must be used in all 367 subsequent calls for the same session. Also see Section 2.3.2.8. 369 An additional mechanism that might increase efficiency for polling 370 implementations is to add a general call, say notify(), which would 371 check the status of all outstanding operations for the calling ASA 372 and return the session_handle values for all sessions that have 373 changed state. This would eliminate the need for repeated calls to 374 the individual functions returning a 'noReply'. This call is not 375 described below as the details are likely to be implementation- 376 specific. 378 An implication of the above for all GRASP implementations is that the 379 GRASP core must keep state for each GRASP operation in progress, most 380 likely keyed by the GRASP Session ID and the GRASP source address of 381 the session initiator. Even in a threaded implementation, the GRASP 382 core will need such state internally. The session_handle parameter 383 exposes this aspect of the implementation. 385 2.2.4. Session Termination 387 GRASP sessions may terminate for numerous reasons. A session ends 388 when discovery succeeds or times out, when negotiation succeeds or 389 fails, when a synchronization result is delivered, when the other end 390 fails to respond before a timeout expires, when a loop count expires, 391 or when a network socket error occurs. Note that a timeout at one 392 end of a session might result in a timeout or a socket error at the 393 other end, since GRASP does not send error messages in this case. In 394 all cases, the API will return an appropriate code to the caller, 395 which should then release any reserved resources. After failure 396 cases, the GRASP specification recommends an exponential backoff 397 before retrying. 399 2.3. API definition 401 2.3.1. Overview of Functions 403 The functions provided by the API fall into several groups: 405 * Registration. These functions allow an ASA to register itself 406 with the GRASP core, and allow a registered ASA to register the 407 GRASP objectives that it will manipulate. 409 * Discovery. This function allows an ASA that needs to initiate 410 negotiation or synchronization of a particular objective to 411 discover a peer willing to respond. 413 * Negotiation. These functions allow an ASA to act as an initiator 414 (requester) or responder (listener) for a GRASP negotiation 415 session. After initiation, negotiation is a symmetric process, so 416 most of the functions can be used by either party. 418 * Synchronization. These functions allow an ASA to to act as an 419 initiator (requester) or responder (listener and data source) for 420 a GRASP synchronization session. 422 * Flooding. These functions allow an ASA to send and receive an 423 objective that is flooded to all nodes of the ACP. 425 Some example logic flows for a resource management ASA are given in 426 [I-D.ietf-anima-asa-guidelines], which may be of help in 427 understanding the following descriptions. The next section describes 428 parameters and data structures used in multiple API calls. The 429 following sections describe various groups of function APIs. Those 430 APIs that do not list asynchronous mechanisms are implicitly 431 synchronous in their behaviour. 433 2.3.2. Parameters and data structures 435 2.3.2.1. Integers 437 In this API, integers are assumed to be 32 bit unsigned integers 438 (uint32_t) unless otherwise indicated. 440 2.3.2.2. Errorcode 442 All functions in the API have an unsigned 'errorcode' integer as 443 their return value (the first return value in languages that allow 444 multiple return values). An errorcode of zero indicates success. 445 Any other value indicates failure of some kind. The first three 446 errorcodes have special importance: 448 1. Declined: used to indicate that the other end has sent a GRASP 449 Negotiation End message (M_END) with a Decline option 450 (O_DECLINE). 452 2. No reply: used in non-blocking calls to indicate that the other 453 end has sent no reply so far (see Section 2.2). 455 3. Unspecified error: used when no more specific error code applies. 457 Appendix A gives a full list of currently suggested error codes, 458 based on implementation experience. While there is no absolute 459 requirement for all implementations to use the same error codes, this 460 is highly recommended for portability of applications. 462 2.3.2.3. Timeout 464 Wherever a 'timeout' parameter appears, it is an unsigned integer 465 expressed in milliseconds. Except for the discover() function, if it 466 is zero, the GRASP default timeout (GRASP_DEF_TIMEOUT, see 467 [I-D.ietf-anima-grasp]) will apply. If no response is received 468 before the timeout expires, the call will fail unless otherwise 469 noted. 471 2.3.2.4. Objective 473 An 'objective' parameter is a data structure with the following 474 components: 476 * name (UTF-8 string) - the objective's name 478 * neg (Boolean flag) - True if objective supports negotiation 479 (default False) 481 * synch (Boolean flag) - True if objective supports synchronization 482 (default False) 484 * dry (Boolean flag) - True if objective supports dry-run 485 negotiation (default False) 487 - Note 1: Only one of 'synch' or 'neg' may be True. 489 - Note 2: 'dry' must not be True unless 'neg' is also True. 491 - Note 3: In some programming languages the preferred 492 implementation may be to represent the Boolean flags as bits in 493 a single byte, which is how they are encoded in GRASP messages. 494 In other languages an enumeration might be preferable. 496 * loop_count (unsigned integer, uint8_t) - Limit on negotiation 497 steps etc. (default GRASP_DEF_LOOPCT, see [I-D.ietf-anima-grasp]) 498 The 'loop_count' is set to a suitable value by the initiator of a 499 negotiation, to prevent indefinite loops. It is also used to 500 limit the propagation of discovery and flood messages. 502 * value - a specific data structure expressing the value of the 503 objective. The format is language dependent, with the constraint 504 that it can be validly represented in CBOR [RFC8949]. 506 An important advantage of CBOR is that the value of an objective 507 can be completely opaque to the GRASP core yet pass transparently 508 through it to and from the ASA. Although the GRASP core must 509 validate the format and syntax of GRASP messages, it cannot 510 validate the value of an objective; all it can do is detect 511 malformed CBOR. The handling of decoding errors depends on the 512 CBOR library in use, but a corresponding error code ('CBORfail') 513 is defined in the API and will be returned to the ASA if a faulty 514 message can be assigned to a current GRASP session. However, it 515 is the responsibility of each ASA to validate the value of a 516 received objective, as discussed in Section 5.3 of [RFC8949]. If 517 the programming language in use is suitably object-oriented, the 518 GRASP API may deserialize the value and present it to the ASA as 519 an object. If not, it will be presented as a CBOR data item. In 520 all cases, the syntax and semantics of the objective value are the 521 responsibility of the ASA. 523 A requirement for all language mappings and all API 524 implementations is that, regardless of what other options exist 525 for a language-specific representation of the value, there is 526 always an option to use a raw CBOR data item as the value. The 527 API will then wrap this with CBOR Tag 24 as an encoded CBOR data 528 item for transmission via GRASP, and unwrap it after reception. 529 By this means, ASAs will be able to communicate regardless of 530 programming language. 532 The 'name' and 'value' fields are of variable length. GRASP does not 533 set a maximum length for these fields, but only for the total length 534 of a GRASP message. Implementations might impose length limits. 536 An example data structure definition for an objective in the C 537 language, using at least the C99 version, and assuming the use of a 538 particular CBOR library [libcbor], is: 540 typedef struct { 541 unsigned char *name; 542 uint8_t flags; // flag bits as defined by GRASP 543 uint8_t loop_count; 544 uint32_t value_size; // size of value in bytes 545 cbor_mutable_data cbor_value; 546 // CBOR bytestring (libcbor/cbor/data.h) 547 } objective; 549 An example data structure definition for an objective in the Python 550 language (version 3.4 or later) is: 552 class objective: 553 """A GRASP objective""" 554 def __init__(self, name): 555 self.name = name #Unique name (string) 556 self.negotiate = False #True if objective supports negotiation 557 self.dryrun = False #True if objective supports dry-run neg. 558 self.synch = False #True if objective supports synch 559 self.loop_count = GRASP_DEF_LOOPCT # Default starting value 560 self.value = None #Place holder; any valid Python object 562 2.3.2.5. ASA_locator 564 An 'ASA_locator' parameter is a data structure with the following 565 contents: 567 * locator - The actual locator, either an IP address or an ASCII 568 string. 570 * ifi (unsigned integer) - The interface identifier index via which 571 this was discovered (of limited use to most ASAs). 573 * expire (system dependent type) - The time on the local system 574 clock when this locator will expire from the cache 576 * The following cover all locator types currently supported by 577 GRASP: 579 - is_ipaddress (Boolean) - True if the locator is an IP address 581 - is_fqdn (Boolean) - True if the locator is an FQDN 583 - is_uri (Boolean) - True if the locator is a URI 585 - These options are mutually exclusive. Depending on the 586 programming language, they could be represented as a bit 587 pattern or an enumeration. 589 * diverted (Boolean) - True if the locator was discovered via a 590 Divert option 592 * protocol (unsigned integer) - Applicable transport protocol 593 (IPPROTO_TCP or IPPROTO_UDP). These constants are defined in the 594 CDDL specification of GRASP [I-D.ietf-anima-grasp]. 596 * port (unsigned integer) - Applicable port number 598 The 'locator' field is of variable length in the case of an FQDN or a 599 URI. GRASP does not set a maximum length for this field, but only 600 for the total length of a GRASP message. Implementations might 601 impose length limits. 603 It should be noted that when one ASA discovers the ASA_locator of 604 another, there is no explicit authentication mechanism. In 605 accordance with the trust model provided by the secure ACP, ASAs are 606 presumed to provide correct locators in response to discovery. See 607 the section 'Locator Options' of [I-D.ietf-anima-grasp] for further 608 details. 610 2.3.2.6. Tagged_objective 612 A 'tagged_objective' parameter is a data structure with the following 613 contents: 615 * objective - An objective 617 * locator - The ASA_locator associated with the objective, or a null 618 value. 620 2.3.2.7. Asa_handle 622 Although an authentication and authorization scheme for ASAs has not 623 been defined, the API provides a very simple hook for such a scheme. 624 When an ASA starts up, it registers itself with the GRASP core, which 625 provides it with an opaque handle that, although not 626 cryptographically protected, would be difficult for a third party to 627 predict. The ASA must present this handle in future calls. This 628 mechanism will prevent some elementary errors or trivial attacks such 629 as an ASA manipulating an objective it has not registered to use. 631 Thus, in most calls, an 'asa_handle' parameter is required. It is 632 generated when an ASA first registers with GRASP, and the ASA must 633 then store the asa_handle and use it in every subsequent GRASP call. 634 Any call in which an invalid handle is presented will fail. It is an 635 up to 32-bit opaque value (for example represented as a uint32_t, 636 depending on the language). Since it is only used locally, not in 637 GRASP messages, it is only required to be unique within the local 638 GRASP instance. It is valid until the ASA terminates. It should be 639 unpredictable; a possible implementation is to use the same mechanism 640 that GRASP uses to generate Session Identifiers (see 641 Section 2.3.2.8). 643 2.3.2.8. Session_handle and Callbacks 645 In some calls, a 'session_handle' parameter is required. This is an 646 opaque data structure as far as the ASA is concerned, used to 647 identify calls to the API as belonging to a specific GRASP session 648 (see Section 2.2.3). It will be provided as a parameter in callback 649 functions. As well as distinguishing calls from different sessions, 650 it also allows GRASP to detect and ignore calls from non-existent or 651 timed-out sessions. 653 In an event loop implementation, callback functions (Section 2.2.1) 654 may be supported for all API functions that involve waiting for a 655 remote operation: 657 discover() whose callback would be discovery_received(). 659 request_negotiate() whose callback would be 660 negotiate_step_received(). 662 negotiate_step() whose callback would be 663 negotiate_step_received(). 665 listen_negotiate() whose callback would be 666 negotiate_step_received(). 668 synchronize() whose callback would be synchronization_received(). 670 Further details of callbacks are implementation-dependent. 672 2.3.3. Registration 674 These functions are used to register an ASA, and the objectives that 675 it modifies, with the GRASP module. In the absence of an 676 authorization model, these functions are very simple but they will 677 avoid multiple ASAs choosing the same name, and will prevent multiple 678 ASAs manipulating the same objective. If an authorization model is 679 added to GRASP, these API calls would need to be modified 680 accordingly. 682 * register_asa() 684 All ASAs must use this call before issuing any other API calls. 686 - Input parameter: 688 name of the ASA (UTF-8 string) 690 - Return value: 692 errorcode (unsigned integer) 694 asa_handle (unsigned integer) 696 - This initialises state in the GRASP module for the calling 697 entity (the ASA). In the case of success, an 'asa_handle' is 698 returned which the ASA must present in all subsequent calls. 699 In the case of failure, the ASA has not been authorized and 700 cannot operate. The 'asa_handle' value is undefined. 702 * deregister_asa() 704 - Input parameters: 706 asa_handle (unsigned integer) 708 name of the ASA (UTF-8 string) 710 - Return value: 712 errorcode (unsigned integer) 714 - This removes all state in the GRASP module for the calling 715 entity (the ASA), and deregisters any objectives it has 716 registered. Note that these actions must also happen 717 automatically if an ASA exits. 719 - Note - the ASA name is strictly speaking redundant in this 720 call, but is present to detect and reject erroneous 721 deregistrations. 723 * register_objective() 725 ASAs must use this call for any objective whose value they need to 726 transmit by negotiation, synchronization or flooding. 728 - Input parameters: 730 asa_handle (unsigned integer) 732 objective (structure) 734 ttl (unsigned integer - default GRASP_DEF_TIMEOUT) 736 discoverable (Boolean - default False) 738 overlap (Boolean - default False) 740 local (Boolean - default False) 742 - Return value: 744 errorcode (unsigned integer) 746 - This registers an objective that this ASA may modify and 747 transmit to other ASAs by flooding or negotiation. It is not 748 necessary to register an objective that is only received by 749 GRASP synchronization or flooding. The 'objective' becomes a 750 candidate for discovery. However, discovery responses should 751 not be enabled until the ASA calls listen_negotiate() or 752 listen_synchronize(), showing that it is able to act as a 753 responder. The ASA may negotiate the objective or send 754 synchronization or flood data. Registration is not needed for 755 "read-only" operations, i.e., the ASA only wants to receive 756 synchronization or flooded data for the objective concerned. 758 - The 'ttl' parameter is the valid lifetime (time to live) in 759 milliseconds of any discovery response generated for this 760 objective. The default value should be the GRASP default 761 timeout (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]). 763 - If the parameter 'discoverable' is True, the objective is 764 immediately discoverable. This is intended for objectives that 765 are only defined for GRASP discovery, and which do not support 766 negotiation or synchronization. 768 - If the parameter 'overlap' is True, more than one ASA may 769 register this objective in the same GRASP instance. This is of 770 value for life cycle management of ASAs 771 [I-D.ietf-anima-asa-guidelines] and must be used consistently 772 for a given objective (always True or always False). 774 - If the parameter 'local' is True, discovery must return a link- 775 local address. This feature is for objectives that must be 776 restricted to the local link. 778 - This call may be repeated for multiple objectives. 780 * deregister_objective() 782 - Input parameters: 784 asa_handle (unsigned integer) 786 objective (structure) 788 - Return value: 790 errorcode (unsigned integer) 792 - The 'objective' must have been registered by the calling ASA; 793 if not, this call fails. Otherwise, it removes all state in 794 the GRASP module for the given objective. 796 2.3.4. Discovery 798 * discover() 800 This function may be used by any ASA to discover peers handling a 801 given objective. 803 - Input parameters: 805 asa_handle (unsigned integer) 806 objective (structure) 808 timeout (unsigned integer) 810 minimum_TTL (unsigned integer) 812 - Return values: 814 errorcode (unsigned integer) 816 locator_list (structure) 818 - This returns a list of discovered 'ASA_locator's for the given 819 objective. An empty list means that no locators were 820 discovered within the timeout. Note that this structure 821 includes all the fields described in Section 2.3.2.5. 823 - The parameter 'minimum_TTL' must be greater than or equal to 824 zero. Any locally cached locators for the objective whose 825 remaining time to live in milliseconds is less than or equal to 826 'minimum_TTL' are deleted first. Thus 'minimum_TTL' = 0 will 827 flush all entries. Note that this will not affect sessions 828 already in progress using the deleted locators. 830 - If the parameter 'timeout' is zero, any remaining locally 831 cached locators for the objective are returned immediately and 832 no other action is taken. (Thus, a call with 'minimum_TTL' and 833 'timeout' both equal to zero is pointless.) 835 - If the parameter 'timeout' is greater than zero, GRASP 836 discovery is performed, and all results obtained before the 837 timeout in milliseconds expires are returned. If no results 838 are obtained, an empty list is returned after the timeout. 839 That is not an error condition. GRASP discovery is not a 840 deterministic process. If there are multiple nodes handling an 841 objective, none, some or all of them will be discovered before 842 the timeout expires. 844 - Asynchronous Mechanisms: 846 o Threaded implementation: This should be called in a separate 847 thread if asynchronous operation is required. 849 o Event loop implementation: An additional in/out 850 'session_handle' parameter is used. If the 'errorcode' 851 parameter has the value 2 ('noReply'), no response has been 852 received so far. The 'session_handle' parameter must be 853 presented in subsequent calls. A callback may be used in 854 the case of a non-zero timeout. 856 2.3.5. Negotiation 858 Since the negotiation mechanism is different from a typical client/ 859 server exchange, Figure 2 illustrates the sequence of calls and GRASP 860 messages in a negotiation. Note that after the first protocol 861 exchange, the process is symmetrical, with negotiating steps strictly 862 alternating between the two sides. Either side can end the 863 negotiation. Also, the side that is due to respond next can insert a 864 delay at any time, to extend the other side's timeout. This would be 865 used, for example, if an ASA needed to negotiate with a third party 866 before continuing with the current negotiation. 868 The loop count embedded in the objective that is the subject of 869 negotiation is initialised by the ASA that starts a negotiation, and 870 then decremented by the GRASP core at each step, prior to sending 871 each M_NEGOTIATE message. If it reaches zero, the negotiation will 872 fail and each side will receive an error code. 874 Initiator Responder 875 --------- --------- 877 listen_negotiate() \ Await request 879 request_negotiate() 880 M_REQ_NEG -> negotiate_step() \ Open session, 881 <- M_NEGOTIATE / start negotiation 882 negotiate_step() 883 M_NEGOTIATE -> negotiate_step() \ Continue 884 <- M_NEGOTIATE / negotiation 885 ... 886 negotiate_wait() \ Insert 887 M_WAIT -> / delay 888 negotiate_step() 889 M_NEGOTIATE -> negotiate_step() \ Continue 890 <- M_NEGOTIATE / negotiation 891 negotiate_step() 892 M_NEGOTIATE -> end_negotiate() \ End 893 <- M_END / negotiation 895 \ Process results 897 Figure 2: Negotiation sequence 899 As the negotiation proceeds, each side will update the value of the 900 objective in accordance with its particular semantics, defined in the 901 specification of the objective. Although many objectives will have 902 values that can be ordered, so that negotiation can be a simple 903 bidding process, this is not a requirement. 905 Failure to agree, a timeout, or loop count exhaustion may all end a 906 negotiation session, but none of these cases is a protocol failure. 908 * request_negotiate() 910 This function is used by any ASA to initiate negotiation of a 911 GRASP objective as a requester (client). 913 - Input parameters: 915 asa_handle (unsigned integer) 917 objective (structure) 919 peer (ASA_locator) 921 timeout (unsigned integer) 923 - Return values: 925 errorcode (unsigned integer) 927 session_handle (structure) (undefined unless successful) 929 proffered_objective (structure) (undefined unless 930 successful) 932 reason (string) (empty unless negotiation declined) 934 - This function opens a negotiation session between two ASAs. 935 Note that GRASP currently does not support multi-party 936 negotiation, which would need to be added as an extended 937 function. 939 - The 'objective' parameter must include the requested value, and 940 its loop count should be set to a suitable starting value by 941 the ASA. If not, the GRASP default will apply. 943 - Note that a given negotiation session may or may not be a dry- 944 run negotiation; the two modes must not be mixed in a single 945 session. 947 - The 'peer' parameter is the target node; it must be an 948 'ASA_locator' as returned by discover(). If 'peer' is null, 949 GRASP discovery is automatically performed first to find a 950 suitable peer (i.e., any node that supports the objective in 951 question). 953 - The 'timeout' parameter is described in Section 2.3.2.3. 955 - If the 'errorcode' return value is 0, the negotiation has 956 successfully started. There are then two cases: 958 1. The 'session_handle' parameter is null. In this case the 959 negotiation has succeeded with one exchange of messages and 960 the peer has accepted the request. The returned 961 'proffered_objective' contains the value accepted by the 962 peer, which is therefore equal to the value in the 963 requested 'objective'. For this reason, no session handle 964 is needed, since the session has ended. 966 2. The 'session_handle' parameter is not null. In this case 967 negotiation must continue. The 'session_handle' must be 968 presented in all subsequent negotiation steps. The 969 returned 'proffered_objective' contains the first value 970 proffered by the negotiation peer in the first exchange of 971 messages; in other words it is a counter-offer. The 972 contents of this instance of the objective must be used to 973 prepare the next negotiation step (see negotiate_step() 974 below) because it contains the updated loop count, sent by 975 the negotiation peer. The GRASP code automatically 976 decrements the loop count by 1 at each step, and returns an 977 error if it becomes zero. Since this terminates the 978 negotiation, the other end will experience a timeout, which 979 will terminate the other end of the session. 981 This function must be followed by calls to 'negotiate_step' 982 and/or 'negotiate_wait' and/or 'end_negotiate' until the 983 negotiation ends. 'request_negotiate' may then be called 984 again to start a new negotiation. 986 - If the 'errorcode' parameter has the value 1 ('declined'), the 987 negotiation has been declined by the peer (M_END and O_DECLINE 988 features of GRASP). The 'reason' string is then available for 989 information and diagnostic use, but it may be a null string. 990 For this and any other error code, an exponential backoff is 991 recommended before any retry (see Section 4). 993 - Asynchronous Mechanisms: 995 o Threaded implementation: This should be called in a separate 996 thread if asynchronous operation is required. 998 o Event loop implementation: The 'session_handle' parameter is 999 used to distinguish multiple simultaneous sessions. If the 1000 'errorcode' parameter has the value 2 ('noReply'), no 1001 response has been received so far. The 'session_handle' 1002 parameter must be presented in subsequent calls. 1004 - Use of dry run mode: This must be consistent within a GRASP 1005 session. The state of the 'dry' flag in the initial 1006 request_negotiate() call must be the same in all subsequent 1007 negotiation steps of the same session. The semantics of the 1008 dry run mode are built into the ASA; GRASP merely carries the 1009 flag bit. 1011 - Special note for the ACP infrastructure ASA: It is likely that 1012 this ASA will need to discover and negotiate with its peers in 1013 each of its on-link neighbors. It will therefore need to know 1014 not only the link-local IP address but also the physical 1015 interface and transport port for connecting to each neighbor. 1016 One implementation approach to this is to include these details 1017 in the 'session_handle' data structure, which is opaque to 1018 normal ASAs. 1020 * listen_negotiate() 1022 This function is used by an ASA to start acting as a negotiation 1023 responder (listener) for a given GRASP objective. 1025 - Input parameters: 1027 asa_handle (unsigned integer) 1029 objective (structure) 1031 - Return values: 1033 errorcode (unsigned integer) 1034 session_handle (structure) (undefined unless successful) 1036 requested_objective (structure) (undefined unless 1037 successful) 1039 - This function instructs GRASP to listen for negotiation 1040 requests for the given 'objective'. It also enables discovery 1041 responses for the objective, as mentioned under 1042 register_objective() in Section 2.3.3. 1044 - Asynchronous Mechanisms: 1046 o Threaded implementation: It will block waiting for an 1047 incoming request, so should be called in a separate thread 1048 if asynchronous operation is required. Unless there is an 1049 unexpected failure, this call only returns after an incoming 1050 negotiation request. If the ASA supports multiple 1051 simultaneous transactions, a new sub-thread must be spawned 1052 for each new session, so that listen_negotiate() can be 1053 called again immediately. 1055 o Event loop implementation: A 'session_handle' parameter is 1056 used to distinguish individual sessions. If the ASA 1057 supports multiple simultaneous transactions, a new event 1058 must be inserted in the event loop for each new session, so 1059 that listen_negotiate() can be reactivated immediately. 1061 - This call only returns (threaded model) or triggers (event 1062 loop) after an incoming negotiation request. When this occurs, 1063 'requested_objective' contains the first value requested by the 1064 negotiation peer. The contents of this instance of the 1065 objective must be used in the subsequent negotiation call 1066 because it contains the loop count sent by the negotiation 1067 peer. The 'session_handle' must be presented in all subsequent 1068 negotiation steps. 1070 - This function must be followed by calls to 'negotiate_step' 1071 and/or 'negotiate_wait' and/or 'end_negotiate' until the 1072 negotiation ends. 1074 - If an ASA is capable of handling multiple negotiations 1075 simultaneously, it may call 'listen_negotiate' simultaneously 1076 from multiple threads, or insert multiple events. The API and 1077 GRASP implementation must support re-entrant use of the 1078 listening state and the negotiation calls. Simultaneous 1079 sessions will be distinguished by the threads or events 1080 themselves, the GRASP session handles, and the underlying 1081 unicast transport sockets. 1083 * stop_listen_negotiate() 1085 This function is used by an ASA to stop acting as a responder 1086 (listener) for a given GRASP objective. 1088 - Input parameters: 1090 asa_handle (unsigned integer) 1092 objective (structure) 1094 - Return value: 1096 errorcode (unsigned integer) 1098 - Instructs GRASP to stop listening for negotiation requests for 1099 the given objective, i.e., cancels 'listen_negotiate'. 1101 - Asynchronous Mechanisms: 1103 o Threaded implementation: Must be called from a different 1104 thread than 'listen_negotiate'. 1106 o Event loop implementation: no special considerations. 1108 * negotiate_step() 1110 This function is used by either ASA in a negotiation session to 1111 make the next step in negotiation. 1113 - Input parameters: 1115 asa_handle (unsigned integer) 1117 session_handle (structure) 1119 objective (structure) 1121 timeout (unsigned integer) as described in Section 2.3.2.3 1123 - Return values: 1125 Exactly as for 'request_negotiate' 1127 - Executes the next negotation step with the peer. The 1128 'objective' parameter contains the next value being proffered 1129 by the ASA in this step. It must also contain the latest 1130 'loop_count' value received from request_negotiate() or 1131 negotiate_step(). 1133 - Asynchronous Mechanisms: 1135 o Threaded implementation: Usually called in the same thread 1136 as the preceding 'request_negotiate' or 'listen_negotiate', 1137 with the same value of 'session_handle'. 1139 o Event loop implementation: Must use the same value of 1140 'session_handle' returned by the preceding 1141 'request_negotiate' or 'listen_negotiate'. 1143 * negotiate_wait() 1145 This function is used by either ASA in a negotiation session to 1146 delay the next step in negotiation. 1148 - Input parameters: 1150 asa_handle (unsigned integer) 1152 session_handle (structure) 1154 timeout (unsigned integer) 1156 - Return value: 1158 errorcode (unsigned integer) 1160 - Requests the remote peer to delay the negotiation session by 1161 'timeout' milliseconds, thereby extending the original timeout. 1162 This function simply triggers a GRASP Confirm Waiting message 1163 (see [I-D.ietf-anima-grasp] for details). 1165 - Asynchronous Mechanisms: 1167 o Threaded implementation: Called in the same thread as the 1168 preceding 'request_negotiate' or 'listen_negotiate', with 1169 the same value of 'session_handle'. 1171 o Event loop implementation: Must use the same value of 1172 'session_handle' returned by the preceding 1173 'request_negotiate' or 'listen_negotiate'. 1175 * end_negotiate() 1177 This function is used by either ASA in a negotiation session to 1178 end a negotiation. 1180 - Input parameters: 1182 asa_handle (unsigned integer) 1184 session_handle (structure) 1186 result (Boolean) 1188 reason (UTF-8 string) 1190 - Return value: 1192 errorcode (unsigned integer) 1194 - End the negotiation session. 1196 'result' = True for accept (successful negotiation), False for 1197 decline (failed negotiation). 1199 'reason' = string describing reason for decline (may be null; 1200 ignored if accept). 1202 - Asynchronous Mechanisms: 1204 o Threaded implementation: Called in the same thread as the 1205 preceding 'request_negotiate' or 'listen_negotiate', with 1206 the same value of 'session_handle'. 1208 o Event loop implementation: Must use the same value of 1209 'session_handle' returned by the preceding 1210 'request_negotiate' or 'listen_negotiate'. 1212 2.3.6. Synchronization and Flooding 1214 * synchronize() 1216 This function is used by any ASA to cause synchronization of a 1217 GRASP objective as a requester (client). 1219 - Input parameters: 1221 asa_handle (unsigned integer) 1222 objective (structure) 1224 peer (ASA_locator) 1226 timeout (unsigned integer) 1228 - Return values: 1230 errorcode (unsigned integer) 1232 result (structure) (undefined unless successful) 1234 - This call requests the synchronized value of the given 1235 'objective'. 1237 - If the 'peer' parameter is null, and the objective is already 1238 available in the local cache, the flooded objective is returned 1239 immediately in the 'result' parameter. In this case, the 1240 'timeout' is ignored. 1242 - If the 'peer' parameter is not null, or a cached value is not 1243 available, synchronization with a discovered ASA is performed. 1244 If successful, the retrieved objective is returned in the 1245 'result' value. 1247 - The 'peer' parameter is an 'ASA_locator' as returned by 1248 discover(). If 'peer' is null, GRASP discovery is 1249 automatically performed first to find a suitable peer (i.e., 1250 any node that supports the objective in question). 1252 - The 'timeout' parameter is described in Section 2.3.2.3. 1254 - This call should be repeated whenever the latest value is 1255 needed. 1257 - Asynchronous Mechanisms: 1259 o Threaded implementation: Call in a separate thread if 1260 asynchronous operation is required. 1262 o Event loop implementation: An additional in/out 1263 'session_handle' parameter is used, as in 1264 request_negotiate(). If the 'errorcode' parameter has the 1265 value 2 ('noReply'), no response has been received so far. 1266 The 'session_handle' parameter must be presented in 1267 subsequent calls. 1269 - In the case of failure, an exponential backoff is recommended 1270 before retrying (Section 4). 1272 * listen_synchronize() 1274 This function is used by an ASA to start acting as a 1275 synchronization responder (listener) for a given GRASP objective. 1277 - Input parameters: 1279 asa_handle (unsigned integer) 1281 objective (structure) 1283 - Return value: 1285 errorcode (unsigned integer) 1287 - This instructs GRASP to listen for synchronization requests for 1288 the given objective, and to respond with the value given in the 1289 'objective' parameter. It also enables discovery responses for 1290 the objective, as mentioned under register_objective() in 1291 Section 2.3.3. 1293 - This call is non-blocking and may be repeated whenever the 1294 value changes. 1296 * stop_listen_synchronize() 1298 This function is used by an ASA to stop acting as a 1299 synchronization responder (listener) for a given GRASP objective. 1301 - Input parameters: 1303 asa_handle (unsigned integer) 1305 objective (structure) 1307 - Return value: 1309 errorcode (unsigned integer) 1311 - This call instructs GRASP to stop listening for synchronization 1312 requests for the given 'objective', i.e. it cancels a previous 1313 listen_synchronize. 1315 * flood() 1316 This function is used by an ASA to flood one or more GRASP 1317 objectives throughout the autonomic network. 1319 Note that each GRASP node caches all flooded objectives that it 1320 receives, until each one's time-to-live expires. Cached 1321 objectives are tagged with their origin as well as an expiry time, 1322 so multiple copies of the same objective may be cached 1323 simultaneously. Further details are given in the section 'Flood 1324 Synchronization Message' of [I-D.ietf-anima-grasp] 1326 - Input parameters: 1328 asa_handle (unsigned integer) 1330 ttl (unsigned integer) 1332 tagged_objective_list (structure) 1334 - Return value: 1336 errorcode (unsigned integer) 1338 - This call instructs GRASP to flood the given synchronization 1339 objective(s) and their value(s) and associated locator(s) to 1340 all GRASP nodes. 1342 - The 'ttl' parameter is the valid lifetime (time to live) of the 1343 flooded data in milliseconds (0 = infinity) 1345 - The 'tagged_objective_list' parameter is a list of one or more 1346 'tagged_objective' couplets. The 'locator' parameter that tags 1347 each objective is normally null but may be a valid 1348 'ASA_locator'. Infrastructure ASAs needing to flood an 1349 {address, protocol, port} 3-tuple with an objective create an 1350 ASA_locator object to do so. If the IP address in that locator 1351 is the unspecified address ('::') it is replaced by the link- 1352 local address of the sending node in each copy of the flood 1353 multicast, which will be forced to have a loop count of 1. 1354 This feature is for objectives that must be restricted to the 1355 local link. 1357 - The function checks that the ASA registered each objective. 1359 - This call may be repeated whenever any value changes. 1361 * get_flood() 1362 This function is used by any ASA to obtain the current value of a 1363 flooded GRASP objective. 1365 - Input parameters: 1367 asa_handle (unsigned integer) 1369 objective (structure) 1371 - Return values: 1373 errorcode (unsigned integer) 1375 tagged_objective_list (structure) (undefined unless 1376 successful) 1378 - This call instructs GRASP to return the given synchronization 1379 objective if it has been flooded and its lifetime has not 1380 expired. 1382 - The 'tagged_objective_list' parameter is a list of 1383 'tagged_objective' couplets, each one being a copy of the 1384 flooded objective and a coresponding locator. Thus if the same 1385 objective has been flooded by multiple ASAs, the recipient can 1386 distinguish the copies. 1388 - Note that this call is for advanced ASAs. In a simple case, an 1389 ASA can simply call synchronize() in order to get a valid 1390 flooded objective. 1392 * expire_flood() 1394 This function may be used by an ASA to expire specific entries in 1395 the local GRASP flood cache. 1397 - Input parameters: 1399 asa_handle (unsigned integer) 1401 tagged_objective (structure) 1403 - Return value: 1405 errorcode (unsigned integer) 1407 - This is a call that can only be used after a preceding call to 1408 get_flood() by an ASA that is capable of deciding that the 1409 flooded value is stale or invalid. Use with care. 1411 - The 'tagged_objective' parameter is the one to be expired. 1413 2.3.7. Invalid Message Function 1415 * send_invalid() 1417 This function may be used by any ASA to stop an ongoing GRASP 1418 session. 1420 - Input parameters: 1422 asa_handle (unsigned integer) 1424 session_handle (structure) 1426 info (bytes) 1428 - Return value: 1430 errorcode (unsigned integer) 1432 - Sends a GRASP Invalid Message (M_INVALID) message, as described 1433 in [I-D.ietf-anima-grasp]. Should not be used if 1434 end_negotiate() would be sufficient. Note that this message 1435 may be used in response to any unicast GRASP message that the 1436 receiver cannot interpret correctly. In most cases this 1437 message will be generated internally by a GRASP implementation. 1439 'info' = optional diagnostic data supplied by the ASA. May be 1440 raw bytes from the invalid message. 1442 3. Implementation Status [RFC Editor: please remove] 1444 A prototype open source Python implementation of GRASP, including an 1445 API similar to this document, has been used to verify the concepts 1446 for the threaded model. It may be found at 1447 https://github.com/becarpenter/graspy with associated documentation 1448 and demonstration ASAs. 1450 4. Security Considerations 1452 Security considerations for the GRASP protocol are discussed in 1453 [I-D.ietf-anima-grasp]. These include denial of service issues, even 1454 though these are considered a low risk in the ACP. In various places 1455 GRASP recommends an exponential backoff. An ASA using the API should 1456 use exponential backoff after failed discover(), req_negotiate() or 1457 synchronize() operations. The timescale for such backoffs depends on 1458 the semantics of the GRASP objective concerned. Additionally, a 1459 flood() operation should not be repeated at shorter intervals than is 1460 useful. The appropriate interval depends on the semantics of the 1461 GRASP objective concerned. These precautions are intended to assist 1462 the detection of denial of service attacks. 1464 As a general precaution, all ASAs able to handle multiple negotiation 1465 or synchronization requests in parallel may protect themselves 1466 against a denial of service attack by limiting the number of requests 1467 they handle simultaneously and silently discarding excess requests. 1468 It might also be useful for the GRASP core to limit the number of 1469 objectives registered by a given ASA, the total number of ASAs 1470 registered, and the total number of simultaneous sessions, to protect 1471 system resources. During times of high autonomic activity, such as 1472 recovery from widespread faults, ASAs may experience many GRASP 1473 session failures. Guidance on making ASAs suitably robust is given 1474 in [I-D.ietf-anima-asa-guidelines]. 1476 As noted earlier, the trust model is that all ASAs in a given 1477 autonomic network communicate via a secure autonomic control plane 1478 and therefore trust each other's messages. Specific authorization of 1479 ASAs to use particular GRASP objectives is a subject for future 1480 study, also briefly discussed in [I-D.ietf-anima-grasp]. 1482 The careful reader will observe that a malicious ASA could extend a 1483 negotiation session indefinitely by use of the negotiate_wait() 1484 function or by manipulating the loop count of an objective. A 1485 robustly implemented ASA could detect such behavior by a peer and 1486 break off negotiation. 1488 The 'asa_handle' is used in the API as a first line of defence 1489 against a malware process attempting to imitate a legitimately 1490 registered ASA. The 'session_handle' is used in the API as a first 1491 line of defence against a malware process attempting to hijack a 1492 GRASP session. Both these handles are likely to be created using 1493 GRASP's 32-bit pseudo-random session ID. By construction, GRASP 1494 avoids the risk of session ID collisions (see the section 'Session 1495 Identifier' of [I-D.ietf-anima-grasp]). There remains a finite 1496 probability that an attacker could guess a session ID, 1497 session_handle, or asa_handle. However, this would only be of value 1498 to an attacker that had already penetrated the ACP, which would allow 1499 many other simpler forms of attack than hijacking GRASP sessions. 1501 5. IANA Considerations 1503 This document makes no request of the IANA. 1505 6. Acknowledgements 1507 Excellent suggestions were made by Ignas Bagdonas, Carsten Bormann, 1508 Laurent Ciavaglia, Roman Danyliw, Toerless Eckert, Benjamin Kaduk 1509 Erik Kline, Murray Kucherawy, Paul Kyzivat, Guangpeng Li, Michael 1510 Richardson, Joseph Salowey, Eric Vyncke, Magnus Westerlund, Rob 1511 Wilton, and other participants in the ANIMA WG and the IESG. 1513 7. References 1515 7.1. Normative References 1517 [I-D.ietf-anima-grasp] 1518 Bormann, C., Carpenter, B., and B. Liu, "A Generic 1519 Autonomic Signaling Protocol (GRASP)", Work in Progress, 1520 Internet-Draft, draft-ietf-anima-grasp-15, 13 July 2017, 1521 . 1523 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1524 Definition Language (CDDL): A Notational Convention to 1525 Express Concise Binary Object Representation (CBOR) and 1526 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1527 June 2019, . 1529 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 1530 Representation (CBOR)", STD 94, RFC 8949, 1531 DOI 10.17487/RFC8949, December 2020, 1532 . 1534 7.2. Informative References 1536 [I-D.ciavaglia-anima-coordination] 1537 Ciavaglia, L. and P. Peloso, "Autonomic Functions 1538 Coordination", Work in Progress, Internet-Draft, draft- 1539 ciavaglia-anima-coordination-01, 21 March 2016, 1540 . 1543 [I-D.ietf-anima-asa-guidelines] 1544 Carpenter, B., Ciavaglia, L., Jiang, S., and P. Pierre, 1545 "Guidelines for Autonomic Service Agents", Work in 1546 Progress, Internet-Draft, draft-ietf-anima-asa-guidelines- 1547 00, 14 November 2020, . 1550 [I-D.ietf-anima-autonomic-control-plane] 1551 Eckert, T., Behringer, M., and S. Bjarnason, "An Autonomic 1552 Control Plane (ACP)", Work in Progress, Internet-Draft, 1553 draft-ietf-anima-autonomic-control-plane-30, 30 October 1554 2020, . 1557 [I-D.ietf-anima-bootstrapping-keyinfra] 1558 Pritikin, M., Richardson, M., Eckert, T., Behringer, M., 1559 and K. Watsen, "Bootstrapping Remote Secure Key 1560 Infrastructures (BRSKI)", Work in Progress, Internet- 1561 Draft, draft-ietf-anima-bootstrapping-keyinfra-45, 11 1562 November 2020, . 1565 [I-D.ietf-anima-grasp-distribution] 1566 Liu, B., Xiao, X., Hecker, A., Jiang, S., Despotovic, Z., 1567 and B. Carpenter, "Information Distribution over GRASP", 1568 Work in Progress, Internet-Draft, draft-ietf-anima-grasp- 1569 distribution-01, 1 September 2020, 1570 . 1573 [I-D.ietf-anima-reference-model] 1574 Behringer, M., Carpenter, B., Eckert, T., Ciavaglia, L., 1575 and J. Nobre, "A Reference Model for Autonomic 1576 Networking", Work in Progress, Internet-Draft, draft-ietf- 1577 anima-reference-model-10, 22 November 2018, 1578 . 1581 [libcbor] Kalvoda, P., "libcbor - Documentation", December 2020, 1582 . 1584 Appendix A. Error Codes 1586 This Appendix lists the error codes defined so far on the basis of 1587 implementation experience, with suggested symbolic names and 1588 corresponding descriptive strings in English. It is expected that 1589 complete API implementations will provide for localisation of these 1590 descriptive strings, and that additional error codes will be needed 1591 according to implementation details. 1593 The error codes that may only be returned by one or two functions are 1594 annotated accordingly, and the others may be returned by numerous 1595 functions. The 'noSecurity' error will be returned to most calls if 1596 GRASP is running in an insecure mode (i.e., with no secure substrate 1597 such as the ACP), except for the specific DULL usage mode described 1598 in the section 'Discovery Unsolicited Link-Local' of 1599 [I-D.ietf-anima-grasp]. 1601 ok 0 "OK" 1602 declined 1 "Declined" (req_negotiate, negotiate_step) 1603 noReply 2 "No reply" (indicates waiting state in 1604 event loop calls) 1605 unspec 3 "Unspecified error" 1606 ASAfull 4 "ASA registry full" (register_asa) 1607 dupASA 5 "Duplicate ASA name" (register_asa) 1608 noASA 6 "ASA not registered" 1609 notYourASA 7 "ASA registered but not by you" 1610 (deregister_asa) 1611 notBoth 8 "Objective cannot support both negotiation 1612 and synchronization" (register_obj) 1613 notDry 9 "Dry-run allowed only with negotiation" 1614 (register_obj) 1615 notOverlap 10 "Overlap not supported by this implementation" 1616 (register_obj) 1617 objFull 11 "Objective registry full" 1618 (register_obj) 1619 objReg 12 "Objective already registered" 1620 (register_obj) 1621 notYourObj 13 "Objective not registered by this ASA" 1622 notObj 14 "Objective not found" 1623 notNeg 15 "Objective not negotiable" 1624 (req_negotiate, listen_negotiate) 1625 noSecurity 16 "No security" 1626 noDiscReply 17 "No reply to discovery" 1627 (req_negotiate) 1628 sockErrNegRq 18 "Socket error sending negotiation request" 1629 (req_negotiate) 1630 noSession 19 "No session" 1631 noSocket 20 "No socket" 1632 loopExhausted 21 "Loop count exhausted" (negotiate_step) 1633 sockErrNegStep 22 "Socket error sending negotiation step" 1634 (negotiate_step) 1635 noPeer 23 "No negotiation peer" 1636 (req_negotiate, negotiate_step) 1637 CBORfail 24 "CBOR decode failure" 1638 (req_negotiate, negotiate_step, synchronize) 1639 invalidNeg 25 "Invalid Negotiate message" 1640 (req_negotiate, negotiate_step) 1641 invalidEnd 26 "Invalid end message" 1642 (req_negotiate, negotiate_step) 1643 noNegReply 27 "No reply to negotiation step" 1644 (req_negotiate, negotiate_step) 1645 noValidStep 28 "No valid reply to negotiation step" 1646 (req_negotiate, negotiate_step) 1647 sockErrWait 29 "Socket error sending wait message" 1648 (negotiate_wait) 1650 sockErrEnd 30 "Socket error sending end message" 1651 (end_negotiate, send_invalid) 1652 IDclash 31 "Incoming request Session ID clash" 1653 (listen_negotiate) 1654 notSynch 32 "Not a synchronization objective" 1655 (synchronize, get_flood) 1656 notFloodDisc 33 "Not flooded and no reply to discovery" 1657 (synchronize) 1658 sockErrSynRq 34 "Socket error sending synch request" 1659 (synchronize) 1660 noListener 35 "No synch listener" 1661 (synchronize) 1662 noSynchReply 36 "No reply to synchronization request" 1663 (synchronize) 1664 noValidSynch 37 "No valid reply to synchronization request" 1665 (synchronize) 1666 invalidLoc 38 "Invalid locator" (flood) 1668 Appendix B. Change log [RFC Editor: Please remove] 1670 draft-ietf-anima-grasp-api-10, 2021-01: 1672 * Closed two final IESG comments 1674 draft-ietf-anima-grasp-api-09, 2020-12: 1676 * Added short discussions of CBOR usage and verification. 1678 * Added section on session termination. 1680 * Clarified that integers are uint32 or uint8. 1682 * Minor technical correction to timeout specification. 1684 * Clarified sequencing of negotiation messages. 1686 * Minor technical addition to request_negotiate() and synchronize() 1687 in event loop model. 1689 * Expanded several points in Security Considerations, including 1690 precautions against resource exhaustion. 1692 * Other clarifications and minor reorganizations; removed some 1693 duplicated text. 1695 * Updated references. 1697 draft-ietf-anima-grasp-api-08, 2020-11: 1699 * Clarified trust model 1701 * Added explanations of GRASP objectives and sessions 1703 * Added note about non-idempotent messages 1705 * Added overview of API functions, and annotated each function with 1706 a brief description 1708 * Added protocol diagram for negotiation session 1710 * Clarified (absence of) authorization model 1712 * Changed precise semantics of synchronize() for flooded objectives 1714 * Clarified caching of flooded objectives 1716 * Changed 'age_limit' to 'minimum_TTL' 1718 * Improved security considerations, including DOS precautions 1720 * Annotated error codes to indicate which functions generate which 1721 errors 1723 * Other clarifications from Last Call reviews 1725 draft-ietf-anima-grasp-api-07, 2020-10-13: 1727 * Improved diagram and its description 1729 * Added pointer to example logic flows 1731 * Added note on variable length parameters 1733 * Clarified that API decrements loop count automatically 1735 * Other corrections and clarifications from AD review 1737 draft-ietf-anima-grasp-api-06, 2020-06-07: 1739 * Improved diagram 1741 * Numerous clarifications and layout changes 1743 draft-ietf-anima-grasp-api-05, 2020-05-08: 1745 * Converted to xml2rfc v3 1746 * Editorial fixes. 1748 draft-ietf-anima-grasp-api-04, 2019-10-07: 1750 * Improved discussion of layering, mentioned daemon. 1752 * Added callbacks and improved description of asynchronous 1753 operations. 1755 * Described use case for 'session_handle'. 1757 * More explanation of 'asa_handle'. 1759 * Change 'discover' to use 'age_limit' instead of 'flush'. 1761 * Clarified use of 'dry run'. 1763 * Editorial improvements. 1765 draft-ietf-anima-grasp-api-03, 2019-01-21: 1767 * Replaced empty "logic flows" section by "implementation status". 1769 * Minor clarifications. 1771 * Editorial improvements. 1773 draft-ietf-anima-grasp-api-02, 2018-06-30: 1775 * Additional suggestion for event-loop API. 1777 * Discussion of error code values. 1779 draft-ietf-anima-grasp-api-01, 2018-03-03: 1781 * Editorial updates 1783 draft-ietf-anima-grasp-api-00, 2017-12-23: 1785 * WG adoption 1787 * Editorial improvements. 1789 draft-liu-anima-grasp-api-06, 2017-11-24: 1791 * Improved description of event-loop model. 1793 * Changed intended status to Informational. 1795 * Editorial improvements. 1797 draft-liu-anima-grasp-api-05, 2017-10-02: 1799 * Added send_invalid() 1801 draft-liu-anima-grasp-api-04, 2017-06-30: 1803 * Noted that simple nodes might not include the API. 1805 * Minor clarifications. 1807 draft-liu-anima-grasp-api-03, 2017-02-13: 1809 * Changed error return to integers. 1811 * Required all implementations to accept objective values in CBOR. 1813 * Added non-blocking alternatives. 1815 draft-liu-anima-grasp-api-02, 2016-12-17: 1817 * Updated for draft-ietf-anima-grasp-09 1819 draft-liu-anima-grasp-api-02, 2016-09-30: 1821 * Added items for draft-ietf-anima-grasp-07 1823 * Editorial corrections 1825 draft-liu-anima-grasp-api-01, 2016-06-24: 1827 * Updated for draft-ietf-anima-grasp-05 1829 * Editorial corrections 1831 draft-liu-anima-grasp-api-00, 2016-04-04: 1833 * Initial version 1835 Authors' Addresses 1836 Brian Carpenter 1837 School of Computer Science 1838 University of Auckland 1839 PB 92019 1840 Auckland 1142 1841 New Zealand 1843 Email: brian.e.carpenter@gmail.com 1845 Bing Liu (editor) 1846 Huawei Technologies 1847 Q14, Huawei Campus 1848 No.156 Beiqing Road 1849 Hai-Dian District, Beijing 1850 100095 1851 P.R. China 1853 Email: leo.liubing@huawei.com 1855 Wendong Wang 1856 BUPT University 1857 Beijing University of Posts & Telecom. 1858 No.10 Xitucheng Road 1859 Hai-Dian District, Beijing 100876 1860 P.R. China 1862 Email: wdwang@bupt.edu.cn 1864 Xiangyang Gong 1865 BUPT University 1866 Beijing University of Posts & Telecom. 1867 No.10 Xitucheng Road 1868 Hai-Dian District, Beijing 100876 1869 P.R. China 1871 Email: xygong@bupt.edu.cn