rfc8991.original.xml   rfc8991.xml 
<?xml version="1.0" encoding="utf-8"?> <?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent"> <rfc xmlns:xi="http://www.w3.org/2001/XInclude" version="3" category="info" cons
<?rfc toc="yes"?> ensus="true" docName="draft-ietf-anima-grasp-api-10" indexInclude="true" ipr="tr
<!-- You want a table of contents --> ust200902" number="8991" prepTime="2021-05-20T22:42:20" scripts="Common,Latin" s
<?rfc symrefs="yes"?> ortRefs="true" submissionType="IETF" symRefs="true" tocDepth="3" tocInclude="tru
<!-- Use symbolic labels for references --> e" xml:lang="en">
<?rfc sortrefs="yes"?> <link href="https://datatracker.ietf.org/doc/draft-ietf-anima-grasp-api-10" re
<!-- This sorts the references --> l="prev"/>
<?rfc iprnotified="no" ?> <link href="https://dx.doi.org/10.17487/rfc8991" rel="alternate"/>
<!-- Change to "yes" if someone has disclosed IPR for the draft --> <link href="urn:issn:2070-1721" rel="alternate"/>
<?rfc compact="yes"?>
<!-- This defines the specific filename and version number of your draft (and in
serts the appropriate IETF boilerplate -->
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="info" docName="draft-i
etf-anima-grasp-api-10" ipr="trust200902" obsoletes="" updates="" submissionType
="IETF" xml:lang="en" tocInclude="true" symRefs="true" sortRefs="true" version="
3">
<!-- xml2rfc v2v3 conversion 2.44.0 -->
<front> <front>
<title abbrev="GRASP API">Generic Autonomic Signaling Protocol Application <title abbrev="GRASP API">GeneRic Autonomic Signaling Protocol Application P
Program Interface (GRASP API)</title> rogram Interface (GRASP API)</title>
<seriesInfo name="Internet-Draft" value="draft-ietf-anima-grasp-api-10"/> <seriesInfo name="RFC" value="8991" stream="IETF"/>
<author fullname="Brian Carpenter" initials="B. E." surname="Carpenter"> <author fullname="Brian E. Carpenter" initials="B." surname="Carpenter">
<organization abbrev="Univ. of Auckland"/> <organization abbrev="Univ. of Auckland" showOnFrontPage="true"/>
<address> <address>
<postal> <postal>
<street>School of Computer Science</street> <extaddr>School of Computer Science</extaddr>
<street>University of Auckland</street> <extaddr>University of Auckland</extaddr>
<street>PB 92019</street> <street>PB 92019</street>
<city>Auckland</city> <city>Auckland</city>
<region/> <region/>
<code>1142</code> <code>1142</code>
<country>New Zealand</country> <country>New Zealand</country>
</postal> </postal>
<email>brian.e.carpenter@gmail.com</email> <email>brian.e.carpenter@gmail.com</email>
</address> </address>
</author> </author>
<author fullname="Bing Liu" initials="B." role="editor" surname="Liu"> <author fullname="Bing Liu" initials="B." role="editor" surname="Liu">
<organization>Huawei Technologies</organization> <organization showOnFrontPage="true">Huawei Technologies</organization>
<address> <address>
<postal> <postal>
<street>Q14, Huawei Campus</street> <extaddr>Q14, Huawei Campus</extaddr>
<street>No.156 Beiqing Road</street> <street>No.156 Beiqing Road</street>
<city>Hai-Dian District, Beijing</city> <city>Hai-Dian District, Beijing</city>
<code>100095</code> <code>100095</code>
<country>P.R. China</country> <country>China</country>
</postal> </postal>
<email>leo.liubing@huawei.com</email> <email>leo.liubing@huawei.com</email>
</address> </address>
</author> </author>
<author fullname="Wendong Wang" initials="W." surname="Wang "> <author fullname="Wendong Wang" initials="W." surname="Wang">
<organization>BUPT University</organization> <organization showOnFrontPage="true">BUPT University</organization>
<address> <address>
<postal> <postal>
<street>Beijing University of Posts &amp; Telecom.</street> <extaddr>Beijing University of Posts &amp; Telecom.</extaddr>
<street>No.10 Xitucheng Road</street> <street>No.10 Xitucheng Road</street>
<city>Hai-Dian District, Beijing 100876</city> <city>Hai-Dian District, Beijing 100876</city>
<country>P.R. China</country> <country>China</country>
</postal> </postal>
<email>wdwang@bupt.edu.cn</email> <email>wdwang@bupt.edu.cn</email>
</address> </address>
</author> </author>
<author fullname="Xiangyang Gong" initials="X." surname="Gong"> <author fullname="Xiangyang Gong" initials="X." surname="Gong">
<organization>BUPT University</organization> <organization showOnFrontPage="true">BUPT University</organization>
<address> <address>
<postal> <postal>
<street>Beijing University of Posts &amp; Telecom.</street> <extaddr>Beijing University of Posts &amp; Telecom.</extaddr>
<street>No.10 Xitucheng Road</street> <street>No.10 Xitucheng Road</street>
<city>Hai-Dian District, Beijing 100876</city> <city>Hai-Dian District, Beijing 100876</city>
<country>P.R. China</country> <country>China</country>
</postal> </postal>
<email>xygong@bupt.edu.cn</email> <email>xygong@bupt.edu.cn</email>
</address> </address>
</author> </author>
<!----> <date month="05" year="2021"/>
<area>Operations and Management</area>
<date year="2021"/> <workgroup>ANIMA</workgroup>
<abstract> <abstract pn="section-abstract">
<t>This document is a conceptual outline of an application <t indent="0" pn="section-abstract-1">This document is a conceptual outlin
programming interface (API) for the e of an Application
Generic Autonomic Signaling Protocol (GRASP). Such an API is needed for Programming Interface (API) for the
Autonomic Service Agents (ASA) calling the GRASP protocol module to GeneRic Autonomic Signaling Protocol (GRASP). Such an API is needed for
exchange autonomic network messages with other ASAs. Since GRASP is Autonomic Service Agents (ASAs) calling the GRASP protocol module to
exchange Autonomic Network messages with other ASAs. Since GRASP is
designed to support asynchronous operations, the API will need to designed to support asynchronous operations, the API will need to
be adapted according to the support for asynchronicity in various be adapted according to the support for asynchronicity in various
programming languages and operating systems.</t> programming languages and operating systems.</t>
</abstract> </abstract>
<boilerplate>
<section anchor="status-of-memo" numbered="false" removeInRFC="false" toc=
"exclude" pn="section-boilerplate.1">
<name slugifiedName="name-status-of-this-memo">Status of This Memo</name
>
<t indent="0" pn="section-boilerplate.1-1">
This document is not an Internet Standards Track specification; it i
s
published for informational purposes.
</t>
<t indent="0" pn="section-boilerplate.1-2">
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Not all documents
approved by the IESG are candidates for any level of Internet
Standard; see Section 2 of RFC 7841.
</t>
<t indent="0" pn="section-boilerplate.1-3">
Information about the current status of this document, any
errata, and how to provide feedback on it may be obtained at
<eref target="https://www.rfc-editor.org/info/rfc8991" brackets="non
e"/>.
</t>
</section>
<section anchor="copyright" numbered="false" removeInRFC="false" toc="excl
ude" pn="section-boilerplate.2">
<name slugifiedName="name-copyright-notice">Copyright Notice</name>
<t indent="0" pn="section-boilerplate.2-1">
Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved.
</t>
<t indent="0" pn="section-boilerplate.2-2">
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<eref target="https://trustee.ietf.org/license-info" brackets="none
"/>) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with
respect to this document. Code Components extracted from this
document must include Simplified BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Simplified BSD License.
</t>
</section>
</boilerplate>
<toc>
<section anchor="toc" numbered="false" removeInRFC="false" toc="exclude" p
n="section-toc.1">
<name slugifiedName="name-table-of-contents">Table of Contents</name>
<ul bare="true" empty="true" indent="2" spacing="compact" pn="section-to
c.1-1">
<li pn="section-toc.1-1.1">
<t indent="0" keepWithNext="true" pn="section-toc.1-1.1.1"><xref der
ivedContent="1" format="counter" sectionFormat="of" target="section-1"/>.  <xref
derivedContent="" format="title" sectionFormat="of" target="name-introduction">
Introduction</xref></t>
</li>
<li pn="section-toc.1-1.2">
<t indent="0" pn="section-toc.1-1.2.1"><xref derivedContent="2" form
at="counter" sectionFormat="of" target="section-2"/>.  <xref derivedContent="" f
ormat="title" sectionFormat="of" target="name-grasp-api-for-asa">GRASP API for A
SA</xref></t>
<ul bare="true" empty="true" indent="2" spacing="compact" pn="sectio
n-toc.1-1.2.2">
<li pn="section-toc.1-1.2.2.1">
<t indent="0" keepWithNext="true" pn="section-toc.1-1.2.2.1.1"><
xref derivedContent="2.1" format="counter" sectionFormat="of" target="section-2.
1"/>.  <xref derivedContent="" format="title" sectionFormat="of" target="name-de
sign-assumptions">Design Assumptions</xref></t>
</li>
<li pn="section-toc.1-1.2.2.2">
<t indent="0" pn="section-toc.1-1.2.2.2.1"><xref derivedContent=
"2.2" format="counter" sectionFormat="of" target="section-2.2"/>.  <xref derived
Content="" format="title" sectionFormat="of" target="name-asynchronous-operation
s">Asynchronous Operations</xref></t>
<ul bare="true" empty="true" indent="2" spacing="compact" pn="se
ction-toc.1-1.2.2.2.2">
<li pn="section-toc.1-1.2.2.2.2.1">
<t indent="0" keepWithNext="true" pn="section-toc.1-1.2.2.2.
2.1.1"><xref derivedContent="2.2.1" format="counter" sectionFormat="of" target="
section-2.2.1"/>.  <xref derivedContent="" format="title" sectionFormat="of" tar
get="name-alternative-asynchronous-me"> Alternative Asynchronous Mechanisms</xre
f></t>
</li>
<li pn="section-toc.1-1.2.2.2.2.2">
<t indent="0" pn="section-toc.1-1.2.2.2.2.2.1"><xref derived
Content="2.2.2" format="counter" sectionFormat="of" target="section-2.2.2"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-multiple-n
egotiation-scenar">Multiple Negotiation Scenario</xref></t>
</li>
<li pn="section-toc.1-1.2.2.2.2.3">
<t indent="0" pn="section-toc.1-1.2.2.2.2.3.1"><xref derived
Content="2.2.3" format="counter" sectionFormat="of" target="section-2.2.3"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-overlappin
g-sessions-and-op">Overlapping Sessions and Operations</xref></t>
</li>
<li pn="section-toc.1-1.2.2.2.2.4">
<t indent="0" pn="section-toc.1-1.2.2.2.2.4.1"><xref derived
Content="2.2.4" format="counter" sectionFormat="of" target="section-2.2.4"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-session-te
rmination">Session Termination</xref></t>
</li>
</ul>
</li>
<li pn="section-toc.1-1.2.2.3">
<t indent="0" pn="section-toc.1-1.2.2.3.1"><xref derivedContent=
"2.3" format="counter" sectionFormat="of" target="section-2.3"/>.  <xref derived
Content="" format="title" sectionFormat="of" target="name-api-definition">API De
finition</xref></t>
<ul bare="true" empty="true" indent="2" spacing="compact" pn="se
ction-toc.1-1.2.2.3.2">
<li pn="section-toc.1-1.2.2.3.2.1">
<t indent="0" pn="section-toc.1-1.2.2.3.2.1.1"><xref derived
Content="2.3.1" format="counter" sectionFormat="of" target="section-2.3.1"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-overview-o
f-functions">Overview of Functions</xref></t>
</li>
<li pn="section-toc.1-1.2.2.3.2.2">
<t indent="0" pn="section-toc.1-1.2.2.3.2.2.1"><xref derived
Content="2.3.2" format="counter" sectionFormat="of" target="section-2.3.2"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-parameters
-and-data-structu">Parameters and Data Structures</xref></t>
</li>
<li pn="section-toc.1-1.2.2.3.2.3">
<t indent="0" pn="section-toc.1-1.2.2.3.2.3.1"><xref derived
Content="2.3.3" format="counter" sectionFormat="of" target="section-2.3.3"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-registrati
on">Registration</xref></t>
</li>
<li pn="section-toc.1-1.2.2.3.2.4">
<t indent="0" pn="section-toc.1-1.2.2.3.2.4.1"><xref derived
Content="2.3.4" format="counter" sectionFormat="of" target="section-2.3.4"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-discovery"
>Discovery</xref></t>
</li>
<li pn="section-toc.1-1.2.2.3.2.5">
<t indent="0" pn="section-toc.1-1.2.2.3.2.5.1"><xref derived
Content="2.3.5" format="counter" sectionFormat="of" target="section-2.3.5"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-negotiatio
n">Negotiation</xref></t>
</li>
<li pn="section-toc.1-1.2.2.3.2.6">
<t indent="0" pn="section-toc.1-1.2.2.3.2.6.1"><xref derived
Content="2.3.6" format="counter" sectionFormat="of" target="section-2.3.6"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-synchroniz
ation-and-floodin">Synchronization and Flooding</xref></t>
</li>
<li pn="section-toc.1-1.2.2.3.2.7">
<t indent="0" pn="section-toc.1-1.2.2.3.2.7.1"><xref derived
Content="2.3.7" format="counter" sectionFormat="of" target="section-2.3.7"/>.  <
xref derivedContent="" format="title" sectionFormat="of" target="name-invalid-me
ssage-function">Invalid Message Function</xref></t>
</li>
</ul>
</li>
</ul>
</li>
<li pn="section-toc.1-1.3">
<t indent="0" pn="section-toc.1-1.3.1"><xref derivedContent="3" form
at="counter" sectionFormat="of" target="section-3"/>.  <xref derivedContent="" f
ormat="title" sectionFormat="of" target="name-security-considerations">Security
Considerations</xref></t>
</li>
<li pn="section-toc.1-1.4">
<t indent="0" pn="section-toc.1-1.4.1"><xref derivedContent="4" form
at="counter" sectionFormat="of" target="section-4"/>.  <xref derivedContent="" f
ormat="title" sectionFormat="of" target="name-iana-considerations">IANA Consider
ations</xref></t>
</li>
<li pn="section-toc.1-1.5">
<t indent="0" pn="section-toc.1-1.5.1"><xref derivedContent="5" form
at="counter" sectionFormat="of" target="section-5"/>.  <xref derivedContent="" f
ormat="title" sectionFormat="of" target="name-references">References</xref></t>
<ul bare="true" empty="true" indent="2" spacing="compact" pn="sectio
n-toc.1-1.5.2">
<li pn="section-toc.1-1.5.2.1">
<t indent="0" pn="section-toc.1-1.5.2.1.1"><xref derivedContent=
"5.1" format="counter" sectionFormat="of" target="section-5.1"/>.  <xref derived
Content="" format="title" sectionFormat="of" target="name-normative-references">
Normative References</xref></t>
</li>
<li pn="section-toc.1-1.5.2.2">
<t indent="0" pn="section-toc.1-1.5.2.2.1"><xref derivedContent=
"5.2" format="counter" sectionFormat="of" target="section-5.2"/>.  <xref derived
Content="" format="title" sectionFormat="of" target="name-informative-references
">Informative References</xref></t>
</li>
</ul>
</li>
<li pn="section-toc.1-1.6">
<t indent="0" pn="section-toc.1-1.6.1"><xref derivedContent="Appendi
x A" format="default" sectionFormat="of" target="section-appendix.a"/>.  <xref d
erivedContent="" format="title" sectionFormat="of" target="name-error-codes">Err
or Codes</xref></t>
<ul bare="true" empty="true" indent="2" spacing="compact" pn="sectio
n-toc.1-1.6.2">
<li pn="section-toc.1-1.6.2.1">
<t indent="0" pn="section-toc.1-1.6.2.1.1"><xref derivedContent=
"" format="none" sectionFormat="of" target="section-a.1"/><xref derivedContent="
" format="title" sectionFormat="of" target="name-acknowledgements">Acknowledgeme
nts</xref></t>
</li>
</ul>
</li>
<li pn="section-toc.1-1.7">
<t indent="0" pn="section-toc.1-1.7.1"><xref derivedContent="" forma
t="none" sectionFormat="of" target="section-appendix.b"/><xref derivedContent=""
format="title" sectionFormat="of" target="name-authors-addresses">Authors' Addr
esses</xref></t>
</li>
</ul>
</section>
</toc>
</front> </front>
<middle> <middle>
<section anchor="intro" numbered="true" toc="default"> <section anchor="intro" numbered="true" toc="include" removeInRFC="false" pn
<name>Introduction</name> ="section-1">
<t>As defined in <xref target="I-D.ietf-anima-reference-model"/>, the <name slugifiedName="name-introduction">Introduction</name>
<t indent="0" pn="section-1-1">As defined in <xref target="RFC8993" format
="default" sectionFormat="of" derivedContent="RFC8993"/>, the
Autonomic Service Agent (ASA) Autonomic Service Agent (ASA)
is the atomic entity of an autonomic function, and it is instantiated is the atomic entity of an autonomic function, and it is instantiated
on autonomic nodes. These nodes are members of a secure Autonomic Control Plane (ACP) on autonomic nodes. These nodes are members of a secure Autonomic Control Plane (ACP)
such as defined by <xref target="I-D.ietf-anima-autonomic-control-plane"/> such as defined by <xref target="RFC8994" format="default" sectionFormat="
.</t> of" derivedContent="RFC8994"/>.</t>
<t indent="0" pn="section-1-2">When ASAs communicate with each other, they
<t>When ASAs communicate with each other, they should should
use the Generic Autonomic Signaling Protocol (GRASP) <xref target="I-D.iet use the GeneRic Autonomic Signaling Protocol (GRASP) <xref target="RFC8990
f-anima-grasp"/>. " format="default" sectionFormat="of" derivedContent="RFC8990"/>.
GRASP relies on the message confidentiality and integrity provided by the GRASP relies on the message confidentiality and integrity provided by the
ACP, ACP; a
with the consequence that all nodes in a consequence of this is that all nodes in a
given autonomic network share the same trust boundary, i.e., the boundary given Autonomic Network share the same trust boundary, i.e., the boundary
of the ACP. of the ACP.
Nodes that have not successfully joined the ACP cannot send, receive or in Nodes that have not successfully joined the ACP cannot send, receive, or i
tercept GRASP messages ntercept GRASP messages
via the ACP, and cannot usurp ACP addresses. via the ACP and cannot usurp ACP addresses.
An ASA runs in an ACP node and therefore benefits from the node's security properties when An ASA runs in an ACP node and therefore benefits from the node's security properties when
transmitting over the ACP, i.e., transmitting over the ACP, i.e.,
message integrity, message confidentiality and the fact that unauthorized message integrity, message confidentiality, and the fact that unauthorized
nodes cannot join the ACP. nodes cannot join the ACP.
All ASAs within a given autonomic network therefore trust each other's mes All ASAs within a given Autonomic Network therefore trust each other's mes
sages. For these reasons, the sages. For these reasons, the
API defined in this document has no explicit security features. API defined in this document has no explicit security features.
</t> </t>
<t indent="0" pn="section-1-3">An important feature of GRASP is the concep
<t>An important feature of GRASP is the concept of a GRASP objective. This t of a GRASP objective. This is a data structure
is a data structure encoded, like all GRASP messages, in Concise Binary Object Representation
encoded, like all GRASP messages, in CBOR <xref target="RFC8949"/>. (CBOR) <xref target="RFC8949" format="default" sectionFormat="of" derivedContent
Its main contents are a name and a value, explained at more length in the ="RFC8949"/>.
'Terminology' section Its main contents are a name and a value, explained at more length in the
of <xref target="I-D.ietf-anima-grasp"/>. When an objective is passed Terminology section
of <xref target="RFC8990" format="default" sectionFormat="of" derivedConte
nt="RFC8990"/>. When an objective is passed
from one ASA to another using GRASP, its value is either conveyed in one d irection from one ASA to another using GRASP, its value is either conveyed in one d irection
(by a process of synchronization or flooding), or negotiated bilaterally. The (by a process of synchronization or flooding) or negotiated bilaterally. T he
semantics of the value are opaque to GRASP and therefore to the API. Each objective semantics of the value are opaque to GRASP and therefore to the API. Each objective
must be accurately specified in a dedicated specification, as discussed in must be accurately specified in a dedicated specification, as discussed in
the "Objective Options" (<xref target="RFC8990" section="2.10" sectionFormat="
'Objective Options' section of <xref target="I-D.ietf-anima-grasp"/>. of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc8990#section-2.1
0" derivedContent="RFC8990"/>).
In particular, the specification will define the syntax and semantics of t he In particular, the specification will define the syntax and semantics of t he
value of the objective, whether and how it supports a negotiation process, value of the objective, whether and how it supports a negotiation process,
whether it supports a dry run mode, and any other details needed for inter whether it supports a dry-run mode, and any other details needed for inter
operability. operability.
The use of CBOR, with CDDL <xref target="RFC8610"/> as the data definition The use of CBOR, with Concise Data Definition Language (CDDL) <xref target
language, ="RFC8610" format="default" sectionFormat="of" derivedContent="RFC8610"/> as the
data definition language,
allows the value to be passed between ASAs regardless of the programming l anguages allows the value to be passed between ASAs regardless of the programming l anguages
in use. Data storage in use. Data storage
and consistency during negotiation are the responsibility of the ASAs invo lved. and consistency during negotiation are the responsibility of the ASAs invo lved.
Additionally, GRASP needs to cache the latest values of objectives that ar e Additionally, GRASP needs to cache the latest values of objectives that ar e
received by flooding.</t> received by flooding.</t>
<t indent="0" pn="section-1-4">As <xref target="sw" format="default" secti
<t>As <xref target="sw"/> shows, a GRASP implementation could contain seve onFormat="of" derivedContent="Figure 1"/> shows, a GRASP implementation could co
ral ntain several
sub-layers. The bottom layer is the GRASP base protocol module, which is o nly sub-layers. The bottom layer is the GRASP base protocol module, which is o nly
responsible for sending and receiving GRASP messages and maintaining responsible for sending and receiving GRASP messages and maintaining
shared data structures. Above that is the basic API described in this shared data structures. Above that is the basic API described in this
document. The upper layer contains document. The upper layer contains
some extended API functions based upon GRASP basic protocol. For example, some extended API functions based upon the GRASP basic protocol. For examp
<xref target="I-D.ietf-anima-grasp-distribution"/> describes a possible ex le,
tended <xref target="I-D.ietf-anima-grasp-distribution" format="default" sectionF
ormat="of" derivedContent="GRASP-DISTRIB"/> describes a possible extended
function.</t> function.</t>
<figure anchor="sw" align="left" suppress-title="false" pn="figure-1">
<figure anchor="sw"> <name slugifiedName="name-software-layout">Software Layout</name>
<name>Software layout</name> <artwork align="center" name="" type="" alt="" pn="section-1-5.1">
<artwork align="center" name="" type="" alt=""><![CDATA[
+--------------+ +--------------+ +--------------+ +--------------+
| ASAs | | ASAs | | ASAs | | ASAs |
+--------------+ +--------------+ +--------------+ +--------------+
| | | | | |
| +------------------+ | | +------------------+ |
| | GRASP Extended | | | | GRASP Extended | |
| | Function API | | | | Function API | |
| +------------------+ | | +------------------+ |
| | | | | |
+------------------------------------------+ +------------------------------------------+
| Basic GRASP API Library | | Basic GRASP API Library |
+------------------------------------------+ +------------------------------------------+
| |
IPC or system call IPC or system call
| |
+------------------------------------------+ +------------------------------------------+
| GRASP Core | | GRASP Core |
| (functions, data structures, daemon(s)) | | (functions, data structures, daemon(s)) |
+------------------------------------------+ +------------------------------------------+
]]></artwork> </artwork>
</figure> </figure>
<t indent="0" pn="section-1-6">Multiple ASAs in a single node will share t
<t>Multiple ASAs in a single node will share the same instance of GRASP, m he same instance of GRASP, much as
uch as
multiple applications share a single TCP/IP stack. This aspect is hidden f rom multiple applications share a single TCP/IP stack. This aspect is hidden f rom
individual ASAs by the API, and is not further discussed here.</t> individual ASAs by the API and is not further discussed here.</t>
<t indent="0" pn="section-1-7">It is desirable that ASAs be designed as po
<t>It is desirable that ASAs can be designed as portable user-space progra rtable user-space programs
ms
using a system-independent API. In many implementations, the GRASP code wi ll therefore using a system-independent API. In many implementations, the GRASP code wi ll therefore
be split between user space and kernel space. In user space, library funct ions provide the API be split between user space and kernel space. In user space, library funct ions provide the API
and communicate directly with ASAs. In kernel space is a daemon, or a set and communicate directly with ASAs. In kernel space, a daemon, or a set
of sub-services, providing GRASP core functions that are of sub-services, provides GRASP core functions that are
independent of specific ASAs, such as multicast handling and relaying, and independent of specific ASAs, such as multicast handling and relaying, and
common data structures such as the discovery cache. The GRASP API common data structures, such as the discovery cache. The GRASP API
library would need to communicate with the GRASP core via an inter-process library would need to communicate with the GRASP core via an interprocess
communication (IPC) or system call mechanism. The details of this are syst communication (IPC) or a system call mechanism. The details of this are sy
em-dependent. stem-dependent.
</t> </t>
<t indent="0" pn="section-1-8">Both the GRASP library and the extended fun
<t>Both the GRASP library and the extended function modules should ction modules should
be available to the ASAs. be available to the ASAs.
However, since the extended functions are expected to be added in an incre mental However, since the extended functions are expected to be added in an incre mental
manner, they will be the subject of future documents. manner, they will be the subject of future documents.
This document only describes the basic GRASP API.</t> This document only describes the basic GRASP API.</t>
<t indent="0" pn="section-1-9">The functions provided by the API do not ma
<t>The functions provided by the API do not map one-to-one onto GRASP mess p one-to-one onto GRASP messages. Rather,
ages. Rather,
they are intended to offer convenient support for message sequences (such as a discovery they are intended to offer convenient support for message sequences (such as a discovery
request followed by responses from several peers, request followed by responses from several peers
or a negotiation request followed by various possible responses). or a negotiation request followed by various possible responses).
This choice was made to assist ASA programmers in writing This choice was made to assist ASA programmers in writing
code based on their application requirements rather than needing to code based on their application requirements rather than needing to
understand protocol details.</t> understand protocol details.</t>
<t indent="0" pn="section-1-10">
<t>Note that a simple autonomic node might contain very few ASAs in In addition to containing the autonomic infrastructure components describe
addition to the autonomic infrastructure components described in d in
<xref target="I-D.ietf-anima-bootstrapping-keyinfra"/> <xref target="RFC8994" format="default" sectionFormat="of" derivedContent=
and <xref target="I-D.ietf-anima-autonomic-control-plane"/>. "RFC8994"/>
and <xref target="RFC8995" format="default" sectionFormat="of" derivedCont
ent="RFC8995"/>, a simple autonomic node might contain very few ASAs.
Such a node might directly integrate a GRASP protocol stack in Such a node might directly integrate a GRASP protocol stack in
its code and therefore not its code and therefore not
require this API to be installed. However, the programmer would then need require this API to be installed. However, the programmer would need
a deeper understanding of the GRASP protocol than is needed to use the API a deeper understanding of the GRASP protocol than what is needed to use th
.</t> e API.</t>
<t indent="0" pn="section-1-11">This document gives a conceptual outline o
<t>This document gives a conceptual outline of the API. It is not a formal f the API. It is not a formal
specification for any particular programming language or operating system, specification for any particular programming language or operating system,
and it is expected that details will be clarified in individual implementa tions.</t> and it is expected that details will be clarified in individual implementa tions.</t>
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="include" removeInRFC="false" pn="section-2">
<name>GRASP API for ASA</name> <name slugifiedName="name-grasp-api-for-asa">GRASP API for ASA</name>
<section numbered="true" toc="default"> <section numbered="true" toc="include" removeInRFC="false" pn="section-2.1
<name>Design Assumptions</name> ">
<t>The assumption of this document is that an Autonomic Service Agent <name slugifiedName="name-design-assumptions">Design Assumptions</name>
(ASA) needs to call a separate GRASP implementation. The latter handles <t indent="0" pn="section-2.1-1">The design assumes that an
protocol details ASA needs to call a separate GRASP implementation. The latter handles pr
otocol details
(security, sending and listening for GRASP messages, waiting, caching (security, sending and listening for GRASP messages, waiting, caching
discovery results, negotiation looping, sending and receiving discovery results, negotiation looping, sending and receiving
sychronization data, etc.) but understands nothing about individual synchronization data, etc.) but understands nothing about individual
GRASP objectives (Section 2.10 of <xref target="I-D.ietf-anima-grasp"/>) GRASP objectives (see <xref target="RFC8990" sectionFormat="of" section=
. "2.10" format="default" derivedLink="https://rfc-editor.org/rfc/rfc8990#section-
2.10" derivedContent="RFC8990"/>).
The semantics of objectives are unknown to the GRASP The semantics of objectives are unknown to the GRASP
protocol and are handled only by the ASAs. Thus, this is an protocol and are handled only by the ASAs. Thus, this is an
abstract API for use by ASAs. Individual abstract API for use by ASAs. Individual
language bindings should be defined in separate documents.</t> language bindings should be defined in separate documents.</t>
<t>Different ASAs may make different use of GRASP features, such as: <t indent="0" pn="section-2.1-2">Different ASAs may utilize GRASP featur es differently, by using GRASP for:
</t> </t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="section-2
<li>Use GRASP only for discovery purposes.</li> .1-3">
<li>Use GRASP negotiation but only as an initiator (client).</li> <li pn="section-2.1-3.1">discovery purposes only.</li>
<li>Use GRASP negotiation but only as a responder.</li> <li pn="section-2.1-3.2">negotiation but only as an initiator (client)
<li>Use GRASP negotiation as an initiator or responder.</li> .</li>
<li>Use GRASP synchronization but only as an initiator (recipient).</l <li pn="section-2.1-3.3">negotiation but only as a responder.</li>
i> <li pn="section-2.1-3.4">negotiation as an initiator or responder.</li
<li>Use GRASP synchronization but only as a responder and/or flooder.< >
/li> <li pn="section-2.1-3.5">synchronization but only as an initiator (rec
<li>Use GRASP synchronization as an initiator, responder and/or floode ipient).</li>
r.</li> <li pn="section-2.1-3.6">synchronization but only as a responder and/o
r flooder.</li>
<li pn="section-2.1-3.7">synchronization as an initiator, responder, a
nd/or flooder.</li>
</ul> </ul>
<t> <t indent="0" pn="section-2.1-4">
The API also assumes that one ASA may support multiple objectives. Nothi ng prevents The API also assumes that one ASA may support multiple objectives. Nothi ng prevents
an ASA from supporting some objectives for synchronization and others fo r negotiation. an ASA from supporting some objectives for synchronization and others fo r negotiation.
</t> </t>
<t>The API design assumes that the operating system and programming lang uage <t indent="0" pn="section-2.1-5">The API design assumes that the operati ng system and programming language
provide a mechanism for simultaneous asynchronous operations. This is di scussed provide a mechanism for simultaneous asynchronous operations. This is di scussed
in detail in <xref target="asynchop"/>.</t> in detail in <xref target="asynchop" format="default" sectionFormat="of"
derivedContent="Section 2.2"/>.</t>
<t>A few items are out of scope in this version, since practical experie <t indent="0" pn="section-2.1-6">A few items are out of scope in this ve
nce is required before including them:</t> rsion, since practical experience is required before including them:</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="section-2
<li>Authorization of ASAs is not defined as part of GRASP and is a sub .1-7">
ject for future study.</li> <li pn="section-2.1-7.1">Authorization of ASAs is not defined as part
<li>User-supplied explicit locators for an objective are not supported of GRASP and is a subject for future study.</li>
. The GRASP core will <li pn="section-2.1-7.2">User-supplied explicit locators for an object
ive are not supported. The GRASP core will
supply the locator, using the IP address of the node concerned.</li> supply the locator, using the IP address of the node concerned.</li>
<li>The Rapid mode of GRASP (Section 2.5.4 of <xref target="I-D.ietf-a nima-grasp"/>) <li pn="section-2.1-7.3">The rapid mode of GRASP (<xref target="RFC899 0" sectionFormat="of" section="2.5.4" format="default" derivedLink="https://rfc- editor.org/rfc/rfc8990#section-2.5.4" derivedContent="RFC8990"/>)
is not supported.</li> is not supported.</li>
</ul> </ul>
</section> </section>
<section anchor="asynchop" numbered="true" toc="default"> <section anchor="asynchop" numbered="true" toc="include" removeInRFC="fals
<name>Asynchronous Operations</name> e" pn="section-2.2">
<t>GRASP depends on asynchronous operations and wait states, and some of <name slugifiedName="name-asynchronous-operations">Asynchronous Operatio
its messages ns</name>
<t indent="0" pn="section-2.2-1">GRASP depends on asynchronous operation
s and wait states, and some of its messages
are not idempotent, meaning that repeating a message may cause repeated chan ges are not idempotent, meaning that repeating a message may cause repeated chan ges
of state in the recipient ASA. Many ASAs will of state in the recipient ASA. Many ASAs will
need to support several concurrent operations; for example an ASA might need need to support several concurrent operations; for example, an ASA might nee d
to negotiate one objective with a peer while discovering and synchronizing to negotiate one objective with a peer while discovering and synchronizing
a different objective with a different peer. Alternatively, an ASA which a different objective with a different peer. Alternatively, an ASA that
acts as a resource manager might need to run simultaneous negotiations acts as a resource manager might need to run simultaneous negotiations
for a given objective with multiple different peers. Such an ASA will probab ly for a given objective with multiple different peers. Such an ASA will probab ly
need to support uninterruptible atomic changes to its internal data structur es, need to support uninterruptible atomic changes to its internal data structur es,
using a mechanism provided by the operating system and programming language in use.</t> using a mechanism provided by the operating system and programming language in use.</t>
<section anchor="asynchmech" numbered="true" toc="include" removeInRFC="
<section anchor="asynchmech" numbered="true" toc="default"> false" pn="section-2.2.1">
<name> Alternative Asynchronous Mechanisms</name> <name slugifiedName="name-alternative-asynchronous-me"> Alternative As
<t>Thus, some ASAs need to support asynchronous operations, and therefore ynchronous Mechanisms</name>
<t indent="0" pn="section-2.2.1-1">Some ASAs need to support asynchron
ous operations; therefore,
the GRASP core must do so. Depending on both the the GRASP core must do so. Depending on both the
operating system and the programming language in use, there are various operating system and the programming language in use, there are various
techniques for such parallel operations, three of which we techniques for such parallel operations, three of which we
consider here: multi-threading, an event loop structure using polling, consider here: multithreading, an event loop structure using polling,
and an event loop structure using callback functions.</t> and an event loop structure using callback functions.</t>
<ol spacing="normal" type="1"> <ol spacing="normal" type="1" indent="adaptive" start="1" pn="section-
<li>In multi-threading, the operating system and language will provide 2.2.1-2">
<li pn="section-2.2.1-2.1" derivedCounter="1.">In multithreading, the
operating system and language will provide
the necessary support for asynchronous operations, including creation the necessary support for asynchronous operations, including creation
of new threads, context switching between threads, queues, locks, of new threads, context switching between threads, queues, locks,
and implicit wait states. In this case, API calls can be treated as simple and implicit wait states. In this case, API calls can be treated as simple
synchronous function calls within their own thread, even if the function inc ludes synchronous function calls within their own thread, even if the function inc ludes
wait states, blocking and queueing. Concurrent operations will each run wait states, blocking, and queueing. Concurrent operations will each run
in their own threads. For example, the discover() call may not return in their own threads. For example, the discover() call may not return
until discovery results have arrived or a timeout has occurred. If the ASA until discovery results have arrived or a timeout has occurred. If the ASA
has other work to do, the discover() call must be in a thread of its own.</l i> has other work to do, the discover() call must be in a thread of its own.</l i>
<li>In an event loop implementation with polling, blocking calls <li pn="section-2.2.1-2.2" derivedCounter="2.">In an event loop impl
are not acceptable. Therefore all calls must be non-blocking, and ementation with polling, blocking calls
are not acceptable. Therefore, all calls must be non-blocking, and
the main loop could support multiple GRASP sessions in parallel the main loop could support multiple GRASP sessions in parallel
by repeatedly polling each one for a change of state. To facilitate this, th e by repeatedly polling each one for a change of state. To facilitate this, th e
API implementation would provide non-blocking versions of all the functions that API implementation would provide non-blocking versions of all the functions that
otherwise involve blocking and queueing. In these calls, a 'noReply' code otherwise involve blocking and queueing. In these calls, a 'noReply' code
will be returned by each call instead of blocking, until such time as the ev ent will be returned by each call instead of blocking, until such time as the ev ent
for which it is waiting (or a failure) has occurred. Thus, for example, disc over() for which it is waiting (or a failure) has occurred. Thus, for example, disc over()
would return 'noReply' instead of waiting until discovery has succeeded would return 'noReply' instead of waiting until discovery has succeeded
or timed out. The discover() call would be repeated in every cycle of the or timed out. The discover() call would be repeated in every cycle of the
main loop until it completes. Effectively, it becomes a polling call.</li> main loop until it completes. Effectively, it becomes a polling call.</li>
<li>It was noted earlier that some GRASP messages are not idempotent; <li pn="section-2.2.1-2.3" derivedCounter="3.">It was noted earlier
in particular that some GRASP messages are not idempotent; in particular,
this applies to each step in a negotiation session - sending the same this applies to each step in a negotiation session -- sending the same
message message
twice might produce unintended side effects. This is not affected by twice might produce unintended side effects. This is not affected by
event loop polling: repeating a call after a 'noReply' does not event loop polling: repeating a call after a 'noReply' does not
repeat a message; it simply checks whether a reply has been received.< /li> repeat a message; it simply checks whether a reply has been received.< /li>
<li>In an event loop implementation with callbacks, the ASA programmer would <li pn="section-2.2.1-2.4" derivedCounter="4.">In an event loop impl ementation with callbacks, the ASA programmer would
provide a callback function for each asynchronous operation. provide a callback function for each asynchronous operation.
This would be called asynchronously when a reply is received or a failure su ch as a This would be called asynchronously when a reply is received or a failure su ch as a
timeout occurs.</li> timeout occurs.</li>
</ol> </ol>
</section>
</section> <section anchor="multineg" numbered="true" toc="include" removeInRFC="fa
lse" pn="section-2.2.2">
<section anchor="multineg" numbered="true" toc="default"> <name slugifiedName="name-multiple-negotiation-scenar">Multiple Negoti
<name>Multiple Negotiation Scenario</name> ation Scenario</name>
<t indent="0" pn="section-2.2.2-1">The design of GRASP allows the foll
<t>The design of GRASP allows the following scenario. Consider owing scenario. Consider
an ASA "A" that acts as a resource allocator for some objective. An ASA "B" launches an ASA "A" that acts as a resource allocator for some objective. An ASA "B" launches
a negotiation with "A" to obtain or release a quantity of the resource. Whil e this negotatition a negotiation with "A" to obtain or release a quantity of the resource. Whil e this negotiation
is under way, "B" chooses to launch a second simultaneous negotiation with " A" for a different is under way, "B" chooses to launch a second simultaneous negotiation with " A" for a different
quantity of the same resource. "A" must therefore conduct two separate negot iation sessions quantity of the same resource. "A" must therefore conduct two separate negot iation sessions
at the same time with the same peer, and must not mix them up.</t> at the same time with the same peer and must not mix them up.</t>
<t>Note that ASAs could be designed to avoid such a scenario, i.e. restr <t indent="0" pn="section-2.2.2-2">Note that ASAs could be designed to
icted to exactly one avoid such a scenario, i.e., restricted to exactly one
negotiation session at a time for a given objective, but this would be a vol untary negotiation session at a time for a given objective, but this would be a vol untary
restriction not required by the GRASP protocol. In fact it is an assumption of GRASP restriction not required by the GRASP protocol. In fact, GRASP assumes
that any ASA managing a resource may need to conduct multiple parallel negot iations, that any ASA managing a resource may need to conduct multiple parallel negot iations,
possibly with the same peer. Communication patterns could be very complex, w ith a group possibly with the same peer. Communication patterns could be very complex, w ith a group
of ASAs overlapping negotiations among themselves, as described in of ASAs overlapping negotiations among themselves, as described in
<xref target="I-D.ciavaglia-anima-coordination"/>. <xref target="I-D.ciavaglia-anima-coordination" format="default" sectionForm at="of" derivedContent="ANIMA-COORD"/>.
Therefore, the API design allows for such scenarios.</t> Therefore, the API design allows for such scenarios.</t>
<t>In the callback model, for the scenario just described, <t indent="0" pn="section-2.2.2-3">In the callback model, for the scen ario just described,
the ASAs "A" and "B" will each provide two instances of the callback functio n, one for the ASAs "A" and "B" will each provide two instances of the callback functio n, one for
each session. For this reason, each ASA must be each session. For this reason, each ASA must be
able to distinguish the two sessions, and the peer's IP address is not suffi cient for this. able to distinguish the two sessions, and the peer's IP address is not suffi cient for this.
It is also not safe to rely on transport port numbers for this, since future variants of GRASP It is also not safe to rely on transport port numbers for this, since future variants of GRASP
might use shared ports rather than a separate port per session. Hence the GR might use shared ports rather than a separate port per session. Hence, the G
ASP design RASP design
includes a session identifier. Thus, when necessary, a session handle (see n includes a Session ID. Thus, when necessary, a session handle (see the next
ext section) is section) is
used in the API to distinguish simultaneous GRASP sessions from each other, so that any used in the API to distinguish simultaneous GRASP sessions from each other, so that any
number of sessions may proceed asynchronously in parallel.</t> number of sessions may proceed asynchronously in parallel.</t>
</section>
</section> <section anchor="overlap" numbered="true" toc="include" removeInRFC="fal
se" pn="section-2.2.3">
<section anchor="overlap" numbered="true" toc="default"> <name slugifiedName="name-overlapping-sessions-and-op">Overlapping Ses
<name>Overlapping Sessions and Operations</name> sions and Operations</name>
<t>A GRASP session consists of a finite sequence of messages (for discov <t indent="0" pn="section-2.2.3-1">A GRASP session consists of a finit
ery, e sequence of messages (for discovery,
synchronization, or negotiation) between two ASAs. It is uniquely identi fied synchronization, or negotiation) between two ASAs. It is uniquely identi fied
on the wire on the wire
by a pseudo-random session identifier plus the IP address by a pseudorandom Session ID plus the IP address
of the initiator of the session. Further details are given in of the initiator of the session. Further details are given in
the section 'Session Identifier' of <xref target="I-D.ietf-anima-grasp"/ "Session Identifier (Session ID)" (<xref target="RFC8990" section="2.7"
>.</t> sectionFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc8
990#section-2.7" derivedContent="RFC8990"/>).</t>
<t>On the first call in a new GRASP session, the API returns a 'session_ <t indent="0" pn="section-2.2.3-2">On the first call in a new GRASP se
handle' ssion, the API returns a 'session_handle'
handle that uniquely identifies the session within the API, so that mult iple overlapping handle that uniquely identifies the session within the API, so that mult iple overlapping
sessions can be distinguished. A likely implementation is to form the sessions can be distinguished. A likely implementation is to form the
handle from the underlying GRASP Session ID and IP address. handle from the underlying GRASP Session ID and IP address.
This handle must be used in all subsequent This handle must be used in all subsequent
calls for the same session. Also see <xref target="sessn"/>.</t> calls for the same session. Also see <xref target="sessn" format="defaul
t" sectionFormat="of" derivedContent="Section 2.3.2.8"/>.</t>
<t>An additional mechanism that might increase efficiency for polling <t indent="0" pn="section-2.2.3-3">An additional mechanism that might
increase efficiency for polling
implementations is to add a general call, say notify(), which would check th e implementations is to add a general call, say notify(), which would check th e
status of all outstanding operations for the calling ASA and return the sess ion_handle values status of all outstanding operations for the calling ASA and return the sess ion_handle values
for all sessions that have changed state. This would eliminate the need for repeated calls for all sessions that have changed state. This would eliminate the need for repeated calls
to the individual functions returning a 'noReply'. This call is not describe d below to the individual functions returning a 'noReply'. This call is not describe d below
as the details are likely to be implementation-specific.</t> as the details are likely to be implementation specific.</t>
<t>An implication of the above for all GRASP implementations is that the <t indent="0" pn="section-2.2.3-4">An implication of the above for all
GRASP core GRASP implementations is that the GRASP core
must keep state for each GRASP operation in progress, most likely keyed by t he GRASP must keep state for each GRASP operation in progress, most likely keyed by t he GRASP
Session ID and the GRASP source address of the session initiator. Even in a threaded Session ID and the GRASP source address of the session initiator. Even in a threaded
implementation, the GRASP core will need such state internally. The session_ handle implementation, the GRASP core will need such state internally. The session_ handle
parameter exposes this aspect of the implementation.</t> parameter exposes this aspect of the implementation.</t>
</section> </section>
<section anchor="termin" numbered="true" toc="include" removeInRFC="fals
<section anchor="termin" numbered="true" toc="default"> e" pn="section-2.2.4">
<name>Session Termination</name> <name slugifiedName="name-session-termination">Session Termination</na
<t>GRASP sessions may terminate for numerous reasons. me>
A session ends when discovery succeeds or times out, when negotiation su <t indent="0" pn="section-2.2.4-1">GRASP sessions may terminate for nu
cceeds merous reasons.
or fails, when a synchronization result is delivered, when the other end A session ends when discovery succeeds or times out, negotiation succeed
fails to respond before a timeout expires, when a loop count expires, or s
when a network socket error occurs. Note that a timeout at one end of or fails, a synchronization result is delivered, the other end
fails to respond before a timeout expires, a loop count expires, or
a network socket error occurs. Note that a timeout at one end of
a session might result in a timeout or a socket error at the other end, a session might result in a timeout or a socket error at the other end,
since GRASP does not send error messages in this case. In all cases, the API since GRASP does not send error messages in this case. In all cases, the API
will return an appropriate code to the caller, which should then release any reserved will return an appropriate code to the caller, which should then release any reserved
resources. After failure cases, the GRASP specification recommends an ex ponential resources. After failure cases, the GRASP specification recommends an ex ponential
backoff before retrying.</t> backoff before retrying.</t>
</section> </section>
</section> </section>
<section numbered="true" toc="include" removeInRFC="false" pn="section-2.3
<section numbered="true" toc="default"> ">
<name>API definition</name> <name slugifiedName="name-api-definition">API Definition</name>
<section numbered="true" toc="include" removeInRFC="false" pn="section-2
<section numbered="true" toc="default"> .3.1">
<name>Overview of Functions</name> <name slugifiedName="name-overview-of-functions">Overview of Functions
<t>The functions provided by the API fall into several groups:</t> </name>
<ul> <t indent="0" pn="section-2.3.1-1">The functions provided by the API f
<li>Registration. These functions allow an ASA to register itself all into several groups:</t>
with the GRASP core, and allow a registered ASA to register the GRAS <dl newline="false" spacing="normal" indent="3" pn="section-2.3.1-2">
P <dt pn="section-2.3.1-2.1">Registration:</dt>
objectives that it will manipulate.</li> <dd pn="section-2.3.1-2.2"> These functions allow an ASA to register
<li>Discovery. This function allows an ASA that needs to initiate itself
with the GRASP core and allow a registered ASA to register the GRASP
objectives that it will manipulate.</dd>
<dt pn="section-2.3.1-2.3">Discovery:</dt>
<dd pn="section-2.3.1-2.4"> This function allows an ASA that needs t
o initiate
negotiation or synchronization of a particular objective to discover negotiation or synchronization of a particular objective to discover
a peer willing to respond.</li> a peer willing to respond.</dd>
<li>Negotiation. These functions allow an ASA to act as an initiator <dt pn="section-2.3.1-2.5">Negotiation:</dt>
<dd pn="section-2.3.1-2.6"> These functions allow an ASA to act as a
n initiator
(requester) or responder (listener) for a GRASP negotiation session. (requester) or responder (listener) for a GRASP negotiation session.
After initiation, negotiation is a symmetric process, so most of the After initiation, negotiation is a symmetric process, so most of the
functions can be used by either party.</li> functions can be used by either party.</dd>
<li>Synchronization. These functions allow an ASA to to act as an in <dt pn="section-2.3.1-2.7">Synchronization:</dt>
itiator <dd pn="section-2.3.1-2.8"> These functions allow an ASA to act as a
n initiator
(requester) or responder (listener and data source) for a GRASP (requester) or responder (listener and data source) for a GRASP
synchronization session.</li> synchronization session.</dd>
<li>Flooding. These functions allow an ASA to send and receive <dt pn="section-2.3.1-2.9">Flooding:</dt>
an objective that is flooded to all nodes of the ACP.</li> <dd pn="section-2.3.1-2.10"> These functions allow an ASA to send an
</ul> d receive
an objective that is flooded to all nodes of the ACP.</dd>
<t>Some example logic flows for a resource management ASA are given in </dl>
<xref target="I-D.ietf-anima-asa-guidelines"/>, which may be of help <t indent="0" pn="section-2.3.1-3">Some example logic flows for a reso
urce management ASA are given in
<xref target="I-D.ietf-anima-asa-guidelines" format="default" sectionF
ormat="of" derivedContent="ASA-GUIDE"/>, which may be of help
in understanding the following descriptions. in understanding the following descriptions.
The next section describes parameters and data structures used in mult iple API calls. The next section describes parameters and data structures used in mult iple API calls.
The following sections describe various groups of function APIs. Those APIs that The following sections describe various groups of function APIs. Those APIs that
do not list asynchronous mechanisms are implicitly synchronous in thei r behaviour.</t> do not list asynchronous mechanisms are implicitly synchronous in thei r behavior.</t>
</section> </section>
<section numbered="true" toc="include" removeInRFC="false" pn="section-2
<section numbered="true" toc="default"> .3.2">
<name>Parameters and data structures</name> <name slugifiedName="name-parameters-and-data-structu">Parameters and
Data Structures</name>
<section numbered="true" toc="default"> <section numbered="true" toc="exclude" removeInRFC="false" pn="section
<name>Integers</name> -2.3.2.1">
<t>In this API, integers are assumed to be 32 bit unsigned integers <name slugifiedName="name-integers">Integers</name>
(uint32_t) unless otherwise indicated.</t> <t indent="0" pn="section-2.3.2.1-1">In this API, integers are assum
ed to be 32-bit unsigned integers (uint32_t) unless otherwise indicated.</t>
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="exclude" removeInRFC="false" pn="section
<name>Errorcode</name> -2.3.2.2">
<t>All functions in the API have an unsigned 'errorcode' integer as <name slugifiedName="name-errorcode">Errorcode</name>
their return value (the first return value <t indent="0" pn="section-2.3.2.2-1">All functions in the API have a
n unsigned 'errorcode' integer as their return value (the first return value
in languages that allow multiple return values). An errorcode of zero ind icates success. in languages that allow multiple return values). An errorcode of zero ind icates success.
Any other value indicates failure of some kind. The first three errorcode s have special importance: Any other value indicates failure of some kind. The first three errorcode s have special importance:
</t> </t>
<ol spacing="normal" type="1"> <dl newline="false" spacing="normal" indent="3" pn="section-2.3.2.2-
<li>Declined: used to indicate that the other end has sent a GRASP 2">
Negotiation End message (M_END) with a Decline option (O_DECLINE).</li> <dt pn="section-2.3.2.2-2.1">1 - Declined:</dt>
<li>No reply: used in non-blocking calls to indicate that the othe <dd pn="section-2.3.2.2-2.2"> used to indicate that the other end
r end has sent no reply so far (see <xref target="asynchop"/>).</li> has sent a GRASP Negotiation End message (M_END) with a Decline option (O_DECLIN
<li>Unspecified error: used when no more specific error code appli E).</dd>
es.</li> <dt pn="section-2.3.2.2-2.3">2 - No reply:</dt>
</ol> <dd pn="section-2.3.2.2-2.4"> used in non-blocking calls to indica
<t><xref target="ErrAppx"/> gives a full list of currently suggested te that the other end has sent no reply so far (see <xref target="asynchop" form
error codes, based on at="default" sectionFormat="of" derivedContent="Section 2.2"/>).</dd>
<dt pn="section-2.3.2.2-2.5">3 - Unspecified error:</dt>
<dd pn="section-2.3.2.2-2.6"> used when no more specific error cod
es apply.</dd>
</dl>
<t indent="0" pn="section-2.3.2.2-3"><xref target="ErrAppx" format="
default" sectionFormat="of" derivedContent="Appendix A"/> gives a full list of c
urrently suggested error codes, based on
implementation experience. While there is no absolute requirement for all implementations implementation experience. While there is no absolute requirement for all implementations
to use the same error codes, this is highly recommended for portability o f applications.</t> to use the same error codes, this is highly recommended for portability o f applications.</t>
</section> </section>
<section anchor="tout" numbered="true" toc="default"> <section anchor="tout" numbered="true" toc="exclude" removeInRFC="fals
<name>Timeout</name> e" pn="section-2.3.2.3">
<t>Wherever a 'timeout' parameter appears, it is an unsigned integer <name slugifiedName="name-timeout">Timeout</name>
expressed <t indent="0" pn="section-2.3.2.3-1">Whenever a 'timeout' parameter
in milliseconds. Except for the discover() function, if it is zero, the G appears, it is an unsigned integer expressed
RASP in milliseconds. If it is zero, the GRASP
default timeout (GRASP_DEF_TIMEOUT, default timeout (GRASP_DEF_TIMEOUT; see <xref target="RFC8990" format="de
see <xref target="I-D.ietf-anima-grasp"/>) will apply. If no response fault" sectionFormat="of" derivedContent="RFC8990"/>) will apply. An exception
is the discover() function, which has a different interpretation of a zero timeo
ut. If no response
is received before the timeout expires, the call will fail unless otherwi se noted.</t> is received before the timeout expires, the call will fail unless otherwi se noted.</t>
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="exclude" removeInRFC="false" pn="section
<name>Objective</name> -2.3.2.4">
<t>An 'objective' parameter is a data structure with the following c <name slugifiedName="name-objective">Objective</name>
omponents: <t indent="0" pn="section-2.3.2.4-1">An 'objective' parameter is a d
ata structure with the following components:
</t> </t>
<ul spacing="normal"> <dl newline="false" spacing="normal" indent="3" pn="section-2.3.2.4-
<li>name (UTF-8 string) - the objective's name</li> 2">
<li>neg (Boolean flag) - True if objective supports negotiation (d <dt pn="section-2.3.2.4-2.1">name (UTF-8 string):</dt>
efault False)</li> <dd pn="section-2.3.2.4-2.2">The objective's name</dd>
<li>synch (Boolean flag) - True if objective supports synchronizat <dt pn="section-2.3.2.4-2.3">neg (Boolean flag):</dt>
ion (default False)</li> <dd pn="section-2.3.2.4-2.4">True if objective supports negotiatio
<li> n (default False)</dd>
<t>dry (Boolean flag) - True if objective supports dry-run negot <dt pn="section-2.3.2.4-2.5">synch (Boolean flag):</dt>
iation (default False) <dd pn="section-2.3.2.4-2.6">True if objective supports synchroniz
</t> ation (default False)</dd>
<ul spacing="normal"> <dt pn="section-2.3.2.4-2.7">dry (Boolean flag):</dt>
<!-- <li>Note 1: All objectives are assumed to support discove <dd pn="section-2.3.2.4-2.8">
ry, so there is no Boolean for that.</li> --> <t indent="0" pn="section-2.3.2.4-2.8.1">True if objective suppo
<li>Note 1: Only one of 'synch' or 'neg' may be True.</li> rts dry-run negotiation (default False)</t>
<li>Note 2: 'dry' must not be True unless 'neg' is also True.< <dl newline="false" spacing="compact" indent="3" pn="section-2.3
/li> .2.4-2.8.2">
<li>Note 3: In some programming languages the preferred implem <dt pn="section-2.3.2.4-2.8.2.1">Note 1:</dt>
entation <dd pn="section-2.3.2.4-2.8.2.2">Only one of 'synch' or 'neg'
may be True.</dd>
<dt pn="section-2.3.2.4-2.8.2.3">Note 2:</dt>
<dd pn="section-2.3.2.4-2.8.2.4">'dry' must not be True unless
'neg' is also True.</dd>
<dt pn="section-2.3.2.4-2.8.2.5">Note 3:</dt>
<dd pn="section-2.3.2.4-2.8.2.6"> In some programming language
s, the preferred implementation
may be to represent the Boolean flags as bits in a single byte , may be to represent the Boolean flags as bits in a single byte ,
which is how they are encoded in GRASP messages. which is how they are encoded in GRASP messages.
In other languages an enumeration might be preferable.</li> In other languages, an enumeration might be preferable.</dd>
</ul> </dl>
</li> </dd>
<li>loop_count (unsigned integer, uint8_t) - Limit on negotiation <dt pn="section-2.3.2.4-2.9">loop_count (unsigned integer, uint8_t
steps etc. (default GRASP_DEF_LOOPCT, ):</dt>
see <xref target="I-D.ietf-anima-grasp"/>) <dd pn="section-2.3.2.4-2.10">Limit on negotiation steps, etc. (de
fault GRASP_DEF_LOOPCT;
see <xref target="RFC8990" format="default" sectionFormat="of" derivedCo
ntent="RFC8990"/>).
The 'loop_count' is set to a suitable value by the initiator of a negoti ation, to prevent The 'loop_count' is set to a suitable value by the initiator of a negoti ation, to prevent
indefinite loops. It is also used to limit the propagation of di indefinite loops. It is also used to limit the propagation of di
scovery and flood messages.</li> scovery and flood messages.</dd>
<li> <dt pn="section-2.3.2.4-2.11">value:</dt>
<t>value - a specific data structure expressing the value of the <dd pn="section-2.3.2.4-2.12">
objective. The <t indent="0" pn="section-2.3.2.4-2.12.1">A specific data struct
ure expressing the value of the objective. The
format is language dependent, with the constraint that it can be validly format is language dependent, with the constraint that it can be validly
represented in CBOR <xref target="RFC8949"/>. represented in CBOR <xref target="RFC8949" format="default" sect
</t> ionFormat="of" derivedContent="RFC8949"/>.</t>
<t>An important advantage of CBOR is that the value of an object <ul spacing="normal" empty="true" bare="false" indent="3" pn="se
ive can be completely ction-2.3.2.4-2.12.2">
<li pn="section-2.3.2.4-2.12.2.1">An important advantage of CB
OR is that the value of an objective can be completely
opaque to the GRASP core yet pass transparently through it to an d from the ASA. opaque to the GRASP core yet pass transparently through it to an d from the ASA.
Although the GRASP core must validate the format and syntax of G RASP messages, Although the GRASP core must validate the format and syntax of G RASP messages,
it cannot validate the value of an objective; all it can do is d etect it cannot validate the value of an objective; all it can do is d etect
malformed CBOR. The handling of decoding errors depends on the C BOR library malformed CBOR. The handling of decoding errors depends on the C BOR library
in use, but a corresponding error code ('CBORfail') is defined i n the API in use, but a corresponding error code ('CBORfail') is defined i n the API
and will be returned to the ASA if a faulty message can be assig ned and will be returned to the ASA if a faulty message can be assig ned
to a current GRASP session. However, it is the responsibility of to a current GRASP session. However, it is the responsibility of
each ASA to validate the value of a received objective, as discu ssed each ASA to validate the value of a received objective, as discu ssed
in Section 5.3 of <xref target="RFC8949"/>. in <xref target="RFC8949" sectionFormat="of" section="5.3" forma t="default" derivedLink="https://rfc-editor.org/rfc/rfc8949#section-5.3" derived Content="RFC8949"/>.
If the programming language in use is suitably object-oriented, the GRASP API If the programming language in use is suitably object-oriented, the GRASP API
may deserialize the value and present it to the ASA as an object . may deserialize the value and present it to the ASA as an object .
If not, it will be presented as a CBOR data item. In all cases, the syntax If not, it will be presented as a CBOR data item. In all cases, the syntax
and semantics of the objective value are the responsibility of t and semantics of the objective value are the responsibility of t
he ASA.</t> he ASA.</li>
<t> <li pn="section-2.3.2.4-2.12.2.2">A requirement for all langua
A requirement for all language mappings and all API implementati ge mappings and all API implementations is
ons is
that, regardless of what other options exist for a language-spec ific representation that, regardless of what other options exist for a language-spec ific representation
of the value, there is always an option to use a raw CBOR data i tem as the value. of the value, there is always an option to use a raw CBOR data i tem as the value.
The API will then wrap this with CBOR Tag 24 as an encoded CBOR data item The API will then wrap this with CBOR Tag 24 as an encoded CBOR data item
for transmission via GRASP, and unwrap it after reception. By th is means, for transmission via GRASP, and unwrap it after reception. By th is means,
ASAs will be able to communicate regardless of programming langu age. ASAs will be able to communicate regardless of programming langu age.
</t>
</li> </li>
</ul> </ul>
</dd>
<t>The 'name' and 'value' fields are of variable length. GRASP d </dl>
oes not set a maximum <t indent="0" pn="section-2.3.2.4-3">The 'name' and 'value' fields a
re of variable length. GRASP does not set a maximum
length for these fields, but only for the total length of a GRAS P message. Implementations length for these fields, but only for the total length of a GRAS P message. Implementations
might impose length limits.</t> might impose length limits.</t>
<t> <t indent="0" pn="section-2.3.2.4-4">
An example data structure definition for an objective in the C langua ge, An example data structure definition for an objective in the C langua ge,
using at least the C99 version, and using at least the C99 version, and
assuming the use of a particular CBOR library <xref target="libcbor"/ assuming the use of a particular CBOR library <xref target="libcbor"
>, is: format="default" sectionFormat="of" derivedContent="libcbor"/>, is:
</t> </t>
<artwork align="center" name="" type="" alt=""><![CDATA[ <sourcecode type="c" markers="false" pn="section-2.3.2.4-5">
typedef struct { typedef struct {
unsigned char *name; unsigned char *name;
uint8_t flags; // flag bits as defined by GRASP uint8_t flags; // flag bits as defined by GRASP
uint8_t loop_count; uint8_t loop_count;
uint32_t value_size; // size of value in bytes uint32_t value_size; // size of value in bytes
cbor_mutable_data cbor_value; cbor_mutable_data cbor_value;
// CBOR bytestring (libcbor/cbor/data.h) // CBOR bytestring (libcbor/cbor/data.h)
} objective; } objective;
]]></artwork> </sourcecode>
<t> <t indent="0" pn="section-2.3.2.4-6">
An example data structure definition for an objective in the Python l anguage (version 3.4 or later) is: An example data structure definition for an objective in the Python l anguage (version 3.4 or later) is:
</t> </t>
<artwork align="center" name="" type="" alt=""><![CDATA[ <sourcecode type="python" markers="false" pn="section-2.3.2.4-7">
class objective: class objective:
"""A GRASP objective""" """A GRASP objective"""
def __init__(self, name): def __init__(self, name):
self.name = name #Unique name (string) self.name = name #Unique name (string)
self.negotiate = False #True if objective supports negotiation self.negotiate = False #True if negotiation supported
self.dryrun = False #True if objective supports dry-run neg. self.dryrun = False #True if dry-run supported
self.synch = False #True if objective supports synch self.synch = False #True if synchronization supported
self.loop_count = GRASP_DEF_LOOPCT # Default starting value self.loop_count = GRASP_DEF_LOOPCT # Default starting value
self.value = None #Place holder; any valid Python object self.value = None #Place holder; any Python object
]]></artwork> </sourcecode>
</section> </section>
<section anchor="asaL" numbered="true" toc="default"> <section anchor="asaL" numbered="true" toc="exclude" removeInRFC="fals
<name>ASA_locator</name> e" pn="section-2.3.2.5">
<t>An 'ASA_locator' parameter is a data structure with the following <name slugifiedName="name-asa_locator">asa_locator</name>
contents: <t indent="0" pn="section-2.3.2.5-1">An 'asa_locator' parameter is a
data structure with the following contents:
</t> </t>
<ul spacing="normal"> <dl spacing="normal" indent="3" newline="false" pn="section-2.3.2.5-
<li>locator - The actual locator, either an IP address or an ASCII 2">
string.</li> <dt pn="section-2.3.2.5-2.1">locator:</dt>
<li>ifi (unsigned integer) - The interface identifier index via wh <dd pn="section-2.3.2.5-2.2">The actual locator, either an IP addr
ich this was discovered (of limited ess or an ASCII string.</dd>
use to most ASAs).</li> <dt pn="section-2.3.2.5-2.3">ifi (unsigned integer):</dt>
<li>expire (system dependent type) - The time on the local system <dd pn="section-2.3.2.5-2.4">The interface identifier index via wh
clock when this locator will expire from the cache</li> ich this was discovered (of limited
<li><t>The following cover all locator types currently supported b use to most ASAs).</dd>
y GRASP:</t> <dt pn="section-2.3.2.5-2.5">expire (system dependent type):</dt>
<ul><li>is_ipaddress (Boolean) - True if the locator is an IP addr <dd pn="section-2.3.2.5-2.6">The time on the local system clock wh
ess</li> en this locator will expire from the cache.</dd>
<li>is_fqdn (Boolean) - True if the locator is an FQDN</li> <dt pn="section-2.3.2.5-2.7">The following covers all locator type
<li>is_uri (Boolean) - True if the locator is a URI</li> s currently supported by GRASP:</dt>
<li>These options are mutually exclusive. Depending on the pro <dd pn="section-2.3.2.5-2.8">
gramming language, they could <ul bare="false" empty="false" indent="3" spacing="normal" pn="s
be represented as a bit pattern or an enumeration.</li></ul></ ection-2.3.2.5-2.8.1">
li> <li pn="section-2.3.2.5-2.8.1.1">is_ipaddress (Boolean) - True
<li>diverted (Boolean) - True if the locator was discovered via a if the locator is an IP address.</li>
Divert option</li> <li pn="section-2.3.2.5-2.8.1.2">is_fqdn (Boolean) - True if
<li>protocol (unsigned integer) - Applicable transport protocol (I the locator is a Fully Qualified Domain Name (FQDN).</li>
PPROTO_TCP or IPPROTO_UDP). <li pn="section-2.3.2.5-2.8.1.3">is_uri (Boolean) - True if t
These constants are defined in the CDDL specification of GRASP <xr he locator is a URI.</li>
ef target="I-D.ietf-anima-grasp"/>.</li> </ul>
<li>port (unsigned integer) - Applicable port number</li> <t indent="0" pn="section-2.3.2.5-2.8.2">These options are mutua
</ul> lly exclusive. Depending on the programming language, they could
be represented as a bit pattern or an enumeration.</t>
<t>The 'locator' field is of variable length in the case of an FQDN </dd>
or a URI. GRASP does not set a maximum <dt pn="section-2.3.2.5-2.9">diverted (Boolean):</dt>
<dd pn="section-2.3.2.5-2.10">True if the locator was discovered v
ia a Divert option.</dd>
<dt pn="section-2.3.2.5-2.11">protocol (unsigned integer):</dt>
<dd pn="section-2.3.2.5-2.12">Applicable transport protocol (IPPRO
TO_TCP or IPPROTO_UDP).
These constants are defined in the CDDL specification of GRASP <xr
ef target="RFC8990" format="default" sectionFormat="of" derivedContent="RFC8990"
/>.</dd>
<dt pn="section-2.3.2.5-2.13">port (unsigned integer):</dt>
<dd pn="section-2.3.2.5-2.14">Applicable port number.</dd>
</dl>
<t indent="0" pn="section-2.3.2.5-3">The 'locator' field is of varia
ble length in the case of an FQDN or a URI. GRASP does not set a maximum
length for this field, but only for the total length of a GRASP message. Implementations length for this field, but only for the total length of a GRASP message. Implementations
might impose length limits.</t> might impose length limits.</t>
<t>It should be noted that when one ASA discovers the ASA_locator of another, there is no <t indent="0" pn="section-2.3.2.5-4">It should be noted that when on e ASA discovers the asa_locator of another, there is no
explicit authentication mechanism. In accordance with the trust mode l provided by the explicit authentication mechanism. In accordance with the trust mode l provided by the
secure ACP, ASAs are presumed to provide correct locators in respons e to discovery. secure ACP, ASAs are presumed to provide correct locators in respons e to discovery.
See the section 'Locator Options' of <xref target="I-D.ietf-anima-gr asp"/> for further details.</t> See "Locator Options" (<xref target="RFC8990" section="2.9.5" sectio nFormat="of" format="default" derivedLink="https://rfc-editor.org/rfc/rfc8990#se ction-2.9.5" derivedContent="RFC8990"/>) for further details.</t>
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="exclude" removeInRFC="false" pn="section
<name>Tagged_objective</name> -2.3.2.6">
<t>A 'tagged_objective' parameter is a data structure with the follo <name slugifiedName="name-tagged_objective">Tagged_objective</name>
wing contents: <t indent="0" pn="section-2.3.2.6-1">A 'tagged_objective' parameter
is a data structure with the following contents:
</t> </t>
<ul spacing="normal"> <dl spacing="normal" indent="3" newline="false" pn="section-2.3.2.6-
<li>objective - An objective</li> 2">
<li>locator - The ASA_locator associated with the objective, or a <dt pn="section-2.3.2.6-2.1">objective:</dt>
null value.</li> <dd pn="section-2.3.2.6-2.2">An objective.</dd>
</ul> <dt pn="section-2.3.2.6-2.3">locator:</dt>
<dd pn="section-2.3.2.6-2.4">The asa_locator associated with the o
bjective, or a null value.</dd>
</dl>
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="exclude" removeInRFC="false" pn="section
<name>Asa_handle</name> -2.3.2.7">
<t>Although an authentication and authorization scheme for ASAs has <name slugifiedName="name-asa_handle">asa_handle</name>
not been defined, the API <t indent="0" pn="section-2.3.2.7-1">Although an authentication and
authorization scheme for ASAs has not been defined, the API
provides a very simple hook for such a scheme. When an ASA starts up, it registers itself provides a very simple hook for such a scheme. When an ASA starts up, it registers itself
with the GRASP core, which provides it with an opaque handle that, althou gh not cryptographically with the GRASP core, which provides it with an opaque handle that, althou gh not cryptographically
protected, would be difficult for a third party to predict. The ASA must present this handle protected, would be difficult for a third party to predict. The ASA must present this handle
in future calls. This mechanism will prevent some elementary errors or tr ivial attacks in future calls. This mechanism will prevent some elementary errors or tr ivial attacks
such as an ASA manipulating an objective it has not registered to use.</t > such as an ASA manipulating an objective it has not registered to use.</t >
<t>Thus, in most calls, an 'asa_handle' parameter is required. It is generated when an ASA <t indent="0" pn="section-2.3.2.7-2">Thus, in most calls, an 'asa_ha ndle' parameter is required. It is generated when an ASA
first registers with GRASP, and the ASA must then store the asa_handle first registers with GRASP, and the ASA must then store the asa_handle
and use it in every subsequent GRASP call. Any call in which an invalid h andle is presented will fail. and use it in every subsequent GRASP call. Any call in which an invalid h andle is presented will fail.
It is an up to 32-bit opaque value (for example represented as a uint32_t It is an up to 32-bit opaque value (for example, represented as a uint32_
, depending on the language). t, depending on the language).
Since it is only used locally, not in GRASP messages, it is only required Since it is only used locally, and not in GRASP messages, it is only requ
to be unique ired to be unique
within the local GRASP instance. It is valid until the ASA terminates. within the local GRASP instance. It is valid until the ASA terminates.
It should be unpredictable; a possible implementation is to use the same mechanism that GRASP It should be unpredictable; a possible implementation is to use the same mechanism that GRASP
uses to generate Session Identifiers (see <xref target="sessn"/>).</t> uses to generate Session IDs (see <xref target="sessn" format="default" s ectionFormat="of" derivedContent="Section 2.3.2.8"/>).</t>
</section> </section>
<section anchor="sessn" numbered="true" toc="default"> <section anchor="sessn" numbered="true" toc="exclude" removeInRFC="fal
<name>Session_handle and Callbacks</name> se" pn="section-2.3.2.8">
<t>In some calls, a 'session_handle' parameter is required. This is <name slugifiedName="name-session_handle-and-callback">Session_handl
an opaque data e and Callbacks</name>
<t indent="0" pn="section-2.3.2.8-1">In some calls, a 'session_handl
e' parameter is required. This is an opaque data
structure as far as the ASA is concerned, structure as far as the ASA is concerned,
used to identify calls to the API as belonging to a specific GRASP sessio n used to identify calls to the API as belonging to a specific GRASP sessio n
(see <xref target="overlap"/>). (see <xref target="overlap" format="default" sectionFormat="of" derivedCo ntent="Section 2.2.3"/>).
It will be provided as a parameter in callback functions. It will be provided as a parameter in callback functions.
As well as distinguishing calls from different sessions, it also allows G RASP As well as distinguishing calls from different sessions, it also allows G RASP
to detect and ignore calls from non-existent or timed-out sessions. </t> to detect and ignore calls from non-existent or timed-out sessions. </t>
<t indent="0" pn="section-2.3.2.8-2">In an event loop implementation
<t>In an event loop implementation, callback functions (<xref target="asy , callback functions (<xref target="asynchmech" format="default" sectionFormat="
nchmech"/>) may be of" derivedContent="Section 2.2.1"/>) may be
supported for all API functions that involve waiting for a remote operati on: supported for all API functions that involve waiting for a remote operati on:
</t> </t>
<ul empty="true" spacing="normal"> <ul empty="true" spacing="normal" bare="false" indent="3" pn="sectio
<li>discover() whose callback would be discovery_received().</li> n-2.3.2.8-3">
<li>request_negotiate() whose callback would be negotiate_step_receive <li pn="section-2.3.2.8-3.1">discover() whose callback would be di
d().</li> scovery_received().</li>
<li>negotiate_step() whose callback would be negotiate_step_received() <li pn="section-2.3.2.8-3.2">request_negotiate() whose callback wo
.</li> uld be negotiate_step_received().</li>
<li>listen_negotiate() whose callback would be negotiate_step_received <li pn="section-2.3.2.8-3.3">negotiate_step() whose callback would
().</li> be negotiate_step_received().</li>
<li>synchronize() whose callback would be synchronization_received().< <li pn="section-2.3.2.8-3.4">listen_negotiate() whose callback wou
/li> ld be negotiate_step_received().</li>
</ul> <li pn="section-2.3.2.8-3.5">synchronize() whose callback would be
<t>Further details of callbacks are implementation-dependent.</t> synchronization_received().</li>
</section> </ul>
<t indent="0" pn="section-2.3.2.8-4">Further details of callbacks ar
e implementation dependent.</t>
</section>
</section> </section>
<section anchor="regi" numbered="true" toc="default"> <section anchor="regi" numbered="true" toc="include" removeInRFC="false"
<name>Registration</name> pn="section-2.3.3">
<t>These functions are used to register an ASA, and the objectives tha <name slugifiedName="name-registration">Registration</name>
t it modifies, <t indent="0" pn="section-2.3.3-1">These functions are used to registe
r an ASA, and the objectives that it modifies,
with the GRASP module. In the absence of an authorization with the GRASP module. In the absence of an authorization
model, these functions are very simple but they will avoid multiple model, these functions are very simple, but they will avoid multiple
ASAs choosing the ASAs choosing the
same name, and will prevent multiple ASAs manipulating the same obje same name and will prevent multiple ASAs manipulating the same objec
ctive. tive.
If an authorization model is added to GRASP, these API calls would If an authorization model is added to GRASP, these API calls would
need to be modified accordingly.</t> need to be modified accordingly.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="section
<li> -2.3.3-2">
<t>register_asa()</t> <li pn="section-2.3.3-2.1">
<t>All ASAs must use this call before issuing any other API calls. <t indent="0" pn="section-2.3.3-2.1.1">register_asa()</t>
</t> <t indent="0" pn="section-2.3.3-2.1.2">All ASAs must use this call
<ul spacing="normal"> before issuing any other API calls.</t>
<li> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<t>Input parameter:</t> tion-2.3.3-2.1.3">
<dl newline="false" spacing="normal"> <li pn="section-2.3.3-2.1.3.1">
<dt/> <t indent="0" pn="section-2.3.3-2.1.3.1.1">Input parameter:</t
<dd>name of the ASA (UTF-8 string)</dd> >
</dl> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
section-2.3.3-2.1.3.1.2">
<li pn="section-2.3.3-2.1.3.1.2.1">name of the ASA (UTF-8 st
ring)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.3-2.1.3.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.3-2.1.3.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.3-2.1.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.3-2.1.3.2.2.1">errorcode (unsigned integ
<dt/> er)</li>
<dd>asa_handle (unsigned integer)</dd> <li pn="section-2.3.3-2.1.3.2.2.2">asa_handle (unsigned inte
</dl> ger)</li>
</ul>
</li> </li>
<li>This initialises state in the GRASP module for the calling e <li pn="section-2.3.3-2.1.3.3">This initializes the state in the
ntity (the ASA). GRASP module for the calling entity (the ASA).
In the case of success, an 'asa_handle' is returned which the ASA In the case of success, an 'asa_handle' is returned, which the AS
must present in A must present in
all subsequent calls. all subsequent calls.
In the case of failure, the ASA has not been authorized and canno t operate. In the case of failure, the ASA has not been authorized and canno t operate.
The 'asa_handle' value is undefined.</li> The 'asa_handle' value is undefined.</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.3-2.2">
<t>deregister_asa()</t> <t indent="0" pn="section-2.3.3-2.2.1">deregister_asa()</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.3-2.2.2">
<t>Input parameters:</t> <li pn="section-2.3.3-2.2.2.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.3-2.2.2.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.3-2.2.2.1.2">
<dd>name of the ASA (UTF-8 string)</dd> <li pn="section-2.3.3-2.2.2.1.2.1">asa_handle (unsigned inte
</dl> ger)</li>
<li pn="section-2.3.3-2.2.2.1.2.2">name of the ASA (UTF-8 st
ring)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.3-2.2.2.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.3-2.2.2.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.3-2.2.2.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.3-2.2.2.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li>This removes all state in the GRASP module for the calling e ntity (the ASA), <li pn="section-2.3.3-2.2.2.3">This removes all state in the GRA SP module for the calling entity (the ASA)
and deregisters any objectives it has registered. Note that these a ctions must and deregisters any objectives it has registered. Note that these a ctions must
also happen automatically if an ASA exits.</li> also happen automatically if an ASA exits.</li>
<li>Note - the ASA name is strictly speaking redundant in this c all, but is present to <li pn="section-2.3.3-2.2.2.4">Note -- the ASA name is, strictly speaking, redundant in this call but is present to
detect and reject erroneous deregistrations.</li> detect and reject erroneous deregistrations.</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.3-2.3">
<t>register_objective()</t> <t indent="0" pn="section-2.3.3-2.3.1">register_objective()</t>
<t>ASAs must use this call for any objective whose value they need <t indent="0" pn="section-2.3.3-2.3.2">ASAs must use this call for
to transmit any objective whose value they need to transmit
by negotiation, synchronization or flooding.</t> by negotiation, synchronization, or flooding.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.3-2.3.3">
<t>Input parameters:</t> <li pn="section-2.3.3-2.3.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.3-2.3.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.3-2.3.3.1.2">
<dd>objective (structure)</dd> <li pn="section-2.3.3-2.3.3.1.2.1">asa_handle (unsigned inte
<dt/> ger)</li>
<dd>ttl (unsigned integer - default GRASP_DEF_TIMEOUT)</dd> <li pn="section-2.3.3-2.3.3.1.2.2">objective (structure)</li
<dt/> >
<dd>discoverable (Boolean - default False)</dd> <li pn="section-2.3.3-2.3.3.1.2.3">ttl (unsigned integer --
<dt/> default GRASP_DEF_TIMEOUT)</li>
<dd>overlap (Boolean - default False)</dd> <li pn="section-2.3.3-2.3.3.1.2.4">discoverable (Boolean --
<dt/> default False)</li>
<dd>local (Boolean - default False)</dd> <li pn="section-2.3.3-2.3.3.1.2.5">overlap (Boolean -- defau
</dl> lt False)</li>
<li pn="section-2.3.3-2.3.3.1.2.6">local (Boolean -- default
False)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.3-2.3.3.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.3-2.3.3.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.3-2.3.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.3-2.3.3.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li>This registers an objective that this ASA may modify <li pn="section-2.3.3-2.3.3.3">This registers an objective that this ASA may modify
and transmit to other ASAs by flooding or negotiation. It is not necessary to register and transmit to other ASAs by flooding or negotiation. It is not necessary to register
an objective that is only received by GRASP synchronization or f looding. an objective that is only received by GRASP synchronization or f looding.
The 'objective' becomes a candidate for discovery. However, disc overy The 'objective' becomes a candidate for discovery. However, disc overy
responses should not be enabled until the ASA calls listen_negot iate() or responses should not be enabled until the ASA calls listen_negot iate() or
listen_synchronize(), showing that it is able to act as a respon der. listen_synchronize(), showing that it is able to act as a respon der.
The ASA may negotiate the objective or send synchronization or f lood data. The ASA may negotiate the objective or send synchronization or f lood data.
Registration is not needed for "read-only" operations, i.e., the ASA only wants Registration is not needed for "read-only" operations, i.e., the ASA only wants
to receive synchronization or flooded data for the objective con cerned. </li> to receive synchronization or flooded data for the objective con cerned. </li>
<li>The 'ttl' parameter is the valid lifetime (time to live) in milliseconds of any <li pn="section-2.3.3-2.3.3.4">The 'ttl' parameter is the valid lifetime (time to live) in milliseconds of any
discovery response generated for this objective. The default val ue should be the GRASP discovery response generated for this objective. The default val ue should be the GRASP
default timeout (GRASP_DEF_TIMEOUT, see <xref target="I-D.ietf-a default timeout (GRASP_DEF_TIMEOUT; see <xref target="RFC8990" f
nima-grasp"/>).</li> ormat="default" sectionFormat="of" derivedContent="RFC8990"/>).</li>
<li>If the parameter 'discoverable' is True, the objective <li pn="section-2.3.3-2.3.3.5">If the parameter 'discoverable' i
s True, the objective
is immediately discoverable. This is is immediately discoverable. This is
intended for objectives that are only defined for GRASP discover intended for objectives that are only defined for GRASP discover
y, y
and which do not support negotiation or synchronization.</li> and that do not support negotiation or synchronization.</li>
<li>If the parameter 'overlap' is True, more than one ASA may re <li pn="section-2.3.3-2.3.3.6">If the parameter 'overlap' is Tru
gister this objective e, more than one ASA may register this objective
in the same GRASP instance. This is of value for life cycle mana gement in the same GRASP instance. This is of value for life cycle mana gement
of ASAs <xref target="I-D.ietf-anima-asa-guidelines"/> and must be of ASAs <xref target="I-D.ietf-anima-asa-guidelines" format="def ault" sectionFormat="of" derivedContent="ASA-GUIDE"/> and must be
used consistently for a given objective (always True or always F alse).</li> used consistently for a given objective (always True or always F alse).</li>
<li>If the parameter 'local' is True, discovery must return a li nk-local address. <li pn="section-2.3.3-2.3.3.7">If the parameter 'local' is True, discovery must return a link-local address.
This feature is for objectives that must be restricted to the lo cal link.</li> This feature is for objectives that must be restricted to the lo cal link.</li>
<li>This call may be repeated for multiple objectives.</li> <li pn="section-2.3.3-2.3.3.8">This call may be repeated for mul tiple objectives.</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.3-2.4">
<t>deregister_objective()</t> <t indent="0" pn="section-2.3.3-2.4.1">deregister_objective()</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.3-2.4.2">
<t>Input parameters:</t> <li pn="section-2.3.3-2.4.2.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.3-2.4.2.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.3-2.4.2.1.2">
<dd>objective (structure)</dd> <li pn="section-2.3.3-2.4.2.1.2.1">asa_handle (unsigned inte
</dl> ger)</li>
<li pn="section-2.3.3-2.4.2.1.2.2">objective (structure)</li
>
</ul>
</li> </li>
<li> <li pn="section-2.3.3-2.4.2.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.3-2.4.2.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.3-2.4.2.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.3-2.4.2.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li>The 'objective' must have been registered by the calling ASA ; if not, this call fails. <li pn="section-2.3.3-2.4.2.3">The 'objective' must have been re gistered by the calling ASA; if not, this call fails.
Otherwise, it removes all state in the GRASP module for the given o bjective.</li> Otherwise, it removes all state in the GRASP module for the given o bjective.</li>
</ul> </ul>
</li> </li>
</ul> </ul>
<!-- End of registration functions -->
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="include" removeInRFC="false" pn="section-2
<name>Discovery</name> .3.4">
<ul spacing="normal"> <name slugifiedName="name-discovery">Discovery</name>
<li> <ul spacing="normal" bare="false" empty="false" indent="3" pn="section
<t>discover()</t> -2.3.4-1">
<t>This function may be used by any ASA to discover peers handling <li pn="section-2.3.4-1.1">
a given objective.</t> <t indent="0" pn="section-2.3.4-1.1.1">discover()</t>
<ul spacing="normal"> <t indent="0" pn="section-2.3.4-1.1.2">This function may be used b
<li> y any ASA to discover peers handling a given objective.</t>
<t>Input parameters:</t> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<dl newline="false" spacing="normal"> tion-2.3.4-1.1.3">
<dt/> <li pn="section-2.3.4-1.1.3.1">
<dd>asa_handle (unsigned integer)</dd> <t indent="0" pn="section-2.3.4-1.1.3.1.1">Input parameters:</
<dt/> t>
<dd>objective (structure)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.4-1.1.3.1.2">
<dd>timeout (unsigned integer)</dd> <li pn="section-2.3.4-1.1.3.1.2.1">asa_handle (unsigned inte
<dt/> ger)</li>
<dd>minimum_TTL (unsigned integer)</dd> <li pn="section-2.3.4-1.1.3.1.2.2">objective (structure)</li
</dl> >
<li pn="section-2.3.4-1.1.3.1.2.3">timeout (unsigned integer
)</li>
<li pn="section-2.3.4-1.1.3.1.2.4">minimum_TTL (unsigned int
eger)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.4-1.1.3.2">
<t>Return values:</t> <t indent="0" pn="section-2.3.4-1.1.3.2.1">Return values:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.4-1.1.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.4-1.1.3.2.2.1">errorcode (unsigned integ
<dt/> er)</li>
<dd>locator_list (structure)</dd> <li pn="section-2.3.4-1.1.3.2.2.2">locator_list (structure)<
</dl> /li>
</ul>
</li> </li>
<li>This returns a list of discovered 'ASA_locator's for the giv en objective. <li pn="section-2.3.4-1.1.3.3">This returns a list of discovered 'asa_locators' for the given objective.
An empty list means that no locators were discovered within the timeout. An empty list means that no locators were discovered within the timeout.
Note that this structure includes all the fields described in <x ref target="asaL"/>. Note that this structure includes all the fields described in <x ref target="asaL" format="default" sectionFormat="of" derivedContent="Section 2. 3.2.5"/>.
</li> </li>
<li>The parameter 'minimum_TTL' must be greater than or equal to <li pn="section-2.3.4-1.1.3.4">The parameter 'minimum_TTL' must be greater than or equal to
zero. Any locally cached locators for the objective whose zero. Any locally cached locators for the objective whose
remaining time to live in milliseconds is less than or equal to remaining time to live in milliseconds is less than or equal to
'minimum_TTL' are deleted first. Thus 'minimum_TTL' = 0 will 'minimum_TTL' are deleted first. Thus, 'minimum_TTL' = 0 wil l
flush all entries. Note that this will not affect sessions a lready flush all entries. Note that this will not affect sessions a lready
in progress using the deleted locators.</li> in progress using the deleted locators.</li>
<li>If the parameter 'timeout' is zero, any remaining locally ca <li pn="section-2.3.4-1.1.3.5">If the parameter 'timeout' is zer
ched locators for the o, any remaining locally cached locators for the
objective are returned immediately and no other action is taken. objective are returned immediately, and no other action is taken
(Thus, . (Thus,
a call with 'minimum_TTL' and 'timeout' both equal to zero is po intless.)</li> a call with 'minimum_TTL' and 'timeout' both equal to zero is po intless.)</li>
<li>If the parameter 'timeout' is greater than zero, <li pn="section-2.3.4-1.1.3.6">If the parameter 'timeout' is gre ater than zero,
GRASP discovery is performed, and all results obtained before th e timeout in milliseconds GRASP discovery is performed, and all results obtained before th e timeout in milliseconds
expires are returned. If no results are obtained, an empty list is returned after the timeout. expires are returned. If no results are obtained, an empty list is returned after the timeout.
That is not an error condition. GRASP discovery is not a determi nistic process. That is not an error condition. GRASP discovery is not a determi nistic process.
If there are multiple nodes handling an objective, none, some or all of them If there are multiple nodes handling an objective, none, some, o r all of them
will be discovered before the timeout expires.</li> will be discovered before the timeout expires.</li>
<li><t>Asynchronous Mechanisms:</t><ul> <li pn="section-2.3.4-1.1.3.7">
<li>Threaded implementation: This should be called in a separate <t indent="0" pn="section-2.3.4-1.1.3.7.1">Asynchronous Mechan
thread isms:</t>
if asynchronous operation is required.</li> <dl indent="3" newline="false" spacing="normal" pn="section-2.
<li>Event loop implementation: An additional in/out 'session_han 3.4-1.1.3.7.2">
dle' parameter is used. <dt pn="section-2.3.4-1.1.3.7.2.1">Threaded implementation:<
/dt>
<dd pn="section-2.3.4-1.1.3.7.2.2">This should be called in
a separate thread
if asynchronous operation is required.</dd>
<dt pn="section-2.3.4-1.1.3.7.2.3">Event loop implementation
:</dt>
<dd pn="section-2.3.4-1.1.3.7.2.4">An additional in/out 'ses
sion_handle' parameter is used.
If the 'errorcode' parameter has the value 2 ('noReply'), If the 'errorcode' parameter has the value 2 ('noReply'),
no response has been received so far. The 'session_handle' param eter must be presented no response has been received so far. The 'session_handle' param eter must be presented
in subsequent calls. in subsequent calls.
A callback may be used in the case of a non-zero timeout.</li></ A callback may be used in the case of a non-zero timeout.</dd>
ul></li> </dl>
</li>
</ul> </ul>
</li> </li>
</ul> </ul>
</section> </section>
<!-- End of discovery functions --> <section numbered="true" toc="include" removeInRFC="false" pn="section-2
.3.5">
<section numbered="true" toc="default"> <name slugifiedName="name-negotiation">Negotiation</name>
<name>Negotiation</name> <t indent="0" pn="section-2.3.5-1">Since the negotiation mechanism is
different from a typical client/server
<t>Since the negotiation mechanism is different from a typical client/ exchange, <xref target="negfig" format="default" sectionFormat="of" de
server rivedContent="Figure 2"/> illustrates the sequence of calls and GRASP
exchange, <xref target="negfig"/> illustrates the sequence of calls an
d GRASP
messages in a negotiation. Note that after the first protocol exchange , the process messages in a negotiation. Note that after the first protocol exchange , the process
is symmetrical, with negotiating steps strictly alternating between th e two sides. is symmetrical, with negotiating steps strictly alternating between th e two sides.
Either side can end the negotiation. Also, the side that is due to res pond Either side can end the negotiation. Also, the side that is due to res pond
next can insert a delay at any time, to extend the other side's timeou t. next can insert a delay at any time, to extend the other side's timeou t.
This would be used, for example, if an ASA needed to negotiate with This would be used, for example, if an ASA needed to negotiate with
a third party before continuing with the current negotiation.</t> a third party before continuing with the current negotiation.</t>
<t indent="0" pn="section-2.3.5-2">The loop count embedded in the obje
<t>The loop count embedded in the objective that is the subject of ctive that is the subject of
negotiation is initialised by the ASA that starts a negotiation, negotiation is initialized by the ASA that starts a negotiation
and then decremented by the GRASP core at each step, prior to and is then decremented by the GRASP core at each step, prior to
sending each M_NEGOTIATE message. If it reaches sending each M_NEGOTIATE message. If it reaches
zero, the negotiation will fail and each side will receive an error co zero, the negotiation will fail, and each side will receive an error c
de.</t> ode.</t>
<figure anchor="negfig" align="left" suppress-title="false" pn="figure
<figure anchor="negfig"> -2">
<name>Negotiation sequence</name> <name slugifiedName="name-negotiation-sequence">Negotiation Sequence
<artwork align="center" name="" type="" alt=""><![CDATA[ </name>
<artwork align="center" name="" type="" alt="" pn="section-2.3.5-3.1
">
Initiator Responder Initiator Responder
--------- --------- --------- ---------
listen_negotiate() \ Await request listen_negotiate() \ Await request
request_negotiate() request_negotiate()
M_REQ_NEG -> negotiate_step() \ Open session, M_REQ_NEG -&gt; negotiate_step() \ Open session,
<- M_NEGOTIATE / start negotiation &lt;- M_NEGOTIATE / start negotiation
negotiate_step() negotiate_step()
M_NEGOTIATE -> negotiate_step() \ Continue M_NEGOTIATE -&gt; negotiate_step() \ Continue
<- M_NEGOTIATE / negotiation &lt;- M_NEGOTIATE / negotiation
... ...
negotiate_wait() \ Insert negotiate_wait() \ Insert
M_WAIT -> / delay M_WAIT -&gt; / delay
negotiate_step() negotiate_step()
M_NEGOTIATE -> negotiate_step() \ Continue M_NEGOTIATE -&gt; negotiate_step() \ Continue
<- M_NEGOTIATE / negotiation &lt;- M_NEGOTIATE / negotiation
negotiate_step() negotiate_step()
M_NEGOTIATE -> end_negotiate() \ End M_NEGOTIATE -&gt; end_negotiate() \ End
<- M_END / negotiation &lt;- M_END / negotiation
\ Process results \ Process results
]]></artwork> </artwork>
</figure> </figure>
<t indent="0" pn="section-2.3.5-4">As the negotiation proceeds, each s
<t>As the negotiation proceeds, each side will update the value of the o ide will update the value of the objective in accordance with
bjective in accordance with
its particular semantics, defined in the specification of the objective. Although many objectives its particular semantics, defined in the specification of the objective. Although many objectives
will have values that can be ordered, so that negotiation can be a simpl e bidding process, this will have values that can be ordered, so that negotiation can be a simpl e bidding process, it
is not a requirement.</t> is not a requirement.</t>
<t>Failure to agree, a timeout, or loop count exhaustion may all end a n <t indent="0" pn="section-2.3.5-5">Failure to agree, a timeout, or loo
egotiation session, but none p count exhaustion may all end a negotiation session, but none
of these cases is a protocol failure.</t> of these cases are protocol failures.</t>
<ul spacing="normal" bare="false" empty="false" indent="3" pn="section
<ul spacing="normal"> -2.3.5-6">
<li> <li pn="section-2.3.5-6.1">
<t>request_negotiate()</t> <t indent="0" pn="section-2.3.5-6.1.1">request_negotiate()</t>
<t>This function is used by any ASA to initiate negotiation of a G <t indent="0" pn="section-2.3.5-6.1.2">This function is used by an
RASP objective as a requester (client).</t> y ASA to initiate negotiation of a GRASP objective as a requester (client).</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.5-6.1.3">
<t>Input parameters:</t> <li pn="section-2.3.5-6.1.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.5-6.1.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.1.3.1.2">
<dd>objective (structure)</dd> <li pn="section-2.3.5-6.1.3.1.2.1">asa_handle (unsigned inte
<dt/> ger)</li>
<dd>peer (ASA_locator)</dd> <li pn="section-2.3.5-6.1.3.1.2.2">objective (structure)</li
<dt/> >
<dd>timeout (unsigned integer)</dd> <li pn="section-2.3.5-6.1.3.1.2.3">peer (asa_locator)</li>
</dl> <li pn="section-2.3.5-6.1.3.1.2.4">timeout (unsigned integer
)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.5-6.1.3.2">
<t>Return values:</t> <t indent="0" pn="section-2.3.5-6.1.3.2.1">Return values:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.1.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.5-6.1.3.2.2.1">errorcode (unsigned integ
<dt/> er)</li>
<dd>session_handle (structure) (undefined unless successful) <li pn="section-2.3.5-6.1.3.2.2.2">session_handle (structure
</dd> ) (undefined unless successful)</li>
<dt/> <li pn="section-2.3.5-6.1.3.2.2.3">proffered_objective (stru
<dd>proffered_objective (structure) (undefined unless succes cture) (undefined unless successful)</li>
sful)</dd> <li pn="section-2.3.5-6.1.3.2.2.4">reason (string) (empty un
<dt/> less negotiation declined)</li>
<dd>reason (string) (empty unless negotiation declined)</dd> </ul>
</dl>
</li> </li>
<li>This function opens a negotiation session between two ASAs. <li pn="section-2.3.5-6.1.3.3">This function opens a negotiation
Note that GRASP currently session between two ASAs. Note that GRASP currently
does not support multi-party negotiation, which would need to be does not support multiparty negotiation, which would need to be
added as an extended added as an extended
function.</li> function.</li>
<li>The 'objective' parameter must <li pn="section-2.3.5-6.1.3.4">The 'objective' parameter must
include the requested value, and its loop count should be set to a include the requested value, and its loop count should be set to a
suitable starting value by the ASA. If not, the GRASP default will apply.</li> suitable starting value by the ASA. If not, the GRASP default will apply.</li>
<li>Note that a given negotiation session may or may not be a dr y-run negotiation; <li pn="section-2.3.5-6.1.3.5">Note that a given negotiation ses sion may or may not be a dry-run negotiation;
the two modes must not be mixed in a single session.</li> the two modes must not be mixed in a single session.</li>
<li>The 'peer' parameter is the target node; it must be an 'ASA_ locator' as returned <li pn="section-2.3.5-6.1.3.6">The 'peer' parameter is the targe t node; it must be an 'asa_locator' as returned
by discover(). If 'peer' is null, GRASP discovery is automatically performed first to find by discover(). If 'peer' is null, GRASP discovery is automatically performed first to find
a suitable peer (i.e., any node that supports the objective in ques tion).</li> a suitable peer (i.e., any node that supports the objective in ques tion).</li>
<li>The 'timeout' parameter is described in <xref target="tout"/ <li pn="section-2.3.5-6.1.3.7">The 'timeout' parameter is descri
>.</li> bed in <xref target="tout" format="default" sectionFormat="of" derivedContent="S
<li> ection 2.3.2.3"/>.</li>
<t>If the 'errorcode' return value is 0, the negotiation has s <li pn="section-2.3.5-6.1.3.8">
uccessfully <t indent="0" pn="section-2.3.5-6.1.3.8.1">If the 'errorcode'
return value is 0, the negotiation has successfully
started. There are then two cases: started. There are then two cases:
</t> </t>
<ol spacing="normal" type="1"> <ol spacing="normal" type="1" indent="adaptive" start="1" pn="
<li>The 'session_handle' parameter is null. In this case the section-2.3.5-6.1.3.8.2">
negotiation <li pn="section-2.3.5-6.1.3.8.2.1" derivedCounter="1.">The '
has succeeded with one exchange of messages and the peer has accep session_handle' parameter is null. In this case, the negotiation
ted the request. The returned has succeeded with one exchange of messages, and the peer has acce
pted the request. The returned
'proffered_objective' contains the value accepted by the peer, whi ch is 'proffered_objective' contains the value accepted by the peer, whi ch is
therefore equal to the value in the requested 'objective'. For thi s reason, therefore equal to the value in the requested 'objective'. For thi s reason,
no session handle is needed, since the session has ended.</li> no session handle is needed, since the session has ended.</li>
<li> <li pn="section-2.3.5-6.1.3.8.2.2" derivedCounter="2.">
<t>The 'session_handle' parameter is not null. In this cas <t indent="0" pn="section-2.3.5-6.1.3.8.2.2.1">The 'sessio
e negotiation n_handle' parameter is not null. In this case, negotiation
must continue. The 'session_handle' must be presented in all subse quent negotiation steps. must continue. The 'session_handle' must be presented in all subse quent negotiation steps.
The returned 'proffered_objective' contains the first value The returned 'proffered_objective' contains the first value
proffered by the negotiation peer in the first exchange of message s; proffered by the negotiation peer in the first exchange of message s;
in other words it is a counter-offer. in other words, it is a counter-offer.
The contents of this instance of the objective The contents of this instance of the objective
must be used to prepare the next negotiation step (see negotiate_s tep() below) because must be used to prepare the next negotiation step (see negotiate_s tep() below) because
it contains the updated loop count, sent by the negotiation peer. it contains the updated loop count, sent by the negotiation peer.
The GRASP code automatically decrements the loop count by 1 at eac h step, The GRASP code automatically decrements the loop count by 1 at eac h step
and returns an error if it becomes zero. Since this terminates the and returns an error if it becomes zero. Since this terminates the
negotiation, the other end will experience a timeout, which will negotiation, the other end will experience a timeout, which will
terminate the other end of the session. terminate the other end of the session.
</t> </t>
<t> <t indent="0" pn="section-2.3.5-6.1.3.8.2.2.2">
This function must be followed by calls to 'negotiate_step' and/or 'negotiate_wait' This function must be followed by calls to 'negotiate_step' and/or 'negotiate_wait'
and/or 'end_negotiate' until the negotiation ends. 'request_negoti ate' may then be called and/or 'end_negotiate' until the negotiation ends. 'request_negoti ate' may then be called
again to start a new negotiation.</t> again to start a new negotiation.</t>
</li> </li>
</ol> </ol>
</li> </li>
<li>If the 'errorcode' parameter has the value 1 ('declined'), t he negotiation has been declined <li pn="section-2.3.5-6.1.3.9">If the 'errorcode' parameter has the value 1 ('declined'), the negotiation has been declined
by the peer (M_END and O_DECLINE features of GRASP). The 'reason' s tring is then available for by the peer (M_END and O_DECLINE features of GRASP). The 'reason' s tring is then available for
information and diagnostic use, but it may be a null string. For th is and any other error code, information and diagnostic use, but it may be a null string. For th is and any other error code,
an exponential backoff is recommended before any retry (see <xref t an exponential backoff is recommended before any retry (see <xref t
arget="security"/>).</li> arget="security" format="default" sectionFormat="of" derivedContent="Section 3"/
<li><t>Asynchronous Mechanisms:</t><ul> >).</li>
<li>Threaded implementation: This should be called in a separate <li pn="section-2.3.5-6.1.3.10">
thread <t indent="0" pn="section-2.3.5-6.1.3.10.1">Asynchronous Mecha
if asynchronous operation is required.</li> nisms:</t>
<li>Event loop implementation: The 'session_handle' parameter is <dl indent="3" newline="false" spacing="normal" pn="section-2.
used to distinguish 3.5-6.1.3.10.2">
<dt pn="section-2.3.5-6.1.3.10.2.1">Threaded implementation:
</dt>
<dd pn="section-2.3.5-6.1.3.10.2.2">This should be called in
a separate thread
if asynchronous operation is required.</dd>
<dt pn="section-2.3.5-6.1.3.10.2.3">Event loop implementatio
n:</dt>
<dd pn="section-2.3.5-6.1.3.10.2.4">The 'session_handle' par
ameter is used to distinguish
multiple simultaneous sessions. If the 'errorcode' parameter has the value 2 ('noReply'), multiple simultaneous sessions. If the 'errorcode' parameter has the value 2 ('noReply'),
no response has been received so far. The 'session_handle' param eter must be presented no response has been received so far. The 'session_handle' param eter must be presented
in subsequent calls.</li></ul></li> in subsequent calls.</dd>
</dl>
<li>Use of dry run mode: This must be consistent within a GRASP </li>
session. The state of the 'dry' <li pn="section-2.3.5-6.1.3.11">Use of dry-run mode must be cons
istent within a GRASP session. The state of the 'dry'
flag in the initial request_negotiate() call must be the same in al l subsequent negotiation flag in the initial request_negotiate() call must be the same in al l subsequent negotiation
steps of the same session. The semantics of the dry run mode are bu ilt into the ASA; GRASP steps of the same session. The semantics of the dry-run mode are bu ilt into the ASA; GRASP
merely carries the flag bit.</li> merely carries the flag bit.</li>
<li>Special note for the ACP infrastructure ASA: It is likely th at this ASA will need to <li pn="section-2.3.5-6.1.3.12">Special note for the ACP infrast ructure ASA: It is likely that this ASA will need to
discover and negotiate with its peers in each of its on-link neighb ors. It will therefore need to discover and negotiate with its peers in each of its on-link neighb ors. It will therefore need to
know not only the link-local IP address but also the physical inter face and transport port for know not only the link-local IP address but also the physical inter face and transport port for
connecting to each neighbor. One implementation approach to this is to include these connecting to each neighbor. One implementation approach to this is to include these
details in the 'session_handle' data structure, which is opaque to normal ASAs.</li> details in the 'session_handle' data structure, which is opaque to normal ASAs.</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.5-6.2">
<t>listen_negotiate()</t> <t indent="0" pn="section-2.3.5-6.2.1">listen_negotiate()</t>
<t>This function is used by an ASA to start acting as a negotiatio <t indent="0" pn="section-2.3.5-6.2.2">This function is used by an
n responder (listener) ASA to start acting as a negotiation responder (listener)
for a given GRASP objective.</t> for a given GRASP objective.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.5-6.2.3">
<t>Input parameters:</t> <li pn="section-2.3.5-6.2.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.5-6.2.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.2.3.1.2">
<dd>objective (structure)</dd> <li pn="section-2.3.5-6.2.3.1.2.1">asa_handle (unsigned inte
</dl> ger)</li>
<li pn="section-2.3.5-6.2.3.1.2.2">objective (structure)</li
>
</ul>
</li> </li>
<li> <li pn="section-2.3.5-6.2.3.2">
<t>Return values:</t> <t indent="0" pn="section-2.3.5-6.2.3.2.1">Return values:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.2.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.5-6.2.3.2.2.1">errorcode (unsigned integ
<dt/> er)</li>
<dd>session_handle (structure) (undefined unless successful) <li pn="section-2.3.5-6.2.3.2.2.2">session_handle (structure
</dd> ) (undefined unless successful)</li>
<dt/> <li pn="section-2.3.5-6.2.3.2.2.3">requested_objective (stru
<dd>requested_objective (structure) (undefined unless succes cture) (undefined unless successful)</li>
sful)</dd> </ul>
</dl>
</li> </li>
<li>This function instructs GRASP to listen for negotiation <li pn="section-2.3.5-6.2.3.3">This function instructs GRASP to listen for negotiation
requests for the given 'objective'. It also enables discovery respo nses for the objective, requests for the given 'objective'. It also enables discovery respo nses for the objective,
as mentioned under register_objective() in <xref target="regi"/>.</ as mentioned under register_objective() in <xref target="regi" fo
li> rmat="default" sectionFormat="of" derivedContent="Section 2.3.3"/>.</li>
<li><t>Asynchronous Mechanisms:</t><ul> <li pn="section-2.3.5-6.2.3.4">
<li>Threaded implementation: It will block waiting for an incomi <t indent="0" pn="section-2.3.5-6.2.3.4.1">Asynchronous Mechan
ng request, so isms:</t>
should be called in a separate thread if asynchronous operation is <dl indent="3" newline="false" spacing="normal" pn="section-2.
required. 3.5-6.2.3.4.2">
<dt pn="section-2.3.5-6.2.3.4.2.1">Threaded implementation:<
/dt>
<dd pn="section-2.3.5-6.2.3.4.2.2">It will block waiting for
an incoming request, so
it should be called in a separate thread if asynchronous operation
is required.
Unless there is an unexpected failure, this call only returns after an Unless there is an unexpected failure, this call only returns after an
incoming negotiation request. incoming negotiation request.
If the ASA supports multiple simultaneous transactions, a new sub-t hread must If the ASA supports multiple simultaneous transactions, a new sub-t hread must
be spawned for each new session, so that listen_negotiate() can be spawned for each new session, so that listen_negotiate() can
be called again immediately.</li> be called again immediately.</dd>
<li>Event loop implementation: A 'session_handle' parameter is u <dt pn="section-2.3.5-6.2.3.4.2.3">Event loop implementation
sed :</dt>
<dd pn="section-2.3.5-6.2.3.4.2.4">A 'session_handle' parame
ter is used
to distinguish individual sessions. to distinguish individual sessions.
If the ASA supports multiple simultaneous transactions, a new event must be inserted If the ASA supports multiple simultaneous transactions, a new event must be inserted
in the event loop for each new session, so that listen_negotiate() can in the event loop for each new session, so that listen_negotiate() can
be reactivated immediately.</li></ul></li> be reactivated immediately.</dd>
<li>This call only returns (threaded model) or triggers (event l </dl>
oop) after an </li>
<li pn="section-2.3.5-6.2.3.5">This call only returns (threaded
model) or triggers (event loop) after an
incoming negotiation request. When this occurs, incoming negotiation request. When this occurs,
'requested_objective' contains the first value requested by 'requested_objective' contains the first value requested by
the negotiation peer. The contents of this instance of the objectiv e the negotiation peer. The contents of this instance of the objectiv e
must be used in the subsequent negotiation call because must be used in the subsequent negotiation call because
it contains the loop count sent by the negotiation peer. The 'sess ion_handle' must be it contains the loop count sent by the negotiation peer. The 'sess ion_handle' must be
presented in all subsequent negotiation steps. </li> presented in all subsequent negotiation steps. </li>
<li>This function must be followed by calls to 'negotiate_step' and/or 'negotiate_wait' <li pn="section-2.3.5-6.2.3.6">This function must be followed by calls to 'negotiate_step' and/or 'negotiate_wait'
and/or 'end_negotiate' until the negotiation ends.</li> and/or 'end_negotiate' until the negotiation ends.</li>
<li>If an ASA is capable of handling multiple negotiations simul taneously, it may <li pn="section-2.3.5-6.2.3.7">If an ASA is capable of handling multiple negotiations simultaneously, it may
call 'listen_negotiate' simultaneously from multiple threads, or in sert multiple events. call 'listen_negotiate' simultaneously from multiple threads, or in sert multiple events.
The API and GRASP implementation The API and GRASP implementation
must support re-entrant use of the listening state and the negotiat ion calls. Simultaneous must support re-entrant use of the listening state and the negotiat ion calls. Simultaneous
sessions will be distinguished by the threads or events themselves, sessions will be distinguished by the threads or events themselves,
the GRASP session handles, and the underlying unicast transport soc kets.</li> the GRASP session handles, and the underlying unicast transport soc kets.</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.5-6.3">
<t>stop_listen_negotiate()</t> <t indent="0" pn="section-2.3.5-6.3.1">stop_listen_negotiate()</t>
<t>This function is used by an ASA to stop acting as a responder ( <t indent="0" pn="section-2.3.5-6.3.2">This function is used by an
listener) for a given GRASP objective.</t> ASA to stop acting as a responder (listener) for a given GRASP objective.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.5-6.3.3">
<t>Input parameters:</t> <li pn="section-2.3.5-6.3.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.5-6.3.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.3.3.1.2">
<dd>objective (structure)</dd> <li pn="section-2.3.5-6.3.3.1.2.1">asa_handle (unsigned inte
</dl> ger)</li>
<li pn="section-2.3.5-6.3.3.1.2.2">objective (structure)</li
>
</ul>
</li> </li>
<li> <li pn="section-2.3.5-6.3.3.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.5-6.3.3.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.3.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.5-6.3.3.2.2.1">errorcode (unsigned integ
er)</li>
</ul>
</li>
<li pn="section-2.3.5-6.3.3.3">Instructs GRASP to stop listening
for negotiation
requests for the given objective, i.e., cancels 'listen_negotiate
'.</li>
<li pn="section-2.3.5-6.3.3.4">
<t indent="0" pn="section-2.3.5-6.3.3.4.1">Asynchronous Mechan
isms:</t>
<dl indent="3" newline="false" spacing="normal" pn="section-2.
3.5-6.3.3.4.2">
<dt pn="section-2.3.5-6.3.3.4.2.1">Threaded implementation:<
/dt>
<dd pn="section-2.3.5-6.3.3.4.2.2">Must be called
from a different thread than 'listen_negotiate'. </dd>
<dt pn="section-2.3.5-6.3.3.4.2.3">Event loop implementation
:</dt>
<dd pn="section-2.3.5-6.3.3.4.2.4">No special considerations
.</dd>
</dl> </dl>
</li> </li>
<li>Instructs GRASP to stop listening for negotiation
requests for the given objective, i.e., cancels 'listen_negotiate'.
</li>
<li><t>Asynchronous Mechanisms:</t><ul>
<li>Threaded implementation: Must be called
from a different thread than 'listen_negotiate'. </li>
<li>Event loop implementation: no special considerations.</li></
ul></li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.5-6.4">
<t>negotiate_step()</t> <t indent="0" pn="section-2.3.5-6.4.1">negotiate_step()</t>
<t>This function is used by either ASA in a negotiation session to <t indent="0" pn="section-2.3.5-6.4.2">This function is used by ei
make the next step in negotiation.</t> ther ASA in a negotiation session to make the next step in negotiation.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.5-6.4.3">
<t>Input parameters:</t> <li pn="section-2.3.5-6.4.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.5-6.4.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.4.3.1.2">
<dd>session_handle (structure)</dd> <li pn="section-2.3.5-6.4.3.1.2.1">asa_handle (unsigned inte
<dt/> ger)</li>
<dd>objective (structure)</dd> <li pn="section-2.3.5-6.4.3.1.2.2">session_handle (structure
<dt/> )</li>
<dd>timeout (unsigned integer) as described in <xref target= <li pn="section-2.3.5-6.4.3.1.2.3">objective (structure)</li
"tout"/></dd> >
</dl> <li pn="section-2.3.5-6.4.3.1.2.4">timeout (unsigned integer
) as described in <xref target="tout" format="default" sectionFormat="of" derive
dContent="Section 2.3.2.3"/></li>
</ul>
</li> </li>
<li> <li pn="section-2.3.5-6.4.3.2">
<t>Return values:</t> <t indent="0" pn="section-2.3.5-6.4.3.2.1">Return values:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.4.3.2.2">
<dd>Exactly as for 'request_negotiate'</dd> <li pn="section-2.3.5-6.4.3.2.2.1">Exactly as for 'request_n
</dl> egotiate'</li>
</ul>
</li> </li>
<li>Executes the next negotation step with the peer. The 'object ive' parameter <li pn="section-2.3.5-6.4.3.3">Executes the next negotiation ste p with the peer. The 'objective' parameter
contains the next value being proffered by the ASA in this step. It must also contains the next value being proffered by the ASA in this step. It must also
contain the latest 'loop_count' value received from request_nego tiate() contain the latest 'loop_count' value received from request_nego tiate()
or negotiate_step().</li> or negotiate_step().</li>
<li><t>Asynchronous Mechanisms:</t><ul> <li pn="section-2.3.5-6.4.3.4">
<li>Threaded implementation: Usually called in the same thread a <t indent="0" pn="section-2.3.5-6.4.3.4.1">Asynchronous Mechan
s the isms:</t>
<dl indent="3" newline="false" spacing="normal" pn="section-2.
3.5-6.4.3.4.2">
<dt pn="section-2.3.5-6.4.3.4.2.1">Threaded implementation:<
/dt>
<dd pn="section-2.3.5-6.4.3.4.2.2">Usually called in the sam
e thread as the
preceding 'request_negotiate' or 'listen_negotiate', preceding 'request_negotiate' or 'listen_negotiate',
with the same value of 'session_handle'.</li> with the same value of 'session_handle'.</dd>
<li>Event loop implementation: Must use the same value of 'sessi <dt pn="section-2.3.5-6.4.3.4.2.3">Event loop implementation
on_handle' returned by the :</dt>
preceding 'request_negotiate' or 'listen_negotiate'.</li></ul></li> <dd pn="section-2.3.5-6.4.3.4.2.4">Must use the same value o
f 'session_handle' returned by the
preceding 'request_negotiate' or 'listen_negotiate'.</dd>
</dl>
</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.5-6.5">
<t>negotiate_wait()</t> <t indent="0" pn="section-2.3.5-6.5.1">negotiate_wait()</t>
<t>This function is used by either ASA in a negotiation session to <t indent="0" pn="section-2.3.5-6.5.2">This function is used by ei
delay the next step in negotiation.</t> ther ASA in a negotiation session to delay the next step in negotiation.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.5-6.5.3">
<t>Input parameters:</t> <li pn="section-2.3.5-6.5.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.5-6.5.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.5.3.1.2">
<dd>session_handle (structure)</dd> <li pn="section-2.3.5-6.5.3.1.2.1">asa_handle (unsigned inte
<dt/> ger)</li>
<dd>timeout (unsigned integer)</dd> <li pn="section-2.3.5-6.5.3.1.2.2">session_handle (structure
</dl> )</li>
<li pn="section-2.3.5-6.5.3.1.2.3">timeout (unsigned integer
)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.5-6.5.3.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.5-6.5.3.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.5.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.5-6.5.3.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li>Requests the remote peer to delay the negotiation session by 'timeout' milliseconds, <li pn="section-2.3.5-6.5.3.3">Requests the remote peer to delay the negotiation session by 'timeout' milliseconds,
thereby extending the original timeout. This thereby extending the original timeout. This
function simply triggers a GRASP Confirm Waiting message (see <x ref target="I-D.ietf-anima-grasp"/> function simply triggers a GRASP Confirm Waiting message (see <x ref target="RFC8990" format="default" sectionFormat="of" derivedContent="RFC8990 "/>
for details).</li> for details).</li>
<li><t>Asynchronous Mechanisms:</t><ul> <li pn="section-2.3.5-6.5.3.4">
<li>Threaded implementation: Called in the same thread as the pr <t indent="0" pn="section-2.3.5-6.5.3.4.1">Asynchronous Mechan
eceding isms:</t>
'request_negotiate' or 'listen_negotiate', with the same value o <dl indent="3" newline="false" spacing="normal" pn="section-2.
f 'session_handle'.</li> 3.5-6.5.3.4.2">
<li>Event loop implementation: Must use the same value of 'sessi <dt pn="section-2.3.5-6.5.3.4.2.1">Threaded implementation:<
on_handle' returned by the /dt>
preceding 'request_negotiate' or 'listen_negotiate'.</li></ul></li> <dd pn="section-2.3.5-6.5.3.4.2.2">Called in the same thread
as the preceding
'request_negotiate' or 'listen_negotiate', with the same value o
f 'session_handle'.</dd>
<dt pn="section-2.3.5-6.5.3.4.2.3">Event loop implementation
:</dt>
<dd pn="section-2.3.5-6.5.3.4.2.4">Must use the same value o
f 'session_handle' returned by the
preceding 'request_negotiate' or 'listen_negotiate'.</dd>
</dl>
</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.5-6.6">
<t>end_negotiate()</t> <t indent="0" pn="section-2.3.5-6.6.1">end_negotiate()</t>
<t>This function is used by either ASA in a negotiation session to <t indent="0" pn="section-2.3.5-6.6.2">This function is used by ei
end a negotiation.</t> ther ASA in a negotiation session to end a negotiation.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.5-6.6.3">
<t>Input parameters:</t> <li pn="section-2.3.5-6.6.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.5-6.6.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.6.3.1.2">
<dd>session_handle (structure)</dd> <li pn="section-2.3.5-6.6.3.1.2.1">asa_handle (unsigned inte
<dt/> ger)</li>
<dd>result (Boolean)</dd> <li pn="section-2.3.5-6.6.3.1.2.2">session_handle (structure
<dt/> )</li>
<dd>reason (UTF-8 string)</dd> <li pn="section-2.3.5-6.6.3.1.2.3">result (Boolean)</li>
</dl> <li pn="section-2.3.5-6.6.3.1.2.4">reason (UTF-8 string)</li
>
</ul>
</li> </li>
<li> <li pn="section-2.3.5-6.6.3.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.5-6.6.3.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.5-6.6.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.5-6.6.3.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.5-6.6.3.3">
<t>End the negotiation session. <t indent="0" pn="section-2.3.5-6.6.3.3.1">End the negotiation
session:
</t> </t>
<t> <t indent="0" pn="section-2.3.5-6.6.3.3.2">
'result' = True for accept (successful negotiation), False for decl 'result' = True for accept (successful negotiation), and False for
ine (failed negotiation). decline (failed negotiation).
</t> </t>
<t> <t indent="0" pn="section-2.3.5-6.6.3.3.3">
'reason' = string describing reason for decline (may be null; ignor ed if accept).</t> 'reason' = string describing reason for decline (may be null; ignor ed if accept).</t>
</li> </li>
<li><t>Asynchronous Mechanisms:</t><ul> <li pn="section-2.3.5-6.6.3.4">
<li>Threaded implementation: Called in the same thread as the pr <t indent="0" pn="section-2.3.5-6.6.3.4.1">Asynchronous Mechan
eceding 'request_negotiate' or 'listen_negotiate', isms:</t>
with the same value of 'session_handle'.</li> <dl indent="3" newline="false" spacing="normal" pn="section-2.
<li>Event loop implementation: Must use the same value of 'sessi 3.5-6.6.3.4.2">
on_handle' returned by the <dt pn="section-2.3.5-6.6.3.4.2.1">Threaded implementation:<
preceding 'request_negotiate' or 'listen_negotiate'.</li></ul></li> /dt>
<dd pn="section-2.3.5-6.6.3.4.2.2">Called in the same thread
as the preceding 'request_negotiate' or 'listen_negotiate',
with the same value of 'session_handle'.</dd>
<dt pn="section-2.3.5-6.6.3.4.2.3">Event loop implementation
:</dt>
<dd pn="section-2.3.5-6.6.3.4.2.4">Must use the same value o
f 'session_handle' returned by the
preceding 'request_negotiate' or 'listen_negotiate'.</dd>
</dl>
</li>
</ul> </ul>
</li> </li>
</ul> </ul>
</section> </section>
<!-- End of negotiation functions --> <section numbered="true" toc="include" removeInRFC="false" pn="section-2
.3.6">
<section numbered="true" toc="default"> <name slugifiedName="name-synchronization-and-floodin">Synchronization
<name>Synchronization and Flooding</name> and Flooding</name>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="section
<li> -2.3.6-1">
<t>synchronize()</t> <li pn="section-2.3.6-1.1">
<t>This function is used by any ASA to cause synchronization of a <t indent="0" pn="section-2.3.6-1.1.1">synchronize()</t>
GRASP objective as a requester (client).</t> <t indent="0" pn="section-2.3.6-1.1.2">This function is used by an
<ul spacing="normal"> y ASA to cause synchronization of a GRASP objective as a requester (client).</t>
<li> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<t>Input parameters:</t> tion-2.3.6-1.1.3">
<dl newline="false" spacing="normal"> <li pn="section-2.3.6-1.1.3.1">
<dt/> <t indent="0" pn="section-2.3.6-1.1.3.1.1">Input parameters:</
<dd>asa_handle (unsigned integer)</dd> t>
<dt/> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dd>objective (structure)</dd> section-2.3.6-1.1.3.1.2">
<dt/> <li pn="section-2.3.6-1.1.3.1.2.1">asa_handle (unsigned inte
<dd>peer (ASA_locator)</dd> ger)</li>
<dt/> <li pn="section-2.3.6-1.1.3.1.2.2">objective (structure)</li
<dd>timeout (unsigned integer)</dd> >
</dl> <li pn="section-2.3.6-1.1.3.1.2.3">peer (asa_locator)</li>
<li pn="section-2.3.6-1.1.3.1.2.4">timeout (unsigned integer
)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.6-1.1.3.2">
<t>Return values:</t> <t indent="0" pn="section-2.3.6-1.1.3.2.1">Return values:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.1.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.6-1.1.3.2.2.1">errorcode (unsigned integ
<dt/> er)</li>
<dd>result (structure) (undefined unless successful)</dd> <li pn="section-2.3.6-1.1.3.2.2.2">result (structure) (undef
</dl> ined unless successful)</li>
</ul>
</li> </li>
<li>This call requests the synchronized value of the given 'obje <li pn="section-2.3.6-1.1.3.3">This call requests the synchroniz
ctive'.</li> ed value of the given 'objective'.</li>
<!-- <li>Since this is essentially a read operation, any ASA can <li pn="section-2.3.6-1.1.3.4">If the 'peer' parameter is null,
do it, unless and the objective is already
an authorization model is added to GRASP in future. Therefore
the API checks that the ASA is registered, but the objective do
es not need to
be registered by the calling ASA.</li> -->
<li>If the 'peer' parameter is null, and the objective is alread
y
available in the local cache, the flooded objective is returned immediately available in the local cache, the flooded objective is returned immediately
in the 'result' parameter. In this case, the 'timeout' is ignore d.</li> in the 'result' parameter. In this case, the 'timeout' is ignore d.</li>
<li> If the 'peer' parameter is not null, or a cached value <li pn="section-2.3.6-1.1.3.5"> If the 'peer' parameter is not n ull, or a cached value
is not available, synchronization with a discovered ASA is perfo rmed. is not available, synchronization with a discovered ASA is perfo rmed.
If successful, the retrieved objective is returned If successful, the retrieved objective is returned
in the 'result' value.</li> in the 'result' value.</li>
<li>The 'peer' parameter is an 'ASA_locator' as returned by disc over(). <li pn="section-2.3.6-1.1.3.6">The 'peer' parameter is an 'asa_l ocator' as returned by discover().
If 'peer' is null, GRASP discovery is automatically performed fi rst to find If 'peer' is null, GRASP discovery is automatically performed fi rst to find
a suitable peer (i.e., any node that supports the objective in q uestion).</li> a suitable peer (i.e., any node that supports the objective in q uestion).</li>
<li>The 'timeout' parameter is described in <xref target="tout"/ <li pn="section-2.3.6-1.1.3.7">The 'timeout' parameter is descri
>.</li> bed in <xref target="tout" format="default" sectionFormat="of" derivedContent="S
<li>This call should be repeated whenever the latest value is ne ection 2.3.2.3"/>.</li>
eded.</li> <li pn="section-2.3.6-1.1.3.8">This call should be repeated when
<li><t>Asynchronous Mechanisms:</t><ul> ever the latest value is needed.</li>
<li>Threaded implementation: Call in a separate thread if asynch <li pn="section-2.3.6-1.1.3.9">
ronous operation is required.</li> <t indent="0" pn="section-2.3.6-1.1.3.9.1">Asynchronous Mechan
<li>Event loop implementation: An additional in/out 'session_han isms:</t>
dle' parameter is used, <dl indent="3" newline="false" spacing="normal" pn="section-2.
3.6-1.1.3.9.2">
<dt pn="section-2.3.6-1.1.3.9.2.1">Threaded implementation:<
/dt>
<dd pn="section-2.3.6-1.1.3.9.2.2">Call in a separate thread
if asynchronous operation is required.</dd>
<dt pn="section-2.3.6-1.1.3.9.2.3">Event loop implementation
:</dt>
<dd pn="section-2.3.6-1.1.3.9.2.4">An additional in/out 'ses
sion_handle' parameter is used,
as in request_negotiate(). If the 'errorcode' parameter has the value 2 ('noReply'), as in request_negotiate(). If the 'errorcode' parameter has the value 2 ('noReply'),
no response has been received so far. The 'session_handle' param eter must be presented no response has been received so far. The 'session_handle' param eter must be presented
in subsequent calls.</li></ul></li> in subsequent calls.</dd>
<!-- <li>Since this is essentially a read operation, any ASA can </dl>
use </li>
it. Therefore GRASP checks that the calling ASA is registered but t <li pn="section-2.3.6-1.1.3.10">In the case of failure, an expon
he ential backoff is recommended before
objective does not need to be registered by the calling ASA.</li> - retrying (<xref target="security" format="default" sectionFormat
-> ="of" derivedContent="Section 3"/>).</li>
<li>In the case of failure, an exponential backoff is recommende
d before
retrying (<xref target="security"/>).</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.6-1.2">
<t>listen_synchronize()</t> <t indent="0" pn="section-2.3.6-1.2.1">listen_synchronize()</t>
<t>This function is used by an ASA to start acting as a synchroniz <t indent="0" pn="section-2.3.6-1.2.2">This function is used by an
ation responder (listener) ASA to start acting as a synchronization responder (listener)
for a given GRASP objective.</t> for a given GRASP objective.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.6-1.2.3">
<t>Input parameters:</t> <li pn="section-2.3.6-1.2.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.6-1.2.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.2.3.1.2">
<dd>objective (structure)</dd> <li pn="section-2.3.6-1.2.3.1.2.1">asa_handle (unsigned inte
</dl> ger)</li>
<li pn="section-2.3.6-1.2.3.1.2.2">objective (structure)</li
>
</ul>
</li> </li>
<li> <li pn="section-2.3.6-1.2.3.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.6-1.2.3.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.2.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.6-1.2.3.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li>This instructs GRASP to listen for synchronization <li pn="section-2.3.6-1.2.3.3">This instructs GRASP to listen fo
requests for the given objective, and to r synchronization
requests for the given objective and to
respond with the value given in the 'objective' parameter. respond with the value given in the 'objective' parameter.
It also enables discovery responses for the objective, It also enables discovery responses for the objective,
as mentioned under register_objective() in <xref target="regi"/>.</ as mentioned under register_objective() in <xref target="regi" form
li> at="default" sectionFormat="of" derivedContent="Section 2.3.3"/>.</li>
<li>This call is non-blocking and may be repeated whenever the v <li pn="section-2.3.6-1.2.3.4">This call is non-blocking and may
alue changes.</li> be repeated whenever the value changes.</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.6-1.3">
<t>stop_listen_synchronize()</t> <t indent="0" pn="section-2.3.6-1.3.1">stop_listen_synchronize()</
<t>This function is used by an ASA to stop acting as a synchroniza t>
tion responder (listener) <t indent="0" pn="section-2.3.6-1.3.2">This function is used by an
ASA to stop acting as a synchronization responder (listener)
for a given GRASP objective.</t> for a given GRASP objective.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.6-1.3.3">
<t>Input parameters:</t> <li pn="section-2.3.6-1.3.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.6-1.3.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.3.3.1.2">
<dd>objective (structure)</dd> <li pn="section-2.3.6-1.3.3.1.2.1">asa_handle (unsigned inte
</dl> ger)</li>
<li pn="section-2.3.6-1.3.3.1.2.2">objective (structure)</li
>
</ul>
</li> </li>
<li> <li pn="section-2.3.6-1.3.3.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.6-1.3.3.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.3.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.6-1.3.3.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li>This call instructs GRASP to stop listening for synchronizat <li pn="section-2.3.6-1.3.3.3">This call instructs GRASP to stop
ion listening for synchronization
requests for the given 'objective', i.e. it cancels a previous list requests for the given 'objective', i.e., it cancels a previous lis
en_synchronize.</li> ten_synchronize.</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.6-1.4">
<t>flood()</t> <t indent="0" pn="section-2.3.6-1.4.1">flood()</t>
<t>This function is used by an ASA to flood one or more GRASP obje <t indent="0" pn="section-2.3.6-1.4.2">This function is used by an
ctives ASA to flood one or more GRASP objectives
throughout the autonomic network.</t> throughout the Autonomic Network.</t>
<t>Note that each GRASP node caches all flooded objectives that it <t indent="0" pn="section-2.3.6-1.4.3">Note that each GRASP node c
receives, until aches all flooded objectives that it receives, until
each one's time-to-live expires. Cached objectives are tagged with each one's time to live expires. Cached objectives are tagged with
their origin their origin
as well as an expiry time, so multiple as well as an expiry time, so multiple
copies of the same objective may be cached simultaneously. Further details copies of the same objective may be cached simultaneously. Further details
are given in the section 'Flood Synchronization Message' of are given in "Flood Synchronization Message" (<xref target="RFC899
<xref target="I-D.ietf-anima-grasp"/></t> 0" section="2.8.11" sectionFormat="of" format="default" derivedLink="https://rfc
<ul spacing="normal"> -editor.org/rfc/rfc8990#section-2.8.11" derivedContent="RFC8990"/>).</t>
<li> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<t>Input parameters:</t> tion-2.3.6-1.4.4">
<dl newline="false" spacing="normal"> <li pn="section-2.3.6-1.4.4.1">
<dt/> <t indent="0" pn="section-2.3.6-1.4.4.1.1">Input parameters:</
<dd>asa_handle (unsigned integer)</dd> t>
<dt/> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dd>ttl (unsigned integer)</dd> section-2.3.6-1.4.4.1.2">
<dt/> <li pn="section-2.3.6-1.4.4.1.2.1">asa_handle (unsigned inte
<dd>tagged_objective_list (structure)</dd> ger)</li>
</dl> <li pn="section-2.3.6-1.4.4.1.2.2">ttl (unsigned integer)</l
i>
<li pn="section-2.3.6-1.4.4.1.2.3">tagged_objective_list (st
ructure)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.6-1.4.4.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.6-1.4.4.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.4.4.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.6-1.4.4.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li>This call instructs GRASP to flood the given synchronization <li pn="section-2.3.6-1.4.4.3">This call instructs GRASP to floo d the given synchronization
objective(s) and their value(s) and associated locator(s) to all GR ASP nodes.</li> objective(s) and their value(s) and associated locator(s) to all GR ASP nodes.</li>
<li>The 'ttl' parameter is the valid lifetime (time to live) of <li pn="section-2.3.6-1.4.4.4">The 'ttl' parameter is the valid
the flooded data in milliseconds (0 = infinity)</li> lifetime (time to live) of
<li>The 'tagged_objective_list' parameter is a list of one or mo the flooded data in milliseconds (0 = infinity).</li>
re 'tagged_objective' <li pn="section-2.3.6-1.4.4.5">The 'tagged_objective_list' param
eter is a list of one or more 'tagged_objective'
couplets. couplets.
The 'locator' parameter that tags each objective is normally null b ut may The 'locator' parameter that tags each objective is normally null b ut may
be a valid 'ASA_locator'. be a valid 'asa_locator'.
Infrastructure ASAs needing to flood an {address, protocol, port} 3 -tuple Infrastructure ASAs needing to flood an {address, protocol, port} 3 -tuple
with an objective create an ASA_locator object to do so. If the IP address with an objective create an asa_locator object to do so. If the IP address
in that locator is the unspecified address in that locator is the unspecified address
('::') it is replaced by the link-local address of the sending node in each ('::'), it is replaced by the link-local address of the sending nod e in each
copy of the flood multicast, which will be forced to have a loop co unt of 1. copy of the flood multicast, which will be forced to have a loop co unt of 1.
This feature is for objectives that must be restricted to the local link. This feature is for objectives that must be restricted to the local link.
</li> </li>
<li>The function checks that the ASA registered each objective.< <li pn="section-2.3.6-1.4.4.6">The function checks that the ASA
/li> registered each objective.</li>
<li>This call may be repeated whenever any value changes.</li> <li pn="section-2.3.6-1.4.4.7">This call may be repeated wheneve
r any value changes.</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.6-1.5">
<t>get_flood()</t> <t indent="0" pn="section-2.3.6-1.5.1">get_flood()</t>
<t>This function is used by any ASA to obtain the current value of <t indent="0" pn="section-2.3.6-1.5.2">This function is used by an
a flooded GRASP objective.</t> y ASA to obtain the current value of a flooded GRASP objective.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.6-1.5.3">
<t>Input parameters:</t> <li pn="section-2.3.6-1.5.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.6-1.5.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.5.3.1.2">
<dd>objective (structure)</dd> <li pn="section-2.3.6-1.5.3.1.2.1">asa_handle (unsigned inte
</dl> ger)</li>
<li pn="section-2.3.6-1.5.3.1.2.2">objective (structure)</li
>
</ul>
</li> </li>
<li> <li pn="section-2.3.6-1.5.3.2">
<t>Return values:</t> <t indent="0" pn="section-2.3.6-1.5.3.2.1">Return values:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.5.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.6-1.5.3.2.2.1">errorcode (unsigned integ
<dt/> er)</li>
<dd>tagged_objective_list (structure) (undefined unless succ <li pn="section-2.3.6-1.5.3.2.2.2">tagged_objective_list (st
essful)</dd> ructure) (undefined unless successful)</li>
</dl> </ul>
</li> </li>
<li>This call instructs GRASP to return the given synchronizatio n <li pn="section-2.3.6-1.5.3.3">This call instructs GRASP to retu rn the given synchronization
objective if it has been flooded and its lifetime has not expired. </li> objective if it has been flooded and its lifetime has not expired. </li>
<!-- <li>Since this is essentially a read operation, any ASA can <li pn="section-2.3.6-1.5.3.4">The 'tagged_objective_list' param
do eter is a list of 'tagged_objective'
it. Therefore the API checks that the ASA is registered but the couplets, each one being a copy of the flooded objective and a corr
objective does not need to be registered by the calling ASA.</li> - esponding locator.
-> Thus, if the same objective has been flooded by multiple ASAs, the
<li>The 'tagged_objective_list' parameter is a list of 'tagged_o recipient can distinguish
bjective'
couplets, each one being a copy of the flooded objective and a core
sponding locator.
Thus if the same objective has been flooded by multiple ASAs, the r
ecipient can distinguish
the copies.</li> the copies.</li>
<li>Note that this call is for advanced ASAs. In a simple case, an ASA can simply call <li pn="section-2.3.6-1.5.3.5">Note that this call is for advanc ed ASAs. In a simple case, an ASA can simply call
synchronize() in order to get a valid flooded objective.</li> synchronize() in order to get a valid flooded objective.</li>
</ul> </ul>
</li> </li>
<li> <li pn="section-2.3.6-1.6">
<t>expire_flood()</t> <t indent="0" pn="section-2.3.6-1.6.1">expire_flood()</t>
<t>This function may be used by an ASA to expire specific entries <t indent="0" pn="section-2.3.6-1.6.2">This function may be used b
in the local GRASP flood cache.</t> y an ASA to expire specific entries in the local GRASP flood cache.</t>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<li> tion-2.3.6-1.6.3">
<t>Input parameters:</t> <li pn="section-2.3.6-1.6.3.1">
<dl newline="false" spacing="normal"> <t indent="0" pn="section-2.3.6-1.6.3.1.1">Input parameters:</
<dt/> t>
<dd>asa_handle (unsigned integer)</dd> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.6.3.1.2">
<dd>tagged_objective (structure)</dd> <li pn="section-2.3.6-1.6.3.1.2.1">asa_handle (unsigned inte
</dl> ger)</li>
<li pn="section-2.3.6-1.6.3.1.2.2">tagged_objective (structu
re)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.6-1.6.3.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.6-1.6.3.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.6-1.6.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.6-1.6.3.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li>This is a call that can only be used after a preceding <li pn="section-2.3.6-1.6.3.3">This is a call that can only be u sed after a preceding
call to get_flood() by an ASA that is capable of deciding call to get_flood() by an ASA that is capable of deciding
that the flooded value is stale or invalid. Use with care.</li> that the flooded value is stale or invalid. Use with care.</li>
<li>The 'tagged_objective' parameter is the one to be expired.</ li> <li pn="section-2.3.6-1.6.3.4">The 'tagged_objective' parameter is the one to be expired.</li>
</ul> </ul>
</li> </li>
</ul> </ul>
</section> </section>
<!-- End of synchronization functions --> <section numbered="true" toc="include" removeInRFC="false" pn="section-2
.3.7">
<section numbered="true" toc="default"> <name slugifiedName="name-invalid-message-function">Invalid Message Fu
<name>Invalid Message Function</name> nction</name>
<ul spacing="normal"> <ul spacing="normal" bare="false" empty="false" indent="3" pn="section
<li> -2.3.7-1">
<t>send_invalid()</t> <li pn="section-2.3.7-1.1">
<t>This function may be used by any ASA to stop an ongoing GRASP s <t indent="0" pn="section-2.3.7-1.1.1">send_invalid()</t>
ession.</t> <t indent="0" pn="section-2.3.7-1.1.2">This function may be used b
<ul spacing="normal"> y any ASA to stop an ongoing GRASP session.</t>
<li> <ul spacing="normal" bare="false" empty="false" indent="3" pn="sec
<t>Input parameters:</t> tion-2.3.7-1.1.3">
<dl newline="false" spacing="normal"> <li pn="section-2.3.7-1.1.3.1">
<dt/> <t indent="0" pn="section-2.3.7-1.1.3.1.1">Input parameters:</
<dd>asa_handle (unsigned integer)</dd> t>
<dt/> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dd>session_handle (structure)</dd> section-2.3.7-1.1.3.1.2">
<dt/> <li pn="section-2.3.7-1.1.3.1.2.1">asa_handle (unsigned inte
<dd>info (bytes)</dd> ger)</li>
</dl> <li pn="section-2.3.7-1.1.3.1.2.2">session_handle (structure
)</li>
<li pn="section-2.3.7-1.1.3.1.2.3">info (bytes)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.7-1.1.3.2">
<t>Return value:</t> <t indent="0" pn="section-2.3.7-1.1.3.2.1">Return value:</t>
<dl newline="false" spacing="normal"> <ul empty="true" bare="false" indent="3" spacing="normal" pn="
<dt/> section-2.3.7-1.1.3.2.2">
<dd>errorcode (unsigned integer)</dd> <li pn="section-2.3.7-1.1.3.2.2.1">errorcode (unsigned integ
</dl> er)</li>
</ul>
</li> </li>
<li> <li pn="section-2.3.7-1.1.3.3">
<t>Sends a GRASP Invalid Message (M_INVALID) message, as descr <t indent="0" pn="section-2.3.7-1.1.3.3.1">Sends a GRASP Inval
ibed in id message (M_INVALID), as described in
<xref target="I-D.ietf-anima-grasp"/>. Should not be used if end_ne <xref target="RFC8990" format="default" sectionFormat="of" derivedC
gotiate() would be sufficient. ontent="RFC8990"/>. It should not be used if end_negotiate() would be sufficient
.
Note that this message may be used in response to any unicast GRASP message that the receiver Note that this message may be used in response to any unicast GRASP message that the receiver
cannot interpret correctly. In most cases this message will be gene rated internally by a cannot interpret correctly. In most cases, this message will be gen erated internally by a
GRASP implementation. GRASP implementation.
</t> </t>
<t> <t indent="0" pn="section-2.3.7-1.1.3.3.2">
'info' = optional diagnostic data supplied by the ASA. May be raw b 'info' = optional diagnostic data supplied by the ASA. It may be ra
ytes from the invalid message.</t> w bytes from the invalid message.</t>
</li> </li>
</ul> </ul>
</li> </li>
</ul> </ul>
</section> </section>
</section> </section>
</section> </section>
<section numbered="true" toc="default"> <section anchor="security" numbered="true" toc="include" removeInRFC="false"
<name>Implementation Status [RFC Editor: please remove]</name> pn="section-3">
<t>A prototype open source Python implementation of GRASP, including <name slugifiedName="name-security-considerations">Security Considerations
an API similar to this document, has been used </name>
to verify the concepts for the threaded model. It may be found at <t indent="0" pn="section-3-1">Security considerations for the GRASP proto
<eref target="https://github.com/becarpenter/graspy"/> col are discussed in <xref target="RFC8990" format="default" sectionFormat="of"
with associated documentation and demonstration ASAs. derivedContent="RFC8990"/>.
</t> These include denial-of-service issues, even though these are considered a
</section> low risk in the ACP. In various
<!----> places, GRASP recommends an exponential backoff. An ASA using the API shou
ld use exponential backoff
<section anchor="security" numbered="true" toc="default"> after failed discover(), req_negotiate(), or synchronize() operations. The
<name>Security Considerations</name> timescale for such backoffs
<t>Security considerations for the GRASP protocol are discussed in <xref t
arget="I-D.ietf-anima-grasp"/>.
These include denial of service issues, even though these are considered a
low risk in the ACP. In various
places GRASP recommends an exponential backoff. An ASA using the API shoul
d use exponential backoff
after failed discover(), req_negotiate() or synchronize() operations. The
timescale for such backoffs
depends on the semantics of the GRASP objective concerned. Additionally, a flood() operation should depends on the semantics of the GRASP objective concerned. Additionally, a flood() operation should
not be repeated at shorter intervals than is useful. The appropriate inter val depends on the semantics not be repeated at shorter intervals than is useful. The appropriate inter val depends on the semantics
of the GRASP objective concerned. These precautions are intended to assist the detection of of the GRASP objective concerned. These precautions are intended to assist the detection of
denial of service attacks.</t> denial-of-service attacks.</t>
<t indent="0" pn="section-3-2">As a general precaution, all ASAs able to h
<t>As a general precaution, all ASAs able to handle multiple negotiation o andle multiple negotiation or synchronization requests
r synchronization requests in parallel may protect themselves against a denial-of-service attack by l
in parallel may protect themselves against a denial of service attack by l imiting the number
imiting the number
of requests they handle simultaneously and silently discarding excess requ ests. It might also of requests they handle simultaneously and silently discarding excess requ ests. It might also
be useful for the GRASP core to limit the number of objectives registered by a given ASA, the be useful for the GRASP core to limit the number of objectives registered by a given ASA, the
total number of ASAs registered, and the total number of simultaneous sess ions, total number of ASAs registered, and the total number of simultaneous sess ions,
to protect system resources. During times of high autonomic activity, such as recovery to protect system resources. During times of high autonomic activity, such as recovery
from widespread faults, ASAs may experience many GRASP session failures. G uidance on from widespread faults, ASAs may experience many GRASP session failures. G uidance on
making ASAs suitably robust is given in <xref target="I-D.ietf-anima-asa-g making ASAs suitably robust is given in <xref target="I-D.ietf-anima-asa-g
uidelines"/>.</t> uidelines" format="default" sectionFormat="of" derivedContent="ASA-GUIDE"/>.</t>
<t indent="0" pn="section-3-3">As noted earlier, the trust model is that a
<t>As noted earlier, the trust model is that all ASAs in a given autonomic ll ASAs in a given Autonomic Network communicate via a secure
network communicate via a secure autonomic control plane; therefore, they trust each other's messages.
autonomic control plane and therefore trust each other's messages.
Specific authorization of ASAs to use particular GRASP objectives is a sub ject for future study, also briefly Specific authorization of ASAs to use particular GRASP objectives is a sub ject for future study, also briefly
discussed in <xref target="I-D.ietf-anima-grasp"/>.</t> discussed in <xref target="RFC8990" format="default" sectionFormat="of" de
rivedContent="RFC8990"/>.</t>
<t>The careful reader will observe that a malicious ASA could extend a neg <t indent="0" pn="section-3-4">The careful reader will observe that a mali
otiation session cious ASA could extend a negotiation session
indefinitely by use of the negotiate_wait() function or by manipulating th e loop count indefinitely by use of the negotiate_wait() function or by manipulating th e loop count
of an objective. A robustly implemented ASA could detect such behavior by a peer of an objective. A robustly implemented ASA could detect such behavior by a peer
and break off negotiation.</t> and break off negotiation.</t>
<t indent="0" pn="section-3-5">The 'asa_handle' is used in the API as a fi
<t>The 'asa_handle' is used in the API as a first line of defence against rst line of defense against a malware process attempting
a malware process attempting
to imitate a legitimately registered ASA. The 'session_handle' is used in the API as a first line to imitate a legitimately registered ASA. The 'session_handle' is used in the API as a first line
of defence against a malware process attempting to hijack a GRASP session. of defense against a malware process attempting to hijack a GRASP session.
Both these handles Both these handles
are likely to be created using GRASP's 32-bit pseudo-random session ID. By are likely to be created using GRASP's 32-bit pseudorandom Session ID. By
construction, GRASP avoids construction, GRASP avoids
the risk of session ID collisions (see the section 'Session Identifier' of the risk of Session ID collisions (see "Session Identifier (Session ID)",
<xref target="I-D.ietf-anima-grasp"/>). <xref target="RFC8990" section="2.7" sectionFormat="of" format="default" derived
There remains a finite probability that an attacker could guess a session Link="https://rfc-editor.org/rfc/rfc8990#section-2.7" derivedContent="RFC8990"/>
ID, session_handle, or asa_handle. ).
There remains a finite probability that an attacker could guess a Session
ID, session_handle, or asa_handle.
However, this would only be of value to an attacker that had already penet rated the ACP, which would However, this would only be of value to an attacker that had already penet rated the ACP, which would
allow many other simpler forms of attack than hijacking GRASP sessions.</t > allow many other simpler forms of attack than hijacking GRASP sessions.</t >
</section> </section>
<section anchor="iana" numbered="true" toc="default"> <section anchor="iana" numbered="true" toc="include" removeInRFC="false" pn=
<name>IANA Considerations</name> "section-4">
<t>This document makes no request of the IANA.</t> <name slugifiedName="name-iana-considerations">IANA Considerations</name>
<!-- <t>Open question: Do we need an IANA registry for the error codes?</t <t indent="0" pn="section-4-1">This document has no IANA actions.</t>
> -->
</section>
<section anchor="ack" numbered="true" toc="default">
<name>Acknowledgements</name>
<t>Excellent suggestions were made by
Ignas Bagdonas,
Carsten Bormann,
Laurent Ciavaglia,
Roman Danyliw,
Toerless Eckert,
Benjamin Kaduk
Erik Kline,
Murray Kucherawy,
Paul Kyzivat,
Guangpeng Li,
Michael Richardson,
Joseph Salowey,
Eric Vyncke,
Magnus Westerlund,
Rob Wilton,
and other participants in the ANIMA WG and the IESG.</t>
</section> </section>
</middle> </middle>
<back> <back>
<references> <displayreference target="I-D.ietf-anima-grasp-distribution" to="GRASP-DISTR
<name>References</name> IB"/>
<references> <displayreference target="I-D.ciavaglia-anima-coordination" to="ANIMA-COORD"
<name>Normative References</name> />
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/referen <displayreference target="I-D.ietf-anima-asa-guidelines" to="ASA-GUIDE"/>
ce.RFC.8610.xml"/> <references pn="section-5">
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/referen <name slugifiedName="name-references">References</name>
ce.RFC.8949.xml"/> <references pn="section-5.1">
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/refere <name slugifiedName="name-normative-references">Normative References</na
nce.I-D.ietf-anima-grasp.xml"/> me>
<reference anchor="RFC8610" target="https://www.rfc-editor.org/info/rfc8
610" quoteTitle="true" derivedAnchor="RFC8610">
<front>
<title>Concise Data Definition Language (CDDL): A Notational Convent
ion to Express Concise Binary Object Representation (CBOR) and JSON Data Structu
res</title>
<author initials="H." surname="Birkholz" fullname="H. Birkholz">
<organization showOnFrontPage="true"/>
</author>
<author initials="C." surname="Vigano" fullname="C. Vigano">
<organization showOnFrontPage="true"/>
</author>
<author initials="C." surname="Bormann" fullname="C. Bormann">
<organization showOnFrontPage="true"/>
</author>
<date year="2019" month="June"/>
<abstract>
<t indent="0">This document proposes a notational convention to ex
press Concise Binary Object Representation (CBOR) data structures (RFC 7049). I
ts main goal is to provide an easy and unambiguous way to express structures for
protocol messages and data formats that use CBOR or JSON.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="8610"/>
<seriesInfo name="DOI" value="10.17487/RFC8610"/>
</reference>
<reference anchor="RFC8949" target="https://www.rfc-editor.org/info/rfc8
949" quoteTitle="true" derivedAnchor="RFC8949">
<front>
<title>Concise Binary Object Representation (CBOR)</title>
<author initials="C." surname="Bormann" fullname="C. Bormann">
<organization showOnFrontPage="true"/>
</author>
<author initials="P." surname="Hoffman" fullname="P. Hoffman">
<organization showOnFrontPage="true"/>
</author>
<date year="2020" month="December"/>
<abstract>
<t indent="0">The Concise Binary Object Representation (CBOR) is a
data format whose design goals include the possibility of extremely small code
size, fairly small message size, and extensibility without the need for version
negotiation. These design goals make it different from earlier binary serializat
ions such as ASN.1 and MessagePack.</t>
<t indent="0">This document obsoletes RFC 7049, providing editoria
l improvements, new details, and errata fixes while keeping full compatibility w
ith the interchange format of RFC 7049. It does not create a new version of the
format.</t>
</abstract>
</front>
<seriesInfo name="STD" value="94"/>
<seriesInfo name="RFC" value="8949"/>
<seriesInfo name="DOI" value="10.17487/RFC8949"/>
</reference>
<reference anchor="RFC8990" target="https://www.rfc-editor.org/info/rfc8
990" quoteTitle="true" derivedAnchor="RFC8990">
<front>
<title>GeneRic Autonomic Signaling Protocol (GRASP)</title>
<author initials="C" surname="Bormann" fullname="Carsten Bormann">
<organization showOnFrontPage="true"/>
</author>
<author initials="B" surname="Carpenter" fullname="Brian Carpenter"
role="editor">
<organization showOnFrontPage="true"/>
</author>
<author initials="B" surname="Liu" fullname="Bing Liu" role="editor"
>
<organization showOnFrontPage="true"/>
</author>
<date month="May" year="2021"/>
</front>
<seriesInfo name="RFC" value="8990"/>
<seriesInfo name="DOI" value="10.17487/RFC8990"/>
</reference>
</references> </references>
<references> <references pn="section-5.2">
<name>Informative References</name> <name slugifiedName="name-informative-references">Informative References
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/refere </name>
nce.I-D.ietf-anima-reference-model.xml"/> <reference anchor="I-D.ciavaglia-anima-coordination" quoteTitle="true" t
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/refere arget="https://tools.ietf.org/html/draft-ciavaglia-anima-coordination-01" derive
nce.I-D.ietf-anima-grasp-distribution.xml"/> dAnchor="ANIMA-COORD">
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/refere <front>
nce.I-D.ietf-anima-autonomic-control-plane.xml"/> <title>Autonomic Functions Coordination</title>
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/refere <author fullname="Laurent Ciavaglia">
nce.I-D.ietf-anima-bootstrapping-keyinfra.xml"/> </author>
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/refere <author fullname="Pierre Peloso">
nce.I-D.ciavaglia-anima-coordination.xml"/> </author>
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/refere <date month="March" day="21" year="2016"/>
nce.I-D.ietf-anima-asa-guidelines.xml"/> </front>
<seriesInfo name="Internet-Draft" value="draft-ciavaglia-anima-coordin
ation-01"/>
<refcontent>Work in Progress</refcontent>
</reference>
<reference anchor="I-D.ietf-anima-asa-guidelines" quoteTitle="true" targ
et="https://tools.ietf.org/html/draft-ietf-anima-asa-guidelines-00" derivedAncho
r="ASA-GUIDE">
<front>
<title>Guidelines for Autonomic Service Agents</title>
<author fullname="Brian Carpenter">
</author>
<author fullname="Laurent Ciavaglia">
<organization showOnFrontPage="true">Nokia</organization>
</author>
<author fullname="Sheng Jiang">
<organization showOnFrontPage="true">Huawei Technologies Co., Ltd<
/organization>
</author>
<author fullname="Pierre Peloso">
<organization showOnFrontPage="true">Nokia</organization>
</author>
<date month="November" day="14" year="2020"/>
<abstract>
<t indent="0"> This document proposes guidelines for the design
of Autonomic Service
Agents for autonomic networks, as a contribution to describing an
autonomic ecosystem. It is based on the Autonomic Network
Infrastructure outlined in the ANIMA reference model, using the
Autonomic Control Plane and the Generic Autonomic Signaling Protocol.
<reference anchor="libcbor" target="https://libcbor.readthedocs.io/"> </t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-anima-asa-guidelin
es-00"/>
<format type="TXT" target="https://www.ietf.org/archive/id/draft-ietf-
anima-asa-guidelines-00.txt"/>
<refcontent>Work in Progress</refcontent>
</reference>
<reference anchor="I-D.ietf-anima-grasp-distribution" quoteTitle="true"
target="https://tools.ietf.org/html/draft-ietf-anima-grasp-distribution-02" deri
vedAnchor="GRASP-DISTRIB">
<front> <front>
<title>libcbor - Documentation</title> <title>Information Distribution over GRASP</title>
<author fullname="Pavel Kalvoda"/> <author fullname="Bing Liu">
<date month="December" year="2020"/> <organization showOnFrontPage="true">Huawei Technologies</organiza
tion>
</author>
<author fullname="Xun Xiao">
<organization showOnFrontPage="true">MRC, Huawei Technologies</org
anization>
</author>
<author fullname="Artur Hecker">
<organization showOnFrontPage="true">MRC, Huawei Technologies</org
anization>
</author>
<author fullname="Sheng Jiang">
<organization showOnFrontPage="true">Huawei Technologies</organiza
tion>
</author>
<author fullname="Zoran Despotovic">
<organization showOnFrontPage="true">MRC, Huawei Technologies</org
anization>
</author>
<author fullname="Brian Carpenter">
<organization showOnFrontPage="true">School of Computer Science, U
niversity of Auckland</organization>
</author>
<date month="March" day="8" year="2021"/>
</front> </front>
</reference> <seriesInfo name="Internet-Draft" value="draft-ietf-anima-grasp-distri
bution-02"/>
<refcontent>Work in Progress</refcontent>
</reference>
<reference anchor="libcbor" target="https://libcbor.readthedocs.io/" quo
teTitle="true" derivedAnchor="libcbor">
<front>
<title>libcbor - libcbor 0.8.0 documentation</title>
<author fullname="Pavel Kalvoda" surname="Kalvoda" initials="P"/>
<date month="April" year="2021"/>
</front>
</reference>
<reference anchor="RFC8993" target="https://www.rfc-editor.org/info/rfc8
993" quoteTitle="true" derivedAnchor="RFC8993">
<front>
<title>A Reference Model for Autonomic Networking</title>
<author initials="M" surname="Behringer" fullname="Michael Behringer
" role="editor">
<organization showOnFrontPage="true"/>
</author>
<author initials="B" surname="Carpenter" fullname="Brian Carpenter">
<organization showOnFrontPage="true"/>
</author>
<author initials="T" surname="Eckert" fullname="Toerless Eckert">
<organization showOnFrontPage="true"/>
</author>
<author initials="L" surname="Ciavaglia" fullname="Laurent Ciavaglia
">
<organization showOnFrontPage="true"/>
</author>
<author initials="J" surname="Nobre" fullname="Jeferson Nobre">
<organization showOnFrontPage="true"/>
</author>
<date month="May" year="2021"/>
</front>
<seriesInfo name="RFC" value="8993"/>
<seriesInfo name="DOI" value="10.17487/RFC8993"/>
</reference>
<reference anchor="RFC8994" target="https://www.rfc-editor.org/info/rfc8
994" quoteTitle="true" derivedAnchor="RFC8994">
<front>
<title>An Autonomic Control Plane (ACP)</title>
<author initials="T" surname="Eckert" fullname="Toerless Eckert" rol
e="editor">
<organization showOnFrontPage="true"/>
</author>
<author initials="M" surname="Behringer" fullname="Michael Behringer
" role="editor">
<organization showOnFrontPage="true"/>
</author>
<author initials="S" surname="Bjarnason" fullname="Steinthor Bjarnas
on">
<organization showOnFrontPage="true"/>
</author>
<date month="May" year="2021"/>
</front>
<seriesInfo name="RFC" value="8994"/>
<seriesInfo name="DOI" value="10.17487/RFC8994"/>
</reference>
<reference anchor="RFC8995" target="https://www.rfc-editor.org/info/rfc8
995" quoteTitle="true" derivedAnchor="RFC8995">
<front>
<title>Bootstrapping Remote Secure Key Infrastructure (BRSKI)</title
>
<author initials="M" surname="Pritikin" fullname="Max Pritikin">
<organization showOnFrontPage="true"/>
</author>
<author initials="M" surname="Richardson" fullname="Michael Richards
on">
<organization showOnFrontPage="true"/>
</author>
<author initials="T" surname="Eckert" fullname="Toerless Eckert">
<organization showOnFrontPage="true"/>
</author>
<author initials="M" surname="Behringer" fullname="Michael Behringer
">
<organization showOnFrontPage="true"/>
</author>
<author initials="K" surname="Watsen" fullname="Kent Watsen">
<organization showOnFrontPage="true"/>
</author>
<date month="May" year="2021"/>
</front>
<seriesInfo name="RFC" value="8995"/>
<seriesInfo name="DOI" value="10.17487/RFC8995"/>
</reference>
</references> </references>
</references> </references>
<section anchor="ErrAppx" numbered="true" toc="default"> <section anchor="ErrAppx" numbered="true" toc="include" removeInRFC="false"
<name>Error Codes</name> pn="section-appendix.a">
<t>This Appendix lists the error codes defined so far on the basis of <name slugifiedName="name-error-codes">Error Codes</name>
<t indent="0" pn="section-appendix.a-1">This appendix lists the error code
s defined so far on the basis of
implementation experience, with suggested symbolic names implementation experience, with suggested symbolic names
and corresponding descriptive strings in English. It is expected that comp lete API and corresponding descriptive strings in English. It is expected that comp lete API
implementations will provide for localisation of these descriptive strings , implementations will provide for localization of these descriptive strings ,
and that additional error codes will be needed according to implementation details.</t> and that additional error codes will be needed according to implementation details.</t>
<t>The error codes that may only be returned by one or two functions <t indent="0" pn="section-appendix.a-2">The error codes that may only be r eturned by one or two functions
are annotated accordingly, and the others may be returned by numerous are annotated accordingly, and the others may be returned by numerous
functions. The 'noSecurity' functions. The 'noSecurity'
error will be returned to most calls if GRASP is running in an insecure mo de error will be returned to most calls if GRASP is running in an insecure mo de
(i.e., with no secure substrate such as the ACP), (i.e., with no secure substrate such as the ACP),
except for the specific DULL usage mode described in the section except for the specific DULL usage mode described in
'Discovery Unsolicited Link-Local' of <xref target="I-D.ietf-anima-grasp"/ "Discovery Unsolicited Link-Local (DULL) GRASP" (<xref target="RFC8990" se
>.</t> ction="2.5.2" sectionFormat="of" format="default" derivedLink="https://rfc-edito
<artwork name="" type="" align="left" alt=""><![CDATA[ r.org/rfc/rfc8990#section-2.5.2" derivedContent="RFC8990"/>.</t>
ok 0 "OK" <table anchor="table1_error_codes" align="center" pn="table-1">
declined 1 "Declined" (req_negotiate, negotiate_step) <name slugifiedName="name-error-codes-2">Error Codes</name>
noReply 2 "No reply" (indicates waiting state in <thead>
event loop calls) <tr>
unspec 3 "Unspecified error" <th align="left" colspan="1" rowspan="1">Name</th>
ASAfull 4 "ASA registry full" (register_asa) <th align="left" colspan="1" rowspan="1">Error Code</th>
dupASA 5 "Duplicate ASA name" (register_asa) <th align="left" colspan="1" rowspan="1">Description</th>
noASA 6 "ASA not registered" </tr>
notYourASA 7 "ASA registered but not by you" </thead>
(deregister_asa) <tbody>
notBoth 8 "Objective cannot support both negotiation <tr>
and synchronization" (register_obj) <td align="left" colspan="1" rowspan="1">ok</td>
notDry 9 "Dry-run allowed only with negotiation" <td align="left" colspan="1" rowspan="1">0</td>
(register_obj) <td align="left" colspan="1" rowspan="1">"OK"</td>
notOverlap 10 "Overlap not supported by this implementation" </tr>
(register_obj) <tr>
objFull 11 "Objective registry full" <td align="left" colspan="1" rowspan="1">declined</td>
(register_obj) <td align="left" colspan="1" rowspan="1">1</td>
objReg 12 "Objective already registered" <td align="left" colspan="1" rowspan="1">"Declined" (req_negotiate,
(register_obj) negotiate_step)</td>
notYourObj 13 "Objective not registered by this ASA" </tr>
notObj 14 "Objective not found" <tr>
notNeg 15 "Objective not negotiable" <td align="left" colspan="1" rowspan="1">noReply</td>
(req_negotiate, listen_negotiate) <td align="left" colspan="1" rowspan="1">2</td>
noSecurity 16 "No security" <td align="left" colspan="1" rowspan="1">"No reply" (indicates waiti
noDiscReply 17 "No reply to discovery" ng state in event loop calls)</td>
(req_negotiate) </tr>
sockErrNegRq 18 "Socket error sending negotiation request" <tr>
(req_negotiate) <td align="left" colspan="1" rowspan="1">unspec</td>
noSession 19 "No session" <td align="left" colspan="1" rowspan="1">3</td>
noSocket 20 "No socket" <td align="left" colspan="1" rowspan="1">"Unspecified error"</td>
loopExhausted 21 "Loop count exhausted" (negotiate_step) </tr>
sockErrNegStep 22 "Socket error sending negotiation step" <tr>
(negotiate_step) <td align="left" colspan="1" rowspan="1">ASAfull</td>
noPeer 23 "No negotiation peer" <td align="left" colspan="1" rowspan="1">4</td>
(req_negotiate, negotiate_step) <td align="left" colspan="1" rowspan="1">"ASA registry full" (regist
CBORfail 24 "CBOR decode failure" er_asa)</td>
(req_negotiate, negotiate_step, synchronize) </tr>
invalidNeg 25 "Invalid Negotiate message" <tr>
(req_negotiate, negotiate_step) <td align="left" colspan="1" rowspan="1">dupASA</td>
invalidEnd 26 "Invalid end message" <td align="left" colspan="1" rowspan="1">5</td>
(req_negotiate, negotiate_step) <td align="left" colspan="1" rowspan="1">"Duplicate ASA name" (regis
noNegReply 27 "No reply to negotiation step" ter_asa)</td>
(req_negotiate, negotiate_step) </tr>
noValidStep 28 "No valid reply to negotiation step" <tr>
(req_negotiate, negotiate_step) <td align="left" colspan="1" rowspan="1">noASA</td>
sockErrWait 29 "Socket error sending wait message" <td align="left" colspan="1" rowspan="1">6</td>
(negotiate_wait) <td align="left" colspan="1" rowspan="1">"ASA not registered"</td>
sockErrEnd 30 "Socket error sending end message" </tr>
(end_negotiate, send_invalid) <tr>
IDclash 31 "Incoming request Session ID clash" <td align="left" colspan="1" rowspan="1">notYourASA</td>
(listen_negotiate) <td align="left" colspan="1" rowspan="1">7</td>
notSynch 32 "Not a synchronization objective" <td align="left" colspan="1" rowspan="1">"ASA registered but not by
(synchronize, get_flood) you" (deregister_asa)</td>
notFloodDisc 33 "Not flooded and no reply to discovery" </tr>
(synchronize) <tr>
sockErrSynRq 34 "Socket error sending synch request" <td align="left" colspan="1" rowspan="1">notBoth</td>
(synchronize) <td align="left" colspan="1" rowspan="1">8</td>
noListener 35 "No synch listener" <td align="left" colspan="1" rowspan="1">"Objective cannot support b
(synchronize) oth negotiation
noSynchReply 36 "No reply to synchronization request" and synchronization" (register_obj)</td>
(synchronize) </tr>
noValidSynch 37 "No valid reply to synchronization request" <tr>
(synchronize) <td align="left" colspan="1" rowspan="1">notDry</td>
invalidLoc 38 "Invalid locator" (flood) <td align="left" colspan="1" rowspan="1">9</td>
]]></artwork> <td align="left" colspan="1" rowspan="1">"Dry-run allowed only with
negotiation"
(register_obj)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">notOverlap</td>
<td align="left" colspan="1" rowspan="1">10</td>
<td align="left" colspan="1" rowspan="1">"Overlap not supported by t
his implementation"
(register_obj)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">objFull</td>
<td align="left" colspan="1" rowspan="1">11</td>
<td align="left" colspan="1" rowspan="1">"Objective registry full" (
register_obj)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">objReg</td>
<td align="left" colspan="1" rowspan="1">12</td>
<td align="left" colspan="1" rowspan="1">"Objective already register
ed" (register_obj)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">notYourObj</td>
<td align="left" colspan="1" rowspan="1">13</td>
<td align="left" colspan="1" rowspan="1">"Objective not registered b
y this ASA"</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">notObj</td>
<td align="left" colspan="1" rowspan="1">14</td>
<td align="left" colspan="1" rowspan="1">"Objective not found"</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">notNeg</td>
<td align="left" colspan="1" rowspan="1">15</td>
<td align="left" colspan="1" rowspan="1">"Objective not negotiable"
(req_negotiate, listen_negotiate)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noSecurity</td>
<td align="left" colspan="1" rowspan="1">16</td>
<td align="left" colspan="1" rowspan="1">"No security"</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noDiscReply</td>
<td align="left" colspan="1" rowspan="1">17</td>
<td align="left" colspan="1" rowspan="1">"No reply to discovery" (re
q_negotiate)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">sockErrNegRq</td>
<td align="left" colspan="1" rowspan="1">18</td>
<td align="left" colspan="1" rowspan="1">"Socket error sending negot
iation request" (req_negotiate)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noSession</td>
<td align="left" colspan="1" rowspan="1">19</td>
<td align="left" colspan="1" rowspan="1">"No session"</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noSocket</td>
<td align="left" colspan="1" rowspan="1">20</td>
<td align="left" colspan="1" rowspan="1">"No socket"</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">loopExhausted</td>
<td align="left" colspan="1" rowspan="1">21</td>
<td align="left" colspan="1" rowspan="1">"Loop count exhausted" (neg
otiate_step)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">sockErrNegStep</td>
<td align="left" colspan="1" rowspan="1">22</td>
<td align="left" colspan="1" rowspan="1">"Socket error sending negot
iation step" (negotiate_step)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noPeer</td>
<td align="left" colspan="1" rowspan="1">23</td>
<td align="left" colspan="1" rowspan="1"> "No negotiation peer" (req
_negotiate, negotiate_step)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">CBORfail</td>
<td align="left" colspan="1" rowspan="1">24</td>
<td align="left" colspan="1" rowspan="1">"CBOR decode failure" (req_
negotiate, negotiate_step, synchronize)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">invalidNeg</td>
<td align="left" colspan="1" rowspan="1">25</td>
<td align="left" colspan="1" rowspan="1">"Invalid Negotiate message"
(req_negotiate, negotiate_step)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">invalidEnd</td>
<td align="left" colspan="1" rowspan="1">26</td>
<td align="left" colspan="1" rowspan="1">"Invalid end message" (req_
negotiate, negotiate_step)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noNegReply</td>
<td align="left" colspan="1" rowspan="1">27</td>
<td align="left" colspan="1" rowspan="1">"No reply to negotiation st
ep" (req_negotiate, negotiate_step)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noValidStep</td>
<td align="left" colspan="1" rowspan="1">28</td>
<td align="left" colspan="1" rowspan="1">"No valid reply to negotiat
ion step" (req_negotiate, negotiate_step)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">sockErrWait</td>
<td align="left" colspan="1" rowspan="1">29</td>
<td align="left" colspan="1" rowspan="1">"Socket error sending wait
message" (negotiate_wait)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">sockErrEnd</td>
<td align="left" colspan="1" rowspan="1">30</td>
<td align="left" colspan="1" rowspan="1">"Socket error sending end m
essage" (end_negotiate, send_invalid)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">IDclash</td>
<td align="left" colspan="1" rowspan="1">31</td>
<td align="left" colspan="1" rowspan="1">"Incoming request Session I
D clash" (listen_negotiate)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">notSynch</td>
<td align="left" colspan="1" rowspan="1">32</td>
<td align="left" colspan="1" rowspan="1"> "Not a synchronization obj
ective" (synchronize, get_flood)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">notFloodDisc</td>
<td align="left" colspan="1" rowspan="1">33</td>
<td align="left" colspan="1" rowspan="1">"Not flooded and no reply t
o discovery" (synchronize)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">sockErrSynRq</td>
<td align="left" colspan="1" rowspan="1">34</td>
<td align="left" colspan="1" rowspan="1">"Socket error sending synch
request" (synchronize)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noListener</td>
<td align="left" colspan="1" rowspan="1">35</td>
<td align="left" colspan="1" rowspan="1">"No synch listener" (synchr
onize)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noSynchReply</td>
<td align="left" colspan="1" rowspan="1">36</td>
<td align="left" colspan="1" rowspan="1">"No reply to synchronizatio
n request" (synchronize)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">noValidSynch</td>
<td align="left" colspan="1" rowspan="1">37</td>
<td align="left" colspan="1" rowspan="1">"No valid reply to synchron
ization request" (synchronize)</td>
</tr>
<tr>
<td align="left" colspan="1" rowspan="1">invalidLoc</td>
<td align="left" colspan="1" rowspan="1">38</td>
<td align="left" colspan="1" rowspan="1">"Invalid locator" (flood)</
td>
</tr>
</tbody>
</table>
<section anchor="ack" numbered="false" toc="include" removeInRFC="false" p
n="section-a.1">
<name slugifiedName="name-acknowledgements">Acknowledgements</name>
<t indent="0" pn="section-a.1-1">Excellent suggestions were made by
<contact fullname="Ignas Bagdonas"/>,
<contact fullname="Carsten Bormann"/>,
<contact fullname="Laurent Ciavaglia"/>,
<contact fullname="Roman Danyliw"/>,
<contact fullname="Toerless Eckert"/>,
<contact fullname="Benjamin Kaduk"/>,
<contact fullname="Erik Kline"/>,
<contact fullname="Murray Kucherawy"/>,
<contact fullname="Paul Kyzivat"/>,
<contact fullname="Guangpeng Li"/>,
<contact fullname="Michael Richardson"/>,
<contact fullname="Joseph Salowey"/>,
<contact fullname="Éric Vyncke"/>,
<contact fullname="Magnus Westerlund"/>,
<contact fullname="Rob Wilton"/>,
and other participants in the ANIMA WG and the IESG.</t>
</section>
</section> </section>
<section anchor="changes" numbered="true" toc="default"> <section anchor="authors-addresses" numbered="false" removeInRFC="false" toc
<name>Change log [RFC Editor: Please remove]</name> ="include" pn="section-appendix.b">
<name slugifiedName="name-authors-addresses">Authors' Addresses</name>
<t>draft-ietf-anima-grasp-api-10, 2021-01:</t> <author fullname="Brian E. Carpenter" initials="B." surname="Carpenter">
<ul> <organization abbrev="Univ. of Auckland" showOnFrontPage="true"/>
<li>Closed two final IESG comments</li> <address>
</ul> <postal>
<extaddr>School of Computer Science</extaddr>
<t>draft-ietf-anima-grasp-api-09, 2020-12:</t> <extaddr>University of Auckland</extaddr>
<ul> <street>PB 92019</street>
<li>Added short discussions of CBOR usage and verification.</li> <city>Auckland</city>
<li>Added section on session termination.</li> <region/>
<li>Clarified that integers are uint32 or uint8.</li> <code>1142</code>
<li>Minor technical correction to timeout specification.</li> <country>New Zealand</country>
<li>Clarified sequencing of negotiation messages.</li> </postal>
<li>Minor technical addition to request_negotiate() and synchronize() in e <email>brian.e.carpenter@gmail.com</email>
vent loop model.</li> </address>
<li>Expanded several points in Security Considerations, </author>
including precautions against resource exhaustion.</li> <author fullname="Bing Liu" initials="B." role="editor" surname="Liu">
<li>Other clarifications and minor reorganizations; removed some duplicate <organization showOnFrontPage="true">Huawei Technologies</organization>
d text.</li> <address>
<li>Updated references.</li> <postal>
</ul> <extaddr>Q14, Huawei Campus</extaddr>
<street>No.156 Beiqing Road</street>
<t>draft-ietf-anima-grasp-api-08, 2020-11:</t> <city>Hai-Dian District, Beijing</city>
<ul> <code>100095</code>
<li>Clarified trust model</li> <country>China</country>
<li>Added explanations of GRASP objectives and sessions</li> </postal>
<li>Added note about non-idempotent messages</li> <email>leo.liubing@huawei.com</email>
<li>Added overview of API functions, and annotated each function with a br </address>
ief description</li> </author>
<li>Added protocol diagram for negotiation session</li> <author fullname="Wendong Wang" initials="W." surname="Wang">
<li>Clarified (absence of) authorization model</li> <organization showOnFrontPage="true">BUPT University</organization>
<li>Changed precise semantics of synchronize() for flooded objectives</li> <address>
<li>Clarified caching of flooded objectives</li> <postal>
<li>Changed 'age_limit' to 'minimum_TTL'</li> <extaddr>Beijing University of Posts &amp; Telecom.</extaddr>
<li>Improved security considerations, including DOS precautions</li> <street>No.10 Xitucheng Road</street>
<li>Annotated error codes to indicate which functions generate which error <city>Hai-Dian District, Beijing 100876</city>
s</li> <country>China</country>
<li>Other clarifications from Last Call reviews</li> </postal>
</ul> <email>wdwang@bupt.edu.cn</email>
</address>
<t>draft-ietf-anima-grasp-api-07, 2020-10-13:</t> </author>
<ul><li>Improved diagram and its description</li> <author fullname="Xiangyang Gong" initials="X." surname="Gong">
<li>Added pointer to example logic flows</li> <organization showOnFrontPage="true">BUPT University</organization>
<li>Added note on variable length parameters</li> <address>
<li>Clarified that API decrements loop count automatically</li> <postal>
<li>Other corrections and clarifications from AD review</li> <extaddr>Beijing University of Posts &amp; Telecom.</extaddr>
</ul> <street>No.10 Xitucheng Road</street>
<city>Hai-Dian District, Beijing 100876</city>
<t>draft-ietf-anima-grasp-api-06, 2020-06-07:</t> <country>China</country>
<ul><li>Improved diagram</li> </postal>
<li>Numerous clarifications and layout changes</li> <email>xygong@bupt.edu.cn</email>
</ul> </address>
</author>
<t>draft-ietf-anima-grasp-api-05, 2020-05-08:</t>
<ul><li>Converted to xml2rfc v3</li>
<li>Editorial fixes.</li>
</ul>
<t>draft-ietf-anima-grasp-api-04, 2019-10-07:</t>
<ul><li>Improved discussion of layering, mentioned daemon.</li>
<li>Added callbacks and improved description of asynchronous operations.</
li>
<li>Described use case for 'session_handle'.</li>
<li>More explanation of 'asa_handle'.</li>
<li>Change 'discover' to use 'age_limit' instead of 'flush'.</li>
<li>Clarified use of 'dry run'.</li>
<li>Editorial improvements.</li></ul>
<t>draft-ietf-anima-grasp-api-03, 2019-01-21:</t>
<ul><li>Replaced empty "logic flows" section by "implementation status".</
li>
<li>Minor clarifications.</li>
<li>Editorial improvements.</li></ul>
<t>draft-ietf-anima-grasp-api-02, 2018-06-30:</t>
<ul><li>Additional suggestion for event-loop API.</li>
<li>Discussion of error code values.</li></ul>
<t>draft-ietf-anima-grasp-api-01, 2018-03-03:</t>
<ul><li>Editorial updates</li></ul>
<t>draft-ietf-anima-grasp-api-00, 2017-12-23:</t>
<ul><li>WG adoption</li>
<li>Editorial improvements.</li></ul>
<t>draft-liu-anima-grasp-api-06, 2017-11-24:</t>
<ul><li>Improved description of event-loop model.</li>
<li>Changed intended status to Informational.</li>
<li>Editorial improvements.</li></ul>
<t>draft-liu-anima-grasp-api-05, 2017-10-02:</t>
<ul><li>Added send_invalid()</li></ul>
<t>draft-liu-anima-grasp-api-04, 2017-06-30:</t>
<ul><li>Noted that simple nodes might not include the API.</li>
<li>Minor clarifications.</li></ul>
<t>draft-liu-anima-grasp-api-03, 2017-02-13:</t>
<ul><li>Changed error return to integers.</li>
<li>Required all implementations to accept objective values in CBOR.</li>
<li>Added non-blocking alternatives.</li></ul>
<t>draft-liu-anima-grasp-api-02, 2016-12-17:</t>
<ul><li>Updated for draft-ietf-anima-grasp-09</li></ul>
<t>draft-liu-anima-grasp-api-02, 2016-09-30:</t>
<ul><li>Added items for draft-ietf-anima-grasp-07</li>
<li>Editorial corrections</li></ul>
<t>draft-liu-anima-grasp-api-01, 2016-06-24:</t>
<ul><li>Updated for draft-ietf-anima-grasp-05</li>
<li>Editorial corrections
</li></ul>
<t>draft-liu-anima-grasp-api-00, 2016-04-04:</t>
<ul><li>Initial version</li></ul>
</section> </section>
</back> </back>
</rfc> </rfc>
 End of changes. 249 change blocks. 
1385 lines changed or deleted 2139 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/