Host Identity Protocol (HIP) Registration Extension
RFC 5203
| Document | Type |
RFC
- Experimental
(April 2008)
Obsoleted by RFC 8003
|
|
|---|---|---|---|
| Authors | Teemu Koponen , Lars Eggert , Julien Laganier | ||
| Last updated | 2015-10-14 | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Additional resources | Mailing list discussion | ||
| IESG | Responsible AD | Mark Townsley | |
| Send notices to | (None) |
RFC 5203
Network Working Group A. Bierman
Internet-Draft YumaWorks
Intended status: Standards Track M. Bjorklund
Expires: May 13, 2017 Tail-f Systems
K. Watsen
Juniper Networks
November 9, 2016
YANG Patch Media Type
draft-ietf-netconf-yang-patch-13
Abstract
This document describes a method for applying patches to
configuration datastores using data defined with the YANG data
modeling language.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 13, 2017.
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) 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
Bierman, et al. Expires May 13, 2017 [Page 1]
Internet-Draft YANG Patch November 2016
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.3. YANG . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.4. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 5
1.1.5. YANG Patch . . . . . . . . . . . . . . . . . . . . . 5
1.1.6. Examples . . . . . . . . . . . . . . . . . . . . . . 5
1.1.7. Tree Diagram Notations . . . . . . . . . . . . . . . 6
2. YANG Patch . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Target Resource . . . . . . . . . . . . . . . . . . . . . 7
2.2. yang-patch Request . . . . . . . . . . . . . . . . . . . 8
2.3. yang-patch-status Response . . . . . . . . . . . . . . . 9
2.4. Target Data Node . . . . . . . . . . . . . . . . . . . . 10
2.5. Edit Operations . . . . . . . . . . . . . . . . . . . . . 11
2.6. Successful Edit Response Handling . . . . . . . . . . . . 11
2.7. Error Handling . . . . . . . . . . . . . . . . . . . . . 11
2.8. yang-patch RESTCONF Capability . . . . . . . . . . . . . 12
3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 12
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
4.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 21
4.2. Media Types . . . . . . . . . . . . . . . . . . . . . . . 21
4.2.1. Media Type application/yang-patch+xml . . . . . . . . 21
4.2.2. Media Type application/yang-patch+json . . . . . . . 23
4.3. RESTCONF Capability URNs . . . . . . . . . . . . . . . . 25
5. Security Considerations . . . . . . . . . . . . . . . . . . . 25
6. Normative References . . . . . . . . . . . . . . . . . . . . 26
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 27
B.1. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . 27
B.2. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . 27
B.3. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . 28
B.4. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . 28
B.5. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . 28
B.6. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . 29
B.7. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . 29
B.8. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 29
B.9. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 29
B.10. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 30
B.11. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 30
B.12. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 30
B.13. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 30
B.14. bierman:yang-patch-00 to ietf:yang-patch-00 . . . . . . . 31
Bierman, et al. Expires May 13, 2017 [Page 2]
Internet-Draft YANG Patch November 2016
Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 31
Appendix D. Example YANG Module . . . . . . . . . . . . . . . . 31
D.1. YANG Patch Examples . . . . . . . . . . . . . . . . . . . 32
D.1.1. Add Resources: Error . . . . . . . . . . . . . . . . 32
D.1.2. Add Resources: Success . . . . . . . . . . . . . . . 36
D.1.3. Insert list entry example . . . . . . . . . . . . . . 38
D.1.4. Move list entry example . . . . . . . . . . . . . . . 40
D.1.5. Edit datastore resource example . . . . . . . . . . . 41
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43
1. Introduction
There is a need for standard mechanisms to patch datastores defined
in [RFC6241], which contain conceptual data that conforms to schema
specified with YANG [RFC7950]. An "ordered edit list" approach is
needed to provide RESTCONF client developers with more precise
RESTCONF client control of the edit procedure than existing
mechanisms found in [I-D.ietf-netconf-restconf].
This document defines a media type for a YANG-based editing mechanism
that can be used with the HTTP PATCH method [RFC5789]. YANG Patch is
designed to support the RESTCONF protocol, defined in
[I-D.ietf-netconf-restconf]. This document only specifies the use of
the YANG Patch media type with the RESTCONF protocol.
It may be possible to use YANG Patch with other protocols besides
RESTCONF. This is outside the scope of this document. For any
protocol which supports the YANG Patch media type, if the entire
patch document cannot be successfully applied, then the server MUST
NOT apply any of the changes. It may be possible to use YANG Patch
with datastore types other than a configuration datastore. This is
outside the scope of this document.
1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
1.1.1. NETCONF
The following terms are defined in [RFC6241]:
o configuration data
o datastore
o configuration datastore
Bierman, et al. Expires May 13, 2017 [Page 3]
Internet-Draft YANG Patch November 2016
o protocol operation
o running configuration datastore
o state data
o user
1.1.2. HTTP
The following terms are defined in [RFC7230]:
o header field
o message-body
o query
o request URI
The following terms are defined in [RFC7231]:
o method
o request
o resource
1.1.3. YANG
The following terms are defined in [RFC7950]:
o container
o data node
o leaf
o leaf-list
o list
o RPC operation (now called protocol operation)
Bierman, et al. Expires May 13, 2017 [Page 4]
Internet-Draft YANG Patch November 2016
1.1.4. RESTCONF
The following terms are defined in [I-D.ietf-netconf-restconf]:
o application/yang-data+xml
o application/yang-data+json
o data resource
o datastore resource
o patch
o RESTCONF capability
o target resource
o YANG data template
1.1.5. YANG Patch
The following terms are used within this document:
o RESTCONF client: a client which implements the RESTCONF protocol.
o RESTCONF server: a server which implements the RESTCONF protocol.
o YANG Patch: a conceptual edit request using the "yang-patch" YANG
Patch template, defined in Section 3. In HTTP, refers to a PATCH
method where a representation uses either the media type
"application/yang-patch+xml" or "application/yang-patch+json".
o YANG Patch Status: a conceptual edit status response using the
YANG "yang-patch-status" YANG data template, defined in Section 3.
In HTTP, refers to a response message for a PATCH method, where it
has a representation with either the media type "application/
yang-data+xml" or "application/yang-data+json".
o YANG Patch template: this is similar to a YANG data template,
except it has a representation with the media type "application/
yang-patch+xml" or "application/yang-patch+json".
1.1.6. Examples
Some protocol message lines within examples throughout the document
are split into multiple lines for display purposes only. When a line
ends with backslash ('\') as the last character, the line is wrapped
Bierman, et al. Expires May 13, 2017 [Page 5]
Internet-Draft YANG Patch November 2016quot; in this
document are to be interpreted as described in RFC 2119 [RFC2119].
Laganier, et al. Experimental [Page 1]
RFC 5203 HIP Registration Extension April 2008
2. Terminology
In addition to the terminology defined in the HIP Architecture
[RFC4423], the HIP specification [RFC5201], and the HIP Rendezvous
Extension [RFC5204], this document defines and uses the following
terms:
Requester:
a HIP node registering with a HIP registrar to request
registration for a service.
Registrar:
a HIP node offering registration for one or more services.
Service:
a facility that provides requesters with new capabilities or
functionalities operating at the HIP layer. Examples include
firewalls that support HIP traversal or HIP rendezvous servers.
Registration:
shared state stored by a requester and a registrar, allowing the
requester to benefit from one or more HIP services offered by the
registrar. Each registration has an associated finite lifetime.
Requesters can extend established registrations through re-
registration (i.e., perform a refresh).
Registration Type:
an identifier for a given service in the registration protocol.
For example, the rendezvous service is identified by a specific
registration type.
3. HIP Registration Extension Overview
This document does not specify the means by which a requester
discovers the availability of a service, or how a requester locates a
registrar. After a requester has discovered a registrar, it either
initiates HIP base exchange or uses an existing HIP association with
the registrar. In both cases, registrars use additional parameters,
which the remainder of this document defines, to announce their
quality and grant or refuse registration. Requesters use
corresponding parameters to register with the service. Both the
registrar and the requester MAY also include in the messages
exchanged additional HIP parameters specific to the registration type
implicated. Other documents will define parameters and how they
shall be used. The following sections describe the differences
between this registration handshake and the standard HIP base
exchange [RFC5201].
Laganier, et al. Experimental [Page 2]
RFC 5203 HIP Registration Extension April 2008
3.1. Registrar Announcing Its Ability
A host that is capable and willing to act as a registrar SHOULD
include a REG_INFO parameter in the R1 packets it sends during all
base exchanges. If it is currently unable to provide services due to
transient conditions, it SHOULD include an empty REG_INFO, i.e., one
with no services listed. If services can be provided later, it
SHOULD send UPDATE packets indicating the current set of services
available in a new REG_INFO parameter to all hosts it is associated
with.
3.2. Requester Requesting Registration
To request registration with a service, a requester constructs and
includes a corresponding REG_REQUEST parameter in an I2 or UPDATE
packet it sends to the registrar.
If the requester has no HIP association established with the
registrar, it SHOULD send the REG_REQUEST at the earliest
possibility, i.e., in the I2 packet. This minimizes the number of
packets that need to be exchanged with the registrar. A registrar
MAY end a HIP association that does not carry a REG_REQUEST by
including a NOTIFY with the type REG_REQUIRED in the R2. In this
case, no HIP association is created between the hosts. The
REG_REQUIRED notification error type is 51.
3.3. Registrar Granting or Refusing Service(s) Registration
Once registration has been requested, the registrar is able to
authenticate the requester based on the host identity included in I2.
It then verifies that the host identity is authorized to register
with the requested service(s), based on local policies. The details
of this authorization procedure depend on the type of requested
service(s) and on the local policies of the registrar, and are
therefore not further specified in this document.
After authorization, the registrar includes a REG_RESPONSE parameter
in its response, which contains the service type(s) for which it has
authorized registration, and zero or more REG_FAILED parameters
containing the service type(s) for which it has not authorized
registration or registration has failed for other reasons. This
response can be either an R2 or an UPDATE message, respectively,
depending on whether the registration was requested during the base
exchange, or using an existing association. In particular,
REG_FAILED with a failure type of zero indicates the service(s)
type(s) that require further credentials for registration.
Laganier, et al. Experimental [Page 3]
RFC 5203 HIP Registration Extension April 2008
If the registrar requires further authorization and the requester has
additional credentials available, the requester SHOULD try to
register again with the service after the HIP association has been
established. The precise means of establishing and verifying
credentials are beyond the scope of this document and are expected to
be defined in other documents.
Successful processing of a REG_RESPONSE parameter creates
registration state at the requester. In a similar manner, successful
processing of a REG_REQUEST parameter creates registration state at
the registrar and possibly at the service. Both the requester and
registrar can cancel a registration before it expires, if the
services afforded by a registration are no longer needed by the
requester, or cannot be provided any longer by the registrar (for
instance, because its configuration has changed).
+-----+ I1 +-----+-----+
| |--------------------->| | S1 |
| |<---------------------| | |
| | R1(REG_INFO:S1,S2) | +-----+
| RQ | | R | S2 |
| | I2(REG_REQ:S1) | | |
| |--------------------->| +-----+
| |<---------------------| | S3 |
| | R2(REG_RESP:S1) | | |
+-----+ +-----+-----+
A requester (RQ) registers with a registrar (R) of services (S1) and
(S2), with which it has no current HIP association.
+-----+ +-----+-----+
| | UPDATE(REG_INFO:S) | | |
| |<---------------------| | |
| RQ |--------------------->| R | S |
| | UPDATE(REG_REQ:S) | | |
| | UPDATE(REG_RESP:S) | | |
| |<---------------------| | |
+-----+ +-----+-----+
A requester (RQ) registers with a registrar (R) of services (S), with
which it currently has a HIP association established.
Laganier, et al. Experimental [Page 4]
RFC 5203 HIP Registration Extension April 2008
4. Parameter Formats and Processing
This section describes the format and processing of the new
parameters introduced by the HIP registration extension.
4.1. Encoding Registration Lifetimes with Exponents
The HIP registration uses an exponential encoding of registration
lifetimes. This allows compact encoding of 255 different lifetime
values ranging from 4 ms to 178 days into an 8-bit integer field.
The lifetime exponent field used throughout this document MUST be
interpreted as representing the lifetime value 2^((lifetime - 64)/8)
seconds.
4.2. REG_INFO
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Min Lifetime | Max Lifetime | Reg Type #1 | Reg Type #2 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ... | ... | Reg Type #n | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Padding +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Type 930
Length Length in octets, excluding Type, Length, and Padding.
Min Lifetime Minimum registration lifetime.
Max Lifetime Maximum registration lifetime.
Reg Type The registration types offered by the registrar.
Other documents will define specific values for registration types.
See Section 7 for more information.
Registrars include the parameter in R1 packets in order to announce
their registration capabilities. The registrar SHOULD include the
parameter in UPDATE packets when its service offering has changed.
HIP_SIGNATURE_2 protects the parameter within the R1 packets.
Laganier, et al. Experimental [Page 5]
RFC 5203 HIP Registration Extension April 2008
4.3. REG_REQUEST
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Lifetime | Reg Type #1 | Reg Type #2 | Reg Type #3 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ... | ... | Reg Type #n | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Padding +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Type 932
Length Length in octets, excluding Type, Length, and Padding.
Lifetime Requested registration lifetime.
Reg Type The preferred registration types in order of preference.
Other documents will define specific values for registration types.
See Section 7 for more information.
A requester includes the REG_REQUEST parameter in I2 or UPDATE
packets to register with a registrar's service(s). If the
REG_REQUEST parameter is in an UPDATE packet, the registrar MUST NOT
modify the registrations of registration types that are not listed in
the parameter. Moreover, the requester MUST NOT include the
parameter unless the registrar's R1 packet or latest received UPDATE
packet has contained a REG_INFO parameter with the requested
registration types.
The requester MUST NOT include more than one REG_REQUEST parameter in
its I2 or UPDATE packets, while the registrar MUST be able to process
one or more REG_REQUEST parameters in received I2 or UPDATE packets.
When the registrar receives a registration with a lifetime that is
either smaller or greater than the minimum or maximum lifetime,
respectively, then it SHOULD grant the registration for the minimum
or maximum lifetime, respectively.
HIP_SIGNATURE protects the parameter within the I2 and UPDATE
packets.
Laganier, et al. Experimental [Page 6]
RFC 5203 HIP Registration Extension April 2008
4.4. REG_RESPONSE
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Lifetime | Reg Type #1 | Reg Type #2 | Reg Type #3 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ... | ... | Reg Type #n | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Padding +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Type 934
Length Length in octets, excluding Type, Length, and Padding.
Lifetime Granted registration lifetime.
Reg Type The granted registration types in order of preference.
Other documents will define specific values for registration types.
See Section 7 for more information.
The registrar SHOULD includes an REG_RESPONSE parameter in its R2 or
UPDATE packet only if a registration has successfully completed.
The registrar MUST NOT include more than one REG_RESPONSE parameter
in its R2 or UPDATE packets, while the requester MUST be able to
process one or more REG_RESPONSE parameters in received R2 or UPDATE
packets.
The requester MUST be prepared to receive any registration lifetime,
including ones beyond the minimum and maximum lifetime indicated in
the REG_INFO parameter. It MUST NOT expect that the returned
lifetime will be the requested one, even when the requested lifetime
falls within the announced minimum and maximum.
HIP_SIGNATURE protects the parameter within the R2 and UPDATE
packets.
Laganier, et al. Experimental [Page 7]
RFC 5203 HIP Registration Extension April 2008
4.5. REG_FAILED
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Failure Type | Reg Type #1 | Reg Type #2 | Reg Type #3 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ... | ... | Reg Type #n | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Padding +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Type 936
Length Length in octets, excluding Type, Length, and Padding.
Failure Type Reason for failure.
Reg Type The registration types that failed with the specified
reason.
Failure Type Reason
------------ --------------------------------------------
0 Registration requires additional credentials
1 Registration type unavailable
2-200 Unassigned
201-255 Reserved by IANA for private use
Other documents will define specific values for registration types.
See Section 7 for more information.
A failure type of zero means a registrar requires additional
credentials to authorize a requester to register with the
registration types listed in the parameter. A failure type of one
means that the requested service type is unavailable at the
registrar. Failure types other than zero (0) and one (1) have not
been defined.
The registrar SHOULD include the REG_FAILED parameter in its R2 or
UPDATE packet, if registration with the registration types listed has
not completed successfully and a requester is asked to try again with
additional credentials.
HIP_SIGNATURE protects the parameter within the R2 and UPDATE
packets.
for display purposes. It is to be considered to be joined to the
next line by deleting the backslash, the following line break, and
the leading whitespace of the next line.
1.1.7. Tree Diagram Notations
A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these diagrams is as
follows:
o Brackets "[" and "]" enclose list keys.
o Abbreviations before data node names: "rw" means configuration
data (read-write), "ro" state data (read-only), and "x" operation
resource (executable)
o Symbols after data node names: "?" means an optional node and "*"
denotes a "list" and "leaf-list".
o Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":").
o Ellipsis ("...") stands for contents of subtrees that are not
shown.
2. YANG Patch
A "YANG Patch" is an ordered list of edits that are applied to the
target datastore by the RESTCONF server. The specific fields are
defined in the YANG module in Section 3.
The YANG Patch operation is invoked by the RESTCONF client by sending
a PATCH method request with a representation using either the
"application/yang-patch+xml" or "application/yang-patch+json" media
type. This message-body representing the YANG Patch input parameters
MUST be present.
YANG Patch has some features that are not possible with the PATCH
method in RESTCONF:
o YANG Patch allows multiple sub-resources to be edited within the
same PATCH method.
o YANG Patch allows more precise edit operations than RESTCONF.
There are 7 operations supported (create, delete, insert, merge,
move, replace, remove).
Bierman, et al. Expires May 13, 2017 [Page 6]
Internet-Draft YANG Patch November 2016
o YANG Patch uses an edit list with an explicit processing order.
The edits are processed in client-specified order, and error
processing can be precise even when multiple errors occur in the
same patch request.
The YANG Patch "patch-id" may be useful for debugging, and SHOULD be
present in any audit audit logging records generated by the RESTCONF
server for a patch.
The RESTCONF server MUST return the Accept-Patch header field in an
OPTIONS response, as specified in [RFC5789], which includes the media
type for YANG Patch. This is needed by a client to determine the
message encoding formats supported by the server (e.g., XML, JSON, or
both). An example is shown in Figure 1.
Accept-Patch: application/yang-patch+xml,application/yang-patch+json
Figure 1: Example Accept-Patch header
Note that YANG Patch can only edit data resources. The PATCH method
cannot be used to replace the datastore resource. Although the
"ietf-yang-patch" YANG module is written using YANG version 1.1
[RFC7950], an implementation of YANG Patch can be used with content
defined in YANG version 1 [RFC6020] as well.
A YANG Patch can be encoded in XML format according to
[W3C.REC-xml-20081126]. It can also be encoded in JSON, according to
"JSON Encoding of Data Modeled with YANG" [RFC7951]. If any meta-
data needs to be sent in a JSON message, it is encoded according to
"Defining and Using Metadata with YANG" [RFC7952].
2.1. Target Resource
The YANG Patch operation uses the RESTCONF target resource URI to
identify the resource that will be patched. This can be the
datastore resource itself, i.e., "{+restconf}/data", to edit top-
level configuration data resources, or it can be a configuration data
resource within the datastore resource, e.g., "{+restconf}/data/
ietf-interfaces:interfaces", to edit sub-resources within a top-level
configuration data resource.
The target resource MUST identify exactly one resource instance. If
more than one resource instance is identified, then the request MUST
NOT be processed, and a "400 Bad Request" error response MUST be sent
by the server. If the target resource does not identify any existing
resource instance then the request MUST NOT be processed, and a "404
Not Found" error response MUST be sent by the server.
Bierman, et al. Expires May 13, 2017 [Page 7]
Internet-Draft YANG Patch November 2016
Each edit with a YANG Patch identifies a target data node for the
associated edit. This is described in Section 2.4.
2.2. yang-patch Request
A YANG patch is optionally identified by a unique "patch-id" and it
may have an optional comment. A patch is an ordered collection of
edits. Each edit is identified by an "edit-id" and it has an edit
operation (create, delete, insert, merge, move, replace, remove) that
is applied to the target resource. Each edit can be applied to a
sub-resource "target" within the target resource. If the operation
is "insert" or "move", then the "where" parameter indicates how the
node is inserted or moved. For values "before" and "after", the
"point" parameter specifies the data node insertion point.
The merge, replace, create, delete, and remove edit operations have
the exact same meaning as defined for the "operation" attribute in
section 7.2 of [RFC6241].
Each edit within a YANG Patch MUST identify exactly one data resource
instance. If an edit represents more than one resource instance,
then the request MUST NOT be processed, and a "400 Bad Request" error
response MUST be sent by the server. If the edit does not identify
any existing resource instance, and the operation for the edit is not
"create", then the request MUST NOT be processed, and a "404 Not
Found" error response MUST be sent by the server. A
"yang-patch-status" response MUST be sent by the server identifying
the edit(s) that are not valid.
YANG Patch does not provide any access to specific datastores. It is
an implementation detail how a server processes an edit if it is co-
located with a NETCONF server that does provide access to individual
datastores. A complete datastore cannot be replaced in the same
manner as provided by the "copy-config" operation defined in section
7.3 of [RFC6241]. Only the specified nodes in a YANG Patch are
affected.
A message-body representing the YANG Patch is sent by the RESTCONF
client to specify the edit operation request. When used with the
HTTP PATCH method, this data is identified by the YANG Patch media
type.
YANG tree diagram for "yang-patch" Container
Bierman, et al. Expires May 13, 2017 [Page 8]
Internet-Draft YANG Patch November 2016
+---- yang-patch
+---- patch-id string
+---- comment? string
+---- edit* [edit-id]
+---- edit-id string
+---- operation enumeration
+---- target target-resource-offset
+---- point? target-resource-offset
+---- where? enumeration
+---- value?
2.3. yang-patch-status Response
A message-body representing the YANG Patch Status is returned to the
RESTCONF client to report the detailed status of the edit operation.
When used with the HTTP PATCH method, this data is identified by the
YANG Patch Status media type, and the syntax specification is defined
in Section 3.
YANG tree diagram for "yang-patch-status" Container:
Bierman, et al. Expires May 13, 2017 [Page 9]
Internet-Draft YANG Patch November 2016
Laganier, et al. Experimental [Page 8]
RFC 5203 HIP Registration Extension April 2008
5. Establishing and Maintaining Registrations
Establishing and/or maintaining a registration may require additional
information not available in the transmitted REG_REQUEST or
REG_RESPONSE parameters. Therefore, registration type definitions
MAY define dependencies for HIP parameters that are not defined in
this document. Their semantics are subject to the specific
registration type specifications.
The minimum lifetime both registrars and requesters MUST support is
10 seconds, while they SHOULD support a maximum lifetime of 120
seconds, at least. These values define a baseline for the
specification of services based on the registration system. They
were chosen to be neither too short nor too long, and to accommodate
for existing timeouts of state established in middleboxes (e.g., NATs
and firewalls.)
A zero lifetime is reserved for canceling purposes. Requesting a
zero lifetime for a registration type is equal to canceling the
registration of that type. A requester MAY cancel a registration
before it expires by sending a REG_REQ to the registrar with a zero
lifetime. A registrar SHOULD respond and grant a registration with a
zero lifetime. A registrar (and an attached service) MAY cancel a
registration before it expires, at its own discretion. However, if
it does so, it SHOULD send a REG_RESPONSE with a zero lifetime to all
registered requesters.
6. Security Considerations
This section discusses the threats on the HIP registration protocol,
and their implications on the overall security of HIP. In
particular, it argues that the extensions described in this document
do not introduce additional threats to HIP.
The extensions described in this document rely on the HIP base
exchange and do not modify its security characteristics, e.g.,
digital signatures or HMAC. Hence, the only threat introduced by
these extensions is related to the creation of soft registration
state at the registrar.
Registrars act on a voluntary basis and are willing to accept being a
responder and then to create HIP associations with a number of
previously unknown hosts. Because they have to store HIP association
state anyway, adding a certain amount of time-limited HIP
registration state should not introduce any serious additional
threats, especially because HIP registrars may cancel registrations
at any time at their own discretion, e.g., because of resource
constraints during an attack.
Laganier, et al. Experimental [Page 9]
RFC 5203 HIP Registration Extension April 2008
7. IANA Considerations
This section is to be interpreted according to the Guidelines for
Writing an IANA Considerations Section in RFCs [RFC2434].
This document updates the IANA Registry for HIP Parameter Types by
assigning new HIP Parameter Types values for the new HIP Parameters
defined in this document:
o REG_INFO (defined in Section 4.2)
o REG_REQUEST (defined in Section 4.3)
o REG_RESPONSE (defined in Section 4.4)
o REG_FAILED (defined in Section 4.5)
IANA has allocated the Notify Message Type code 51 for the
REG_REQUIRED notification error type in the Notify Message Type
registry.
IANA has opened a new registry for registration types. This document
does not define registration types but makes the following
reservations:
Reg Type Service
-------- -------
0-200 Unassigned
201-255 Reserved by IANA for private use
Adding a new type requires new IETF specifications.
IANA has opened a new registry for registration failure types. This
document makes the following failure type definitions and
reservations:
Failure Type Reason
------------ --------------------------------------------
0 Registration requires additional credentials
1 Registration type unavailable
2-200 Unassigned
201-255 Reserved by IANA for private use
Adding a new type requires new IETF specifications.
Laganier, et al. Experimental [Page 10]
RFC 5203 HIP Registration Extension April 2008
8. Acknowledgments
The following people (in alphabetical order) have provided thoughtful
and helpful discussions and/or suggestions that have helped to
improve this document: Jeffrey Ahrenholz, Miriam Esteban, Mika Kousa,
Pekka Nikander, and Hannes Tschofenig.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 2434,
October 1998.
[RFC5201] Moskowitz, R., Nikander, P., Jokela, P., Ed., and T.
Henderson, "Host Identity Protocol", RFC 5201, April 2008.
9.2. Informative References
[RFC3234] Carpenter, B. and S. Brim, "Middleboxes: Taxonomy and
Issues", RFC 3234, February 2002.
[RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol
(HIP) Architecture", RFC 4423, May 2006.
[RFC5204] Laganier, J. and L. Eggert, "Host Identity Protocol (HIP)
Rendezvous Extension", RFC 5204, April 2008.
Laganier, et al. Experimental [Page 11]
RFC 5203 HIP Registration Extension April 2008
Authors' Addresses
Julien Laganier
DoCoMo Communications Laboratories Europe GmbH
Landsberger Strasse 312
Munich 80687
Germany
Phone: +49 89 56824 231
EMail: julien.ietf@laposte.net
URI: http://www.docomolab-euro.com/
Teemu Koponen
Helsinki Institute for Information Technology
Advanced Research Unit (ARU)
P.O. Box 9800
Helsinki FIN-02015-HUT
Finland
Phone: +358 9 45 1
EMail: teemu.koponen@iki.fi
URI: http://www.hiit.fi/
Lars Eggert
Nokia Research Center
P.O. Box 407
Nokia Group 00045
Finland
Phone: +358 50 48 24461
EMail: lars.eggert@nokia.com
URI: http://research.nokia.com/people/lars_eggert/
Laganier, et al. Experimental [Page 12]
RFC 5203 HIP Registration Extension April 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Laganier, et al. Experimental [Page 13]