User Tools

Site Tools


understanding_iotivity_certs

Understanding Certificates in IoTivity

Introduction

This guide assumes that you are familiar with the OCF Security Specification, X.509 certificates, and the IoTivity security subsystem. All discussion in this document pertains to Manufacture Cert based Ownership Transfer (OTM) as of the 2.0 release of IoTivity (Bangkok). It is also assumed that you have basic familiarity with configuring and running the IoTivity sample provisioning applications.

The term Manufacturers Certificate refers to certificates that are installed in a device by the manufacturer.

OCF Certificate Chains

Overview

OCF specifies that certificate chains must be of length 2 or 3.

For this overview the term Identity Cert Chain (ID Cert Chain) refers to 1 or 2 certificates as shown in the previous diagram, used by a device to identify and authenticate itself to other OCF devices.

The term Validation Certificate (Validation Cert) refers to a Root Certificate used to validate the identity and authenticity of identity Cert Chains of other devices.

OCF defines the cred resource, which is used to hold certificates and keys within devices. We will have much more to say about the cred resource in a later section.

The following diagram show a typical example of how Identity Cert Chains and Validation Certificates might be installed in devices from 2 different manufacturers, each using a specific PKI provider. The certs and entities shown in this diagram will be used within other examples in this document, so it is worth spending a few moments to familiarize yourself with it.

OCF Certificates and the DTLS Handshake

It is important to understand that during Mfg Cert OTM, certificate chains are used by the server and client to identify and authenticate each other via the DTLS handshake.

The following diagram shows how the Identity Cert Chain and the Validation Cert are used in the context of a DTLS handshake. For the sake of simplicity, only the relevant DLTS messages are shown (see Appendix D for a more complete representation of DTLS handshake messaging)

Certificates and the cred Resource

As defined by OCF, Certificates and certificate chains are contained within the cred resource of a device, which itself contains a list of cred entries. The term ‘cred resource’ will be used to refer to the entire list of creds, and the term ‘cred entry’ will be used to refer to a single entry within the cred list.

For Mfg. Cert based OTM, we will be focusing on the following cred entry properties:

credusage:    mfgcert: for Identity Cert Chain entries (for Intermediate and/or EE certs only)
              mfgtrustca: for Validation Cert entries (for Root certs only)
publicdata:   certificate or certificate chain encoded as oic.sec.encoding.pem | oic.sec.encoding.der
privatedata:  private key encoded as oic.sec.encoding.pem | oic.sec.encoding.raw

Representing the Identity Cert Chain and Corresponding Private Key in creds

The Identity Cert Chain, and corresponding private key, will always be contained within cred entries of credusage type mfgcert.

The publicdata field of the cred will holds a certificate or certificate chain, encoded in one of several formats. IoTivity supports two encoding formats for Identity Certificates: PEM and DER.

The privatedata field of the cred entry holds a private key, encoded in one of several formats. IoTivity supports two encoding formats for private keys: PEM and RAW. As the private key must be an Elliptical Curve (EC) Key, the PEM representation will be an ‘EC PRIVATE KEY’ PEM encoding. IoTivity assumes that RAW, in the case of EC private key encoding, corresponds to SEC 1 encoding.

Examples for generating and converting among these various formats will be provided later in this overview.

In order to properly configure IoTivity with ID Cert Chains, it is important to understand the following assumptions that are made by IoTivity for Identity Cert Chain cred configuration:

  • A cred resource encapsulates only 1 Identity Cert Chain, the certs from which will be contained in 1 or more creds with credusage type mfgcert
  • For PEM encoded ID Cert Chains of length > 1, the chain certs may be held in either:
    • A single cred holding concatenated PEM cert representations (EE first followed by Int CA)
    • Multiple creds, each holding one PEM cert representation (first cred = EE, next cred = Int CA)
  • For DER encoded ID Cert Chains of length > 1, the chain certs will be held in Multiple creds, each holding one DER cert representation (first cred = EE, next cred = Int CA)
    • NOTE: IoTivity does not support multiple DER encoded certs in a single cred
  • The order of the chained certificates in both concatenated PEM format, and in multiple cred representation matters. IoTivity assumes in both cases that he EE cert will come first, followed by the Intermediate Certs in the proper chaining order.
  • The cred holding the end entity cert (in publicdata) will also will also hold the corresponding private key (in privatedata)

Representing Validation Certificates in creds

Validation Certificates will always be contained within cred entries of credusage type mfgtrustca.

The publicdata field of the cred entry holds a commonly known Root Certificate trust root (per the OCF spec), encoded in one of several formats. IoTivity supports two encoding formats for validation certificates: PEM and DER.

Validation Cert Assumptions

  • A cred resource may encapsulate 1 or more Identity Cert Chain, the certs from which will be contained in creds with credusage type mfgtrustca
  • IoTivity will gather all of the of the Validation Certificates for use during the DTLS handshake process (i.e. multiple PKI providers can be supported)

