opsawg Lucas Internet Draft Cisco International Limited Intended status: Standards track September 13, 2017 Expires: March 17, 2018 aSSURE Data Security draft-lucas-assure-data-security-00.txt Abstract aSSURE uses industry standards and best practice to provide a secure communications platform for device configuration and life cycle management across the entire range of smart devices, from the largest servers through to more constrained devices, with minimal human involvement. Based on extensions to current standard methods, aSSURE also provides secure end to end communication across any network type. A new approach allows key distribution and encrypted channels to be established between devices that support RSA, EC and/or simple shared secrets. For devices that only support shared secrets, key derivation algorithms ensure that forward and backward compatible secrecy is supported so that secure change of ownership can be obtained. Owners prove ownership via a "case ID" known by the manufacturer and the "Trusted Authority" ID Server but not known by the device. aSSURE defines end-to-end encryption links, called "channels", so that pairs of devices communicate with a unique set of encryption keys. These unique keys, coupled with the end-to-end encryption, mean communication is both secure and private. DTLS supports both certificates and pre-shared keys, but does not cover key distribution or management. DTLS does not support client-specific pre-shared keys because the client cannot identify itself during the handshake. Herein are all the APIs required to support key distribution and management as well as an extension to the DTLS handshake that allows the client identity to be provided. aSSURE cleanly integrates with the Open Interconnect Consortium (OIC) architecture. Both use CBOR encoded data with CoAP over UDP and DTLS. aSSURE URIs do not collide with OIC URIs and aSSURE channels can be used as a secure transport for OIC requests. 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- Lucas Expires March 17, 2018 [Page 1] Internet-Draft aSSURE Data Security September 2017 Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on March 17, 2018. Copyright Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Lucas Expires March 17, 2018 [Page 2] Internet-Draft aSSURE Data Security September 2017 Table of Contents 1. INTRODUCTION..................................................... 7 2. THE ROLE OF ASSURE IN AN IOT ENVIRONMENT......................... 8 2.1. Background..................................................... 8 2.2. Who am I allowed to talk to?................................... 8 2.3. How can I authenticate them?................................... 9 2.4. What am I allowed to tell them?................................ 9 2.5. What are they allowed to tell me?.............................. 9 2.6. How can I ensure that our communication is private?............ 9 3. TERMINOLOGY..................................................... 10 4. THE ROLE OF THE MANAGEMENT SYSTEM IN ASSURE..................... 10 4.1. Overview...................................................... 10 4.2. Creation of Communication Topologies.......................... 10 4.3. Examples of communication topologies.......................... 11 4.3.1. A "star" topology........................................... 11 4.3.2. A "ring" topology........................................... 11 4.3.3. A "tree" topology........................................... 12 4.3.4. A "fully connected" topology................................ 12 5. ASSURE ARCHITECTURE............................................. 13 5.1. Internet Accessible Deployments............................... 13 5.2. Walled Garden Deployments..................................... 14 6. SECURITY CONSIDERATIONS......................................... 15 6.1. Overview...................................................... 15 6.2. Guidelines for manufacturers.................................. 17 6.2.1. Device UUID................................................. 17 6.2.2. Device Asymmetric Key....................................... 17 6.2.3. Device Shared Secret........................................ 17 6.2.4. Case ID..................................................... 17 6.2.5. QR Code..................................................... 17 7. DATA STRUCTURES................................................. 18 7.1. Overview...................................................... 18 7.2. Key Definition................................................ 18 7.3. Signature Definition.......................................... 20 7.4. Authenticated Key Definition.................................. 21 7.5. Content Type IDs.............................................. 22 7.6. Key Format IDs................................................ 23 7.7. Identity Class IDs............................................ 23 7.8. Cipher Suite IDs.............................................. 24 7.9. Signature Format IDs.......................................... 24 7.10. Authenticated Key Metadata................................... 25 7.11. aSSURE timestamps............................................ 25 7.11.1. Simple timestamps.......................................... 25 7.11.2. Precision timestamps....................................... 25 8. DTLS WITH ASSURE KEY IDENTITIES................................. 26 8.1. Overview...................................................... 26 8.2. Extension to (D)TLS........................................... 26 8.2.1. Peer Name Indication........................................ 26 8.3. Proof of identity by public key clients....................... 27 8.4. Proof of identity by shared secret clients.................... 28 9. TRUSTED AUTHORITY APIS.......................................... 29 9.1. Overview...................................................... 29 Lucas Expires March 17, 2018 [Page 3] Internet-Draft aSSURE Data Security September 2017 9.2. Manufacturer API.............................................. 29 9.2.1. PUT /v1/devices/...................................... 30 9.2.2. POST /v1/parametersets...................................... 31 9.2.3. PUT /v1/parametersets/................................ 31 9.2.4. GET /v1/parametersets/................................ 31 9.3. Owner API..................................................... 32 9.3.1. POST /v1/managementsystems.................................. 32 9.3.2. PUT /v1/devices//owner?case_string=........... 33 9.3.3. PUT /v1/devices//owner?mgmtid=................ 33 9.3.4. PUT /v1/devices//owner?case_string=................... 34 &mgmtid= 34 9.3.5. PUT /v1/devices//owner?mgmtid=NULL.................... 34 9.3.6. GET /v1/devices//parameterset......................... 34 9.3.7. PUT /v1/devices//bootstrap............................ 35 9.3.8. GET /v1/devices//bootstrap............................ 35 9.4. Bootstrap API................................................. 36 9.4.1. GET /v1/devices//bootstrap............................ 36 10. DEVICE MANAGEMENT API.......................................... 36 10.1.1. PUT /v1/keys/........................................ 37 10.1.2. POST /v1/keys/generate?type=&persistent= 37 10.1.3. GET /v1/keys/........................................ 38 10.1.4. DELETE /v1/keys/..................................... 38 10.1.5. GET /v1/keys............................................... 39 10.1.6. PUT /v1/channels........................................... 39 10.1.7. PUT /v1/channels/...................................... 40 10.1.8. PUT /v1/channels//open......................... 41 10.1.9. PUT /v1/channels//close........................ 41 10.1.10. DELETE /v1/channels/.......................... 41 10.1.11. GET /v1/channels/..................................... 42 10.1.12. GET /v1/channels.......................................... 43 10.1.13. PUT /v1/reboot............................................ 44 10.1.14. PUT /v1/shutdown.......................................... 44 10.1.15. PUT /v1/bootstrap......................................... 44 10.1.16. GET /v1/ping.............................................. 45 10.1.17. GET /v1/info.............................................. 45 11. MANAGEMENT SERVER API.......................................... 46 11.1. Overview..................................................... 46 11.2. Registration API............................................. 46 11.2.1. POST /v1/devices/?case_string=.......... 46 11.2.2. POST /v1/devices//replace?uuid=........ 47 11.2.3. GET /v1/devices//status.............................. 47 11.2.4. GET /v1/devices//info................................ 47 11.3. Presence API................................................. 48 11.3.1. PUT /v1/devices//info................................ 48 11.3.2. PUT /v1/devices//goodbye............................. 49 11.4. Miscellaneous................................................ 49 11.4.1. GET /v1/timestamp.......................................... 49 12. PHYSICAL / NETWORK LAYER IMPLEMENTATIONS....................... 50 12.1. BACnet....................................................... 50 12.1.1. aSSURE Bootstrap........................................... 50 12.1.2. aSSURE Secure Management Channels.......................... 52 12.1.3. aSSURE Secure Data Channels................................ 52 Lucas Expires March 17, 2018 [Page 4] Internet-Draft aSSURE Data Security September 2017 12.2. IP........................................................... 52 12.2.1. Bootstrap Server FQDN...................................... 53 12.3. Bluetooth.................................................... 53 12.4. Assigned address types....................................... 53 13. DTLS CONNECTION CONFIGURATION EXAMPLES......................... 54 13.1. Example Topology............................................. 54 13.2. Elliptic Curve device . Elliptic Curve device................ 55 13.3. Elliptic Curve device . RSA device........................... 55 13.3.1. Option 1 - Issue EC key to RSA device...................... 55 13.3.2. Option 2 - Issue RSA key to EC device...................... 55 13.3.3. Option 3 - Issue Shared Secret to both devices............. 55 13.4. Elliptic Curve device . Shared Secret device................. 55 13.5. RSA device . RSA device...................................... 55 13.6. RSA device . Shared Secret device............................ 56 13.7. Shared Secret device . Shared Secret device.................. 56 14. MESSAGE SEQUENCE DIAGRAMS...................................... 57 14.1. Manufacturing Flow........................................... 57 14.2. Management System Preparation................................ 58 14.3. Device Registration.......................................... 59 14.4. Device Ownership State Machine............................... 60 14.5. Device Configuration and Bootstrap........................... 61 14.6. Device Configuration and Bootstrap (Walled Garden)........... 62 14.7. Device Change Owner.......................................... 63 15. CONFIGURATION AND BOOTSTRAP DATA FORMATS....................... 65 15.1. Overview..................................................... 65 15.2. Configuration data format.................................... 65 15.3. Device connection to the bootstrap server using DTLS using... 66 pre-shared secrets........................................... 66 15.4. Device connection to the bootstrap server using DTLS using... 66 public keys.................................................. 66 15.5. Bootstrap data format........................................ 66 15.5.1. Payload protected by Elliptic Curve keys................... 67 15.5.2. Payload protected by RSA keys.............................. 68 15.5.3. Payload protected by shared secrets........................ 68 15.5.4. Decrypted payload content.................................. 68 16. SECURITY CONSIDERATIONS........................................ 69 17. IANA CONSIDERATIONS............................................ 69 18. CONCLUSIONS.................................................... 69 19. REFERENCES..................................................... 69 19.1. Normative References......................................... 69 19.2. Informative References....................................... 70 20. ACKNOWLEDGMENTS............................................... 711 Lucas Expires March 17, 2018 [Page 5] Internet-Draft aSSURE Data Security September 2017 Table of Figures Star Topology 11 Ring Topology 11 Tree Topology 12 Fully Connected Topology 12 Internet-accessible architecture 13 Walled-garden architecture 14 DTLS Connection Example Topology 55 Manufacturing Flow Sequence Diagram 57 Management System Preparation Sequence Diagram 58 Device Registration Sequence Diagram 59 Device Ownership State Machine 60 Device Configuration and Bootstrap Sequence Diagram 61 Device Configuration and Bootstrap Sequence Diagram (Walled Garden) 62 Device Change Owner Sequence Diagram (first part) 63 Device Change Owner Sequence Diagram (second part) 64 Lucas Expires March 17, 2018 [Page 6] Internet-Draft aSSURE Data Security September 2017 Glossary of Terms API Application Programming Interface CA Certificate Authority CBOR Concise Binary Object Representation, RFC-7049 CoAP Constrained Application Protocol, RFC-7252 DHCP Dynamic Host Configuration Protocol DNS Domain Name System DTLS Datagram Transport Layer Security (v1.2), RFC-6347 EC Elliptic Curve ECDSA E C Digital Signature Algorithm, NIST FIPS 186-4 ECIES Elliptic Curve Integrated Encryption Scheme, ANSI X9.63 FQDN Fully Qualified Domain Name PKCS Public Key Cryptography Service PKI Public Key Infrastructure TA Trusted Authority TLS Transport Layer Security (v1.2), RFC-5246 1. Introduction This document provides the reference technical specification for aSSURE. aSSURE uses industry standards and best practice to provide a secure communications platform for device configuration and life cycle management. Where possible, a minimal approach is taken to standards implementation so that the complexity and code footprint for implementation is kept to a minimum. The underlying standards are: o Transport Layer Security, TLS v1.2, RFC-5246 o Datagram Transport Layer Security, DTLS v1.2, RFC-6347 o Constrained Application Framework, CoAP, RFC-7252 o Concise Binary Object Representation, CBOR, RFC-7049 o CoAP Block-wise Transfers, https://www.ietf.org/id/draft-ietf o core-block-21.txt The additional functionality provided by aSSURE is intended to work within existing communications frameworks. This allows aSSURE to provide an upgrade path to add a common security approach that provides both secure communications and lifecycle management including change of ownership. aSSURE uses a "Trusted Authority" (TA), similar to the role that a Certificate Authority (CA) plays in a Public Key Infrastructure (PKI) today, to track the manufacture and ownership of devices. Any number of Trusted Authorities may exist but each device will be assigned to a specific TA during its manufacture and will remain assigned to this TA for its entire life. Device owners communicate with the various Trusted Authorities to assert ownership of individual devices and upload the initial Lucas Expires March 17, 2018 [Page 7] Internet-Draft aSSURE Data Security September 2017 configuration for the device. When the device powers up, it will contact the Trusted Authority to obtain its initial configuration - this process is called "bootstrap". The initial configuration will provide sufficient information for the device to establish a secure communications channel to the system that will be managing it. Once this channel is established, additional configuration will be provided from the management system directly to the device and the device can enter "normal service". The detailed device lifecycle flow is described elsewhere. Note aSSURE is designed to cleanly integrate with the Open Interconnect Consortium (OIC) architecture. Both OIC and aSSURE use CBOR encoded data with CoAP over UDP and DTLS. aSSURE URIs have been deliberately chosen not to collide with OIC URIs and aSSURE channels can be used as a secure transport for OIC requests. 2. The role of aSSURE in an IoT environment 2.1. Background In any secure environment, there are five basic questions that any device must ask: 1. Who am I allowed to talk to? 2. How can I authenticate them? 3. What am I allowed to tell them? 4. What are they allowed to tell me? 5. How can I ensure that our communication is private? If these basic questions can all be answered with confidence, there is the foundation for a secure system. If any of the above are uncertain then the system has weaknesses that may be exploited by an attacker. The aSSURE standard provides an answer to all these questions in a way that allows devices to communicate across different network architectures and device capabilities yet still providing end-to end security at a level that is appropriate to the abilities of the devices that are communicating. Furthermore, aSSURE provides this with a solution that involves minimal human involvement. The following sections will address each of these questions in turn. 2.2. Who am I allowed to talk to? In many ways, this is one of the biggest hurdles to overcome. If we want to be able to manufacture and sell "generic" product that Lucas Expires March 17, 2018 [Page 8] Internet-Draft aSSURE Data Security September 2017 has no pre-configuration, how does that device know that we own it? There are a lot of different approaches to this with "Trusted On First Use" (TOFU) being an obvious one, but with all of them they either have weaknesses in the initial security or rely on public key cryptography. Public key cryptography is fine in more powerful devices, but not an option in the smallest ones, so for a universally secure solution, a different approach is required. The aSSURE standard uses a Trusted Authority (TA) as the reference for the device. The device is programmed with the identity and credentials of the TA during manufacture and, on first power up, will only talk to the TA. The user will register ownership of the device with the TA and securely upload the initial configuration data for the device to the TA. The TA will then forward that configuration to the device. That configuration includes the location and security parameters for the device to connect to the owner's systems, so now the device knows that it can trust its owner. Once the device has connected to the owner's management system, this system can deliver additional configuration parameters, encryption keys, etc. to the device. This allows the management system to tell devices to set up secure peer-to-peer connections, connect to additional management systems and perform other actions. 2.3. How can I authenticate them? The same sequence as for 2.2. above is used to provide the authentication details to the device. This information allows the device to authenticate the owner's systems and allows the owner's systems to authenticate the device. 2.4. What am I allowed to tell them? The same sequence as for 2.2. above is used to provide the access control rules for access to the device data. This allows the device to know what information it can disclose. 2.5. What are they allowed to tell me? The same sequence as for 2.2. above is used to provide the access control rules for commands and configuration sent to the device. This allows the device to know what parameters and commands it will accept from the owner's systems. 2.6. How can I ensure that our communication is private? The aSSURE standard defines end-to-end encryption links, called "channels", that ensure each pair of devices communicate with a Lucas Expires March 17, 2018 [Page 9] Internet-Draft aSSURE Data Security September 2017 unique set of encryption keys. These unique keys, coupled with the end-to-end encryption, means that their communication is both secure and private. 3. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT","SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. In this document, these words will appear with that interpretation only when in ALL CAPS. Lower case uses of these words are not to be interpreted as carrying significance described in RFC 2119. In this document, the characters ">>" preceding an indented line(s) indicates a statement using the key words listed above. This convention aids reviewers in quickly identifying or finding The portions of this RFC covered by these keywords. 4. The role of the Management System in aSSURE 4.1. Overview The Management System is a key part in the trust relationship that the device creates. The root of trust is the Trusted Authority. The Trusted Authority tells the device which management systems(s) it can trust. The Management Systems tell the device which other management systems and devices it can trust (if any) and what their permissions are on the device. 4.2. Creation of Communication Topologies The Management System can instruct the aSSURE devices to form any topology that is within their capabilities. The limits on the topology types and complexity are only: o Limitations set by the underlying network architecture o Limitations set by the device memory and/or processing power o and/or software o Limitations set by the management software In aSSURE terminology, each connection between devices is called a channel. The rules about how channel keys are determined and assigned is described in detail in section 13. below. Lucas Expires March 17, 2018 [Page 10] Internet-Draft aSSURE Data Security September 2017 4.3. Examples of communication topologies 4.3.1. A "star" topology _______ / \ | Device| _______ \_______/ ______ / \ | / \ | Device| | |Device| \_______/\ | /\______/ \ ___|___ / / \ | Device| \_______/ _______ / | \ _______ / \/ | \/ \ | Device| | | Device| \_______/ ___|___ \_______/ / \ | Device| \_______/ Star Topology 4.3.2. A "ring" topology _______ / \ | Device| _______ /\_______/\ ______ / \/ \/ \ | Device| |Device| \_______/ \______/ | | | | ___|___ ___|___ / \ / \ | Device| | Device| \_______/\ _______ /\_______/ \/ \/ | Device| \_______/ Ring Topology Lucas Expires March 17, 2018 [Page 11] Internet-Draft aSSURE Data Security September 2017 4.3.3. A "tree" topology _______ / \ | Device| _______ \_______/ ______ / \ | / \ | Device| | |Device| \_______/\ | /\______/ \ ___|___ / / \ | Device| \_______/ _______ | _______ / \ | / \ | Device| | | Device| \_______/\ ___|___ /\_______/ \/ \/ | Device| \_______/ Tree Topology 4.3.4. A "fully connected" topology The fully connected topology shows four devices where each device has a connector to all of the other three devices. If there are "n" devices they each have "n-1" connectors. _______ _______ / \ / \ | Device|<------->| Device| \_______/ \_______/ ^ ^ ^ ^ | \ / | | \ --/ | | \ / | | ------ | | / \ | | --/ \ | | / \ | __v_ _v_ v____v_ / \ / \ | Device|<------->| Device| \_______/ \_______/ Fully Connected Topology Lucas Expires March 17, 2018 [Page 12] Internet-Draft aSSURE Data Security September 2017 5. aSSURE Architecture 5.1. Internet Accessible Deployments TRUSTED AUTHORITY MANUFACTURER +-------------------------+ +--------------------------+ | | | | |+----------------------+ | | +--------------+ | || MANUFACTURER |<--(-)--------|MANUFACTURING |-- | || GATEWAY | |Manufacturer| SYSTEM | | | |+--------------------!-+ | Interface +--------------+ | | | | ! | | V | | | ! | | +-------+ | | | ! | | Short-Lived | DEVICE| | | | +--A-I-R-G-A-P-!---| | Make & Delete +-------+ | | | | ! | | ! | | | A LOCK ! | +--------------------!-----+ | | I +-----------V-+ | ! | | R | IDENTITY | | ! | | G | SERVER | | ! | | A +-----------!-+ | OWNER ! | | P ! | +------------------------!-----+ | | | ! | | ! | | | +---A-I-R-G-A-P!---| | Bootstrap Interface+---v---+ | | v ! | | -----(-)-------| DEVICE| | |+-----------------+ ! | | / +-------+ | || REGISTRATION | ! | | / /|QR CODE| | || SERVER | ! | | / / +-------+ | |+-----------------+ ! | | / / | | | ^ ^ ! | |/ (/) | | | | | ! | / Management v | | | +------------V-+ | (/) Interface +-------+ | | | | BOOTSTRAP |<--/ | (/) INSTALLER | | | | SERVER | | | / +-------+ | | | +--------------+ | | / / | | | ^ | | / (/) | | | | | | +------v----+ Registration | | | | | | | | Interface | | | | | | | MANAGEMENT| (/) | |+-------------+ | | | SYSTEM | / | || OWNER | | | | | / | || GATEWAY |<--------(-)-----| | / | |+-------------+ Owner | | |v | | Interface| +-----------+ | | | | | | | | | +-------------------------+ +------------------------------+ Internet-accessible architecture Lucas Expires March 17, 2018 [Page 13] Internet-Draft aSSURE Data Security September 2017 5.2. Walled Garden Deployments TRUSTED AUTHORITY MANUFACTURER +----------------------+ +----------------------------+ | | | | |+-------------------+ | | +----------------+ | || MANUFACTURER |<----(-)------| MANUFACTURING |-- | || GATEWAY | |Manufacturer| SYSTEM | | | |+-----------------!-+ | Interface +----------------+ | | | | ! | | V | | | ! | | Short-lived +-------+ | | | ! | | Make & Delete | DEVICE| | | | +--A-I-R-G-A-P-!---| | +-------+ | | | | ! | | ! | | | A LOCK ! | +----------------------!-----+ | | I +-----------V-+ | ! | | R | IDENTITY | | ! | | G | SERVER | | ! | | A +-----------!-+ | OWNER ! | | P ! | +----------------------------!-----+ | | | ! | | ! | | | +---A-I-R-G-A-P!---| |+-----------+ Bootstrap +---v---+ | | v ! | || Bootstrap|<--(-)-----| DEVICE| | |+--------------+ ! | || Server | Interface +-------+ | || REGISTRATION | ! | |+-----------+ / |QR CODE| | || SERVER | ! | | ^ (/) +-------+ | |+--------------+ ! | | ! +----------+ Management | | | ^ ^ ! | | ! |Management| Interface | | | | | ! | | ! | Server |<-/ | | | | +------------V-+ | | ! +----------+ | | | | | BOOTSTRAP | | | ! ^ | | | | | SERVER | | +=!===!===WALLED=GARDEN======|=====| | | +--------------+ | | ! ! v | | | ^ | | ! / +---------+ | | | | | | ! / |INSTALLER| | | | | | | !/ +---------+ | | | | | |+----------+ / | |+----------+ | ||INTERNET | (/) | || OWNER | | || FACING | Registration | || GATEWAY |<----(-)-----|MANAGEMENT| Interface | |+----------+ Owner | || SYSTEM | (/) | | Interface| || |<-----/ | | | |+----------+ | | | | | +----------------------+ +----------------------------------+ Walled-garden architecture Lucas Expires March 17, 2018 [Page 14] Internet-Draft aSSURE Data Security September 2017 6. Security Considerations 6.1. Overview The aSSURE framework is intended to be usable across the entire range of smart devices - from the largest servers through to more constrained devices (as defined in RFC-7228). This is a very challenging goal and means that some security approaches in common use today are not universally suitable. Examples of approaches that are not universally suitable include: o Public Key Cryptography, e.g. RSA, DSA, EC o This is computationally intensive and may take too long to be acceptable on devices with minimal processing ability. o This is computationally intensive and the necessary additional processing load may have an unacceptable impact on battery life. o This requires reasonably large code size to implement in software and this may not be available on the more constrained devices. o X.509 certificates o These use time stamps and small devices may not have a real time clock. o These assume public key cryptography (RSA, DSA or EC) and constrained devices may not be able to support this as explained above. o These have a fixed lifetime, thus requiring them to be reissued before they expire. o These require a certificate authority to issue (and reissue) them. o Due to their complexity, these have been the target of various attacks in the past, so removing them reduces the attack surface. o Complex text-based data representations such as ASN.1, HTML, XML, YAML or JSON o These are difficult to parse, requiring larger code libraries and more processing power than simpler formats such as CBOR. o Due to their complexity, these have been the target of various attacks in the past, so removing them reduces the attack surface. o Complex protocols such as SOAP, HTML, etc. o Again, these are more difficult to parse, requiring larger code libraries and more processing power than simpler protocols such as CoAP. o Full standards implementation o Lots of industry standards are large and have a lot of different options, most of which are unnecessary for a new implementation with no legacy support requirements. o For example, TLS supports over 200 different cipher suites and this list continues to grow. Lucas Expires March 17, 2018 [Page 15] Internet-Draft aSSURE Data Security September 2017 o Due to their complexity, these have been the target of various attacks in the past, so reducing the scope of the implementation also reduces the attack surface. Support for shared secrets Very constrained devices that cannot support public key cryptography have to fall back on "shared secrets" (also known as "pre-shared keys") to identify themselves. Typical approaches using shared secrets require the secret to be disclosed to both parties to set up the secure connection. Once a secret has been disclosed, it can never be proved to have been forgotten. This makes transfer of device ownership problematic, as the previous owner of the device may still know the shared secret even after the device has been transferred to a new owner. In this scenario, the previous owner would be able to decrypt all traffic between the device and its new owner, making the device untrustworthy to the new owner. aSSURE offers a new approach using shared secrets that allows the original secret to be concealed from the peer involved in the connection. In the aSSURE scenario, a shared secret can be distributed to a device (or multiple devices) with one or two derivation functions. These derivation functions allow a device with the correct reference key to derive the shared secret. Different derivation functions exist to derive the shared secret from an Elliptic Curve key, an RSA key or another shared secret. This ability to derive shared secrets is used to secure the ownership lifecycle for devices that do not support public key cryptography. With this approach, the device owner is provided with the parameters for the hashing function and the derived shared secret but not the original shared secret programmed into the device during manufacture. When the owner wishes to communicate with the device, the owner provides the device with the derived secret parameters, thus allowing the device to derive the new secret from the original secret. The owner is provided with a second derivation function that uses the owner key, so they can also derive the same secret and hence establish a secure communication link to the device. When the device changes owner, the new owner is given a different derived secret, not the original secret. The new owner can communicate with the device using the new parameters and the knowledge of the new derived secret. The previous owner, however, does not have the new owner's key nor the device key, so cannot derive the new shared secret and so is unable to decrypt the communications with the new owner. The only entities that know the original device secret are the device itself and the Identity server within the Trusted Authority (this is described in more detail later). Lucas Expires March 17, 2018 [Page 16] Internet-Draft aSSURE Data Security September 2017 Shared secrets are described more in 7.2. and 8.4. below. 6.2. Guidelines for manufacturers 6.2.1. Device UUID All device UUIDs should be truly randomly generated. This means that they are completely unpredictable and knowledge of the UUID does not disclose any information about what the device is, who manufactured it or when. 6.2.2. Device Asymmetric Key If a device uses an RSA or EC asymmetric key, this should be securely generated within the device and the private key must never be disclosed outside of the device. The device should have access to a suitable entropy source to ensure that the key is truly randomly generated. 6.2.3. Device Shared Secret If a device uses a shared secret, this should be truly randomly generated and at least 128 bits in size. It may be generated inside the device or on the local manufacturing station but, if generated outside the device, must never be stored in an unencrypted form and must be wiped from RAM as soon as it is no longer needed. The device secret can only ever be stored in non volatile storage AFTER it has been formed into the device identity structure and encrypted as described in 9.2.1. below. 6.2.4. Case ID The aSSURE solution needs a method for an owner to prove that a device is in their possession. This is done through knowledge of a "case ID", an identification string that is printed on the outside of the case. This number is NOT known to the device - it is only known to the manufacturer and the Trusted Authority's Identity Server. The case ID should be a randomly generated number that is at least 128 bits. 6.2.5. QR Code The device ID and case ID should be printed in a QR Code on the side of the device. The data should be encoded in CBOR as follows: ARRAY { INTEGER version // Set to 1 for aSSURE v1 BYTE STRING device_uuid BYTE STRING case_id } Lucas Expires March 17, 2018 [Page 17] Internet-Draft aSSURE Data Security September 2017 If the device UUID and case UUID are both 128 bits then this will encode in 36 bytes. This can be encoded in a type 3 QR code (27 x 27 pixels) with "M" level of error correction, a type 4 QR code (33 x 33 pixels) with a "Q" level of error or a type 5 QR code (37 x 37 pixels) with "H" level of error correction. The manufacturer may choose any of these QR formats, but the type 5 is recommended as it has a higher level of error correction and is therefore less susceptible to damage. 7. Data Structures 7.1. Overview Where possible, common data structures are used across the system. This simplifies the development and allows better code reuse. 7.2. Key Definition A key is defined using one of the following CBOR formats depending on its type. All keys are identified by their ID, which is a 128 bit randomly assigned UUID. Keys have a format which may be Elliptic Curve, RSA or derived secret. Elliptic Curve and RSA keys must include the public key part and may optionally also include the associated private key. If the key is an Elliptic Curve key, the definition is: ARRAY { INTEGER content // "Key Content Type", see 7.5. below INTEGER format // "EC key", see 7.6. below BYTE STRING key_id // UUID BYTE STRING public_key // ASN.1 DER encoded string BYTE STRING private_key // ASN.1 DER encoded string } The private_key BYTE STRING must be zero length if only a public key is provided. Note that the private key definition is not encrypted so if the private key is provided, the definition must be transferred over an encrypted channel and stored in a protected store. If the key is an RSA key, the definition is: ARRAY { INTEGER content // "Key Content Type", see 7.5. below INTEGER format // "RSA key", see 7.6. below BYTE STRING key_id // UUID BYTE STRING public_key // ASN.1 DER encoded string BYTE STRING private_key // ASN.1 DER encoded string Lucas Expires March 17, 2018 [Page 18] Internet-Draft aSSURE Data Security September 2017 } The private_key BYTE STRING must be zero length if only a public key is provided. Note that the private key definition is not encrypted so if the private key is provided, the definition must be transferred over an encrypted channel and stored in a protected store. If the key is a derived secret, the definition is: ARRAY { INTEGER content // "Key Content Type", see 7.5. below INTEGER format // "Derived shared secret", see 7.6. below // below BYTE STRING key_id // UUID ARRAY { // Derivation definition BYTE STRING reference_A_key // UUID BYTE STRING salt INTEGER iterations_or_cipher BYTE_STRING encrypted_secret } // Additional derivation definitions may be present in // the same format as above } The derived secret has one or more derivation definitions. All derivations can be disclosed publicly and all derivations must produce the same secret. A device may use any of the derivations for which it already knows the reference key. If the reference key is a shared secret then the PBKDF2 algorithm is used with SHA2 as the digest function, the reference key shared secret used as the passphrase, the "iterations_or_cipher" used as the iteration count, salt and a length value determined by the length of the "encrypted_secret". After the PBKDF2 is completed, the result is XOR'd against the "encrypted_secret". This allows secure generation of any byte sequence. If the reference key is an elliptic curve key, then the "salt" and "iterations_or_cipher" fields are ignored (and should be zero length and value zero respectively). The "encrypted_secret" contains the shared secret protected by the Cryptographic Message Syntax with "enveloped-data" as the ContentInfo (see RFC 5652 and RFC 5753) using the "Standard" variation of Ephemeral Static ECDH (see RFC 5753 section 3.1). The default choices for encryption cipher and hash function should be AES-128 and SHA-256 respectively. If the reference key is an RSA key, then the "salt" and "iterations_or_cipher" fields are ignored (and should be zero Lucas Expires March 17, 2018 [Page 19] Internet-Draft aSSURE Data Security September 2017 length and value zero respectively). The "encrypted_secret" contains the shared secret protected by the Cryptographic Message Syntax with "enveloped-data" as the ContentInfo (see RFC 5652) using RSAES-OAEP (see RFC 8017 section 7.1). The default choices for encryption cipher and hash function should be AES-128 and SHA 256 respectively. The SHA-1 hash should not be used. 7.3. Signature Definition Rather than use X.509 signatures, which require public key cryptography and ASN.1 encoding, aSSURE uses a simpler approach using CBOR that can also be used with derived secrets as well as public keys. If the signature is generated by an Elliptic Curve private key, the signature structure is: ARRAY { INTEGER content // "Signature Content Type", see // 7.5. below INTEGER format // Signature format, see 7.9. below INTEGER created_at INTEGER valid_until BYTE STRING key_id BYTE STRING r BYTE STRING s } Here, "r" and "s" are the signature values as defined in the Elliptic Curve Digital Signature Algorithm (ECDSA). If the signature is generated by an RSA private key, the signature structure is: ARRAY { INTEGER content // "Signature Content Type", see // 7.5. below INTEGER format // Signature format, see 7.9. below INTEGER created_at INTEGER valid_until BYTE STRING key_id BYTE STRING s } Here, "s" are the signature values as defined in the RSA Digital Signature Algorithm (PKCS #1 v1.5). If the signature is generated by a derived secret, the signature structure is: ARRAY { INTEGER content // "Signature Content Type", see // 7.5. below Lucas Expires March 17, 2018 [Page 20] Internet-Draft aSSURE Data Security September 2017 INTEGER format // Signature format, see 7.9. below INTEGER created_at INTEGER valid_until BYTE STRING key_id BYTE STRING hmac } In all cases, the signature covers the original data structure and the signature structure with the "r", "s" and/or "hmac" fields being treated as zero length when performing the sign or validation actions (i.e. the BYTE STRING definition is considered to be the value 0b010_00000). Two timestamps are part of each signature: o The timestamp of when the signature was created ("created_at") o The timestamp after which the signature invalid ("valid_until") o Each signing authority is free to choose its own validity duration for the signatures that it issues. The authority can therefore balance the rate of re-issue of signatures against the time that a signature or a compromised key would remain valid. These fields can be set to zero to indicate a signature that is always valid and never expires. These fields may also be zero if the signature authority knows that the signature is being issued to a device with no real-time clock capability. If a device has no knowledge of the true time, these fields should be ignored when performing signature validation. 7.4. Authenticated Key Definition Rather than use X.509 certificates which require public key cryptography, ASN.1 encoding and knowledge of real time, aSSURE uses a simpler yet more flexible structure to authenticate a public key or a key derived from a shared secret. An authenticated key definition combines a header, key definition as in 7.2. above, optional metadata and signature as in 7.3. above. ARRAY { INTEGER content // "Identity Content Type", see 7.5. below INTEGER class // Identity class, see 7.7. below ARRAY { // Key definition, see 7.2. above INTEGER content // "Key Content Type", see 7.5. below } MAP { // Metadata (key + value pairs), see 7.10. below } ARRAY { // Signature definition, see 7.3. above Lucas Expires March 17, 2018 [Page 21] Internet-Draft aSSURE Data Security September 2017 INTEGER content // "Signature Content Type", see // 7.5. below } } The device should validate an "authenticated key" as follows: 1. Check that the key used to generate its signature is already present in the device 2. Check that current time is within the timestamp range for the signature 3. For each key in the hierarchy of keys required to validate this signature, check that current time is within the timestamp range for that key's signature 4. Check that the class of the key used to generate the signature is allowed to sign the class of the new authenticated key. The rules for this are in 7.7. below. 5. Check that the signature matches the authenticated key data If all the above checks pass, the authenticated key can be accepted. 7.5. Content Type IDs +-------+------------------------------+ | Value | Meaning | +-------+------------------------------+ | 0 | Identity Content Type | | 1 | Key Content Type | | 2 | Configuration Content Type | | 3 | Encrypted Key Content Type | | 4 | Signature Content Type | | 5 | Owner Content Type | +-------+------------------------------+ +-------+------------------------------+ | Value | Meaning | +-------+------------------------------+ | 0 | Identity Content Type | +--------------------------------------+ | 1 | Key Content Type | +--------------------------------------+ | 2 | Configuration Content Type | +--------------------------------------+ | 3 | Encrypted Key Content Type | +--------------------------------------+ | 4 | Signature Content Type | +--------------------------------------+ | 5 | Owner Content Type | +-------+------------------------------+ Lucas Expires March 17, 2018 [Page 22] Internet-Draft aSSURE Data Security September 2017 7.6. Key Format IDs +-------+-------------------------------------+ | Value | Meaning | +-------+-------------------------------------+ | 0 | Elliptic Curve Key (ASN1.DER encoded| | | following industry standards) | | 1 | RSA Key (ASN1.DER encoded | | | following industry standards) | | 2 | Configuration Content Type | +-------+-------------------------------------+ 7.7. Identity Class IDs +---+------------+---------------------------------------+ | | Signing Permissions| + +----+----+----+----+----+----+ | + | | Identity Classes | | | + +----+----+----+----+----+----+ | + | | M | | | | | | | | | | a | | | | | | | | | | n | |M S | | | | | | | | u |T A |a y |B S | | | |B D | | | f |r u |n s |o e | | | |o a | | | a |u t |a t |o r | | C | |o t | |---+------------| c |s h |g e |t v | D | h | C |t a | | V | | t |t o |e m |s i | e | a | o |s | | a | | u |e r |m |t c | v | n | n |t | | l | | r |d i |e |r e | i | n | f |r | + u + | e | t |n |a | c | e | i |a | | e |Name | r | y |t |p | e l g p | +---+------------+----+----+----+----+----+----+----+----+ | 0 |Manufacturer| Y | Y | N | N | Y | N | N | N | | | | | | | | | | | | +---+------------+----+----+----+----+----+----+----+----+ | 1 |Trusted | N | Y | Y | Y | Y | N | N | N | | |Authority | | | | | | | | | +---+------------+----+----+----+----+----+----+----+----+ | 2 |Management | N | N | Y | Y | Y | Y | Y | Y | | |System | | | | | | | | | +---+------------+----+----+----+----+----+----+----+----+ | 3 |Bootstrap | N | N | N | N | N | N | N | N | | |Service | | | | | | | | | +---+------------+----+----+----+----+----+----+----+----+ | 4 |Device | N | N | N | N | N | Y | N | N | | | | | | | | | | | | +---+------------+----+----+----+----+----+----+----+----+ | 5 |Channel | N | N | N | N | N | N | N | N | | | | | | | | | | | | +--------------------------------------------------------+ The Manufacturer is the manufacturer of the device. A manufacturer Lucas Expires March 17, 2018 [Page 23] Internet-Draft aSSURE Data Security September 2017 may install Device identification keys at the factory to allow the device to authenticate itself. If the device is public key >> capable, the manufacturer MUST install the identity for the Trusted Authority. The Trusted Authority refers to all systems running within the Trusted Authority. A Trusted Authority is only allowed to authenticate other systems running within the Trusted Authority, the Bootstrap Service, the owner's Management Systems or the Device. It is not allowed to authenticate Bootstrap data or device communications Channels. The Management System is not allowed to authenticate Manufacturers or Trusted Authorities but it can authenticate all other identities used by the device. The Bootstrap Service is not allowed to authenticate anything else - it is only able to deliver bootstrap data to the device. The Device is only allowed to authenticate channels. The Channel is not allowed to authenticate anything else - it is only allowed to transport data. 7.8. Cipher Suite IDs +-------+-------------------------------------------------+ | Value | Meaning | +-------+-------------------------------------------------+ | 0 | "AES-128 CBC" (OID 2.16.840.1.101.3.4.2)" | | 1 | "AES-192 CBC" (OID 2.16.840.1.101.3.4.22)" | | 2 | "AES-256 CBC" (OID 2.16.840.1.101.3.4.42)" | | 3 | "AES-128 CCM" (OID 2.16.840.1.101.3.4.7)" | | 4 | "AES-192 CCM" (OID 2.16.840.1.101.3.4.27)" | | 5 | "AES-256 CCM" (OID 2.16.840.1.101.3.4.47)" | | 6 | "AES-128 GCM" (OID 2.16.840.1.101.3.4.6)" | | 7 | "AES-192 GCM" (OID 2.16.840.1.101.3.4.26)" | | 8 | "AES-256 GCM" (OID 2.16.840.1.101.3.4.46)" | +-------+-------------------------------------------------+ 7.9. Signature Format IDs +-------+-------------------------------------------------+ | Value | Meaning | +-------+-------------------------------------------------+ | 0 | ecdsa-with-SHA256 (OID 1.2.840.10045.4.3.2) | +---------------------------------------------------------+ | 1 | ecdsa-with-SHA384 (OID 1.2.840.10045.4.3.3) | +---------------------------------------------------------+ | 2 | ecdsa-with-SHA512 (OID 1.2.840.10045.4.3.4) | +---------------------------------------------------------+ | 3-7 | Reserved..future expansion of ECDSA signatures | Lucas Expires March 17, 2018 [Page 24] Internet-Draft aSSURE Data Security September 2017 +---------------------------------------------------------+ | 8 | sha256-with-rsa-signature | | | (OID 1.2.840.113549.1.1.11) | +---------------------------------------------------------+ | 9 | sha384-with-rsa-signature | | | (OID 1.2.840.113549.1.1.12) | +---------------------------------------------------------- | 10 | sha512-with-rsa-signature | | | (OID 1.2.840.113549.1.1.13) | +---------------------------------------------------------+ | 11-15 | Reserved..future expansion of RSA signatures | +---------------------------------------------------------+ | 16 | hmacWithSHA256 (OID 1.2.840.113549.2.9) | +---------------------------------------------------------+ | 17 | hmacWithSHA384 (OID 1.2.840.113549.2.10) | +---------------------------------------------------------+ | 18 | hmacWithSHA512 (OID 1.2.840.113549.2.11) | +---------------------------------------------------------+ 7.10. Authenticated Key Metadata +----------+------------------+---------------------------+ | Key | Value | Usage | +----------+------------------+---------------------------+ |INTEGER(0)| BYTE STRING | Indicates the device | | | () | owning the key | +----------+------------------+---------------------------+ 7.11. aSSURE timestamps 7.11.1. Simple timestamps aSSURE uses a variant of the Unix time format for all its timestamps. An aSSURE simple timestamp is an integer that tracks the number of seconds since midnight on Friday January 1st 2010 GMT rather than midnight on January 1st 1970 GMT. This allows a signed 32-bit number to provide a valid timestamp until 2078 rather than 2038. aSSURE_timestamp_secs = unix_timestamp_secs - 1262304000 A simple timestamp is defined in CBOR as: INTEGER timestamp_secs 7.11.2. Precision timestamps If more precision is required, a fractional part may also be provided. This holds the fractional part of the second as a 32-bit value (so the precision is ~233ps). A precision timestamp is defined in CBOR as: Lucas Expires March 17, 2018 [Page 25] Internet-Draft aSSURE Data Security September 2017 ARRAY { INTEGER timestamp_secs INTEGER timestamp_frac } 8. DTLS with aSSURE key identities 8.1. Overview aSSURE uses DTLS for all secure connections due to its low overhead both in code and operation. DTLS supports both certificates and pre-shared keys, but does not cover how the certificate authorities or pre-shared keys are to be securely distributed. This section shows how we extend the basic DTLS standard with additional RFC to provide the functionality required for aSSURE. It also shows how to setup DTLS connections in an aSSURE environment. 8.2. Extension to (D)TLS aSSURE needs to be able to provide the client identity to the server during the DTLS handshake. This would normally be done using X.509 certificates, but aSSURE avoids the complexity and overhead of X.509 certificates so an alternative approach is required. aSSURE provides the client identity to the server using a new TLS extension, "Peer Name Indication" that is lightweight and similar to the "Server Name Indication" extension. 8.2.1. Peer Name Indication TLS does not provide a mechanism for a client to tell a server the name of the client that is connecting before the ServerHello is returned. It may be desirable for clients to provide this information to facilitate secure connections to servers where the ServerHello should vary according to the client identity. In order to provide any of the names, clients MAY include an extension of type "peer_name" in the (extended) client hello. The "extension_data" field of this extension SHALL contain "PeerNameList" where: struct { NameType name_type; select (name_type) { case uuid: UUID; } name; } PeerName; Lucas Expires March 17, 2018 [Page 26] Internet-Draft aSSURE Data Security September 2017 enum { uuid(0), (255) } NameType; opaque UUID[16]; struct { PeerName peer_name_list<1..2^16-1> } PeerNameList; This allows the client to provide its UUID in a compact format to the server. It also allows other client formats to be used in the future. 8.3. Proof of identity by public key clients A typical DTLS handshake uses X.509 certificates to allow both mutual authentication of identity and key exchange to set up the secure connection. aSSURE does not use X.509 certificates for the reasons explained in section 6.1. above so an alternative approach is required to allow mutual authentication and key exchange. aSSURE uses the device API calls to allow the management system to securely provide identity credentials for other peers to the device. An aSSURE device WILL NOT communicate with any peer that has not had the peer identity credentials provided to it by an authorised management system over a secured connection. aSSURE uses the Peer Name Indication extension (see 8.2.1. above) to allow a device to indicate its ID to the peer during the initial connection request. This allows the peer to check that the device is in its list of trusted devices. If the device is not in the list, the peer refuses the connection. Similarly, the server uses the Peer Name Indication extension to provide its ID to the client in the initial connection response. This allows the client to quickly check its database to check that the server is in its list of trusted peers. If the server is not in the list, the client aborts the connection attempt. aSSURE then uses the Raw Public Key Extension defined in RFC-7250 to allow just the public keys to be exchanged between device and peer. Both the device and the peer cross-check the public keys provided in the DTLS handshake against the expected public keys their list of trusted devices. If either device or peer detect a public key mismatch, they abort the handshake. If all checks complete without error, the handshake is allowed to continue normally and the secure connection is established. Lucas Expires March 17, 2018 [Page 27] Internet-Draft aSSURE Data Security September 2017 8.4. Proof of identity by shared secret clients When establishing a secure connection, if either device cannot support public keys, they must use the derived shared secret method of authentication. Derived shared secrets are a weaker form of security than public keys, but if used carefully, can still provide a reasonable level of security. DTLS connections protected by derived shared secrets differ from public key cryptography in that both parties must know the same secret to allow the DTLS handshake to complete. Hence, a derived shared secret can be used to prove a link relationship but not an endpoint identity. The management system will have been provided with a unique derived shared secret for each device - this is provided to the device in the bootstrap configuration so that the device can trust the link relationship from itself to the management system. The management system will then generate a unique derived shared secret for each link that the device needs to establish using its knowledge of the available keys on the devices at each end of the link. The management system will then push that derived shared secret to both devices indicating the peer device ID to which the derived shared secret relates and instruct one of them to act as the client to establish the channel. The client will then attempt to connect to the peer using DTLS. aSSURE uses the Peer Name Indication extension (see 8.2.1. above) to allow a device to indicate its ID to the peer during the initial connection request. This allows the peer to check that the device is in its list of trusted devices. If the device is not in the list, the peer refuses the connection. Similarly, the server uses the Peer Name Indication extension to provide its ID to the client in the initial connection response. This allows the client to quickly check its database to check that the server is in its list of trusted peers. If the server is not in the list, the client aborts the connection attempt. aSSURE then uses the Pre-shared Key Identity Hint Extension defined in RFC-4279 to allow the server to provide the necessary key information to the client. The key information is encoded in Base64 because RFC-4279 recommends that the key information only contains printable characters. The key information will be one of: o The UUID of a key known to both client and server. The UUID is provided as a CBOR BYTE STRING of 16 bytes. o A key definition as in 7.2. above. The client can determine which is provided by inspecting the data. Lucas Expires March 17, 2018 [Page 28] Internet-Draft aSSURE Data Security September 2017 A simple UUID is a CBOR BYTE STRING whilst a key definition is a CBOR ARRAY. The client checks that the indicated (or reference) key is available and appropriate for this connection, derives the secret as appropriate and uses this as the pre-shared key for the DTLS session. The server also derives the secret from the key and uses this as the pre-shared key for the DTLS session. The DTLS handshake then continues as normal and the session is established. 9. Trusted Authority APIs 9.1. Overview The Trusted Authority provides three distinct APIs as follows: o Manufacturer API o Owner API o Bootstrap API The Manufacturer API is used by the manufacturer to upload manufacturing details about each device when it is created. Only the minimum amount of information about the device is uploaded and this information is stored in One-Time Programmable (OTP) memory on the device, so can never be changed. For this reason, the Manufacturing API has no requirement to allow device information to be updated after manufacture, such as during Return Merchandise Authorisation (RMA), because this information can never be changed. The Owner API is used by the device owner to assert ownership of the device, update the device bootstrap configuration and change device ownership. The Bootstrap API is used by the devices themselves to download their bootstrap configuration so that they can connect to their management systems and enter service. 9.2. Manufacturer API The Manufacturer API is used by the manufacturer to upload data about the device when it is manufactured. The manufacturer API is a RESTful interface using JSON over HTTPS with client authentication. Generation of the client key and issuing of the client certificate is out of scope for this document (this information could easily be exchanged via email). Similarly, delivery of the Trusted Authority "Identity Service" certificate to the manufacturer and disclosure of the Manufacturer API URL is also out of scope (again, this information could easily be provided via email). Lucas Expires March 17, 2018 [Page 29] Internet-Draft aSSURE Data Security September 2017 9.2.1. PUT /v1/devices/ After a device is manufactured, the manufacturer builds the device data into a JSON data structure as follows: { "id": "", "bootstrap_server": , "case_string": "", "shared_secret": "" "public_key": "" "parameter_set": "" "capabilities": { // Device bootstrap capabilities "ec_capable": , "rsa_capable": , "sha384_capable": , "sha512_capable": , "aes256_capable": , // Additional capabilities may be added in the future } } If the device uses an RSA or EC key as its device key, the "shared_secret" will not present. If the device is only shared secret capable then the "public_key" will not be present. The JSON data will NEVER have both "shared_secret" and "public_key" fields. All devices must support SHA-256, AES-128 and shared secrets. If the device can support other keys, hashing algorithms or ciphers during bootstrap, these should be indicated here. The manufacturer's production line will have encrypted the device data immediately after the device has been tested. The device data is encrypted using ECIES and the Identity Service public key (which must be a strong Elliptic Curve key). The ECIES configuration uses SHA512 and AES-256. The encrypted data is then provided as a binary payload in the request. No payload is returned. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |201 Created | The new device has been created | +--------------+------------------------------------------+ |403 Forbidden | The manufacturer cannot update the | | | device because it already exists | +--------------+------------------------------------------+ | 503 Service | The device cannot be created at | | Unavailable | this time | +--------------+------------------------------------------+ Only a single device is uploaded in each PUT request, but the client may re-use the HTTPS session to send additional requests. Lucas Expires March 17, 2018 [Page 30] Internet-Draft aSSURE Data Security September 2017 9.2.2. POST /v1/parametersets This allows a manufacturer to upload a parameter set definition. The format of the parameter set definition is TBD. The parameter set is defined in CBOR and provided as the request payload. The parameter set is provided in the configuration data to the Management System to guide the bootstrap data definition as described in 15.2. below. The payload will contain the assigned UUID as a simple ASCII string. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |201 Created | The new parameter set has been created | +--------------+------------------------------------------+ | 503 Service | The parameter set cannot be created at | | Unavailable | this time | +--------------+------------------------------------------+ 9.2.3. PUT /v1/parametersets/ This allows a manufacturer to replace a parameter set definition. The format of the parameter set definition is TBD. The parameter set is defined in CBOR and provided as the request payload. The parameter set is provided in the configuration data to the Management System to guide the bootstrap data definition as described in 15.2. below. No payload is returned. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |201 Created | The new parameter set has been created | +--------------+------------------------------------------+ |403 Forbidden | The manufacturer cannot update the | | | parameter set because it does not exist | | | or belongs to a different manufacturer | +--------------+------------------------------------------+ | 503 Service | The parameter set cannot be created at | | Unavailable | this time | +--------------+------------------------------------------+ Only a single parameter set is uploaded in each POST request, but the client may re-use the HTTPS session to send additional requests. 9.2.4. GET /v1/parametersets/ This allows a manufacturer to download a parameter set definition. Lucas Expires March 17, 2018 [Page 31] Internet-Draft aSSURE Data Security September 2017 The format of the parameter set definition is TBD and is exactly the data as provided in 9.2.2. above. The returned payload is the parameter set data. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |200 OK | The parameter set has been returned | +--------------+------------------------------------------+ |403 Forbidden | The parameter set does not exist or was | | | provided by a different manufacturer | +--------------+------------------------------------------+ 9.3. Owner API The Owner API is used to take ownership of a device, set the bootstrap data for the device and transfer ownership of the device. As with the Manufacturer API, the Owner API is a RESTful interface using JSON over HTTPS with client authentication. 9.3.1. POST /v1/managementsystems This is used by management systems to register with the Owner API. The connection does not require client authentication. Before making this request, the management system should generate a new Elliptic Curve key and associated X.509 certificate signing request (CSR). The management system provides the CSR in DER format as the request payload. The Owner API will immediately issue a certificate for this CSR and return it as the response payload in DER format. All management systems must support both Elliptic Curve and RSA public keys, SHA-256, SHA-512, AES-128 and AES-256 so that they can correctly interoperate with all devices irrespective of the device abilities (or lack of abilities). The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |201 Created | The new management system ID | | | has been created | +--------------+------------------------------------------+ | 503 Service | The management system ID cannot be | | Unavailable | created at this time | +--------------+------------------------------------------+ Lucas Expires March 17, 2018 [Page 32] Internet-Draft aSSURE Data Security September 2017 Note: Some Trusted Authorities may require a username and password to be provided to authenticate this request to prevent attackers trying to overload the system with requests. Alternative validation approaches are also possible. Such extensions are out of scope of this document. Note: The serial number of the issued certificate is used as the "manufacturer ID" in owner management API requests (9.3.4. below and 9.3.5. below). For security reasons, the manufacturer ID should not be predictable so ought to be a large random number (>= 64 bits). 9.3.2. PUT /v1/devices//owner?case_string= This is used by management systems to take ownership of a device. The connection must be authenticated with the issued client certificate. The case identification string from the QR code must be provided as the "case_string" parameter. No payload is provided. No payload is returned and the response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |204 Changed | Ownership has been assigned to this | | | management system | +--------------+------------------------------------------+ |403 Forbidden | The device is owned by a different | | | management system, the wrong case string | | | was provided or the device does not exist| +--------------+------------------------------------------+ 9.3.3. PUT /v1/devices//owner?mgmtid= This is a variant of 9.3.2. above and used by management systems to transfer ownership of a device to a different management system. The connection must be authenticated with the issued client certificate. The serial number of the certificate issued to the new management system must be provided as the "mgmtid" parameter. No payload is provided. No payload is returned and the response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |204 Changed | Ownership has been assigned to the new | | | owner | +--------------+------------------------------------------+ |403 Forbidden | The device is owned by a different | | | management system, or the device | | | does not exist | Lucas Expires March 17, 2018 [Page 33] Internet-Draft aSSURE Data Security September 2017 +--------------+------------------------------------------+ 9.3.4. PUT /v1/devices//owner?case_string= &mgmtid= This is a combination of 9.3.2. and 9.3.3. above. It is used by management systems to take ownership of a device and immediately assign it to a different management system. The connection must be authenticated with the issued client certificate. The case identification string must be provided as the "case_string" parameter and the serial number of the certificate issued to the new management system must be provided as the "mgmtid" parameter. No payload is provided. No payload is returned and the response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |204 Changed | Ownership has been assigned to the new | | | owner | +--------------+------------------------------------------+ |403 Forbidden | The device is owned by a different | | | management system, or the device | | | does not exist | +--------------+------------------------------------------+ 9.3.5. PUT /v1/devices//owner?mgmtid=NULL This is a variant of 9.3.2. above and used by management systems to release ownership of a device. Once a device has been released from ownership, any management system may take ownership of the device if knows the device UUID and case string. The connection must be authenticated with the issued client certificate. No payload is provided or returned and the response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |204 Changed | Ownership has been released | +--------------+------------------------------------------+ |403 Forbidden | The device is owned by a different | | | management system, or the device | | | does not exist | +--------------+------------------------------------------+ 9.3.6. GET /v1/devices//parameterset This is used by management systems to obtain the parameter set required for the device. The connection must be authenticated with the issued client certificate. Lucas Expires March 17, 2018 [Page 34] Internet-Draft aSSURE Data Security September 2017 No payload is provided. If the request is successful, the parameter set will be returned in the payload. The format of the parameter set data is TBD. Note that this returns the same data as 9.2.4. above but references the device not the parameter set UUID itself. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |200 OK | The device parameter set has | | | been returned | +--------------+------------------------------------------+ |403 Forbidden | The device is owned by a different | | | management system, or the device | | | does not exist | +--------------+------------------------------------------+ 9.3.7. PUT /v1/devices//bootstrap This is used by management systems to set the bootstrap data for a device. The connection must be authenticated with the issued client certificate. The bootstrap data is provided as a binary payload. The format of the device bootstrap data is device dependent and detailed in the device parameter set returned in 9.3.6. above. No payload is returned. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |204 Changed | The device bootstrap data has been | | | accepted | +--------------+------------------------------------------+ |403 Forbidden | The device is owned by a different | | | management system, or the device | | | does not exist | +--------------+------------------------------------------+ 9.3.8. GET /v1/devices//bootstrap This is used by management systems to return the bootstrap data for a device. The connection must be authenticated with the issued client certificate. No payload is provided. If successful, the bootstrap data is returned as a binary payload. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ Lucas Expires March 17, 2018 [Page 35] Internet-Draft aSSURE Data Security September 2017 |200 OK | The device bootstrap data has | | | been returned | +--------------+------------------------------------------+ |403 Forbidden | The device is owned by a different | | | management system, or the device | | | does not exist | +--------------+------------------------------------------+ 9.4. Bootstrap API The Bootstrap API is used by the device to download its bootstrap data. The Bootstrap API is a RESTful interface using CBOR and CoAP over DTLS with client authentication. 9.4.1. GET /v1/devices//bootstrap This is used by the device to obtain its bootstrap data. The DTLS connection must be authenticated with the device key as described in section 8. above. The in the URI must belong to the device authenticated during the DTLS handshake. No payload is provided. If successful, the bootstrap data is returned as a binary payload. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |2.05 | The device bootstrap data has | | | been returned | +--------------+------------------------------------------+ |4.03 | The device is not allowed to access the | | | requested bootstrap data, or the device | | | does not exist | +--------------+------------------------------------------+ 10. Device Management API The device API is used by the management system to control the aSSURE functionality in the device. Like the Bootstrap API, the Device API is RESTful using CBOR and CoAP over DTLS. The transport of the DTLS messages will vary depending on the device type and installation - examples of different physical and/or network layers are provided in section 11. below. All requests on the Device Management API must be made over authenticated DTLS connections, known as "channels". The definition of channels is in 4.2. above. The Management API is used to define what privileges are assigned to each channel. These privileges are: +--------------+------------------------------------------+ | Privilege | Description | Lucas Expires March 17, 2018 [Page 36] Internet-Draft aSSURE Data Security September 2017 +--------------+------------------------------------------+ | Key | The connection is allowed to create, | | Management | reconfigure and delete keys on the | | | device. | +--------------+------------------------------------------+ | Channel | The connection is allowed to create, | | Management | reconfigure and delete channel | | | definitions on the device. | +--------------+------------------------------------------+ | System | The connection is allowed to instruct | | Management | the device to perform system level | | | actions such as bootstrap or reboot. | +--------------+------------------------------------------+ 10.1.1. PUT /v1/keys/ This request requires "Key Management" privileges on the requesting channel. This instructs the device to add the indicated key to its key store. The key is provided in the payload as a CBOR object as defined in 7.4. above. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.01 | The key has been created | +----------+----------------------------------------------+ | 2.04 | The key already exists on the device | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage keys | +----------+----------------------------------------------+ | 4.13 | The device has no space to add more keys | +----------+----------------------------------------------+ 10.1.2. POST /v1/keys/generate?type=&persistent= This request requires "Key Management" privileges on the requesting channel. This instructs the device to create a new key of the indicated type in its key store. +----------+----------------------------------------------+ | Type | Description | +----------+----------------------------------------------+ | 0 | RSA 2048 bits | +----------+----------------------------------------------+ | 1 | Elliptic Curve (NIST P-256) | +----------+----------------------------------------------+ Lucas Expires March 17, 2018 [Page 37] Internet-Draft aSSURE Data Security September 2017 | 2 | Elliptic Curve (NIST P-384) | +----------+----------------------------------------------+ | 3 | Elliptic Curve (NIST P-521) | +----------+----------------------------------------------+ If the persistent flag is not set, the key will only exist in RAM and will be lost when the device next reboots or loses power. If the creation is successful, the device will create an authenticate key as defined in 7.4. above. The device will add its own ID in the MAP field and create the signature using its device key. The authenticate key is then returned in the response payload. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.01 | The key has been created | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage keys | +----------+----------------------------------------------+ | 4.13 | The device has no space to add more keys | +----------+----------------------------------------------+ | 5.01 | Unsupported key type | +----------+----------------------------------------------+ 10.1.3. GET /v1/keys/ This request requires "Key Management" privileges on the requesting channel. This instructs the device to return the indicated key in its key store. The key is returned in the payload as a CBOR object as defined in 7.4. above. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.05 | The key information has been returned | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | return keys | +----------+----------------------------------------------+ | 4.04 | The key does not exist | +----------+----------------------------------------------+ 10.1.4. DELETE /v1/keys/ This request requires "Key Management" privileges on the requesting channel. Lucas Expires March 17, 2018 [Page 38] Internet-Draft aSSURE Data Security September 2017 This instructs the device to delete the indicated key from its key store. The key must not be in use by any channel nor must it be used as a reference key by any other keys. The device will not permit any key defined in the bootstrap data to be deleted. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.02 | The key has been deleted or did not exist | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage keys | +----------+----------------------------------------------+ | 4.03 | The key is in use and cannot be deleted at | | | this time or is not allowed to be deleted | +----------+----------------------------------------------+ 10.1.5. GET /v1/keys This request requires "Key Management" privileges on the requesting channel. This instructs the device to list the keys in its key store. The key list is returned as a CBOR array of authenticated keys as defined in 7.4. above. For security reasons, no private keys will be disclosed. Instead, if the device has the private data for the key, the string "PRESENT" will be returned as the "private_key" byte string. If the device does not have the private data for the key, the "private_key" byte string will be zero length. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.05 | The key list has been returned | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage keys | +----------+----------------------------------------------+ 10.1.6. PUT /v1/channels This request requires "Channel Management" privileges on the requesting channel. This instructs the device to create a new channel. The channel configuration will be provided in the request payload in CBOR format as below: ARRAY { Lucas Expires March 17, 2018 [Page 39] Internet-Draft aSSURE Data Security September 2017 BYTE STRING local_key_id BYTE STRING peer_key_id // Zero length if the same as // local_key_id ARRAY { BOOLEAN persistent_across_reboots BOOLEAN open_immediately BOOLEAN channel_management_privilege BOOLEAN system_management_privilege BOOLEAN key_management_privilege // Additional configuration flags may follow } ARRAY { INTEGER address_type // Address content, structure varies depending on // address_type } } The format of the address content depends on the target device network and physical layer. As support for additional network and physical layers are added, additional address types and associated address content format will be defined. The list of assigned address types is in 12.4. below. The assigned channel ID will be returned in the response payload as a CBOR integer. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.01 | The channel has been created | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage channels | +----------+----------------------------------------------+ | 4.13 | The device has no space to add more channels | +----------+----------------------------------------------+ 10.1.7. PUT /v1/channels/ As per 10.1.6. above, "PUT /v1/channels" but where the channel ID is explicitly provided. The request and response payload formats are unchanged. Additional response codes may be: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.04 | The channel already exists | +----------+----------------------------------------------+ Lucas Expires March 17, 2018 [Page 40] Internet-Draft aSSURE Data Security September 2017 10.1.8. PUT /v1/channels//open This request requires "Channel Management" privileges on the requesting channel. This instructs the device to open the indicated channel. No request payload is provided. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.04 | The device will try to open the channel | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage channels | +----------+----------------------------------------------+ | 4.04 | The channel does not exist | +----------+----------------------------------------------+ Note that a 2.04 response DOES NOT mean that the channel has been successfully opened. Instead, it means that the device WILL TRY to open the channel. This may take some time and the status can be monitored with the channel status request in 10.1.11. below. 10.1.9. PUT /v1/channels//close This request requires "Channel Management" privileges on the requesting channel. This instructs the device to close the indicated channel. No request payload is provided. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.04 | The device will try to close the channel | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage channels | +----------+----------------------------------------------+ | 4.04 | The channel does not exist | +----------+----------------------------------------------+ Note that a 2.04 response DOES NOT mean that the channel has been successfully closed. Instead, it means that the device WILL TRY to close the channel. This may take some time and the status can be monitored with the channel status request in 10.1.11. below. 10.1.10. DELETE /v1/channels/ Lucas Expires March 17, 2018 [Page 41] Internet-Draft aSSURE Data Security September 2017 This request requires "Channel Management" privileges on the requesting channel. This instructs the device to delete the indicated channel, closing it automatically if it is currently open. No request payload is provided. The device will not permit any channel defined in the bootstrap data to be deleted. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.02 | The channel has been deleted or does not | | | exist | +----------+----------------------------------------------+ | 2.04 | The channel was open so will be cleanly | | | closed then deleted | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage channels | +----------+----------------------------------------------+ | 4.03 | The channel is not allowed to be deleted | +----------+----------------------------------------------+ Note that after a 2.04 response the client can poll the channel status using the "GET" request as in 10.1.11. below. If the channel is still being closed, the response will be a 2.05 with status = 4. As soon as the close completes, the channel will be deleted and the "GET" request in 10.1.11. below will return 4.04 because the channel no longer exists. 10.1.11. GET /v1/channels/ This request requires "Channel Management" privileges on the requesting channel. This requests the device to return the configuration and status of the channel. No request payload is provided. The channel configuration and status will be provided in the request payload in CBOR format as below: ARRAY { ARRAY { // Configuration structure as in 10.1.6. above } ARRAY { INTEGER channel_id INTEGER state // Additional status flags may follow } } Lucas Expires March 17, 2018 [Page 42] Internet-Draft aSSURE Data Security September 2017 The "status" integer will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 0 | The channel is closed | +----------+----------------------------------------------+ | 1 | The channel is requested to be opened | +----------+----------------------------------------------+ | 2 | The channel handshake is in progress | +----------+----------------------------------------------+ | 3 | The channel is open | +----------+----------------------------------------------+ | 4 | The channel is being closed | +----------+----------------------------------------------+ | 10 | The channel handshake failed because the | | | peer did not answer | +----------+----------------------------------------------+ | 11 | The channel handshake failed because the | | | peer provided the wrong key ID | +----------+----------------------------------------------+ | 12 | The channel handshake failed because the | | | peer failed authentication | +----------+----------------------------------------------+ | 13 | The channel has experienced some other error | +----------+----------------------------------------------+ The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.05 | The channel information has been returned | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage channels | +----------+----------------------------------------------+ | 4.04 | The channel does not exist | +----------+----------------------------------------------+ 10.1.12. GET /v1/channels This request requires "Channel Management" privileges on the requesting channel. This requests the device to return the configuration and status of all channels. No request payload is provided. The information is returned as a CBOR array of channel responses as defined in 10.1.11. above. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.05 | The configuration and status for all | Lucas Expires March 17, 2018 [Page 43] Internet-Draft aSSURE Data Security September 2017 | | channels has been returned | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage channels | +----------+----------------------------------------------+ 10.1.13. PUT /v1/reboot This request requires "System Management" privileges on the requesting channel. This instructs the device to reboot. The device will reboot after returning the response. No request payload is provided and no response payload is returned. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.04 | The device is about to reboot | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage the system | +----------+----------------------------------------------+ 10.1.14. PUT /v1/shutdown This request requires "System Management" privileges on the requesting channel. This instructs the device to shut down. The device will shut down after returning the response. No request payload is provided and no response payload is returned. The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.04 | The device is about to shutdown | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage the system | +----------+----------------------------------------------+ 10.1.15. PUT /v1/bootstrap This request requires "System Management" privileges on the requesting channel. This instructs the device to perform an aSSURE bootstrap. The device will bootstrap after returning the response. No request payload is provided and no response payload is returned. Lucas Expires March 17, 2018 [Page 44] Internet-Draft aSSURE Data Security September 2017 The response code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.04 | The device is about to bootstrap | +----------+----------------------------------------------+ | 4.01 | The channel does not have privileges to | | | manage the system | +----------+----------------------------------------------+ 10.1.16. GET /v1/ping This request requires no privileges on the requesting channel. This is used to check that the device is online and able to respond to requests. A payload may be provided. The device will respond with the same payload (or as much of the payload as the device can return if it is a constrained device). The response code will be: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.05 | Ping response | +----------+----------------------------------------------+ 10.1.17. GET /v1/info This request requires no privileges on the requesting channel. This is used to return basic information about the device. The device will return the CBOR structure below: ARRAY { BYTE STRING device_id BYTE STRING device_mac_address TEXT STRING device_manufacturer TEXT STRING device_product_code TEXT STRING device_serial_number TEXT STRING device_build_date TEXT STRING software_manufacturer TEXT STRING software_product_code TEXT STRING software_version } The only field that must be present is the device_id. All other fields may be zero length if the device is unable to provide them for any reason. The response code will be: Lucas Expires March 17, 2018 [Page 45] Internet-Draft aSSURE Data Security September 2017 +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.05 | Information returned | +----------+----------------------------------------------+ 11. Management Server API 11.1. Overview The management server must support the registration and presence APIs. The registration API is used to allow devices to be registered with the management system. The presence API is used by devices after bootstrap to inform the management system of their presence on the network. 11.2. Registration API The Registration API is used to register the device with the management system when it is installed. The Registration API is a RESTful interface using JSON over HTTPS. The authentication behaviour is determined by the Management Server implementation but either username + passphrase or client certificates are recommended. 11.2.1. POST /v1/devices/?case_string= This is used to register the indicated device UUID with the management system. The case string is provided to prove the device is physically present. The UUID and case string would normally come from a QR code or similar attached to the device (use of an RFID is not recommended as the source for obvious security reasons). No payload is returned. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ |201 Created | The new device has been registered | +--------------+------------------------------------------+ | 401 | The device cannot be registered because | | Unauthorised | it already exists | +--------------+------------------------------------------+ | 503 Service | The device cannot be registered | | Unavailable | at this time | +--------------+------------------------------------------+ Only a single device is uploaded in each POST request, but the client may re-use the HTTPS session to send additional requests. Lucas Expires March 17, 2018 [Page 46] Internet-Draft aSSURE Data Security September 2017 11.2.2. POST /v1/devices//replace?uuid= This is used to tell the management system that the indicated device with UUID has been replaced by the device with UUID . For example, this would occur when a device has failed and a maintenance engineer has replaced it. The management system can then update its database, etc. to allow the new device to "seamlessly replace" the old device (e.g. by applying the old device configuration to the new device). For security reasons, the management system should immediately disable the old device as this call indicates that the old device is no longer in use. The new device must be registered with the call in 11.2.1. above before performing this call to replace the old device. No payload is returned. The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ | 201 Created | The new device has replaced the old one | +--------------+------------------------------------------+ | 401 | The old device does not exist, the client| | | is not allowed to update the state of the| | | old device, the new device does not exist| | | or the client is not allowed to update | | | the state of the new device. | +--------------+------------------------------------------+ | 503 Service | The device cannot be replaced | | Unavailable | at this time | +--------------+------------------------------------------+ 11.2.3. GET /v1/devices//status This is used to get the status of the device. The registration, configuration, bootstrap and presence of a device may take some time. A registration client may obtain the status of the device here to check if the device has entered service. If successful, the payload is a JSON structure: { status: , description: "" } 11.2.4. GET /v1/devices//info This is used to get the information for the device. This is only available after the device has sent is presence message to the management system. If successful, the payload is a JSON structure with the same Lucas Expires March 17, 2018 [Page 47] Internet-Draft aSSURE Data Security September 2017 information as in 10.1.17. above: { "device_id": "", "device_mac_address": "", "device_manufacturer": "...", "device_product_code": "...", "device_serial_number": "...", "device_build_date": "...", "software_manufacturer": "...", "software_product_code": "...", "software_version": "..." } The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ | 200 OK | The device information has been returned | +--------------+------------------------------------------+ | 401 | The client is not authorised to access | | Unauthorised | this device | +--------------+------------------------------------------+ | 503 Service | Device information cannot be returned at | | Unavailable | this time | +--------------+------------------------------------------+ Only a single device response is permitted per GET request, but the client may re-use the HTTPS session to send additional requests. 11.3. Presence API The Presence API is used by the device to indicate to the management system that its bootstrap process has completed and it is now online in the network. Like the Bootstrap API and Device Management APIs, the Presence API is RESTful using CBOR and CoAP over DTLS. 11.3.1. PUT /v1/devices//info This is used by the device to confirm it is active and has completed its bootstrap. The device provides the same CBOR structure as in 10.1.17. above as the request payload. No payload is returned. The response code will be one of: +-------------+-------------------------------------------+ | Response | Description | +-------------+-------------------------------------------+ | 2.01 Created| The device presence has been acknowledged | Lucas Expires March 17, 2018 [Page 48] Internet-Draft aSSURE Data Security September 2017 +-------------+-------------------------------------------+ | 4.01 | The device has attempted to provide | |Unauthorized | information for a different device | +-------------+-------------------------------------------+ 11.3.2. PUT /v1/devices//goodbye This is used by the device to indicate it is deliberately going offline. It will send this to all connected management systems. The device will provide a single INTEGER in CBOR format to indicate the reason. +---------+-----------------------------------------------+ | Value | Reason | +---------+-----------------------------------------------+ | 0 | Device is shutting down | +---------+-----------------------------------------------+ | 1 | Device has been instructed to reboot by | | | Management System | +---------+-----------------------------------------------+ | 2 | Device has been instructed to bootstrap by | | | Management System | +---------+-----------------------------------------------+ | 3 | Device has been instructed to reboot by | | | local controls (e.g. button) | +---------+-----------------------------------------------+ | 4 | Device has been instructed to bootstrap by | | | local controls (e.g. button) | +---------+-----------------------------------------------+ No payload is returned. The response code will be one of: +-------------+-------------------------------------------+ | Response | Description | +-------------+-------------------------------------------+ | 2.04 Changed| The device goodbye has been acknowledged | +-------------+-------------------------------------------+ | 4.01 | The device has attempted to provide | |Unauthorized | information for a different device | +-------------+-------------------------------------------+ 11.4. Miscellaneous 11.4.1. GET /v1/timestamp This is used to get the current time from a trusted source. A device may use this to set its clock without having to include support for other protocols such as NTP. This request may be made by any client with or without authentication. No payload is provided. The response is a timestamp in CBOR as defined in 7.11. above (both integer and fractional parts). Lucas Expires March 17, 2018 [Page 49] Internet-Draft aSSURE Data Security September 2017 The response code will be one of: +--------------+------------------------------------------+ | Response | Description | +--------------+------------------------------------------+ | 200 OK | The timestamp has been returned | +--------------+------------------------------------------+ | 503 Service | Device information cannot be returned at | | Unavailable | this time | +--------------+------------------------------------------+ 12. Physical / Network Layer Implementations 12.1. BACnet aSSURE traffic is fully compatible with existing BACnet traffic and is identified as Network Control messages using Message Types 0x80 - 0x82 and Vendor ID 0x_TBD_. Message Types 0x80 through 0x82 are used to identify the aSSURE traffic as belonging to one of three logical groups. +-------------+-------------------------------------------+ | Message Type| Description | +-------------+-------------------------------------------+ | 0x80 | aSSURE Bootstrap | +-------------+-------------------------------------------+ | 0x81 | aSSURE Secure Management Channels | +-------------+-------------------------------------------+ | 0x82 | aSSURE Secure Data Channels | +-------------+-------------------------------------------+ When an address is indicated in a CBOR message, the address format is: ARRAY { INTEGER 0 // Address type 1 = BACnet INTEGER net BYTE STRING addr // "len" is the BYTE STRING length } If the "net" field is a NULL (CBOR Major: 7, Value: 22 => 0xF6) rather than an INTEGER (CBOR Major: 0), this indicates a local network address. When creating the BACnet NPDU, the NPDU destination specifier for that address would not be present. 12.1.1. aSSURE Bootstrap The aSSURE Bootstrap messages are used to identify the bootstrap gateways on the BACnet network and assign a secure data channel for communication with the bootstrap server. This traffic cannot be secured because it happens BEFORE the bootstrap data has been Lucas Expires March 17, 2018 [Page 50] Internet-Draft aSSURE Data Security September 2017 received so the device has no keys for communicating with peers on the local network. All Insecure Control Messages are RESTful using CoAP in the NSDU part of an NPDU frame. They are therefore independent of any specific BACnet LLC such as BACnet IP or BACnet MS/TP. 12.1.1.1. GET /v1/gateway/ This message is broadcast on BACnet to discover the best gateway capable of routing traffic to the indicated bootstrap server. No payload is provided. All gateways capable of routing traffic to the broadcast server should respond with their assigned priority for handling traffic (or zero if it has not been explicitly set). This means that a device may receive multiple replies to its GET message and it should be able to handle this. The device should wait a reasonable time (e.g. 5 seconds) for all replies to be received and should pick the gateway with the lowest priority value. If multiple gateways respond with the same lowest priority value, a gateway should be chosen at random. If no gateways respond, the device should backoff and retry. The gateway response should be a 2.00 status code with a CBOR payload containing the following content: INTEGER priority 12.1.1.2. POST /v1/gateway/channel?server= This message is sent to the chosen gateway that responded to the discovery message described in 12.1.1.1. above. The gateway should assign a channel that routes messages to the indicated bootstrap server. No payload is provided. If successful, the gateway response should be a CBOR payload with the following content: INTEGER channel_id BYTE STRING token The cookie should be a random string of at least 4 bytes. The device must provide this token when closing the channel. The status code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.01 | The channel has been created | +----------+----------------------------------------------+ | 4.04 | The gateway cannot find a route to the | Lucas Expires March 17, 2018 [Page 51] Internet-Draft aSSURE Data Security September 2017 | | indicated bootstrap server | +----------+----------------------------------------------+ | 5.03 | The gateway cannot create the channel at | | | this time | +----------+----------------------------------------------+ 12.1.1.3. DELETE/v1/gateway/channel/?token= This message is sent to the chosen gateway that responded to the discovery message described in 12.1.1.1. above. The gateway should assign a channel that routes messages to the indicated bootstrap server. No payload is provided and no payload is returned. The device must offer the token returned by the gateway in the channel assign request in 12.1.1.2. above and the DELETE request must come from the same network address as the POST request. The status code will be one of: +----------+----------------------------------------------+ | Response | Description | +----------+----------------------------------------------+ | 2.02 | The channel has been deleted | +----------+----------------------------------------------+ | 4.01 | The device is not allowed to delete this | | | channel | +----------+----------------------------------------------+ 12.1.2. aSSURE Secure Management Channels These messages are used for encrypted aSSURE-protected DTLS sessions accessing the Device Management API defined in 10. above. All messages on the aSSURE Secure Management Channel have the following CBOR structure: INTEGER channel_id BYTE STRING dtls_data 12.1.3. aSSURE Secure Data Channels These messages are used for all other aSSURE-protected DTLS session such as secure bootstrap or peer-to-peer channels. All messages on the aSSURE Secure Data Channel have the following CBOR structure: INTEGER channel_id BYTE STRING dtls_data 12.2. IP When deployed on IP networks, aSSURE traffic uses UDP port TBD for Secure Management Channels and UDP port TBD for Secure Data Lucas Expires March 17, 2018 [Page 52] Internet-Draft aSSURE Data Security September 2017 Channels. The UDP payload is the DTLS data. The channel ID is inferred from the local port and remote address and port. When compared to BACnet, the "aSSURE Bootstrap" messages are not required because an IP network is already able to route traffic directly to the bootstrap servers without the explicit establishment of a channel. The device is assumed to be capable of DHCP and DNS to obtain a local IP address, determine the subnet gateway and resolve the bootstrap server FQDN. When an address is indicated in a CBOR message, the address format is: ARRAY { INTEGER 1 // Address type 1 = IP BYTE STRING remote_addr // 4 bytes for IPv4,network byte order //16 bytes for IPv6,network byte order INTEGER local_port // Local UDP port, 0=any INTEGER remote_port // Remote UDP port } 12.2.1. Bootstrap Server FQDN The bootstrap server ID can be converted to a Fully Qualified Domain Name (FQDN) by suffixing the decimal value of the ID with the string ".*TBD*.net". Similarly, an aSSURE bootstrap server FQDN can be converted to the server ID by reversing the process. 12.3. Bluetooth Bluetooth implementations should use the "Internet Protocol Support Profile" to allow the device to send and receive IPv6 traffic. When an address is indicated in a CBOR message, the address format should be type 1 as in 12.2. above. When a Bluetooth MAC address is specifically indicated in a CBOR message, the address format is: ARRAY { INTEGER 2 // Address type 2 = Bluetooth BYTE STRING mac // MAC address, 6 bytes } In all other respects, the Bluetooth implementation follows the "IP" implementation as in 12.2. above. 12.4. Assigned address types +-------------+-------------------------------------------+ | Address Type| Description | +-------------+-------------------------------------------+ | 0 | BACnet NPDU address | Lucas Expires March 17, 2018 [Page 53] Internet-Draft aSSURE Data Security September 2017 +-------------+-------------------------------------------+ | 1 | Destination IP address and UDP ports | +-------------+-------------------------------------------+ | 2 | Bluetooth MAC address | +-------------+-------------------------------------------+ 13. DTLS Connection Configuration Examples 13.1. Example Topology *********** *********** +++++++++++ +Device G +<-ec-->*Device A *<-ec-->*Device B * +++++++++++ *********** *********** ^ ^ ^ | ^ / ^ | | \ / | \ R | e e \ e e s S R c c R c c s A S | | SA-----RSA-------RS \/ A | e / | A/\ | e c-ec---/-e e /\ \ R c e c c / \ s S | c \ | / \ s A | / \ | / \ \ | v v v v v v v v *********** OOOOOOOOOOOO +++++++++++ * * oManagemento + + *Device F *--ec->o System o<-RSA--+Device C + *********** OOOOOOOOOOOO +++++++++++ ^ ^ ^ ^ ^ | / | \ | | / | \ | s / s \ s s ss-/ s \-ss s | / | \ | | / | \ | | / | \ | _____v_/_ _________ _\_v_____ / \ / \ / \ |Device E |<--ss->|Device E |<-ss-->|Device D | |Service X| |Service Y| | | \________ / \_________/ \_________/ *** - (Device A & F) Elliptic Curve and Shared Secret Capable +++ - (Device C) RSA and Shared Secret Capable *** _ (Device G) Elliptic Curve, RSA and Shared Secret Capable +++ (EC Device Key) +++ _ (Device B) Elliptic Curve, RSA and Shared Secret Capable *** (RSA Device Key) ___ - (device D and E) Only Shared Secret Capable (Shared Secret Device Key) Lucas Expires March 17, 2018 [Page 54] Internet-Draft aSSURE Data Security September 2017 "ec", "ss", "RSA" are the channels DTLS Connection Example Topology 13.2. Elliptic Curve device . Elliptic Curve device e.g. Device A . Device F Both endpoints have Elliptic Curve keys so no additional keys need to be created. Each endpoint is sent a channel definition indicating the local device key, the peer device key, the peer address and the privileges for the channel. 13.3. Elliptic Curve device . RSA device We cannot use the two device keys to directly secure the DTLS connection. There are three possible solutions to allow a secure link. These are presented in the order of most to least preferred. 13.3.1. Option 1 - Issue EC key to RSA device e.g. Device A . Device B If the RSA device can support Elliptic Curve keys, then a new Elliptic Curve key should be created on (or issued to) the RSA device by the Management System. The Management System should sign the new key as assigned to the device. Now both devices have an EC key, so 13.2. above can be followed. 13.3.2. Option 2 - Issue RSA key to EC device e.g. Device C . Device G If the EC device can support RSA keys, then a new RSA key should be created on (or issued to) the EC device by the Management System. The Management System should sign the new key as assigned to the device. Now both devices have an RSA key, so 13.5. below can be followed. 13.3.3. Option 3 - Issue Shared Secret to both devices e.g. Device A . Device C Shared secrets must be used, so 13.7. below is followed. 13.4. Elliptic Curve device . Shared Secret device e.g. Device F . Device E (Service X) Shared secrets must be used, so 13.7. below is followed. 13.5. RSA device . RSA device e.g. Device B . Device C Both endpoints have RSA key so no additional keys need to be Lucas Expires March 17, 2018 [Page 55] Internet-Draft aSSURE Data Security September 2017 created. Each endpoint is sent a channel definition indicating the local device key, the peer device key, the peer address and the privileges for the channel. 13.6. RSA device . Shared Secret device e.g. Device C . Device D Shared secrets must be used, so 13.7. below is followed. 13.7. Shared Secret device . Shared Secret device e.g. Device D . Device E (Service Y) The management system must issue a new shared secret (called the "Channel Key") to both devices to identify the channel. Each endpoint is sent a channel definition indicating the Channel Key, the peer address and the privileges for the channel. Lucas Expires March 17, 2018 [Page 56] Internet-Draft aSSURE Data Security September 2017 14. Message Sequence Diagrams 14.1. Manufacturing Flow +------+ +--------+ +--------+ +--------+ +------------+ +---------+ |DEVICE| | MAKER | | MAKER | |IDENTITY| |REGISTRATION| |BOOTSTRAP| | | | | |GATEWAY | | SERVER | | SERVER | | SERVER | +------+ +--------+ +--------+ +--------+ +------------+ +---------+ | | | | | | []<--UUID--| | | | | [Key Generation] | | | | []UUID+KEY-> | | | | | []POST | | | | | []/v1/devices->[] | | | | [] []-CheckDeviceExists()--->[] | | [] [] | [] | | [] []<-------FALSE-----------[] | | [] [] | | | | [] []-----CreareDevice()---->[] | | [Key] [] | [] | | [Encryption] []<--------ACK------------[] | | [] [] | | | | [] []--------------CreateDevice()--------->[] | [] [] | | [] | [] []<-----------------ACK-----------------[] | [] [] | | | | [] []SUBMIT device data | | | [] []--->| | | | []<201 Created-[] [] | | | | [Key Decryption] | | | | [Bootstrap and Registration Identity] | | | [Generation] | | | | []ISSUE device bootstrap data---->| | | [] | | | | []ISSUE device | | | | | registration | | | | | data------->| | | | | | | | | | [] [] | | | IMPORT IMPORT | | | data data | | | [] [] | | | | | | | | Ready for Ready for | | | device owner data | | | registration upload | | | | | Manufacturing Flow Sequence Diagram Lucas Expires March 17, 2018 [Page 57] Internet-Draft aSSURE Data Security September 2017 14.2. Management System Preparation +------------+ +-------+ | MANAGEMENT | | OWNER | | SYSTEM | |GATEWAY| +------------+ +-------+ | | [] | Certificate | Generation | [] POST | [] /v1/managementsystems | []------------------------------>[] [] [] [] 201 Created UUID [] []<------------------------------[] [] | | | Registration of the Management System with the Trusted Authority Management System Preparation Sequence Diagram Lucas Expires March 17, 2018 [Page 58] Internet-Draft aSSURE Data Security September 2017 14.3. Device Registration +------+ +---------+ +----------+ +-------+ +---------+ +-----------+ |DEVICE| |INSTALLER| |MANAGEMENT| | OWNER | |BOOTSTRAP| REGISTRATION| | | | | | SERVER | |GATEWAY| | SERVER | | SERVER | +------+ +---------+ +----------+ +-------+ +---------+ +-----------+ | | | | | | [Installed | | | | | On site ] | | | | | | | | | | | |------->[] | | | | | QR Code[]------------>[] | | | | scanned[] Upload UUID [] | | | | [] and case ID [] | | | | [] [] PUT | | | [] []/v1/devices//owner | | | [] []---------->[] | | | [] [] [] Set DeviceOwner() | | [] [] []------------------------>[] | [] [] [] ACK [] | [] [] []<------------------------[] | [] [] 200 OK [] | | | [] []<----------[] | | | [] ACK [] | | | | []<------------[] | | | | | | | | | | | | | | | Registration of the device with the management systems Device Registration Sequence Diagram Lucas Expires March 17, 2018 [Page 59] Internet-Draft aSSURE Data Security September 2017 14.4. Device Ownership State Machine O | | | V +------------+ | UNOWNED | | |<----------------- +------------+ | | | | | |POST |POST |/v1/devices//owner |/v1/devices//release | | V | +------------+ | | OWNED | | ------->| |------------------ | +------------+ | | | POST | ---------- /v1/devices//transfer Device Ownership State Machine Lucas Expires March 17, 2018 [Page 60] Internet-Draft aSSURE Data Security September 2017 14.5. Device Configuration and Bootstrap +------+ +----------------+ +----------+ +----------+ +------------+ |DEVICE| | MANAGEMENT | |OWNER | |BOOTSTRAP | |REGISTRATION| | | | SYSTEM | |GATEWAY | | SERVER | | SERVER | +------+ +----------------+ +----------+ +----------+ +------------+ | | | | | | [Device Registration | | | | Completed] | | | | [] | | | | [] GET | | | | []/v1/devices//configuration | | | []------------------->[] | | | [] [] | | | [] []GetDeviceData() | | | [] []-------------->[]GetDeviceOwner() | [] [] []------------>[] | [] [] [] [Owner] [] | [] [] []<------------[] | [] [] [data] [] | | [] []<--------------[] | | [] [] | | | [] 200 OK [data] [] | | | []<-------------------[] | | | [] | | | | | | | | [Power | | | | Applied] | | | | | | | | | [] GET /v1/devices//bootstrap | | []---------------------------------------------->[] | [] | | [] | [] | 200 OK [image] | [] | []<----------------------------------------------[] | [] | | | | [Validate and | | | decrypt bootstrap | | | image] | | | | [] | | | | [Apply bootstrap | | | Image] | | | | [] | | | | []PUT /v1/devices//info | | | []------->[] | | | [] [] | | | []<-------[] | | | | | | | | | | | | | Device Configuration and Bootstrap Sequence Diagram Lucas Expires March 17, 2018 [Page 61] Internet-Draft aSSURE Data Security September 2017 14.6. Device Configuration and Bootstrap (Walled Garden) +------+ +-------+ +-------+ +-------+ +-------+ +------+ +--------+ |DEVICE| |WALLED | |WALLED | |MANAGE | |OWNER | |BOOT | REG | | | |BOOT | |MANAGE | |SYSTEM | |GATEWAY| |SERVER| |SERVER | +------+ +-------+ +-------+ +-------+-+-------+ +------+ +--------+ | | |[Device Reg Done] | | | | | | [] | | | | | | [-GET------>] | | | | | [] ?/config[] [] | | | | [] [-GetDevData ] | | | | [] []---------->] | | | | [] [] [GetDevOwner | | | [] [] [--------->] | | | [] [] [] owner [] | | | [] [] data [<---------] | | | [] 200 OK []<----------] [] | | | []<---------] [] | | | | [] [] | | | | (Build Bootstrap Image)| | | | | | [] | | | | |<------------------[]EXPORT device bootstrap data | | | |<-----[]EXPORT device management data | | [] [] | | | | | IMPORT IMPORT | | | | | bootstrap data management data | | | | [] [] | | | | | | | | | | | [Power Applied] | | | | | [] | | | | | | [-GET----->[] | | | | | []?/bootstrap | | | | | [] [] | | | | | [] 200 OK [] | | | | | []<---------] | | | | | [] (image) [] | | | | | [] | | | | | [Validate and decrypt | | | | | Bootstrap image] | | | | | [Apply bootstrap image] | | | | | [] | | | | | | [] | [] | | | | []-POST ?/info---------->] | | | | [] | [] | | | | []<----------------------] | | | | [] | [] | | | | | | | | | | | ?/ is /v1/devices// Configuration of the device to connect to the management system Device Configuration and Bootstrap Sequence Diagram (Walled Garden) Lucas Expires March 17, 2018 [Page 62] Internet-Draft aSSURE Data Security September 2017 14.7. Device Change Owner +------+ +--------+ +--------+ +--------+ +----------+ +------------+ |DEVICE| | MAKER | | MAKER | |OWNER | |BOOTSTRAP | |REGISTRATION| | | |SYSTEM A| |SYSTEM B| |GATEWAY | | SERVER | | SERVER | +------+ +--------+ +--------+ +--------+ +----------+ +------------+ | | | | | | []<-data->[] []---GET--->] | | [] [] []?/configuration | | [] [] [] [] | | [] [] [] []GetDeviceData() | [] [] [] []----------->[]GetDeviceOwner() [] [] [] [] []----------->[] [] [] [] [] [] [Mgmt B] [] [] [] [] []UNAUTHORISED[]<-----------[] [] [] [] 403 []<-----------[] | [] [] []<--------[] | | [] [] | Forbidden| | | [] [] PUT | | | | [] []------------------------>] | | [] []?/transfer?mgmtid=$MgmtB[] SetDeviceOwner("Mgmt B") | [] [] | []------------------------->[] [] [] | [] | Reset [] [] [] | [] | Device [] [] [] | [] | Bootstrap()[] [] [] | [] []<-----------[] [] [] | [] [] ACK [] [] [] | [] []----------->[] [] [] | [] ACK | [] [] [] 200 OK []<-------------------------[] [] []<-----------------------[] | | []<-------[] | | | | [] PUT /v1/bootstrap | | | | [] [] | | | | []-------->] | | | | [] PUT ?/goodbye | | | | [] [] | | | | [] | | | | | []-----------GET /v1/devices//bootstrap---->[] | [] | | | [] | []<----------------- 204 No Content--------------[] | [] | | | | | | | | | | | [sleeps] | | | | | | | | | | | | | | | | | | | | | | | Device Change Owner Sequence Diagram (first part) Lucas Expires March 17, 2018 [Page 63] Internet-Draft aSSURE Data Security September 2017 | | | | | | +------+ +--------+ +--------+ +--------+ +----------+ +------------+ |DEVICE| | MAKER | | MAKER | |OWNER | |BOOTSTRAP | |REGISTRATION| | | |SYSTEM A| |SYSTEM B| |GATEWAY | | SERVER | | SERVER | +------+ +--------+ +--------+ +--------+ +----------+ +------------+ [sleeps] | | | | | | | []---GET--->] | | | | []?/configuration | | | | [] [] | | | | [] []GetDeviceData() | | | [] []----------->[]GetDeviceOwner() | | [] [] []----------->[] | | [] [] [] [Mgmt B] [] | | [] 200 OK [] [data] []<-----------[] | | [] [data] []<-----------[] | | | []<--------[] | | | | [] | | | | | [Build bootstrap image] | | | | | [] | | | | | [] POST ?/bootstrap | | | | []-------->[] | | | | [] []SetDeviceBootstrap() | | | [] []----------->[] | | | [] [] []GetDeviceOwner() | | [] [] []----------->[] | | [] [] [] [Mgmt B] [] | | [] [] ACK []<-----------[] | | [] 200 OK []<-----------[] | | | []<--------[] | | [wakes up] | | | | | | | | | | | [] | | | | | []-----------GET /v1/devices//bootstrap---->[] | [] | | | [] | []<-----------------------[image]-----------------[] | [] | | | | | [Validate and decrypt bootstrap data] | | | [] | | | | | [Apply bootstrap data] | | | | [] | | | | | []-PUT ?/info----------->[] | | | [] | [] | | | [] [data] [] | | | []<--------------------->[] | | | | | | | | | ?/ is /v1/devices// Device Change of Ownership Change the management system authorized for the device Device Change Owner Sequence Diagram (second part) Lucas Expires March 17, 2018 [Page 64] Internet-Draft aSSURE Data Security September 2017 15. Configuration and Bootstrap Data Formats 15.1. Overview The bootstrap data is critical to the device to determine ownership and allow authentication of the management system. Additional parameters may be provided to the device as part of the bootstrap data. The Management System uploads the bootstrap data for a device to the bootstrap server so that the bootstrap server can be provide it to the device during the bootstrap sequence. he Management System therefore encrypts the bootstrap data so that only the target device can decode it (in the case of shared secret devices, the Identity Service is also theoretically capable of this decryption). This protects the data from exposure should the bootstrap server be compromised. The Management System needs to know what information the device needs to complete its bootstrap and it requests this in the request defined in 9.3.6. above. 15.2. Configuration data format The configuration data for a device provides the manufacturing data for the device and information about the key to use to encrypt the bootstrap data. The data is in JSON format as below: { "device": { "id": "", "bootstrap_server": , "capabilities": { // Device bootstrap capabilities "ec_capable": , "rsa_capable": , "sha384_capable": , "sha512_capable": , "aes256_capable": , // Additional capabilities may be added in the future }, }, "authenticated_keys": [ // Array of base-64 encoded key identity strings as in // 7.4. above ], "owner_information": "", "parameter_choices": [ // List of sets of parameter choices. The Management // System should provide exactly one of the sets of // parameters, but it may choose to provide a different // parameter set if it has additional information about // what the device can support. ], } Lucas Expires March 17, 2018 [Page 65] Internet-Draft aSSURE Data Security September 2017 The format of the "parameter_choices" array depends on the types of messages that are required by the device. The exact format is TBD at this time. 15.3. Device connection to the bootstrap server using DTLS using pre-shared secrets The array of "authenticated_keys" provided in the configuration data will include a bootstrap server key. This key and all keys that it relies on to derive it from the device key must be provided to the device by the bootstrap server during the DTLS handshake so that the device can establish the DTLS connection. The bootstrap service in the Trusted Authority will do this automatically. If a bootstrap service is used within the Walled Garden, it must be careful to include all these keys in the correct order (from device key to bootstrap server) so that the device can derive the key necessary for the DTLS session. 15.4. Device connection to the bootstrap server using DTLS using public keys There is a special requirement for the device behaviour when establishing the DTLS connection to the bootstrap server. The DTLS handshake (with extensions as in RFC-7250 allowing raw public keys) uses public keys rather than certificates, so the device cannot authenticate the bootstrap server key during the DTLS handshake. The device must therefore temporarily accept the public key from the bootstrap server during the DTLS handshake and download the bootstrap data. The device must then check that the public key from the bootstrap server is in the list of identities in the bootstrap and that it has the "Bootstrap Service" identity class. Once the identity of the bootstrap server has been confirmed, validation of the bootstrap data can continue. If the identity of the bootstrap server cannot be confirmed, the bootstrap data should be discarded. 15.5. Bootstrap data format The bootstrap data is constructed by the management system based on the configuration data and the additional information that the management system needs to provide. The bootstrap data is in CBOR format comprises three sections - a header, the encrypted content and the signature. The header includes one or more authenticated keys and the owner information. All authenticated keys in the configuration data must be included in the authenticated key list in the order provided. The management system may then append additional keys if it wishes. Lucas Expires March 17, 2018 [Page 66] Internet-Draft aSSURE Data Security September 2017 The order is important because the device will validate and import the authenticated keys in the order provided. If a key is invalid or depends on a key that is not yet imported, the bootstrap data will be rejected. The owner information tells the device the number of owners the device has had. This number starts at zero and is incremented each time the owner changes. The device must store this number in non volatile memory and only accept bootstrap data if the owner sequence_number in the bootstrap data is the same or higher than the owner_sequence_number stored in non-volatile memory. This prevents replay attacks of older owner data in an attempt to reclaim ownership of a device. The owner data must be signed by a manufacturer or registration identity as defined in 7.7. above. ARRAY { // One or more authenticated key definitions in 7.4. above ARRAY { ... // Authenticated key definition } // Owner information ARRAY { INTEGER content //"Owner Content Type" as in 7.5. above INTEGER owner_sequence_number ARRAY { // Signature for owner data, provided by bootstrap // server as in 7.3. above } } // End of owner information // Start of encryption information BYTE STRING decryption_key_id // Key UUID BYTE STRING encrypted_payload // Signature for the entire bootstrap data ARRAY { // Signature as in 7.3. above, signed by Management // Systems key // Signature covers ENCRYPTED payload, so signature //.validation is done before decryption } } 15.5.1. Payload protected by Elliptic Curve keys If the decryption key refers to an Elliptic Curve key, the encrypted_payload is a Cryptographic Message Syntax object containing an enveloped-data block (see RFC 5652 and RFC 5753). The enveloped-data should be encrypted using the "Standard" variation of Ephemeral Static ECDH (see RFC 5753 section 3.1). The Lucas Expires March 17, 2018 [Page 67] Internet-Draft aSSURE Data Security September 2017 default choices for encryption cipher and hash function should be AES-128 and SHA-256 respectively. The "enveloped-data", after decryption, contains the payload CBOR structure as defined in 15.5.4. below. 15.5.2. Payload protected by RSA keys If the decryption key refers to an RSA key, then the encrypted_payload is a Cryptographic Message Syntax object containing an enveloped-data block (see RFC 5652). The enveloped-data should be encrypted using RSAES-OAEP (see RFC 8017 section 7.1). The default choices for encryption cipher and hash function should be AES-128 and SHA-256 respectively. The SHA-1 hash should NOT be used. The "enveloped-data", after decryption, contains the payload CBOR structure as defined in 15.5.4. below. 15.5.3. Payload protected by shared secrets If the decryption key refers to a shared secret then the encrypted_payload contains the CBOR structure below. The salt, iterations_or_cipher and encrypted_secret fields are used to derive a decryption key for the cipher in the same way as a derived secret is obtained in section 7.2. above. This key is then used with the indicated cipher_suite with the cipher_IV and optional tag to decrypt the encrypted_data. ARRAY { BYTE STRING salt INTEGER iterations_or_cipher BYTE_STRING encrypted_secret INTEGER cipher_suite // As in 7.8. above BYTE STRING cipher_IV BYTE STRING tag // Zero length for CBC ciphers BYTE STRING encrypted_data } The "encrypted_data", after decryption, contains the payload CBOR structure as defined in 15.5.4. below. 15.5.4. Decrypted payload content The payload has the following CBOR format: ARRAY { BYTE STRING coap_message0 BYTE STRING coap_message1 ... BYTE STRING coap_messageN } Lucas Expires March 17, 2018 [Page 68] Internet-Draft aSSURE Data Security September 2017 Each message is replayed to the local API in the order in the payload. If the device requires configuration messages to be replayed to a different API, a local API function should be created that understands how to replay the message content to the other API. E.g. replay of a BACnet APDU to the local device. 16. Security Considerations This whole draft concerns security considerations. See Chapter 6. 17. IANA Considerations None 18. Conclusions End to end certificate handling and encrypted communication using "channels" within the DTLS framework can easily be achieved without inventing new standards, just by enhancing current ones. This covers devices from high end servers down to resource constrained devices across different types of network. The underlying standards are: Transport Layer Security, TLS v1.2, RFC-5246 Datagram Transport Layer Security, DTLS v1.2, RFC-6347 Constrained Application Framework, CoAP, RFC-7252 Concise Binary Object Representation, CBOR, RFC-7049 CoAP Block-wise Transfers, https://www.ietf.org/id/draft-ietf core-block-21.txt The aSSURE specification lends itself to the industrial manufacture and distribution of IoT and other connected pieces of equipment and can serve many markets both in retrofit and new build. Indeed IoT is currently disgorging millions of devices in architectures that are not secure enough and could be repaired using the aSSURE framework and philosophy. This problem is better described by Bob Hinden in his paper "Internet of Insecure Things" published in the Internet Protocol Journal. 19. References 19.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4279] Eronen, P., Ed., and H. Tschofenig, Ed., "Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)", RFC4279, DOI Lucas Expires March 17, 2018 [Page 69] Internet-Draft aSSURE Data Security September 2017 10.17487/RFC4279, December 2005, . [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, . [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, RFC 5652, DOI 10.17487/RFC5652, September 2009, . [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, January 2012, . [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013, . [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., Weiler, S., and T. Kivinen, "Using Raw Public Keys in Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, June 2014, . [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, . 19.2. Informative References CoAP Block-wise Transfers, https://www.ietf.org/id/draft-ietf core-block-21.txt [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography Specification Version 2.0", RFC 2898, DOI 10.17487/RFC2898, September 2000, . [RFC5753] Turner, S. and D. Brown, "Use of Elliptic Curve Cryptography (ECC) Algorithms in Cryptographic Message Syntax (CMS)", RFC 5753, DOI 10.17487/RFC5753, January 2010, . [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for Constrained-Node Networks", RFC 7228, DOI 10.17487/RFC7228, May 2014, . "Internet of Insecure Things", Hinden, B., Internet Protocol Journal March 2017 Vol 20, Number 1, Page 12. . Lucas Expires March 17, 2018 [Page 70] Internet-Draft aSSURE Data Security September 2017 20. Acknowledgments This document is a byproduct of the "aSSURE" project, partially funded by Innovate UK. It is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of fitness for a particular purpose. The views and conclusion contained herein are those of the authors and should not be interpreted as necessarily representing the official policies or endorsements, either expressed or implied, of the aSSURE project or Innovate UK. Author's Address Roger Lucas c/o Cisco International Limited 10, New Square Park Bedfont Lakes Feltham TW14 8HA United Kingdom Email: iot@hiddenengine.co.uk Lucas Expires March 17, 2018 [Page 71]