| Internet-Draft | yang-edhoc-oscore | February 2023 |
| Marin-Lopez(Ed.), et al. | Expires 1 September 2023 | [Page] |
This document defines YANG data models which allow a Software-Defined Networking (SDN) Controller (Controller) using NETCONF, RESTCONF or CORECONF to provide configuration and monitoring Internet-of-Things devices (Things) that support Ephemeral Diffie-Hellman Over COSE (EDHOC) and/or OSCORE. In particular, a YANG data model defines the required configuration parameters to perform EDHOC between two Things (EDHOC case). Another YANG data model is to configure the OSCORE contexts directly into the Thing (OSCORE case). The service described in this document allows the configuration and monitoring of Things that supports EDHOC and OSCORE or only OSCORE by allowing a protected Thing-to-Thing communication based on CoAP.¶
This document focuses on providing YANG data models for configuring EDHOC or OSCORE. This allows OSCORE establishment with minimal intervention by the network administrator.¶
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 https://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 1 September 2023.¶
Copyright (c) 2023 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 (https://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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Software-Defined Networking (SDN) is an architecture that enables administrators to directly program, orchestrate, control, and manage network resources through software. The SDN paradigm relocates the control of network resources to a centralized entity, namely the SDN Controller (from now on, the Controller). Controllers configure and manage distributed network resources and provide an abstracted view of the network resources to SDN applications. SDN applications can customize and automate the operations (including management) of the abstracted network resources in a programmable manner via this interface [RFC7149] [ITU-T.Y.3300] [ONF-SDN-Architecture] [ONF-OpenFlow].¶
Ephemeral Diffie-Hellman Over COSE (EDHOC, [I-D.ietf-lake-edhoc]) is a very compact and lightweight authenticated key exchange protocol designed for highly constrained devices. The main objective for EDHOC is to be a matching security handshake protocol to Object Security for Constrained RESTful Environments (OSCORE) [RFC8613], i.e., to provide authentication and session key establishment for IoT use cases such as those built on Constrained Application Protocol (CoAP) [RFC7252] involving 'Things' with embedded microcontrollers, sensors, and actuators. EDHOC reuses the same lightweight primitives as Object Security for Constrained RESTful Environments (OSCORE) [RFC8613], Concise Binary Object Representation (CBOR) [RFC8949] and CBOR Object Signing and Encryption (COSE) [RFC9052], and specifies the use of CoAP, but is not bound to a particular transport protocol.¶
OSCORE is a method for application-layer protection (integrity and confidentiality) of CoAP, using COSE. OSCORE provides end-to-end protection between Things communicating using CoAP or CoAP-mappable HTTP.¶
With the growth of SDN-based scenarios where network resources are deployed and managed in an autonomous and dynamic manner, a mechanism to configure EDHOC and OSCORE from a centralized entity (the Controller) may become more relevant in the industry. Nowadays, this security association management has been standardized with IKEv2 and IPsec [RFC9061], even for contrained devices.¶
This document defines two YANG data models for two different cases: EDHOC case, where the Thing supports EDHOC (and OSCORE); and OSCORE case, where the Thing only supports OSCORE and not EDHOC. An external entity, such as the Controller can configure parameters into the EDHOC and/or OSCORE implementation that allow protecting CoAP messages between Things.¶
In summary, the objectives of this document are:¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
As mentioned in Section Section 1, two cases are considered, depending on whether the Thing ships both EDHOC and OSCORE, or only OSCORE: the EDHOC case and the OSCORE case, respectively.¶
In this case, the Thing implements EDHOC and OSCORE. The Controller is in charge of managing and applying EDHOC connection information, determining which Thing will act as EDHOC Initiator or EDHOC responder; identifying the resources to be protected with OSCORE, deriving and delivering EDHOC identities, credentials, etc.) and other EDHOC configuration parameters (e.g., cryptographic algorithms) to the Thing, necessary for EDHOC negotiation.¶
With this information, the EDHOC implementation can operate to establish the OSCORE contexts. The Administrator establishes the general security requirements (through the Northbound Interface), and the Controller translates these requirements into EDHOC configuration that will be installed into the Thing (through the Southbound Interface). With that information, the device can just run EDHOC with other Things to establish OSCORE contexts (when the access to the resource mandates so). Figure 1 shows the different layers and corresponding functionality.¶
To support this case, a YANG data model for EDHOC configuration data and state data needs to be defined for the Southbound Interface (see Section 6).¶
In this case, the Thing does not deploy EDHOC and, therefore, the Controller has to provide the OSCORE contexts and to manage them.¶
As shown in Figure 2, when an Administrator enforces protection policies through the Northbound Interface, the Controller translates these requirements directly into OSCORE contexts, which are installed in the Thing.¶
In order to support the OSCORE case, a YANG data model for OSCORE configuration data and state data MUST be defined for the Southbound Interface (see Section 6). Specifically, the OSCORE case assumes that the Controller has to perform some security functions that EDHOC typically does, specifically the OSCORE context generation and management.¶
In principle, the EDHOC case offloads the Controller the tasks of monitoring, generating and configuring specific OSCORE contexts, including cryptographic material generation. However, the Things require more resources, such as memory for the EDHOC implementation and computation because it involves Diffie-Hellman (DH) exchanges. Beside, if Things run EDHOC, the data plane network traffic between Things increases due to the additional EDHOC protocol exchange, so it should be taken in account in very constrained data plane networks.¶
Alternatively, the OSCORE case may benefit of the deployment in more resource-constrained Things, because EDHOC does not need to be performed between two Things. Additionally, the network data plane is not overloaded with the EDHOC traffic. On the contrary, the complexity of creating and managing OSCORE contexts, including cryptographic material, is shifted to the Controller since EDHOC is not in the Thing. As a consequence, this may result in a more complex implementation in the Controller side in comparison with the EDHOC case. This complexity may create some scalability and performance issues when the number of Things is high.¶
Nevertheless, literature around SDN-based network management using a centralized controller is aware of scalability and performance issues, and solutions have been already provided and discussed (e.g., hierarchical controllers, having multiple replicated controllers, dedicated high-speed management networks, etc.).¶
Another way to reduce the overhead and the potential scalability and performance issues in the Controller is to apply the EDHOC case described in this document since the OSCORE contexts are managed between Things without the involvement of the Controller, except by the initial configuration provided.¶
In terms of security, the EDHOC case provides better security properties than the OSCORE case, as discussed in Section Section 8. The main reason is that the Things generate the session keys and not the Controller.¶
Figure 3 describes the application of the EDHOC case when a CoAP exchange needs to be protected in the path between Thing A and Thing B, and Things support EDHOC and OSCORE:¶
Figure 4 describes the application of the OSCORE case when a CoAP exchange needs to be protected in the path between Thing A and Thing B, and Things support OSCORE, but does not support EDHOC:¶
In this version of the document we have only considered four ways to configure the renewal of the OSCORE contexts. Two of them are possible for the EDHOC case and another two for the OSCORE case.¶
EDHOC case:¶
OSCORE case:¶
Editor's note: Future updates of this document will include extensions to the model to support OSCORE KUDOS. At this point, the model assumes that the Controller is in charge or renewing the OSCORE contexts periodically following an internal policy.¶
Although the architecture described in this document insists on the communication between Things, it is also common the communication between a Thing and a non-so constrained device. Two main situation are envisaged:¶
Initial security setup (bootstrapping) for a Thing refers to any process that takes place before a device can become operational [I-D.irtf-t2trg-secure-bootstrapping]. The initial security setup process, among other processes, involves network discovery and selection, access authentication, configuration of necessary credentials and parameters.¶
Thus, bootstrapping is the process to provide the Thing with the required information (i.e. credentials) to authenticate to the IoT network. We assume that the Thing is preconfigured with the required information and credentials to carry out the bootstrap process. It enables the Thing to run an authenticated registration process with the Controller in order to enable the management in the particular domain under the Controller.¶
The assumption in this document is that, before a Thing can operate in the IoT network, it MUST be registered in the Controller. In this way, when the Thing starts, it establishes a security association with the Controller. This security association, which can be based on DTLS, EDHOC+OSCORE, or only OSCORE, allows the protected exchange of information between the Controller and the Thing. After the bootstrapping process, the Thing is valid for joining the Controller's security domain.¶
The Controller MUST discover certain capabilities of this Thing, such as the supported cryptographic suites, the authentication method, the support of the EDHOC case and/or the OSCORE case, resources, network addressing, etc. This information is incorporated into a list of Things under its control.¶
The registration and discovery processes are out of the scope of this document.¶
If one of the Thing restarts, it may lose the OSCORE state (affected Thing). By default, the Controller can assume that all the state has been lost and, therefore, it will have to send new configuration information for EDHOC to the affected Thing in the EDHOC case, and new OSCORE contexts in the OSCORE case.¶
In both cases, the Controller is aware of the affected Thing (e.g., by using some keep alive mechanism such as the "CoAP Ping" or because the TCP connection is broken with the affected Thing). The Controller keeps a list of Things registered and can determine what are the affected ones.¶
In the EDHOC case, the Controller may need to configure the affected Thing with the new EDHOC information. Alternatively, EDHOC configuration MAY be made permanent between Thing reboots without compromising security by means of non-volatile memory in the Thing. This way, each time an Thing reboots, it will use that configuration for each rebooting. It would imply avoiding contact with the Controller. Finally, the Controller may also need to send new parameters (e.g., a new authentication credentials, etc.) to the Things that had security associations with the affected Thing.¶
In the OSCORE case, the Controller SHOULD delete the old OSCORE contexts in the non-failed Things established with the affected Thing. Once the affected Thing restarts, the Controller MUST take the necessary actions to reestablish the OSCORE contexts between the failed Thing and those others having security associations with the affected one. How the Controller implements an algorithm for managing a potential Thing state loss is out of the scope of this document.¶
In order to support the EDHOC case and the OSCORE case, YANG data models are provided for the different parameters and values that must be configured to manage EDHOC and OSCORE. Specifically, the EDHOC case requires modeling EDHOC configuration parameters such as Thing's identity and authentication information, and when to run EDHOC, besides parameters to define how the OSCORE context should be established. The OSCORE case requires configuration YANG data models for the definition of OSCORE contexts. Two modules have been defined: ietf-core-edhoc (Section 5.2, case EDHOC), and ietf-core-oscore (Section 5.3, case OSCORE).¶
The YANG data model defines the configuration data for EDHOC. The model provides four lists: 'auth-entry', 'connection', 'target resource' and 'local resource'.¶
NOTE: Although EDHOC is independent of OSCORE, the EDHOC model considers the fact that OSCORE will be used after running EDHOC. In any case, the model has incoporated a flag 'set-oscore' when EDHOC is configured and OSCORE is not required (e.g. for example, EDHOC could be used to derive key material to protect the link-layer). Nevertheless, the list of policies ('target-resource' and 'local-resource') defined in the model only considered the case when the access with CoAP to a particular URI is required. To include additional uses cases this policy should be extended to consider, for example, MAC addresses or IP addresses (TBD).¶
The detailed YANG module for the EDHOC case is described in Appendix A.¶
Appendix B shows an example of an EDHOC case configuration.¶
This version includes the YANG data model taking into account the information in OSCORE. The model contains three main lists: 'context', 'target-resource', 'local-resource'.¶
The detailed YANG module for the EDHOC case is described in Appendix C.¶
Appendix D shows an example of an EDHOC case configuration.¶
First of all, this document shares all the security issues of SDN that are specified in the Security Considerations sections of [ITU-T.Y.3300] and [RFC7426].¶
On the one hand, it is important to note that there MUST exist a security association providing confidentiality and integrity between the Controller and the Things to protect the critical information (cryptographic keys, configuration parameter, etc.) exchanged between these entities. The nature of and means to create that security association is out of the scope of this document (i.e., it is part of device provisioning or bootstrapping).¶
On the other hand, the default policy MUST be to drop (DISCARD) CoAP messages to prevent information leaks. This default policy MUST be preconfigured in the non-volatile memory in the Thing before the Thing contacts the Controller. Moreover, the non-volatile memory MUST be also preconfigured with the required ALLOW policies that allow the Thing and the Controller to communicate each other. This preconfiguration step is not carried out by the Controller but by some other entity before the Thing deployment. In this manner, when the Thing starts/reboots, it will always first apply the configuration in the non-volatile memory before contacting the Controller.¶
Finally, this section is divided in two parts in order to analyze different security considerations for both cases: Thing with EDHOC+OSCORE (EDHOC case) and Thing without EDHOC (OSCORE case). In general, the Controller, as typically happens in the SDN paradigm, is a target for different type of attacks, see [SDNSecServ] and [SDNSecurity]. Thus, the Controller is a key entity in the infrastructure and MUST be protected accordingly. In particular, the Controller will handle cryptographic material; thus, the attacker may try to access this information. The impact is different depending on the EDHOC case or the OSCORE case.¶
In the EDHOC case, the Controller MAY send EDHOC credentials (public/private keys, certificates, etc.) to the Things using the security association between the Controller and Things. The Controller MUST NOT store the EDHOC credentials after distributing them. Moreover, the Controller MUST NOT allow the reading of these values once they have been applied into the Thing (i.e., write-only operations). One option is to always return the same value (i.e., all 0s) if a read operation is carried out.¶
If the attacker has access to the Controller during the period of time that key material is generated, it might have access to the key material. Since these values are used during authentication in EDHOC, it may impersonate the affected Things. Several recommendations are important:¶
In the OSCORE case, the Controller sends the OSCORE contexts that includes the session keys required for integrity and encryption. The Controller MUST NOT store these keys after distributing them. Moreover, the Thing receiving the OSCORE context MUST NOT allow the reading of these keys by any other entity (including the Controller itself) once they have been applied (i.e., write-only operations) into the Thing. Nevertheless, if the attacker has access to the Controller during the period of time that key material is generated, it may obtain these values. In other words, the attacker might be able to observe the CoAP traffic and decrypt, or even modify and re-encrypt, the CoAP exchanges between Things.¶
Finally, the security association between the Controller and the Things MUST provide, at least, the same degree of protection as the one achieved by the session keys used in the OSCORE contexts. In particular, the security association between the Controller and the Things MUST provide forward secrecy if this property is to be achieved in the OSCORE contexts that the Controller configures into the Things. Similarly, the encryption algorithms used in the security association between the Controller and the Things MUST have, at least, the same strength (minimum strength of a 128-bit key) as the algorithms used to establish the OSCORE contexts.¶
module ietf-core-edhoc {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-core-edhoc";
prefix edhoc;
import ietf-inet-types {
prefix inet;
reference
"RFC 6991: Common YANG Data Types.";
}
import ietf-netconf-acm {
prefix nacm;
reference
"RFC 8341: Network Configuration Access Control
Model.";
}
organization
"IETF CORE Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/core/>
WG List: <mailto:core@ietf.org>
Author: Rafael Marin-Lopez
<mailto:rafa@um.es>
Author: Gabriel Lopez-Millan
<mailto:gabilm@um.es>
";
description
"This module contains the EDHOC Case YANG model for the
SDN-based Key Management for EDHOC.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this
document are to be interpreted as described in BCP 14
(RFC 2119) (RFC 8174) when, and only when, they appear
in all capitals, as shown here.
Copyright (c) 2021 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
revision 2022-11-28 {
description
"Initial version. The YANG data model defines the
configuration data for EDHOC. The model provides four lists
'auth-entry', 'connection', 'target resource' and 'local
resource'.
The list 'auth-entry' contains a
set of nodes that contain authentication information for
EDHOC run for this local Thing.
The list 'connection' contains a set of nodes that specifies
different connections between this Thing and a peer Thing.
This list specifies what credentials will be used for the
local Thing (with a
reference to an entry in the list 'auth-entry' and the
credential that will be required to authenticate the remote
Thing).
The list 'target-resource' stores policies
(bypass,discard,protect) related with the target resource
that this Thing can access. In case of protection, a node in
the list has a reference to a node in the list 'connection'
to run EDHOC.
The list 'local-resource' stores policies related with the
local resources provided by this Thing.";
reference
".";
}
typedef auth-method-t {
type enumeration {
enum signature-key {
description
"Authentication Key is a Signature Key.";
}
enum static-dh-key {
description
"Authentication Key is a Static DH Key.";
}
}
description
"The authentication method can include Signature Key or
Static Diffie-Hellman Key.";
}
typedef policy-t {
type enumeration {
enum protect {
description
"PROTECT the traffic with OSCORE.";
}
enum bypass {
description
"The CoAP resource does not require
OSCORE protection";
}
enum discard {
description
"The CoAP message to a resource is
discarded.";
}
}
description
"The policy applicable to access a CoAP resource.
There are three possible values: BYPASS
(the CoAP message is unprotected), PROTECT
(the CoAP message MUST be protected with OSCORE),
and DISCARD (the CoAP message is discarded).";
}
grouping auth-cred-grouping {
leaf id-cred-x {
type binary;
mandatory true;
description
"ID_CRED_X, X=I or R.
COSE header maps and contains one or more
COSE header parameters";
}
leaf auth-method {
type auth-method-t;
default "signature-key";
description
"Type of authentication method
(signature key, static DH key).";
}
leaf cred-x {
type binary;
mandatory true;
description
"X.509 certificates [RFC5280], C509 certificates
[I-D.ietf-cose-cbor-encoded-cert], CWTs [RFC8392]
and CWT Claims Sets (CCS) [RFC8392]. Static DH Public
and RPK are also included here. If this information is
associated to the other peer , it contains the information
required to verify the Signature_or_MAC field.";
}
description
"This grouping contains the ID_CRED_X for a particular
entity X=I or X=R and authentication method and the public
information of the CRED_X information about the
authentication credential";
} /*grouping auth-cred-grouping*/
container edhoc {
description
"EDHOC configuration for a Thing. It includes authentication
credentials for this Thing. EDHOC connection information that
is a represented with a list of 'connection'. Each connection
contains information about the remote EDHOC peer and the
information to authentication against that node.";
list auth-entry {
key "name";
ordered-by user;
description
"Authentication information entry for the Thing.
It is a list of entries ordered by the
Controller, and each entry is
unequivocally identified by a name.";
leaf name {
type string;
description
"Unique name to identify this entry.";
}
uses auth-cred-grouping;
leaf private-key {
nacm:default-deny-all;
type binary;
mandatory true;
description
"The private key used for this auth-entry associated to
the public key contained in the Authentication
Credential. This value can be set either by the
Controller or the node can generate it so that
it is not known by the Controller.";
}
} /*list auth-entry*/
list connection {
key "name";
ordered-by user;
description
"List of connections defined between and the Thing A
(local peer) and B (remote peer). The list is ordered
by the Controller, and each entry is
unequivocally identified by a name.";
leaf name {
type string;
description
"Unique name to identify this entry.";
}
container local {
leaf autostartup {
type boolean;
default 'false';
description
"True: the EDHOC implementation starts immediately
after setting the configuration of this connection.";
}
leaf auth-cred-ref {
type string;
mandatory true;
description
"Local peer authentication information.
This node points to a specific entry in
the list 'auth-entry' where the authentication
information about this peer is stored.
It MUST match a 'name' in the list.";
}
leaf c-x {
type binary;
description
"Connection identifier. This value is optional since,
in general, the connection identifier can be generated
by the node.";
}
leaf suites-x {
type binary;
description
"Array of cipher suites which the peer acting as
Initiator or Responder supports. In case the node acts
as Initiator (X=I) the array is in order of preference,
the first cipher suite in network byte order is the
most preferred by the Initiator, the last is the one
selected by the Initiator for this session. The order
of the cipher suites in SUITES_R has no significance.
If the most preferred cipher suite is selected then
SUITES_I contains only that cipher suite and is encoded
as an int. Since the controller has information
about the nodes in the connection can set the suitable
cipher suite to avoid any crypto suite negotiation.";
}
container ead-x {
leaf ead-a {
type binary;
description
"This value contains the EAD 1 when the peer acts
as the initiator or EAD 2 when it is the responder.";
}
leaf ead-b {
type binary;
description
"This value is EAD 3 when the peer is the initiator
or EAD 4 when it is the responder.";
}
description "To set the EAD in EDHOC (if any).";
}
description
"Local node authentication information.";
} /*container local*/
container remote {
uses auth-cred-grouping;
description
"Remote node authentication information.";
} /*container remote*/
leaf key-confirmation {
type boolean;
default 'false';
description
"True: message 4 will be sent (if the node is acting as
initiator or it has to be received is if the initiator)";
}
leaf set-oscore {
type boolean;
default 'true';
description
"True when after EDHOC we require to establish an
OSCORE Security Context.";
}
leaf key-update-context {
type binary;
description
"The controller sets a context so that EDHOC-KeyUpdate
can be performed. Each time this value is update the
EDHOC-KeyUpdate is performed.";
reference
"Appendix I. Ephemeral Diffie-Hellman Over COSE (EDHOC)
draft-ietf-lake-edhoc-19.";
}
container reauth-time {
leaf soft {
type uint32;
units "seconds";
default "0";
description
"Soft lifetime. After reaching this time the EDHOC
re-authentication will start.";
}
leaf hard {
type uint32;
units "seconds";
default "0";
description
"Hard lifetime. After reaching this time the EDHOC
session will be removed.";
}
description ".";
} /*container reauth-time*/
} /* list connection */
list target-resource {
description
"This list contains the resources that this peer
(acting as CoAP client) will access and that requires
OSCORE protection (depending on the policy) in the other
peer (acting as a CoAP server). They may be discovered by
some other means by the Thing but installing them allows
the device to protect immediately the CoAP
message. The list is ordered by the controller. An node in
the list is evaluated before the next node in the list.
If there is a match the evaluation is stopped and the
policy applied. That is nodes at the beginning of the list
has more priority that final nodes.";
key "target";
ordered-by user;
leaf target {
type inet:uri;
description
"URI to the target resource to be protected with this
OSCORE Sender Context. If the URI is an empty string it
means ANY";
}
leaf policy {
type policy-t;
default 'protect';
description
"The policy applied to this resource. Default policy is
protect. If there is no common context to protect the
CoAP message is discarded. If the list is empty is not
possible to access to any resource.";
}
leaf conn-ref {
when "../policy = 'protect'";
type string;
description
"Byte string used to identify the connection in the list
'connection' that must be used to protect this message.
The Thing will act as EDHOC initiator. If the EDHOC
session is already set and cryptographic material is
available the message will be protected.";
}
} /*list target-resources*/
list local-resource {
description
"This list contains the resources that may require
protection (depending of the policy) in this peer (acting
as a CoAP server).";
key "local";
ordered-by user;
leaf local {
type inet:uri;
description
"URI of the local resources to be protected with
this OSCORE Recipient Context.";
}
leaf policy {
type policy-t;
default 'protect';
description
"The policy applied to this resource. Default policy is
protect. If there is no common context to protect the
CoAP message is discarded.";
}
leaf conn-ref {
when "../policy = 'protect'";
type string;
description
"Byte string used to identify the connection in the list
'connection' that must be used to protect this resource.
The Thing will act as EDHOC responder. If the EDHOC
session is already set and cryptographic material
is available the message will be protected.";
}
} /*list local-resource*/
} /* container edhoc */
} /* module ietf-core-edhoc */
¶
This example shows an XML representation of the configuration sent by the SDN Controller to establish an EDHOC-derived OSCORE context to Thing 't1' using "signature-key" authentication (RSA) when accessing the resource "coap://2001:db8:cafe:123::200/res1". (Some values are simplified for brevity with "base64encodedvalue==").¶
module ietf-core-oscore {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-core-oscore";
prefix oscore;
import ietf-inet-types {
prefix inet;
reference
"RFC 6991: Common YANG Data Types.";
}
import ietf-netconf-acm {
prefix nacm;
reference
"RFC 8341: Network Configuration Access Control
Model.";
}
organization
"IETF CORE Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/core/>
WG List: <mailto:core@ietf.org>
Author: Rafael Marin-Lopez
<mailto:rafa@um.es>
Author: Gabriel Lopez-Millan
<mailto:gabilm@um.es>
";
description
"Data model for OSCORE case (RFC 8613) in the SDN-based
OSCORE flow protection service.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this
document are to be interpreted as described in BCP 14
(RFC 2119) (RFC 8174) when, and only when, they appear
in all capitals, as shown here.
Copyright (c) 2021 IETF Trust and the persons
identified as authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD
License set forth in Section 4.c of the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of ; see
the RFC itself for full legal notices.";
revision 2022-11-28 {
description
"Initial version. This version only includes the YANG Data
model taking into account the information in Object
Security for Constrained RESTful Environments (OSCORE).
The model contains three main lists: context,
targer-resource and local-resource.
The list 'context' stores the OSCORE context in this
Thing. Each node in the list 'context' contains three
contexts: common ('common-ctx'), sender ('sender-ctx') and
recipient ('recipient-ctx') contexts.
The list 'target-resource' stores policies (bypass,
discard, protect) related with the target resource that
this Thing can access'. In case of protection, a node in
the list has a reference to a node in the list 'context'.
The list 'local-resource' stores policies related with the
local resources provided by this Thing.";
reference ".";
}
typedef policy-t {
type enumeration {
enum protect {
description
"PROTECT the traffic with OSCORE.";
}
enum bypass {
description
"The CoAP resource does not require
OSCORE protection";
}
enum discard {
description
"The CoAP message to a resource is
discarded.";
}
}
description
"The policy applicable to access a CoAP resource. There
are three possible values: BYPASS (the CoAP message is
unprotected), PROTECT (the CoAP message MUST be
protected with OSCORE), and DISCARD (The CoAP message
is discarded).";
}
container oscore {
description
"Container for configuration of the OSCORE
case. The container contains a list of OSCORE contexts.
Each node of the list contains three possible contexts.
Common Context, Sender Context and Recipient Context. The
Controller configures at least the Common Context and
configure a Sender Context or a Recipient Context or
both.";
list context {
key "id-entry";
ordered-by user;
leaf id-entry {
type binary;
description
"Unique name to identify this entry.";
}
container common-ctx {
description
"This container carries the
configuration of an OSCORE Common Context.";
leaf id {
type binary;
default 0x00;
description
"Optional variable-length byte string providing
additional information to identify the Common
Context and to derive AEAD keys and Common IV. The
use of ID Context is described in Section 5.1 in RFC
8613";
}
leaf aead-alg {
type uint32;
default "10";
description
"The COSE AEAD algorithm to use for encryption.";
}
leaf hkdf-alg {
type uint32;
default "1";
description
"An HMAC-based key derivation function (HKDF,
[RFC5869]) used to derive the Sender Key, Recipient
Key, and Common IV.";
}
leaf master-key {
nacm:default-deny-all;
type binary;
description
"Variable length, random byte string (see
Section 12.3) in RFC 8613 used to derive AEAD keys
and Common IV.";
}
leaf master-salt {
nacm:default-deny-all;
type binary;
description
"Optional variable-length byte string
containing the salt used to derive AEAD
keys and Common IV.";
}
} /*container common-ctx*/
container sender-ctx {
description
"This container carries the
configuration of an OSCORE Sender Context.";
leaf id {
type binary;
default 0x00;
description
"Byte string used to identify the Sender Context,
to derive AEAD keys and Common IV, and to
contribute to the uniqueness of AEAD nonces.
Maximum length is determined by the AEAD
Algorithm.";
}
} /*container sender-ctx*/
container recipient-ctx {
description
"This container carries the
configuration of an OSCORE Recipient Context.";
leaf id {
type binary;
default 0x01;
description
"Byte string used to identify the Recipient
Context, to derive AEAD keys and Common IV, and to
contribute to the uniqueness of AEAD nonces.
Maximum length is determined by the
AEAD Algorithm.";
}
leaf replay-window {
type uint64;
default "32";
description
"To set the anti-replay window size.
The default value is set to 32,
following the recommendation in RFC 8613.";
reference
"RFC 8613: Object Security for Constrained
RESTful Environments (OSCORE),
Section 3.2.2.";
}
} /*container recipient-ctx*/
container renew-ctx {
description
"This container includes information to update the
OSCORE contexts.";
choice method {
default sdn-based;
case multiple-times {
container ctx-derivation {
leaf r1-length {
type uint64;
default 8;
description
"R1 length.";
}
leaf r2-length {
type uint64;
default 8;
description
"R2 length.";
}
leaf r3-length {
type uint64;
default 8;
description
"R3 length.";
}
description
"This container allow configuring the required
information so that the security context
derivation in Appendix B.2 is implemented. The
Controller is in charge of providing the length
of R1, R2 and R3. If a node is acting as
initiator in this procedure, R1 and R3 lengths
are defined. If it is acting as responder R2
length applies.";
reference
"Appendix B.2 Security Context Derived Multiple
Times - RFC 8613";
} /*container ctx-derivation*/
description
"Appendix B.2. protocol in RFC 8613 is used to
renew OSCORE context.";
} /*case multiple-times*/
case sdn-based {
leaf sdn-based {
type empty;
description
"The OSCORE context is updated by the Controller.";
}
description
"The Controller manages the OSCORE renewal time
and update the contexts when it decides so.";
} /*case sdn-based*/
description
"Different methods to update OSCORE context according
to RFC 8613 and this document.";
} /*choice method*/
} /*container renew-ctx*/
description
"The OSCORE contexts is represented as a list of OSCORE
context entries, where each entry contains a OSCORE
common context, sender context and recipient context
associated to the OSCORE common context.";
} /*list contexts*/
list target-resource {
description
"This list contains the resources that this peer (acting
as CoAP client) will access and that requires OSCORE
protection (depending on the policy) in the other peer
(acting as a CoAP server). They may be discovered by
some other means by the Thing but installing them allows
the device to protect immediately the CoAP message. The
list is ordered by the Controller. A node in the list is
evaluated before the next node in the list. If there is
a match the evaluation is stopped and the policy
applied. That is nodes at the beginning of the list has
more priority that final nodes.";
key "target";
ordered-by user;
leaf target {
type inet:uri;
description
"URI to the target resource to be protected with this
OSCORE Sender Context. If the URI is an empty string
it means ANY";
}
leaf policy {
type policy-t;
default 'protect';
description
"The policy applied to this resource. Default policy
is protect. If there is no common context to protect
the CoAP message is discarded. If the list is empty is
not possible to access to any resource.";
}
leaf id-entry-ref {
when "../policy = 'protect'";
type binary;
description
"Byte string used to identify the context in the list
'context' that will be used for this target source.";
}
} /*list target-resources*/
list local-resource {
description
"This list contains the resources that may require
OSCORE protection (depending of the policy) in this peer
(acting as a CoAP server).";
key "local";
ordered-by user;
leaf local {
type inet:uri;
description
"URI of the local resources to be protected with this
OSCORE Recipient Context.";
}
leaf policy {
type policy-t;
default 'protect';
description
"The policy applied to this resource. Default policy
is protect. If there is no common context to protect
the CoAP message is discarded.";
}
leaf id-entry-ref {
when "../policy = 'protect'";
type binary;
description
"Byte string used to identify the context in the list
'context' that will be used for this local source.";
}
} /*list local-resources*/
} /*container oscore*/
} /*module ietf-core-oscore */
¶
This example shows an XML representation of the configuration sent by the SDN Controller to establish an OSCORE context to Thing 't1' using "signature-key" authentication (RSA) when accessing the resource "coap://2001:db8:cafe:123::200/res1". (Some values are simplified for brevity with "base64encodedvalue==").¶
Authors want to thank¶