idnits 2.17.1 draft-ietf-anima-grasp-api-08.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 (14 November 2020) is 1258 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == 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: 1 error (**), 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: 18 May 2021 Huawei Technologies 6 W. Wang 7 X. Gong 8 BUPT University 9 14 November 2020 11 Generic Autonomic Signaling Protocol Application Program Interface 12 (GRASP API) 13 draft-ietf-anima-grasp-api-08 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 to the support for 23 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 18 May 2021. 43 Copyright Notice 45 Copyright (c) 2020 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 . . . . . . . . . . . . 8 65 2.2.3. Overlapping Sessions and Operations . . . . . . . . . 8 66 2.3. API definition . . . . . . . . . . . . . . . . . . . . . 9 67 2.3.1. Overview of Functions . . . . . . . . . . . . . . . . 9 68 2.3.2. Parameters and data structures . . . . . . . . . . . 10 69 2.3.3. Registration . . . . . . . . . . . . . . . . . . . . 14 70 2.3.4. Discovery . . . . . . . . . . . . . . . . . . . . . . 16 71 2.3.5. Negotiation . . . . . . . . . . . . . . . . . . . . . 18 72 2.3.6. Synchronization and Flooding . . . . . . . . . . . . 24 73 2.3.7. Invalid Message Function . . . . . . . . . . . . . . 29 74 3. Implementation Status [RFC Editor: please remove] . . . . . . 29 75 4. Security Considerations . . . . . . . . . . . . . . . . . . . 30 76 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 77 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30 78 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 79 7.1. Normative References . . . . . . . . . . . . . . . . . . 30 80 7.2. Informative References . . . . . . . . . . . . . . . . . 31 81 Appendix A. Error Codes . . . . . . . . . . . . . . . . . . . . 32 82 Appendix B. Change log [RFC Editor: Please remove] . . . . . . . 33 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 85 1. Introduction 87 As defined in [I-D.ietf-anima-reference-model], the Autonomic Service 88 Agent (ASA) is the atomic entity of an autonomic function, and it is 89 instantiated on autonomic nodes. These nodes are members of a secure 90 Autonomic Control Plane (ACP) such as defined by 91 [I-D.ietf-anima-autonomic-control-plane]. 93 When ASAs communicate with each other, they should use the Generic 94 Autonomic Signaling Protocol (GRASP) [I-D.ietf-anima-grasp]. GRASP 95 relies on the message confidentiality and integrity provided by the 96 ACP, with the consequence that all nodes in a given autonomic network 97 share the same trust boundary, i.e., the boundary of the ACP. Nodes 98 that have not successfully joined the ACP cannot send, receive or 99 intercept GRASP messages via the ACP, and cannot usurp ACP addresses. 100 An ASA runs in an ACP node and therefore inherits all its security 101 properties, i.e., message integrity, message confidentiality and the 102 fact that unauthorized nodes cannot join the ACP. All ASAs within a 103 given autonomic network therefore trust each other's messages. For 104 these reasons, the API defined in this document has no explicit 105 security features. 107 An important feature of GRASP is the concept of a GRASP Objective. 108 This is a data structure whose main contents are a name and a value, 109 explained at more length in the 'Terminology' section of 110 [I-D.ietf-anima-grasp]. When an Objective is passed from one ASA to 111 another using GRASP, its value is either conveyed in one direction 112 (by a process of synchronization or flooding), or negotiated 113 bilaterally. The semantics of the value are opaque to GRASP and 114 therefore to the API. Each objective must be accurately specified, 115 as discussed in the 'Objective Options' section of 116 [I-D.ietf-anima-grasp]. Data storage and consistency during 117 negotiation are the responsibility of the ASAs involved. 118 Additionally, GRASP needs to cache the latest values of Objectives 119 that are received by flooding. 121 As Figure 1 shows, a GRASP implementation could contain several sub- 122 layers. The bottom layer is the GRASP base protocol module, which is 123 only responsible for sending and receiving GRASP messages and 124 maintaining shared data structures. Above that is the basic API 125 described in this document. The upper layer contains some extended 126 API functions based upon GRASP basic protocol. For example, 127 [I-D.ietf-anima-grasp-distribution] describes a possible extended 128 function. 130 Multiple ASAs in a single node will share the same instance of GRASP, 131 much as multiple applications share a single TCP/IP stack. This 132 aspect is hidden from individual ASAs by the API, and is not further 133 discussed here. 135 It is desirable that ASAs can be designed as portable user-space 136 programs using a system-independent API. In many implementations, 137 the GRASP code will therefore be split between user space and kernel 138 space. In user space, library functions provide the API and 139 communicate directly with ASAs. In kernel space is a daemon, or a 140 set of sub-services, providing GRASP core functions that are 141 independent of specific ASAs, such as multicast handling and 142 relaying, and common data structures such as the discovery cache. 143 The GRASP API library would need to communicate with the GRASP core 144 via an inter-process communication (IPC) mechanism. The details of 145 this are system-dependent. 147 +--------------+ +--------------+ 148 | ASAs | | ASAs | 149 +--------------+ +--------------+ 150 | | | 151 | +------------------+ | 152 | | GRASP Extended | | 153 | | Function API | | 154 | +------------------+ | 155 | | | 156 +------------------------------------------+ 157 | GRASP API Library | 158 +------------------------------------------+ 159 | 160 IPC 161 | 162 +------------------------------------------+ 163 | GRASP Core | 164 | (functions, data structures, daemon(s)) | 165 +------------------------------------------+ 167 Figure 1: Software layout 169 Both the GRASP library and the extended function modules should be 170 available to the ASAs. However, since the extended functions are 171 expected to be added in an incremental manner, they will be the 172 subject of future documents. This document only describes the basic 173 GRASP API. 175 The functions provided by the API do not map one-to-one onto GRASP 176 messages. Rather, they are intended to offer convenient support for 177 message sequences (such as a discovery request followed by responses 178 from several peers, or a negotiation request followed by various 179 possible responses). This choice was made to assist ASA programmers 180 in writing code based on their application requirements rather than 181 needing to understand protocol details. 183 Note that a simple autonomic node might contain very few ASAs in 184 addition to the autonomic infrastructure components described in 185 [I-D.ietf-anima-bootstrapping-keyinfra] and 186 [I-D.ietf-anima-autonomic-control-plane]. Such a node might directly 187 integrate a GRASP protocol stack in its code and therefore not 188 require this API to be installed. However, the programmer would then 189 need a deeper understanding of the GRASP protocol than is needed to 190 use the API. 192 This document gives a conceptual outline of the API. It is not a 193 formal specification for any particular programming language or 194 operating system, and it is expected that details will be clarified 195 in individual implementations. 197 2. GRASP API for ASA 199 2.1. Design Assumptions 201 The assumption of this document is that any Autonomic Service Agent 202 (ASA) needs to call a GRASP module. The latter handles protocol 203 details (security, sending and listening for GRASP messages, waiting, 204 caching discovery results, negotiation looping, sending and receiving 205 sychronization data, etc.) but understands nothing about individual 206 GRASP objectives (Section 2.10 of [I-D.ietf-anima-grasp]). The 207 semantics of objectives are unknown to the GRASP module and are 208 handled only by the ASAs. Thus, this is an abstract API for use by 209 ASAs. Individual language bindings should be defined in separate 210 documents. 212 Different ASAs may make different use of GRASP features: 214 * Use GRASP only for discovery purposes. 216 * Use GRASP negotiation but only as an initiator (client). 218 * Use GRASP negotiation but only as a responder. 220 * Use GRASP negotiation as an initiator or responder. 222 * Use GRASP synchronization but only as an initiator (recipient). 224 * Use GRASP synchronization but only as a responder and/or flooder. 226 * Use GRASP synchronization as an initiator, responder and/or 227 flooder. 229 The API also assumes that one ASA may support multiple objectives. 230 Nothing prevents an ASA from supporting some objectives for 231 synchronization and others for negotiation. 233 The API design assumes that the operating system and programming 234 language provide a mechanism for simultaneous asynchronous 235 operations. This is discussed in detail in Section 2.2. 237 A few items are out of scope in this version, since practical 238 experience is required before including them: 240 * Authorization of ASAs is not defined as part of GRASP and is not 241 supported. 243 * User-supplied explicit locators for an objective are not 244 supported. The GRASP core will supply the locator, using the ACP 245 address of the node concerned. 247 * The Rapid mode of GRASP (Section 2.5.4 of [I-D.ietf-anima-grasp]) 248 is not supported. 250 2.2. Asynchronous Operations 252 GRASP depends on asynchronous operations and wait states, and some of 253 its messages are not idempotent, meaning that repeating a message may 254 cause repeated changes of state in the recipient ASA. Many ASAs will 255 need to support several concurrent operations; for example an ASA 256 might need to negotiate one objective with a peer while discovering 257 and synchronizing a different objective with a different peer. 258 Alternatively, an ASA which acts as a resource manager might need to 259 run simultaneous negotiations for a given objective with multiple 260 different peers. Such an ASA will probably need to support 261 uninterruptible atomic changes to its internal data structures, using 262 a mechanism provided by the operating system and programming language 263 in use. 265 2.2.1. Alternative Asynchronous Mechanisms 267 Thus, some ASAs need to support asynchronous operations, and 268 therefore the GRASP core must do so. Depending on both the operating 269 system and the programming language in use, there are various 270 techniques for such parallel operations, three of which we consider 271 here: multi-threading, an event loop structure using polling, and an 272 event loop structure using callback functions. 274 1. In multi-threading, the operating system and language will 275 provide the necessary support for asynchronous operations, 276 including creation of new threads, context switching between 277 threads, queues, locks, and implicit wait states. In this case, 278 API calls can be treated as simple synchronous function calls 279 within their own thread, even if the function includes wait 280 states, blocking and queueing. Concurrent operations will each 281 run in their own threads. For example, the discover() call may 282 not return until discovery results have arrived or a timeout has 283 occurred. If the ASA has other work to do, the discover() call 284 must be in a thread of its own. 286 2. In an event loop implementation with polling, blocking calls are 287 not acceptable. Therefore all calls must be non-blocking, and 288 the main loop could support multiple GRASP sessions in parallel 289 by repeatedly polling each one for a change of state. To 290 facilitate this, the API implementation would provide non- 291 blocking versions of all the functions that otherwise involve 292 blocking and queueing. In these calls, a 'noReply' code will be 293 returned by each call instead of blocking, until such time as the 294 event for which it is waiting (or a failure) has occurred. Thus, 295 for example, discover() would return 'noReply' instead of waiting 296 until discovery has succeeded or timed out. The discover() call 297 would be repeated in every cycle of the main loop until it 298 completes. Effectively, it becomes a polling call. 300 3. It was noted earlier that some GRASP messages are not idempotent; 301 in particular this applies to each step in a negotiation session 302 - sending the same message twice might produce unintended side 303 effects. This is not affected by event loop polling: repeating a 304 call after a 'noReply' does not repeat a message; it simply 305 checks whether a reply has been received. 307 4. In an event loop implementation with callbacks, the ASA 308 programmer would provide a callback function for each 309 asynchronous operation, e.g. discovery_received(). This would be 310 called asynchronously when a reply is received or a failure such 311 as a timeout occurs. 313 The following calls involve waiting for a remote operation, so they 314 could use a polling or callback mechanism. In a threaded mechanism, 315 they will usually require to be called in a separate thread: 317 discover() whose callback would be discovery_received(). 319 request_negotiate() whose callback would be 320 negotiate_step_received(). 322 negotiate_step() whose callback would be 323 negotiate_step_received(). 325 listen_negotiate() whose callback would be 326 negotiate_step_received(). 328 synchronize() whose callback would be synchronization_received(). 330 2.2.2. Multiple Negotiation Scenario 332 The design of GRASP allows the following scenario. Consider an ASA 333 "A" that acts as a resource allocator for some objective. An ASA "B" 334 launches a negotiation with "A" to obtain or release a quantity of 335 the resource. While this negotatition is under way, "B" chooses to 336 launch a second simultaneous negotiation with "A" for a different 337 quantity of the same resource. "A" must therefore conduct two 338 separate negotiation sessions at the same time with the same peer, 339 and must not mix them up. 341 Note that ASAs could be designed to avoid such a scenario, i.e. 342 restricted to exactly one negotiation session at a time for a given 343 objective, but this would be a voluntary restriction not required by 344 the GRASP protocol. In fact it is an assumption of GRASP that any 345 ASA managing a resource may need to conduct multiple parallel 346 negotiations, possibly with the same peer. Communication patterns 347 could be very complex, with a group of ASAs overlapping negotiations 348 among themselves, as described in [I-D.ciavaglia-anima-coordination]. 349 Therefore, the API design allows for such scenarios. 351 In the callback model, for the scenario just described, the ASAs "A" 352 and "B" will each provide two instances of negotiate_step_received(), 353 one for each session. For this reason, each ASA must be able to 354 distinguish the two sessions, and the peer's IP address is not 355 sufficient for this. It is also not safe to rely on transport port 356 numbers for this, since future variants of GRASP might use shared 357 ports rather than a separate port per session. Hence the GRASP 358 design includes a session identifier. Thus, when necessary, a 359 'session_nonce' parameter is used in the API to distinguish 360 simultaneous GRASP sessions from each other, so that any number of 361 sessions may proceed asynchronously in parallel. 363 2.2.3. Overlapping Sessions and Operations 365 A GRASP session consists of a finite sequence of messages (for 366 discovery, synchronization, or negotiation) between ASAs. It is 367 identified by a pseudo-random session identifier tagged with an IP 368 address of the initiator of the session to guarantee uniqueness. 369 Further details are given in [I-D.ietf-anima-grasp]. 371 On the first call in a new GRASP session, the API returns a 372 'session_nonce' value based on the GRASP session identifier. This 373 value must be used in all subsequent calls for the same session, and 374 will be provided as a parameter in the callback functions. By this 375 mechanism, multiple overlapping sessions can be distinguished, both 376 in the ASA and in the GRASP core. The value of the 'session_nonce" 377 is opaque to the ASA. 379 An additional mechanism that might increase efficiency for polling 380 implementations is to add a general call, say notify(), which would 381 check the status of all outstanding operations for the calling ASA 382 and return the session_nonce values for all sessions that have 383 changed state. This would eliminate the need for repeated calls to 384 the individual functions returning a 'noReply'. This call is not 385 described below as the details are likely to be implementation- 386 specific. 388 An implication of the above for all GRASP implementations is that the 389 GRASP core must keep state for each GRASP operation in progress, most 390 likely keyed by the GRASP Session ID and the GRASP source address of 391 the session initiator. Even in a threaded implementation, the GRASP 392 core will need such state internally. The session_nonce parameter 393 exposes this aspect of the implementation. 395 2.3. API definition 397 2.3.1. Overview of Functions 399 The functions provided by the API fall into several groups: 401 * Registration. These functions allow an ASA to register itself 402 with the GRASP core, and allow a registered ASA to register the 403 GRASP Objectives that it will manipulate. 405 * Discovery. This function allows an ASA that needs to initiate 406 negotiation or synchronization of a particular Objective to 407 discover a peer willing to respond. 409 * Negotiation. These functions allow an ASA to act as an initiator 410 (requester) or responder (listener) for a GRASP negotiation 411 session. After initiation, negotiation is a symmetric process, so 412 most of the functions can be used by either party. 414 * Synchronization. These functions allow an ASA to to act as an 415 initiator (requester) or responder (listener and data source) for 416 a GRASP synchronization session. 418 * Flooding. These functions allow an ASA to send and receive an 419 Objective that is flooded to all nodes of the ACP. 421 Some example logic flows for a resource management ASA are given in 422 [I-D.ietf-anima-asa-guidelines], which may be of help in 423 understanding the following descriptions. The next section describes 424 parameters and data structures used in multiple API calls. The 425 following sections describe various groups of function APIs. Those 426 APIs that do not list asynchronous mechanisms are implicitly 427 synchronous in their behaviour. 429 2.3.2. Parameters and data structures 431 2.3.2.1. Errorcode 433 All functions in the API have an unsigned 'errorcode' integer as 434 their return value (the first returned value in languages that allow 435 multiple returned parameters). An errorcode of zero indicates 436 success. Any other value indicates failure of some kind. The first 437 three errorcodes have special importance: 439 1. Declined: used to indicate that the other end has sent a GRASP 440 Negotiation End message (M_END) with a Decline option 441 (O_DECLINE). 443 2. No reply: used in non-blocking calls to indicate that the other 444 end has sent no reply so far (see Section 2.2). 446 3. Unspecified error: used when no more specific error code applies. 448 Appendix A gives a full list of currently suggested error codes, 449 based on implementation experience. While there is no absolute 450 requirement for all implementations to use the same error codes, this 451 is highly recommended for portability of applications. 453 2.3.2.2. Timeout 455 Wherever a 'timeout' parameter appears, it is an integer expressed in 456 milliseconds. If it is zero, the GRASP default timeout 457 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]) will apply. If no 458 response is received before the timeout expires, the call will fail 459 unless otherwise noted. 461 2.3.2.3. Objective 463 An 'objective' parameter is a data structure with the following 464 components: 466 * name (UTF-8 string) - the objective's name 468 * neg (Boolean flag) - True if objective supports negotiation 469 (default False) 471 * synch (Boolean flag) - True if objective supports synchronization 472 (default False) 474 * dry (Boolean flag) - True if objective supports dry-run 475 negotiation (default False) 477 - Note 1: Only one of 'synch' or 'neg' may be True. 479 - Note 2: 'dry' must not be True unless 'neg' is also True. 481 - Note 3: In a language such as C the preferred implementation 482 may be to represent the Boolean flags as bits in a single byte, 483 which is how they are encoded in GRASP messages. In other 484 languages an enumeration might be preferable. 486 * loop_count (integer) - Limit on negotiation steps etc. (default 487 GRASP_DEF_LOOPCT, see [I-D.ietf-anima-grasp]) 489 * value - a specific data structure expressing the value of the 490 objective. The format is language dependent, with the constraint 491 that it can be validly represented in CBOR. 493 An essential requirement for all language mappings and all 494 implementations is that, regardless of what other options exist 495 for a language-specific representation of the value, there is 496 always an option to use a raw CBOR data item as the value. The 497 API will then wrap this with CBOR Tag 24 as an encoded CBOR data 498 item [RFC7049] for transmission via GRASP, and unwrap it after 499 reception. 501 The 'name' and 'value' fields are of variable length. GRASP does 502 not set a maximum length for these fields, but only for the total 503 length of a GRASP message. Implementations might impose length 504 limits. 506 An example data structure definition for an objective in the C 507 language, assuming the use of a particular CBOR library, is: 509 typedef struct { 510 char *name; 511 uint8_t flags; // flag bits as defined by GRASP 512 int loop_count; 513 int value_size; // size of value in bytes 514 cbor_mutable_data cbor_value; 515 // CBOR bytestring (libcbor/cbor/data.h) 516 } objective; 518 An example data structure definition for an objective in the 519 Python language is: 521 class objective: 522 """A GRASP objective""" 523 def __init__(self, name): 524 self.name = name # Unique name (string) 525 self.negotiate = False #True if objective supports negotiation 526 self.dryrun = False #True if objective supports dry-run neg. 527 self.synch = False # True if objective supports synch 528 self.loop_count = GRASP_DEF_LOOPCT # Default starting value 529 self.value = 0 # Place holder; any valid Python object 531 2.3.2.4. ASA_locator 533 An 'ASA_locator' parameter is a data structure with the following 534 contents: 536 * locator - The actual locator, either an IP address or an ASCII 537 string. 539 * ifi (integer) - The interface identifier index via which this was 540 discovered - probably no use to a normal ASA 542 * expire (system dependent type) - The time on the local system 543 clock when this locator will expire from the cache 545 * The following cover all locator types currently supported by 546 GRASP: 548 - is_ipaddress (Boolean) - True if the locator is an IP address 550 - is_fqdn (Boolean) - True if the locator is an FQDN 552 - is_uri (Boolean) - True if the locator is a URI 554 - Note: Depending on the programming language, these could be 555 represented as a bit pattern or an enumeration. 557 * diverted (Boolean) - True if the locator was discovered via a 558 Divert option 560 * protocol (integer) - Applicable transport protocol (IPPROTO_TCP or 561 IPPROTO_UDP) 563 * port (integer) - Applicable port number 565 The 'locator' field is of variable length in the case of an FQDN or a 566 URI. GRASP does not set a maximum length for this field, but only 567 for the total length of a GRASP message. Implementations might 568 impose length limits. 570 It should be noted that when one ASA discovers the ASA_locator of 571 another, there is no explicit authentication mechanism. In 572 accordance with the trust model provided by the secure ACP, ASAs are 573 presumed to provide correct locators in response to discovery. 575 2.3.2.5. Tagged_objective 577 A 'tagged_objective' parameter is a data structure with the following 578 contents: 580 * objective - An objective 582 * locator - The ASA_locator associated with the objective, or a null 583 value. 585 2.3.2.6. Asa_nonce 587 Although an authentication and authorization scheme for ASAs has not 588 been defined, the API provides a very simple hook for such a scheme. 589 When an ASA starts up, it registers itself with the GRASP core, which 590 provides it with an opaque nonce that, although not cryptographically 591 protected, would be difficult for a third party to predict. The ASA 592 must present this nonce in future calls. This mechanism will prevent 593 some elementary errors or trivial attacks such as an ASA manipulating 594 an objective it has not registered to use. 596 Thus, in most calls, an 'asa_nonce' parameter is required. It is 597 generated when an ASA first registers with GRASP, and the ASA must 598 then store the asa_nonce and use it in every subsequent GRASP call. 599 Any call in which an invalid nonce is presented will fail. It is an 600 up to 32-bit opaque value (for example represented as a uint32_t, 601 depending on the language). Since it is only used locally, not in 602 GRASP messages, it is only required to be unique within the local 603 GRASP instance. It is valid until the ASA terminates. It should be 604 unpredictable; a possible implementation is to use the same mechanism 605 that GRASP uses to generate Session Identifiers (see 606 Section 2.3.2.7). Another possible implementation is to hash the 607 name of the ASA with a locally defined secret key. 609 2.3.2.7. Session_nonce 611 In some calls, a 'session_nonce' parameter is required. This is an 612 opaque data structure as far as the ASA is concerned, used to 613 identify calls to the API as belonging to a specific GRASP session 614 (see Section 2.2). The section 'Session Identifier' of 615 [I-D.ietf-anima-grasp] explains how uniqueness of Session Identifiers 616 is provided across the autonomic network. In fully threaded 617 implementations this parameter might not be needed, but it is 618 included to act as a session handle if necessary. It will also allow 619 GRASP to detect and ignore malicious calls or calls from timed-out 620 sessions. A likely implementation is to form the nonce from the 621 underlying GRASP Session ID and the source address of the session. 623 2.3.3. Registration 625 These functions are used to register an ASA, and the objectives that 626 it modifies, with the GRASP module. In the absence of an 627 authorization model, these functions are very simple but they will 628 avoid multiple ASAs choosing the same name, and will prevent multiple 629 ASAs manipulating the same objective. If an authorization model is 630 added to GRASP, these API calls would need to be modified 631 accordingly. 633 * register_asa() 635 All ASAs must use this call. 637 - Input parameter: 639 name of the ASA (UTF-8 string) 641 - Return parameters: 643 errorcode (integer) 645 asa_nonce (integer) (if successful) 647 - This initialises state in the GRASP module for the calling 648 entity (the ASA). In the case of success, an 'asa_nonce' is 649 returned which the ASA must present in all subsequent calls. 650 In the case of failure, the ASA has not been authorized and 651 cannot operate. 653 * deregister_asa() 655 - Input parameters: 657 asa_nonce (integer) 659 name of the ASA (UTF-8 string) 661 - Return parameter: 663 errorcode (integer) 665 - This removes all state in the GRASP module for the calling 666 entity (the ASA), and deregisters any objectives it has 667 registered. Note that these actions must also happen 668 automatically if an ASA crashes. 670 - Note - the ASA name is strictly speaking redundant in this 671 call, but is present for clarity. 673 * register_objective() 675 ASAs must use this call for any objective whose value they need to 676 transmit by negotiation, synchronization or flooding. 678 - Input parameters: 680 asa_nonce (integer) 682 objective (structure) 684 ttl (integer - default GRASP_DEF_TIMEOUT) 686 discoverable (Boolean - default False) 688 overlap (Boolean - default False) 690 local (Boolean - default False) 692 - Return parameter: 694 errorcode (integer) 696 - This registers an objective that this ASA may modify and 697 transmit to other ASAs. It is not necessary to register an 698 objective that is only received by GRASP synchronization or 699 flooding. The 'objective' becomes a candidate for discovery. 700 However, discovery responses should not be enabled until the 701 ASA calls listen_negotiate() or listen_synchronize(), showing 702 that it is able to act as a responder. The ASA may negotiate 703 the objective or send synchronization or flood data. 704 Registration is not needed for "read-only" operations, i.e., 705 the ASA only wants to receive synchronization or flooded data 706 for the objective concerned. 708 - The 'ttl' parameter is the valid lifetime (time to live) in 709 milliseconds of any discovery response for this objective. The 710 default value should be the GRASP default timeout 711 (GRASP_DEF_TIMEOUT, see [I-D.ietf-anima-grasp]). 713 - If the parameter 'discoverable' is True, the objective is 714 immediately discoverable. This is intended for objectives that 715 are only defined for GRASP discovery, and which do not support 716 negotiation or synchronization. 718 - If the parameter 'overlap' is True, more than one ASA may 719 register this objective in the same GRASP instance. 721 - If the parameter 'local' is True, discovery must return a link- 722 local address. This feature is for objectives that must be 723 restricted to the local link. 725 - This call may be repeated for multiple objectives. 727 * deregister_objective() 729 - Input parameters: 731 asa_nonce (integer) 733 objective (structure) 735 - Return parameter: 737 errorcode (integer) 739 - The 'objective' must have been registered by the calling ASA; 740 if not, this call fails. Otherwise, it removes all state in 741 the GRASP module for the given objective. 743 2.3.4. Discovery 745 * discover() 747 This function may be used by any ASA to discover peers handling a 748 given objective. 750 - Input parameters: 752 asa_nonce (integer) 754 objective (structure) 756 timeout (integer) 758 minimum_TTL (integer) 760 - Return parameters: 762 errorcode (integer) 764 locator_list (structure) 766 - This returns a list of discovered 'ASA_locator's for the given 767 objective. Note that this structure includes all the fields 768 described in Section 2.3.2.4. 770 - If the parameter 'minimum_TTL' is greater than zero, any 771 locally cached locators for the objective whose remaining time 772 to live in milliseconds is less than or equal to 'minimum_TTL' 773 are deleted first. Thus 'minimum_TTL' = 0 will flush all 774 entries. 776 - If the parameter 'timeout' is zero, any remaining locally 777 cached locators for the objective are returned immediately and 778 no other action is taken. (Thus, a call with 'minimum_TTL' and 779 'timeout' both equal to zero is pointless.) 781 - If the parameter 'timeout' is greater than zero, GRASP 782 discovery is performed, and all results obtained before the 783 timeout in milliseconds expires are returned. If no results 784 are obtained, an empty list is returned after the timeout. 785 That is not an error condition. 787 - Asynchronous Mechanisms: 789 o Threaded implementation: This should be called in a separate 790 thread if asynchronous operation is required. 792 o Event loop implementation: An additional read/write 793 'session_nonce' parameter is used. A callback may be used 794 in the case of a non-zero tiemout. 796 2.3.5. Negotiation 798 Since the negotiation mechanism is different from a typical client/ 799 server exchange, Figure 2 illustrates the sequence of calls and GRASP 800 messages in a negotiation. Note that after the first protocol 801 exchange, the process is symmetrical and either side can end the 802 negotiation. Similarly, either side can insert a delay at any time, 803 to extend the other side's timeout. 805 Initiator Responder 806 --------- --------- 808 listen_negotiate() \ Await request 810 request_negotiate() 811 M_REQ_NEG -> negotiate_step() \ Open session, 812 <- M_NEGOTIATE / start negotiation 813 negotiate_step() 814 M_NEGOTIATE -> negotiate_step() \ Continue 815 <- M_NEGOTIATE / negotiation 816 ... 817 negotiate_wait() \ Insert 818 M_WAIT -> / delay 819 negotiate_step() 820 M_NEGOTIATE -> negotiate_step() \ Continue 821 <- M_NEGOTIATE / negotiation 822 negotiate_step() 823 M_NEGOTIATE -> end_negotiate() \ End 824 <- M_END / negotiation 826 \ Process results 828 Figure 2: Negotiation sequence 830 * request_negotiate() 832 This function is used by any ASA to initiate negotiation of a 833 GRASP Objective as a requester (client). 835 - Input parameters: 837 asa_nonce (integer) 839 objective (structure) 841 peer (ASA_locator) 843 timeout (integer) 845 - Return parameters: 847 errorcode (integer) 849 session_nonce (structure) (if successful) 851 proffered_objective (structure) (if successful) 853 reason (string) (if negotiation declined) 855 - This function opens a negotiation session between two ASAs. 856 Note that GRASP currently does not support multi-party 857 negotiation, which would need to be added as an extended 858 function. 860 - The 'objective' parameter must include the requested value, and 861 its loop count should be set to a suitable starting value by 862 the ASA. If not, the GRASP default will apply. 864 - Note that a given negotiation session may or may not be a dry- 865 run negotiation; the two modes must not be mixed in a single 866 session. 868 - The 'peer' parameter is the target node; it must be an 869 'ASA_locator' as returned by discover(). If 'peer' is null, 870 GRASP discovery is automatically performed first to find a 871 suitable peer (i.e., any node that supports the objective in 872 question). 874 - The 'timeout' parameter is described in Section 2.3.2.2. 876 - If the 'errorcode' return parameter is 0, the negotiation has 877 successfully started. There are then two cases: 879 1. The 'session_nonce' parameter is null. In this case the 880 negotiation has succeeded in one step and the peer has 881 accepted the request. The returned 'proffered_objective' 882 contains the value accepted by the peer, which is therefore 883 equal to the value in the requested 'objective'. For this 884 reason, no session nonce is needed, since the session has 885 ended. 887 2. The 'session_nonce' parameter is not null. In this case 888 negotiation must continue. The 'session_nonce' must be 889 presented in all subsequent negotiation steps. The 890 returned 'proffered_objective' contains the first value 891 proffered by the negotiation peer. The contents of this 892 instance of the objective must be used to prepare the next 893 negotiation step (see negotiate_step() below) because it 894 contains the updated loop count, sent by the negotiation 895 peer. The GRASP code automatically decrements the loop 896 count by 1 at each step, and returns an error if it becomes 897 zero. 899 This function must be followed by calls to 'negotiate_step' 900 and/or 'negotiate_wait' and/or 'end_negotiate' until the 901 negotiation ends. 'request_negotiate' may then be called 902 again to start a new negotiation. 904 - If the 'errorcode' parameter has the value 1 ('declined'), the 905 negotiation has been declined by the peer (M_END and O_DECLINE 906 features of GRASP). The 'reason' string is then available for 907 information and diagnostic use, but it may be a null string. 908 For this and any other error code, an exponential backoff is 909 recommended before any retry. 911 - Asynchronous Mechanisms: 913 o Threaded implementation: This should be called in a separate 914 thread if asynchronous operation is required. 916 o Event loop implementation: The 'session_nonce' parameter is 917 used to distinguish multiple simultaneous sessions. 919 - Use of dry run mode: This must be consistent within a GRASP 920 session. The state of the 'dry' flag in the initial 921 request_negotiate() call must be the same in all subsequent 922 negotiation steps of the same session. The semantics of the 923 dry run mode are built into the ASA; GRASP merely carries the 924 flag bit. 926 - Special note for the ACP infrastructure ASA: It is likely that 927 this ASA will need to discover and negotiate with its peers in 928 each of its on-link neighbors. It will therefore need to know 929 not only the link-local IP address but also the physical 930 interface and transport port for connecting to each neighbor. 931 One implementation approach to this is to include these details 932 in the 'session_nonce' data structure, which is opaque to 933 normal ASAs. 935 * listen_negotiate() 937 This function is used by an ASA to start acting as a negotiation 938 responder (listener) for a given GRASP objective. 940 - Input parameters: 942 asa_nonce (integer) 944 objective (structure) 946 - Return parameters: 948 errorcode (integer) 950 session_nonce (structure) (if successful) 952 requested_objective (structure) (if successful) 954 - This function instructs GRASP to listen for negotiation 955 requests for the given 'objective'. It also enables discovery 956 responses for the objective, as mentioned under 957 register_objective() in Section 2.3.3. 959 - Asynchronous Mechanisms: 961 o Threaded implementation: It will block waiting for an 962 incoming request, so should be called in a separate thread 963 if asynchronous operation is required. Unless there is an 964 unexpected failure, this call only returns after an incoming 965 negotiation request. If the ASA supports multiple 966 simultaneous transactions, a new sub-thread must be spawned 967 for each new session, so that listen_negotiate() can be 968 called again immediately. 970 o Event loop implementation: A 'session_nonce' parameter is 971 used to distinguish individual sessions. If the ASA 972 supports multiple simultaneous transactions, a new event 973 must be inserted in the event loop for each new session, so 974 that listen_negotiate() can be reactivated immediately. 976 - This call only returns (threaded model) or triggers (event 977 loop) after an incoming negotiation request. When this occurs, 978 'requested_objective' contains the first value requested by the 979 negotiation peer. The contents of this instance of the 980 objective must be used in the subsequent negotiation call 981 because it contains the loop count sent by the negotiation 982 peer. The 'session_nonce' must be presented in all subsequent 983 negotiation steps. 985 - This function must be followed by calls to 'negotiate_step' 986 and/or 'negotiate_wait' and/or 'end_negotiate' until the 987 negotiation ends. 'listen_negotiate' may then be called again 988 to await a new negotiation. 990 - If an ASA is capable of handling multiple negotiations 991 simultaneously, it may call 'listen_negotiate' simultaneously 992 from multiple threads, or insert multiple events. The API and 993 GRASP implementation must support re-entrant use of the 994 listening state and the negotiation calls. Simultaneous 995 sessions will be distinguished by the threads or events 996 themselves, the GRASP session nonces, and the underlying 997 unicast transport sockets. 999 * stop_listen_negotiate() 1001 This function is used by an ASA to stop acting as a responder 1002 (listener) for a given GRASP objective. 1004 - Input parameters: 1006 asa_nonce (integer) 1008 objective (structure) 1010 - Return parameter: 1012 errorcode (integer) 1014 - Instructs GRASP to stop listening for negotiation requests for 1015 the given objective, i.e., cancels 'listen_negotiate'. 1017 - Asynchronous Mechanisms: 1019 o Threaded implementation: Must be called from a different 1020 thread than 'listen_negotiate'. 1022 o Event loop implementation: no special considerations. 1024 * negotiate_step() 1026 This function is used by either ASA in a negotiation session to 1027 make the next step in negotiation. 1029 - Input parameters: 1031 asa_nonce (integer) 1033 session_nonce (structure) 1035 objective (structure) 1037 timeout (integer) as described in Section 2.3.2.2 1039 - Return parameters: 1041 Exactly as for 'request_negotiate' 1043 - Executes the next negotation step with the peer. The 1044 'objective' parameter contains the next value being proffered 1045 by the ASA in this step. It must also contain the latest 1046 'loop_count' value received from request_negotiate() or 1047 negotiate_step(). 1049 - Asynchronous Mechanisms: 1051 o Threaded implementation: Called in the same thread as the 1052 preceding 'request_negotiate' or 'listen_negotiate', with 1053 the same value of 'session_nonce'. 1055 o Event loop implementation: Must use the same value of 1056 'session_nonce' returned by the preceding 1057 'request_negotiate' or 'listen_negotiate'. 1059 * negotiate_wait() 1061 This function is used by either ASA in a negotiation session to 1062 delay the next step in negotiation. 1064 - Input parameters: 1066 asa_nonce (integer) 1068 session_nonce (structure) 1070 timeout (integer) 1072 - Return parameters: 1074 errorcode (integer) 1076 - Requests the remote peer to delay the negotiation session by 1077 'timeout' milliseconds, thereby extending the original timeout. 1078 This function simply triggers a GRASP Confirm Waiting message 1079 (see [I-D.ietf-anima-grasp] for details). 1081 - Asynchronous Mechanisms: 1083 o Threaded implementation: Called in the same thread as the 1084 preceding 'request_negotiate' or 'listen_negotiate', with 1085 the same value of 'session_nonce'. 1087 o Event loop implementation: Must use the same value of 1088 'session_nonce' returned by the preceding 1089 'request_negotiate' or 'listen_negotiate'. 1091 * end_negotiate() 1093 This function is used by either ASA in a negotiation session to 1094 end a negotiation. 1096 - Input parameters: 1098 asa_nonce (integer) 1100 session_nonce (structure) 1102 result (Boolean) 1104 reason (UTF-8 string) 1106 - Return parameters: 1108 errorcode (integer) 1110 - End the negotiation session. 1112 'result' = True for accept (successful negotiation), False for 1113 decline (failed negotiation). 1115 'reason' = optional string describing reason for decline. 1117 - Asynchronous Mechanisms: 1119 o Threaded implementation: Called in the same thread as the 1120 preceding 'request_negotiate' or 'listen_negotiate', with 1121 the same value of 'session_nonce'. 1123 o Event loop implementation: Must use the same value of 1124 'session_nonce' returned by the preceding 1125 'request_negotiate' or 'listen_negotiate'. 1127 2.3.6. Synchronization and Flooding 1129 * synchronize() 1131 This function is used by any ASA to cause synchronization of a 1132 GRASP Objective as a requester (client). 1134 - Input parameters: 1136 asa_nonce (integer) 1138 objective (structure) 1140 peer (ASA_locator) 1142 timeout (integer) 1144 - Return parameters: 1146 errorcode (integer) 1148 result (structure) (if successful) 1150 - This call requests the synchronized value of the given 1151 'objective'. 1153 - Since this is essentially a read operation, any ASA can do it, 1154 unless an authorization model is added to GRASP in future. 1155 Therefore the API checks that the ASA is registered, but the 1156 objective does not need to be registered by the calling ASA. 1158 - If the 'peer' parameter is null, and the objective is already 1159 available in the local cache, the flooded objective is returned 1160 immediately in the 'result' parameter. In this case, the 1161 'timeout' is ignored. 1163 - Otherwise, synchronization with a discovered ASA is performed. 1164 If successful, the retrieved objective is returned in the 1165 'result' parameter. 1167 - The 'peer' parameter is an 'ASA_locator' as returned by 1168 discover(). If 'peer' is null, GRASP discovery is 1169 automatically performed first to find a suitable peer (i.e., 1170 any node that supports the objective in question). 1172 - The 'timeout' parameter is described in Section 2.3.2.2. 1174 - This call should be repeated whenever the latest value is 1175 needed. 1177 - Asynchronous Mechanisms: 1179 o Threaded implementation: Call in a separate thread if 1180 asynchronous operation is required. 1182 o Event loop implementation: An additional read/write 1183 'session_nonce' parameter is used. 1185 - Since this is essentially a read operation, any ASA can use it. 1186 Therefore GRASP checks that the calling ASA is registered but 1187 the objective doesn't need to be registered by the calling ASA. 1189 - In the case of failure, an exponential backoff is recommended 1190 before retrying. 1192 * listen_synchronize() 1194 This function is used by an ASA to start acting as a 1195 synchronization responder (listener) for a given GRASP objective. 1197 - Input parameters: 1199 asa_nonce (integer) 1201 objective (structure) 1203 - Return parameters: 1205 errorcode (integer) 1207 - This instructs GRASP to listen for synchronization requests for 1208 the given objective, and to respond with the value given in the 1209 'objective' parameter. It also enables discovery responses for 1210 the objective, as mentioned under register_objective() in 1211 Section 2.3.3. 1213 - This call is non-blocking and may be repeated whenever the 1214 value changes. 1216 * stop_listen_synchronize() 1218 This function is used by an ASA to stop acting as a 1219 synchronization responder (listener) for a given GRASP objective. 1221 - Input parameters: 1223 asa_nonce (integer) 1225 objective (structure) 1227 - Return parameters: 1229 errorcode (integer) 1231 - This call instructs GRASP to stop listening for synchronization 1232 requests for the given 'objective', i.e. it cancels a previous 1233 listen_synchronize. 1235 * flood() 1237 This function is used by an ASA to flood one or more GRASP 1238 objectives throughout the autonomic network. 1240 Note that each GRASP node caches all flooded objectives that it 1241 receive, until each one's time-to-live expires. Cached objectives 1242 are tagged with their origin as well as an expiry time, so 1243 multiple copies of the same objective may be cached 1244 simultaneously. Further details are given in the section 'Flood 1245 Synchronization Message' of [I-D.ietf-anima-grasp] 1247 - Input parameters: 1249 asa_nonce (integer) 1251 ttl (integer) 1253 tagged_objective_list (structure) 1255 - Return parameters: 1257 errorcode (integer) 1259 - This call instructs GRASP to flood the given synchronization 1260 objective(s) and their value(s) and associated locator(s) to 1261 all GRASP nodes. 1263 - The 'ttl' parameter is the valid lifetime (time to live) of the 1264 flooded data in milliseconds (0 = infinity) 1266 - The 'tagged_objective_list' parameter is a list of one or more 1267 'tagged_objective' couplets. The 'locator' parameter that tags 1268 each objective is normally null but may be a valid 1269 'ASA_locator'. Infrastructure ASAs needing to flood an 1270 {address, protocol, port} 3-tuple with an objective create an 1271 ASA_locator object to do so. If the IP address in that locator 1272 is the unspecified address ('::') it is replaced by the link- 1273 local address of the sending node in each copy of the flood 1274 multicast, which will be forced to have a loop count of 1. 1275 This feature is for objectives that must be restricted to the 1276 local link. 1278 - The function checks that the ASA registered each objective. 1280 - This call may be repeated whenever any value changes. 1282 * get_flood() 1284 This function is used by any ASA to obtain the current value of a 1285 flooded GRASP objective. 1287 - Input parameters: 1289 asa_nonce (integer) 1291 objective (structure) 1293 - Return parameters: 1295 errorcode (integer) 1297 tagged_objective_list (structure) (if successful) 1299 - This call instructs GRASP to return the given synchronization 1300 objective if it has been flooded and its lifetime has not 1301 expired. 1303 - Since this is essentially a read operation, any ASA can do it. 1304 Therefore the API checks that the ASA is registered but the 1305 objective doesn't need to be registered by the calling ASA. 1307 - The 'tagged_objective_list' parameter is a list of 1308 'tagged_objective' couplets, each one being a copy of the 1309 flooded objective and a coresponding locator. Thus if the same 1310 objective has been flooded by multiple ASAs, the recipient can 1311 distinguish the copies. 1313 - Note that this call is for advanced ASAs. In a simple case, an 1314 ASA can simply call synchronize() in order to get a valid 1315 flooded objective. 1317 * expire_flood() 1319 This function may be used by an ASA to expire specific entries in 1320 the local GRASP flood cache. 1322 - Input parameters: 1324 asa_nonce (integer) 1326 tagged_objective (structure) 1328 - Return parameters: 1330 errorcode (integer) 1332 - This is a call that can only be used after a preceding call to 1333 get_flood() by an ASA that is capable of deciding that the 1334 flooded value is stale or invalid. Use with care. 1336 - The 'tagged_objective' parameter is the one to be expired. 1338 2.3.7. Invalid Message Function 1340 * send_invalid() 1342 This function may be used by any ASA to stop an ongoing GRASP 1343 session. 1345 - Input parameters: 1347 asa_nonce (integer) 1349 session_nonce (structure) 1351 info (bytes) 1353 - Return parameters: 1355 errorcode (integer) 1357 - Sends a GRASP Invalid Message (M_INVALID) message, as described 1358 in [I-D.ietf-anima-grasp]. Should not be used if 1359 end_negotiate() would be sufficient. Note that this message 1360 may be used in response to any unicast GRASP message that the 1361 receiver cannot interpret correctly. In most cases this 1362 message will be generated internally by a GRASP implementation. 1364 'info' = optional diagnostic data. May be raw bytes from the 1365 invalid message. 1367 3. Implementation Status [RFC Editor: please remove] 1369 A prototype open source Python implementation of GRASP, including an 1370 API similar to this document, has been used to verify the concepts 1371 for the threaded model. It may be found at 1372 https://github.com/becarpenter/graspy with associated documentation 1373 and demonstration ASAs. 1375 4. Security Considerations 1377 Security considerations for the GRASP protocol are discussed in 1378 [I-D.ietf-anima-grasp]. These include denial of service issues, even 1379 though these are considered a low risk in the ACP. In various places 1380 GRASP recommends an exponential backoff. An ASA using the API should 1381 use exponential backoff after failed discover(), req_negotiate() or 1382 synchronize() operations. The timescale for such backoffs depends on 1383 the semantics of the GRASP objective concerned. Additionally, a 1384 flood() operation should not be repeated at shorter intervals than is 1385 useful. The appropriate interval depends on the semantics of the 1386 GRASP objective concerned. These precautions are intended to assist 1387 the detection of malicious denial of service attacks. 1389 As a general precaution, all ASAs able to handle multiple negotiation 1390 or synchronization requests in parallel may protect themselves 1391 against a denial of service attack by limiting the number of requests 1392 they can handle simultaneously and silently discarding excess 1393 requests. 1395 As noted earlier, the trust model is that all ASAs in a given 1396 autonomic network communicate via a secure autonomic control plane 1397 and therefore trust each other's messages. Specific authorization of 1398 ASAs to use particular GRASP objectives is a subject for future 1399 study, also briefly discussed in [I-D.ietf-anima-grasp]. 1401 The 'asa_nonce' parameter is used in the API as a first line of 1402 defence against a malware process attempting to imitate a 1403 legitimately registered ASA. The 'session_nonce' parameter is used 1404 in the API as a first line of defence against a malware process 1405 attempting to hijack a GRASP session. 1407 5. IANA Considerations 1409 This document makes no request of the IANA. 1411 6. Acknowledgements 1413 Excellent suggestions were made by Ignas Bagdonas, Laurent Ciavaglia, 1414 Toerless Eckert, Paul Kyzivat, Guangpeng Li, Michael Richardson, 1415 Joseph Salowey, Rob Wilton, and other participants in the ANIMA WG. 1417 7. References 1419 7.1. Normative References 1421 [I-D.ietf-anima-grasp] 1422 Bormann, C., Carpenter, B., and B. Liu, "A Generic 1423 Autonomic Signaling Protocol (GRASP)", Work in Progress, 1424 Internet-Draft, draft-ietf-anima-grasp-15, 13 July 2017, 1425 . 1427 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1428 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1429 October 2013, . 1431 7.2. Informative References 1433 [I-D.ciavaglia-anima-coordination] 1434 Ciavaglia, L. and P. Peloso, "Autonomic Functions 1435 Coordination", Work in Progress, Internet-Draft, draft- 1436 ciavaglia-anima-coordination-01, 21 March 2016, 1437 . 1440 [I-D.ietf-anima-asa-guidelines] 1441 Carpenter, B., Ciavaglia, L., Jiang, S., and P. Pierre, 1442 "Guidelines for Autonomic Service Agents", Work in 1443 Progress, Internet-Draft, draft-ietf-anima-asa-guidelines- 1444 00, 14 November 2020, . 1447 [I-D.ietf-anima-autonomic-control-plane] 1448 Eckert, T., Behringer, M., and S. Bjarnason, "An Autonomic 1449 Control Plane (ACP)", Work in Progress, Internet-Draft, 1450 draft-ietf-anima-autonomic-control-plane-30, 30 October 1451 2020, . 1454 [I-D.ietf-anima-bootstrapping-keyinfra] 1455 Pritikin, M., Richardson, M., Eckert, T., Behringer, M., 1456 and K. Watsen, "Bootstrapping Remote Secure Key 1457 Infrastructures (BRSKI)", Work in Progress, Internet- 1458 Draft, draft-ietf-anima-bootstrapping-keyinfra-45, 11 1459 November 2020, . 1462 [I-D.ietf-anima-grasp-distribution] 1463 Liu, B., Xiao, X., Hecker, A., Jiang, S., Despotovic, Z., 1464 and B. Carpenter, "Information Distribution over GRASP", 1465 Work in Progress, Internet-Draft, draft-ietf-anima-grasp- 1466 distribution-01, 1 September 2020, 1467 . 1470 [I-D.ietf-anima-reference-model] 1471 Behringer, M., Carpenter, B., Eckert, T., Ciavaglia, L., 1472 and J. Nobre, "A Reference Model for Autonomic 1473 Networking", Work in Progress, Internet-Draft, draft-ietf- 1474 anima-reference-model-10, 22 November 2018, 1475 . 1478 Appendix A. Error Codes 1480 This Appendix lists the error codes defined so far on the basis of 1481 implementation experience, with suggested symbolic names and 1482 corresponding descriptive strings in English. It is expected that 1483 complete API implementations will provide for localisation of these 1484 descriptive strings, and that additional error codes will be needed 1485 according to implementation details. 1487 The error codes that may only be returned by one or two functions are 1488 annotated accordingly, and the others are more general. The 1489 'noSecurity' error will be returned to most calls if GRASP is running 1490 in an insecure mode (no ACP), except for the specific DULL usage mode 1491 described in the section 'Discovery Unsolicited Link-Local' of 1492 [I-D.ietf-anima-grasp]. 1494 ok 0 "OK" 1495 declined 1 "Declined" (req_negotiate, negotiate_step) 1496 noReply 2 "No reply" 1497 unspec 3 "Unspecified error" 1498 ASAfull 4 "ASA registry full" (register_asa) 1499 dupASA 5 "Duplicate ASA name" (register_asa) 1500 noASA 6 "ASA not registered" 1501 notYourASA 7 "ASA registered but not by you" 1502 (deregister_asa) 1503 notBoth 8 "Objective cannot support both negotiation 1504 and synchronization" (register_obj) 1505 notDry 9 "Dry-run allowed only with negotiation" 1506 (register_obj) 1507 notOverlap 10 "Overlap not supported by this implementation" 1508 (register_obj) 1509 objFull 11 "Objective registry full" 1510 (register_obj) 1511 objReg 12 "Objective already registered" 1512 (register_obj) 1513 notYourObj 13 "Objective not registered by this ASA" 1514 notObj 14 "Objective not found" 1515 notNeg 15 "Objective not negotiable" 1516 (req_negotiate, listen_negotiate) 1517 noSecurity 16 "No security" 1518 noDiscReply 17 "No reply to discovery" 1519 (req_negotiate) 1520 sockErrNegRq 18 "Socket error sending negotiation request" 1521 (req_negotiate) 1522 noSession 19 "No session" 1523 noSocket 20 "No socket" 1524 loopExhausted 21 "Loop count exhausted" (negotiate_step) 1525 sockErrNegStep 22 "Socket error sending negotiation step" 1526 (negotiate_step) 1527 noPeer 23 "No negotiation peer" 1528 (req_negotiate, negotiate_step) 1529 CBORfail 24 "CBOR decode failure" 1530 invalidNeg 25 "Invalid Negotiate message" 1531 (req_negotiate, negotiate_step) 1532 invalidEnd 26 "Invalid end message" 1533 (req_negotiate, negotiate_step) 1534 noNegReply 27 "No reply to negotiation step" 1535 (req_negotiate, negotiate_step) 1536 noValidStep 28 "No valid reply to negotiation step" 1537 (req_negotiate, negotiate_step) 1538 sockErrWait 29 "Socket error sending wait message" 1539 (negotiate_wait) 1540 sockErrEnd 30 "Socket error sending end message" 1541 (end_negotiate, send_invalid) 1542 IDclash 31 "Incoming request Session ID clash" 1543 (listen_negotiate) 1544 notSynch 32 "Not a synchronization objective" 1545 (synchronize, get_flood) 1546 notFloodDisc 33 "Not flooded and no reply to discovery" 1547 (synchronize) 1548 sockErrSynRq 34 "Socket error sending synch request" 1549 (synchronize) 1550 noListener 35 "No synch listener" 1551 (synchronize) 1552 noSynchReply 36 "No reply to synchronization request" 1553 (synchronize) 1554 noValidSynch 37 "No valid reply to synchronization request" 1555 (synchronize) 1556 invalidLoc 38 "Invalid locator" (flood) 1558 Appendix B. Change log [RFC Editor: Please remove] 1560 draft-ietf-anima-grasp-api-08, 2020-11: 1562 * Clarified trust model 1564 * Added explanations of GRASP objectives and sessions 1565 * Added note about non-idempotent messages 1567 * Added overview of API functions, and annotated each function with 1568 a brief description 1570 * Added protocol diagram for negotiation session 1572 * Clarified (absence of) authorization model 1574 * Changed precise semantics of synchronize() for flooded objectives 1576 * Clarified caching of flooded objectives 1578 * Changed 'age_limit' to 'minimum_TTL' 1580 * Improved security considerations, including DOS precautions 1582 * Annotated error codes to indicate which functions generate which 1583 errors 1585 * Other clarifications from Last Call reviews 1587 draft-ietf-anima-grasp-api-07, 2020-10-13: 1589 * Improved diagram and its description 1591 * Added pointer to example logic flows 1593 * Added note on variable length parameters 1595 * Clarified that API decrements loop count automatically 1597 * Other corrections and clarifications from AD review 1599 draft-ietf-anima-grasp-api-06, 2020-06-07: 1601 * Improved diagram 1603 * Numerous clarifications and layout changes 1605 draft-ietf-anima-grasp-api-05, 2020-05-08: 1607 * Converted to xml2rfc v3 1609 * Editorial fixes. 1611 draft-ietf-anima-grasp-api-04, 2019-10-07: 1613 * Improved discussion of layering, mentioned daemon. 1615 * Added callbacks and improved description of asynchronous 1616 operations. 1618 * Described use case for 'session_nonce'. 1620 * More explanation of 'asa_nonce'. 1622 * Change 'discover' to use 'age_limit' instead of 'flush'. 1624 * Clarified use of 'dry run'. 1626 * Editorial improvements. 1628 draft-ietf-anima-grasp-api-03, 2019-01-21: 1630 * Replaced empty "logic flows" section by "implementation status". 1632 * Minor clarifications. 1634 * Editorial improvements. 1636 draft-ietf-anima-grasp-api-02, 2018-06-30: 1638 * Additional suggestion for event-loop API. 1640 * Discussion of error code values. 1642 draft-ietf-anima-grasp-api-01, 2018-03-03: 1644 * Editorial updates 1646 draft-ietf-anima-grasp-api-00, 2017-12-23: 1648 * WG adoption 1650 * Editorial improvements. 1652 draft-liu-anima-grasp-api-06, 2017-11-24: 1654 * Improved description of event-loop model. 1656 * Changed intended status to Informational. 1658 * Editorial improvements. 1660 draft-liu-anima-grasp-api-05, 2017-10-02: 1662 * Added send_invalid() 1664 draft-liu-anima-grasp-api-04, 2017-06-30: 1666 * Noted that simple nodes might not include the API. 1668 * Minor clarifications. 1670 draft-liu-anima-grasp-api-03, 2017-02-13: 1672 * Changed error return to integers. 1674 * Required all implementations to accept objective values in CBOR. 1676 * Added non-blocking alternatives. 1678 draft-liu-anima-grasp-api-02, 2016-12-17: 1680 * Updated for draft-ietf-anima-grasp-09 1682 draft-liu-anima-grasp-api-02, 2016-09-30: 1684 * Added items for draft-ietf-anima-grasp-07 1686 * Editorial corrections 1688 draft-liu-anima-grasp-api-01, 2016-06-24: 1690 * Updated for draft-ietf-anima-grasp-05 1692 * Editorial corrections 1694 draft-liu-anima-grasp-api-00, 2016-04-04: 1696 * Initial version 1698 Authors' Addresses 1700 Brian Carpenter 1701 School of Computer Science 1702 University of Auckland 1703 PB 92019 1704 Auckland 1142 1705 New Zealand 1707 Email: brian.e.carpenter@gmail.com 1708 Bing Liu (editor) 1709 Huawei Technologies 1710 Q14, Huawei Campus 1711 No.156 Beiqing Road 1712 Hai-Dian District, Beijing 1713 100095 1714 P.R. China 1716 Email: leo.liubing@huawei.com 1718 Wendong Wang 1719 BUPT University 1720 Beijing University of Posts & Telecom. 1721 No.10 Xitucheng Road 1722 Hai-Dian District, Beijing 100876 1723 P.R. China 1725 Email: wdwang@bupt.edu.cn 1727 Xiangyang Gong 1728 BUPT University 1729 Beijing University of Posts & Telecom. 1730 No.10 Xitucheng Road 1731 Hai-Dian District, Beijing 100876 1732 P.R. China 1734 Email: xygong@bupt.edu.cn