Examples

Following are a few examples of cred resource structures that are valid for IoTivity

The Nuts and Bolts of Configuring IoTivity Creds

Within IoTivity, Mfg Cert OTM is exercised via the provisioning sample applications listed below. The resources for these sample applications are stored in the noted .dat files.

NOTE: you may need to adjust the platform and build type (shown in bold) in the path below. The notation ${iotivity} is used in this document to indicate the IoTivity root directory
Path: ${iotivity}/out/linux/x86_64/debug/resource/csdk/security/provisioning/sample
provisioningclient: Client App that initiates the onboarding process
                    Configured via oic_svr_db_client.dat
sampleserver_mfg:   Server app that Informs provisioningclient to use server Mfg. Cert based OTM
                    Configured via oic_svr_db_server_mfg.dat

The .dat files are cbor representations of OCF resources and are read by the sample applications at startup to provide initial resource configuration. There are two utilities within IoTivity that can be used to configure .dat files:

  • ${iotivity}/out/linux/x86_64/debug/resource/csdk/security/tool/json2cbor
  • ${iotivity}/out/linux/x86_64/debug/resource/csdk/security/tool/svrdbeditor

This document will focus on the use of json2cbor to create .dat files. json2cbor reads a json representation of OCR resources, and generates the corresponding cbor representation.

$ json2cbor infile.json outfile.dat

Preparing certs and keys for use in the .json files

We will focus on the creds using DER encoding for certificates, and RAW (SEC 1) encoding for private keys.

DER and SEC 1 are both binary encoding formats. The json2cbor tool expects binary data to be represented in the .json config files as binhex. The commands below show how to carry out conversions among cert and key encoding formats to prepare them for use in the .json config files. The examples assume a linux machine with openssl and xxd installed.

Convert a certificate in PEM format to DER format, and then the resulting DER file to binhex

$ openssl x509 -in cert.pem -outform DER -out cert.der
$ xxd -ps cert.der | tr -d \\n > cert.der.hex

Convert a private key in EC PEM Format to DER encoded SEC 1 format, and then the resulting DER file to binhex

$ openssl ec -inform PEM -in privkey.pem -outform DER -out privkey.der
$ xxd -ps privkey.der | tr -d \\n > privkey.der.hex

Configuring cred resources in the .json file

Below is an example cred resource configuration for oic_svr_db_server_mfg.json using binhex formatted cert and private keying material. We will be representing the following cred resource structure:

{
  "cred": {
      "creds": [
          {
              "credid": 1,
              "subjectuuid": "11111111-1111-1111-1111-111111111111",
              "credtype": 8,
              "credusage": "oic.sec.cred.mfgcert",
              "publicdata": {
                 "encoding": "oic.sec.encoding.der",
                 "data": "contents of ee1-cert.der.hex: 308201c03082016 ..."
              },
              "privatedata": {
                 "encoding": "oic.sec.encoding.raw",
                 "data": "contents of ee1-privkey.der.hex: 30770201010420..."
              }
           },
           {
              "credid": 2,
              "subjectuuid": "11111111-1111-1111-1111-111111111111",
              "credtype": 8,
              "credusage": "oic.sec.cred.mfgcert"
              "publicdata": {
                 "encoding": "oic.sec.encoding.der",
                 "data": "contents of contents of int-ca1-cert.der.hex: 308201cc308201…"
              },
           },
          {
              "credid": 3,
              "subjectuuid": "*",
              "credtype": 8,
              "credusage": "oic.sec.cred.mfgtrustca"
              "publicdata": {
                 "encoding": "oic.sec.encoding.der",
                 "data": "contents of root-ca2.der.hex: 308201cc308...",
                 "revstat": false
              },
           }
      ],
      "rowneruuid": "00000000-0000-0000-0000-000000000000",
      "rt": ["oic.r.cred"],
      "if": ["oic.if.baseline"]
   },
} 

Once these changes have been made to oic_svr_db_server_mfg.json run the following command to create the corresponding cbor representation in oic_svr_db_server_mfg.dat

$ cd ${iotivity}/out/linux/x86_64/debug/resource/csdk/security/provisioning/sample
$ edit oic_svr_db_server_mfg.json ## config cred resource as shown above, and save
$ json2cbor   oic_svr_db_server_mfg.json   oic_svr_db_server_mfg.dat

Now start the sample server

$ ./sampleserver_mfg

oic_svr_db_server_mfg.dat will be read by sampleserver_mfg at startup, and will be configured with the cred resource shown above.

The sample client app provisioningclient can be similarly configured via the config file oic_svr_db_client.json

understanding_iotivity_certs.txt · Last modified: 2018/09/24 21:13 by Steven Saunders