CORE Working Group R. Marin-Lopez(Ed.) Internet-Draft G. Lopez-Millan Intended status: Standards Track University of Murcia Expires: 1 September 2023 L. Toutain A. Fernandez IMT 28 February 2023 A YANG data model for SDN-based key management with EDHOC and OSCORE draft-marin-yang-edhoc-oscore-00 Abstract 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. 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 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. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 1] Internet-Draft yang-edhoc-oscore February 2023 Copyright Notice 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4 3. SDN-based key management for EDHOC and OSCORE . . . . . . . . 4 3.1. EDHOC Case: EDHOC+OSCORE in the Things . . . . . . . . . 4 3.2. OSCORE case: only OSCORE in the Things . . . . . . . . . 5 4. EDHOC case vs OSCORE case . . . . . . . . . . . . . . . . . . 6 5. Entities interaction . . . . . . . . . . . . . . . . . . . . 7 5.1. EDHOC case overview . . . . . . . . . . . . . . . . . . . 7 5.2. OSCORE case overview . . . . . . . . . . . . . . . . . . 9 5.3. Renewal of the OSCORE security context . . . . . . . . . 11 5.4. Thing to non constrained devices communication . . . . . 12 5.5. Thing bootstrapping, registration and discovery . . . . . 12 5.6. Thing state loss . . . . . . . . . . . . . . . . . . . . 13 6. YANG Data Models . . . . . . . . . . . . . . . . . . . . . . 14 6.1. EDHOC case . . . . . . . . . . . . . . . . . . . . . . . 14 6.1.1. Data model overview . . . . . . . . . . . . . . . . . 14 6.1.2. YANG module . . . . . . . . . . . . . . . . . . . . . 16 6.1.3. Example usage . . . . . . . . . . . . . . . . . . . . 16 6.2. OSCORE case . . . . . . . . . . . . . . . . . . . . . . . 16 6.2.1. YANG module . . . . . . . . . . . . . . . . . . . . . 17 6.2.2. Example usage . . . . . . . . . . . . . . . . . . . . 17 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 8.1. EDHOC case . . . . . . . . . . . . . . . . . . . . . . . 18 8.2. OSCORE case . . . . . . . . . . . . . . . . . . . . . . . 19 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 9.1. Normative References . . . . . . . . . . . . . . . . . . 20 9.2. Informative References . . . . . . . . . . . . . . . . . 20 Appendix A. YANG data model for EDHOC case . . . . . . . . . . . 22 Appendix B. EDHOC case example usage . . . . . . . . . . . . . . 32 Appendix C. YANG data model for OSCORE case . . . . . . . . . . 33 Appendix D. OSCORE case example usage . . . . . . . . . . . . . 41 Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 2] Internet-Draft yang-edhoc-oscore February 2023 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 42 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 1. Introduction 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. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 3] Internet-Draft yang-edhoc-oscore February 2023 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: * To describe the architecture for SDN-based key management for EDHOC and OSCORE, which allows the establishment and management of OSCORE contexts from the Controller in order to protect specific CoAP exchanges in a Thing-to-Thing communication. * To define the interfaces required to manage and monitor EDHOC and OSCORE in the Thing from an SDN Controller. YANG data models are defined for configuration and state data for EDHOC and OSCORE. The YANG data models can be used via existing protocols, such as the Network Configuration Protocol (NETCONF) [RFC6241], RESTCONF [RFC8040], or CORECONF [I-D.ietf-core-comi] (RECOMMENDED). Thus, this document defines two YANG modules (see Section Section 6) but does not define any new protocol. 2. Conventions and Definitions 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. 3. SDN-based key management for EDHOC and OSCORE 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. 3.1. EDHOC Case: EDHOC+OSCORE in the Things 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. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 4] Internet-Draft yang-edhoc-oscore February 2023 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. +-------------------------------------------+ | Key Management System | Administrator +-------------------------------------------+ | Northbound | Interface +-------------------------------------------+ | EDHOC Configuration | SDN | Generation | Controller +-------------------------------------------+ | Southbound | Interface (CORECONF,RESTCONF,...) +-------------------------------------------+ | EDHOC | Thing |-------------------------------------------| | OSCORE | +-------------------------------------------+ Figure 1: EDHOC Case: EDHOC+OSCORE in the Thing 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). 3.2. OSCORE case: only OSCORE in the Things 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. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 5] Internet-Draft yang-edhoc-oscore February 2023 +-----------------------------------------+ | Key Management System | Administrator +-----------------------------------------+ | Northbound | Interface +-----------------------------------------+ | OSCORE | SDN | contexts generation | Controller +---------------------------------s--------+ | Southbound | Interface (CORECONF,RESTCONF,...) | +-----------------------------------------+ | OSCORE | Thing |-----------------------------------------| Figure 2: OSCORE Case: only OSCORE (No EDHOC) 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. 4. EDHOC case vs OSCORE case 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. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 6] Internet-Draft yang-edhoc-oscore February 2023 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. 5. Entities interaction 5.1. EDHOC case overview 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: Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 7] Internet-Draft yang-edhoc-oscore February 2023 +----------------------------------------+ | Key Management System | +----------------------------------------+ | (1) Security Northbound Protection Policy Interface | +---------|-------------------------------+ | | | | | Controller | | V | | +---------------+ (2) +--------------+ | | |Translate into |---->| CORECONF/ | | | |EDHOC Conf | | RESTCONF | | | +---------------+ +--------------+ | | | | | +-------------------------|-----|---------+ Southbound | | Interface | | | (3) | |----------------------+ +---| V V +----------------+ (4) EDHOC +----------------+ | EDHOC |<--------------->| EDHOC | | OSCORE | (5)CoAP+OSCORE | OSCORE | | CoAP Client | --------------> | CoAP Server | +----------------+ +----------------+ Thing A Thing B Figure 3: EDHOC case overview 1. The network administrator establishes the general security protection policies, including security policies for protecting resources between A and B. The Controller looks for the involved Things (A and B). 2. The Controller translates these policies into EDHOC configuration for the specific Things (connection identifiers, authentication credentials, cipher suites, authorization data, etc.), following the requirements described in [I-D.ietf-lake-edhoc][I-D.ietf-core-oscore-edhoc]. 3. The Controller sends these EDHOC configurations to both Thing A and Thing B. Due to one may have the role of EDHOC responder (e.g. Thing B) and the other the role of EDHOC initiator (e.g. Thing A), it is advised to send configurations first to the EDHOC responder and, once it is successfully finished, to the EDHOC initiator. If some of the operations described above fail (e.g., Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 8] Internet-Draft yang-edhoc-oscore February 2023 Things A reports an error when the Controller is trying to install the EDHOC configuration), the Controller MAY perform a rollback operation by deleting any previous EDHOC configuration that had been successfully installed in the other Thing (e.g. Thing B) and stop the process. Note that the Controller MAY retry several times before giving up. NOTE: It is assumed that a security association has been previously setup between the Controller and each Thing. 4. If the previous steps are successful, the EDHOC initiator can start the EDHOC exchange. It is worth noting that EDHOC may be started by the initiator either only when the traffic need to be protected or just after the EDHOC configuration is applied in the Thing, instructed by the Controller. 1. After completion of the EDHOC exchange, OSCORE contexts are created in Things A and B, and the CoAP traffic can be protected. Finally, the Controller may associate a lifetime to renew OSCORE contexts, as described in Section 5.3. 5.2. OSCORE case overview 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: Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 9] Internet-Draft yang-edhoc-oscore February 2023 +----------------------------------------+ | Key Management System | +----------------------------------------+ | (1) Security Northbound Protection Policy Interface | +---------|-------------------------------+ | | | | | Controller | | V | | +---------------+ (2) +--------------+ | | |Translate into |---->| CORECONF/ | | | |OSCORE Contexts| | RESTCONF | | | +---------------+ +--------------+ | | | | | +-------------------------|-----|---------+ Southbound | | Interface | | | (3) | |----------------------+ +---| V V +----------------+ +----------------+ | OSCORE | (4)CoAP+OSCORE | OSCORE | | CoAP Client |<--------------->| CoAP Server | +----------------+ +----------------+ Thing A Thing B Figure 4: OSCORE case overview 1. The network administrator establishes the general security protection policies, including security policies for protecting resources between A and B. The Controller looks for the involved Things (A and B). 2. The Controller translates these policies into specific OSCORE contexts (Common, Sender and Recipient) for the specific CoAP service. Following the requirements described in [RFC8613]. It generates the cryptographic keys and salts using random values. 3. The Controller sends these OSCORE contexts to both Thing A and Thing B. Due to one may have the role of CoAP server (e.g. Thing B) and the other the role of CoAP client (e.g. Thing A), it is advised to send the contexts first to the CoAP server and, once it is successfully finished, to send the contexts to the CoAP client. If some of the operations described above fail (e.g., Things A reports an error when the Controller is trying to install the OSCORE contexts), the Controller MAY perform a Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 10] Internet-Draft yang-edhoc-oscore February 2023 rollback operation by deleting any OSCORE context that had been successfully installed in the other Thing (e.g. Thing B) and stop the process. Note that the Controller MAY retry several times before giving up. 4. If the steps 1 to 3 are successful, the CoAP exchanges between Thing A and Thing B are protected with OSCORE. It is worth mentioning that the Controller associates a lifetime to the new OSCORE contexts. When this lifetime expires, the Controller will update the OSCORE contexts. 5.3. Renewal of the OSCORE security context 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 contexts are renewed after a full EDHOC re-run. The Controller can configure the Thing to perform the EDHOC re-run each certain time (reauth time). - An SDN-based renewal where the Controller sends a context to the Things used for the EDHOC_KeyUpdate (Appendix I in [I-D.ietf-lake-edhoc]). With this context, the Things can call EDHOC_KeyUpdate to generate a new PRK and, therefore, new keys for the OSCORE context. * OSCORE case: - An SDN-based renewal where the Controller is in charge of sending new OSCORE contexts periodically following an internal policy (e.g. each 8 hours). The cryptographic material generated for the OSCORE contexts is completely fresh and separated from previous contexts. - The mechanism explained in OSCORE [RFC8613] (section B.2. Security Context Derived Multiple Times) where the Controller only sets the length of the nonces R1, R2, and R3 in each Thing. 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. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 11] Internet-Draft yang-edhoc-oscore February 2023 5.4. Thing to non constrained devices communication 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: * If both entities (the Thing and the non-so constrained device) are under the management of the Controller. The solution described here applies with no change. The only comment here is that the protocol for carrying the configuration to the non-so constrained device can be less constrained (e.g. NETCONF or RESTCONF). * Only the Thing is managed by the Controller, then it is assumed that the non-so constrained device is configured somehow (out of scope this document) and the Controller only configures the Thing to communicate securely with this non-so constrained device. The YANG data models are still applicable in this case. 5.5. Thing bootstrapping, registration and discovery 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. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 12] Internet-Draft yang-edhoc-oscore February 2023 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. 5.6. Thing state loss 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. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 13] Internet-Draft yang-edhoc-oscore February 2023 6. YANG Data Models 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). 6.1. EDHOC case 6.1.1. Data model overview 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 leafs that contain authentication information for running EDHOC in this Thing (such as Thing credential identity, preferred authentication method and public and private key credentials). Each Thing may be configured with several 'auth-entry' elements. Each element in the list may be used by one or more 'connections' defined to other Things. * The list 'connection' contains a list of containers and leafs that specifies different connections between this Thing (local) and a peer (remote), for example, another Thing. This list specifies the local credentials that will be used for this Thing with the remote peer (with a reference to an entry in the list 'auth- entry'), and the credentials that will be required to authenticate the remote peer. For the local Thing, it also specifies the connection identifier, cipher suites, and authorization data depending on the role defined by this Thing (EDHOC initiator or responder). Additionally, other EDHOC parameters may be defined, such as EDHOC key confirmation option, the automatically establishment of an OSCORE context between local and remote Things, or rekey management options and lifetimes. * The list 'target-resource' stores policies (bypass, discard, protect) related with the target resource (URI) that this Thing can access. In case OSCORE protection is required, an entry in this list defines a reference to a list 'connection' entry to run EDHOC. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 14] Internet-Draft yang-edhoc-oscore February 2023 * The list 'local-resource' stores policies related with the local resources provided by this Thing. module: ietf-core-edhoc +--rw edhoc +--rw auth-entry* [name] | +--rw name string | +--rw id-cred-x binary | +--rw auth-method? auth-method-t | +--rw cred-x binary | +--rw private-key binary +--rw connection* [name] | +--rw name string | +--rw local | | +--rw autostartup? boolean | | +--rw auth-cred-ref string | | +--rw c-x? binary | | +--rw suites-x? binary | | +--rw ead-x | | +--rw ead-a? binary | | +--rw ead-b? binary | +--rw remote | | +--rw id-cred-x binary | | +--rw auth-method? auth-method-t | | +--rw cred-x binary | +--rw key-confirmation? boolean | +--rw set-oscore? boolean | +--rw key-update-context? binary | +--rw reauth-time | +--rw soft? uint32 | +--rw hard? uint32 +--rw target-resource* [target] | +--rw target inet:uri | +--rw policy? policy-t | +--rw conn-ref? string +--rw local-resource* [local] +--rw local inet:uri +--rw policy? policy-t +--rw conn-ref? string Figure 5: EDHOC data model tree 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- Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 15] Internet-Draft yang-edhoc-oscore February 2023 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). 6.1.2. YANG module The detailed YANG module for the EDHOC case is described in Appendix A. 6.1.3. Example usage Appendix B shows an example of an EDHOC case configuration. 6.2. OSCORE case 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 list 'context' stores the OSCORE contexts in this Thing. Each node in the list 'context' contains three specific contexts: common ('common-ctx'), sender ('sender-ctx') and recipient ('recipient-ctx'). 'common-ctx' defines the common context ID, authentication encryption algorithms, key derivation function, master key and master salt used by this OSCORE context. 'sender- ctx' defines the sender context ID, and 'recipient-ctx' defines the recipient context ID and the replay-window value, as described in [RFC8613]. For each OSCORE context this container also defines how the context renew has to be carried out by the Things. As described in section Section 5.3, two options are included in this model, SDN-based and OSCORE-based. * The list 'target-resource' stores policies (bypass,discard,protect) related with the target resource that this Thing can access. In case of protection with OSCORE, 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, acting as server of a particular resource. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 16] Internet-Draft yang-edhoc-oscore February 2023 module: ietf-core-oscore +--rw oscore +--rw context* [id-entry] | +--rw id-entry binary | +--rw common-ctx | | +--rw id? binary | | +--rw aead-alg? uint32 | | +--rw hkdf-alg? uint32 | | +--rw master-key? binary | | +--rw master-salt? binary | +--rw sender-ctx | | +--rw id? binary | +--rw recipient-ctx | | +--rw id? binary | | +--rw replay-window? uint64 | +--rw renew-ctx | +--rw (method)? | +--:(multiple-times) | | +--rw ctx-derivation | | +--rw r1-length? uint64 | | +--rw r2-length? uint64 | | +--rw r3-length? uint64 | +--:(sdn-based) | +--rw sdn-based? empty +--rw target-resource* [target] | +--rw target inet:uri | +--rw policy? policy-t | +--rw id-entry-ref? binary +--rw local-resource* [local] +--rw local inet:uri +--rw policy? policy-t +--rw id-entry-ref? binary Figure 6: OSCORE data model tree 6.2.1. YANG module The detailed YANG module for the EDHOC case is described in Appendix C. 6.2.2. Example usage Appendix D shows an example of an EDHOC case configuration. 7. IANA Considerations TBD Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 17] Internet-Draft yang-edhoc-oscore February 2023 8. Security Considerations 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. 8.1. EDHOC 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. Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 18] Internet-Draft yang-edhoc-oscore February 2023 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 EDHOC case, the Controller MAY generate both public key and private key for the authentication process. In such a case, the Controller MUST remove the associated private key immediately after distributing them to the Things. * Alternatively, the Thing MAY generate the private key and export only the public key to the Controller. How the Thing generates these cryptographic materials (public key/ private keys) and exports the public key is out of scope of this document. * If certificates are used, the Thing MAY generate the private key and export the public key for certification to the Controller. How the Thing generates these cryptographic material (public key/ private keys) and exports the public key is out of scope of this document. 8.2. OSCORE case 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. 9. References Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 19] Internet-Draft yang-edhoc-oscore February 2023 9.1. Normative References [I-D.ietf-core-comi] Veillette, M., Van der Stok, P., Pelov, A., Bierman, A., and I. Petrov, "CoAP Management Interface (CORECONF)", Work in Progress, Internet-Draft, draft-ietf-core-comi-11, 17 January 2021, . [I-D.ietf-core-oscore-edhoc] Palombini, F., Tiloca, M., Höglund, R., Hristozov, S., and G. Selander, "Profiling EDHOC for CoAP and OSCORE", Work in Progress, Internet-Draft, draft-ietf-core-oscore-edhoc- 06, 23 November 2022, . [I-D.ietf-lake-edhoc] Selander, G., Mattsson, J. P., and F. Palombini, "Ephemeral Diffie-Hellman Over COSE (EDHOC)", Work in Progress, Internet-Draft, draft-ietf-lake-edhoc-19, 3 February 2023, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, . 9.2. Informative References [I-D.ietf-cose-cbor-encoded-cert] Mattsson, J. P., Selander, G., Raza, S., Höglund, J., and M. Furuhed, "CBOR Encoded X.509 Certificates (C509 Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 20] Internet-Draft yang-edhoc-oscore February 2023 Certificates)", Work in Progress, Internet-Draft, draft- ietf-cose-cbor-encoded-cert-05, 10 January 2023, . [I-D.irtf-t2trg-secure-bootstrapping] Sethi, M., Sarikaya, B., and D. Garcia-Carrillo, "Terminology and processes for initial security setup of IoT devices", Work in Progress, Internet-Draft, draft- irtf-t2trg-secure-bootstrapping-03, 26 November 2022, . [ITU-T.Y.3300] "Y.3300:Framework of software-defined networking", June 2014, . [ONF-OpenFlow] "OpenFlow Switch Specification, Version 1.4.1 (Wire Protocol 0x05)", March 2015, . [ONF-SDN-Architecture] "SDN architecture, Issue 1", June 2014, . [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, . [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand Key Derivation Function (HKDF)", RFC 5869, DOI 10.17487/RFC5869, May 2010, . [RFC7149] Boucadair, M. and C. Jacquenet, "Software-Defined Networking: A Perspective from within a Service Provider Environment", RFC 7149, DOI 10.17487/RFC7149, March 2014, . [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, . Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 21] Internet-Draft yang-edhoc-oscore February 2023 [RFC7426] Haleplidis, E., Ed., Pentikousis, K., Ed., Denazis, S., Hadi Salim, J., Meyer, D., and O. Koufopavlou, "Software- Defined Networking (SDN): Layers and Architecture Terminology", RFC 7426, DOI 10.17487/RFC7426, January 2015, . [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018, . [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, December 2020, . [RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, August 2022, . [RFC9061] Marin-Lopez, R., Lopez-Millan, G., and F. Pereniguez- Garcia, "A YANG Data Model for IPsec Flow Protection Based on Software-Defined Networking (SDN)", RFC 9061, DOI 10.17487/RFC9061, July 2021, . [SDNSecServ] Scott-Hayward, S., Callaghan, G. O., and P. Sezer, "SDN Security A Survey", November 2013, . [SDNSecurity] Kreutz, D., Ramos, F., and P. Verissimo, "Towards secure and dependable software-defined networks", August 2013, . Appendix A. YANG data model for EDHOC case module ietf-core-edhoc { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-core-edhoc"; prefix edhoc; import ietf-inet-types { Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 22] Internet-Draft yang-edhoc-oscore February 2023 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: WG List: Author: Rafael Marin-Lopez Author: Gabriel Lopez-Millan "; 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 { Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 23] Internet-Draft yang-edhoc-oscore February 2023 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."; Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 24] Internet-Draft yang-edhoc-oscore February 2023 } 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; Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 25] Internet-Draft yang-edhoc-oscore February 2023 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 Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 26] Internet-Draft yang-edhoc-oscore February 2023 "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 Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 27] Internet-Draft yang-edhoc-oscore February 2023 "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."; Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 28] Internet-Draft yang-edhoc-oscore February 2023 } /*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 "."; Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 29] Internet-Draft yang-edhoc-oscore February 2023 } /*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."; Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 30] Internet-Draft yang-edhoc-oscore February 2023 } } /*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 */ Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 31] Internet-Draft yang-edhoc-oscore February 2023 Appendix B. EDHOC case example usage 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=="). +------------------+ | SDN Controller | +------------------+ Southbound | Interface | /-----------------+---------------\ / \ / \ +--------+ +--------+ | t1 |======= EDHOC/OSCORE ======= |t2 /res1| +--------+ +--------+ :100 :200 (2001:db8:cafe:123:/64) Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 32] Internet-Draft yang-edhoc-oscore February 2023 auth_entry_t1 base64encodedvalue== base64encodedvalue== signature-key base64encodedvalue== edhoc_conn_t1_t2 true auth_entry_t1 Mzc= MDI= \ MDE= MDI= base64encodedvalue== base64encodedvalue== true true coap://2001:db8:cafe:123::200/res1 protect edhoc_conn_t1_t2 Appendix C. YANG data model for OSCORE case 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 Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 33] Internet-Draft yang-edhoc-oscore February 2023 "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: WG List: Author: Rafael Marin-Lopez Author: Gabriel Lopez-Millan "; 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 Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 34] Internet-Draft yang-edhoc-oscore February 2023 "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 { Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 35] Internet-Draft yang-edhoc-oscore February 2023 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, Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 36] Internet-Draft yang-edhoc-oscore February 2023 [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."; Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 37] Internet-Draft yang-edhoc-oscore February 2023 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."; Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 38] Internet-Draft yang-edhoc-oscore February 2023 } 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."; Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 39] Internet-Draft yang-edhoc-oscore February 2023 } /*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 { Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 40] Internet-Draft yang-edhoc-oscore February 2023 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 */ Appendix D. OSCORE case example usage 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=="). Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 41] Internet-Draft yang-edhoc-oscore February 2023 +------------------+ | SDN Controller | +------------------+ Southbound | Interface | /-----------------+---------------\ / \ / \ +--------+ +--------+ | t1 |=========== OSCORE ========= |t2/res1 | +--------+ +--------+ :100 :200 (2001:db8:cafe:123:/64) ctx-t1_t2 Mzc6Y2I6ZjM6MjE6MDA6MTc6YTI6ZDM= 10 1 base64encodedvalue== base64encodedvalue== MEY= MDE= coap://2001:db8:cafe:123::200/res1 protect ctx-t1_t2 Acknowledgments Authors want to thank Authors' Addresses Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 42] Internet-Draft yang-edhoc-oscore February 2023 Rafa Marin-Lopez University of Murcia Murcia 30100 Spain Email: rafa@um.es Gabriel Lopez-Millan University of Murcia Murcia 30100 Spain Email: gabilm@um.es Laurent Toutain Institut Mines Telecom Atlantique 2 rue de la Chataigneraie CS 17607 35576 Cesson-Sevigne Cedex France Email: laurent.toutain@imt-atlantique.fr Alex Fernandez Institut Mines Telecom Atlantique 2 rue de la Chataigneraie CS 17607 35576 Cesson-Sevigne Cedex France Email: javier-alejandro.fernandez-cordova@imt-atlantique.net Marin-Lopez(Ed.), et al.Expires 1 September 2023 [Page 43]