Overview

Skill Level: Intermediate

Basic knowledge on PKI and TLS is required.

Automated generation of Trusted digital certificates thanks to integration of Watson IoT API and certificate enrollment using the WISeKey Managed PKI API. This process can be used for initial provisioning during manufacture or remotely on deployed devices

Ingredients

  • IBM Watson IoT account and organization ID
  • WISeKey MPKI service account (contact us for an evaluation access)
  • Endpoint capable of using MQTT and TLS with client certificate

 

WK_logo_ROJO_MINI

WISeKey provides security solutions for the IoT. Please contact us at sales@wisekey.com to obtain a trial license and access to the API mentioned in this article (please refer to IBM WATSON RECIPE in your message).

Step-by-step

  1. Prepare the Watson IoT environment

    For this recipe you will require an IBM Cloud account, enabled for the Watson IoT platform. The creation of this account is out of the scope of this recipe.

     1.LaunchWatson
    1. Access to the IBM Cloud services portal with your credentials
    2. Click con “Launch” to get access to your Watson IoT account¬†
     2.WatsonDashboard-1

    We’ll use the Web console for a few manual configurations, the rest will be done using the API¬†

  2. Configure CA Certificate

    -----BEGIN CERTIFICATE-----
    MIIDGzCCAgOgAwIBAgIQTF0lOEfOta5PFHG5r/V1STANBgkqhkiG9w0BAQsFADAg
    MR4wHAYDVQQDExVXSVNFS0VZIE1TQ0EgUElMT1QtQ0EwHhcNMTYwMjIyMDYzNjA1
    WhcNNDYwMjIyMDY0NjAzWjAgMR4wHAYDVQQDExVXSVNFS0VZIE1TQ0EgUElMT1Qt
    Q0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCnv/IV/dRNp/q+4G0A
    beVEklHXV9Sfgg5+sO7AXOd8CjdwKvWyOsLraSFQXSHfpUQ55V1zCAf2ht/uVJxP
    TwOG+qO9SPs3GJDsTDQcPGT6rxQjF9xMtV0ZssWsHTFizXHG8XAtVsidoAdvSAIf
    Jws6lH5wFGjXZn9wF67qnz0Li0/1KozBuXP9Nb3cKjNREWQx0THtMP1mdj32/ACo
    8dgGA8d/wb0t2W0wWRw03sxzdkXEfp4ksqS+coIIXh3ui04msa81OYQbZ34dLi4E
    sJh77rxv5M4b86cfxTUFATLkT92OxkMz0VBjncGslvgU0hGv1P9ldu/3uo9DMFbg
    88t3AgMBAAGjUTBPMAsGA1UdDwQEAwIBhjAPBgNVHRMBAf8EBTADAQH/MB0GA1Ud
    DgQWBBR1i/hK37kts3ptTKG9jPdytDIqBDAQBgkrBgEEAYI3FQEEAwIBADANBgkq
    hkiG9w0BAQsFAAOCAQEAAvgsfDrGA4/yKVsiWYUbW7+hGKWE21EOJCd7Q4o2X2AL
    VlrlCjqtbrZCiX8mbOzf6lQ92ijDywr9Y8+Qe1HdJwxQ8WTjTtcPfbJpCI/d1ihK
    aM86yfhCwoiJd9eoUmFtzf7bRGpmjKafBD4/0VwqSAGXYes6jXKA8mFk31Flqbgu
    LjQ/wsbsScQPJghMfBVp3g6ReKxItuuHth/3b2eiClbPZH5g/0Ma8pdpXwcKC/m7
    U6fdFWSs018oczdf1rgAWiJsvjQkXkFH2Qszb6xEPwNcGY4icwi9HjmngAOgKitq
    Qgs1Oh6Rfl7VVH+aJTyeD7o9N4m48ILKwcbxNzsoEw==
    -----END CERTIFICATE-----
     

    Let’s create a file with the CA Certificate. This is a Pilot CA¬†that will sign the device certificates used later in this recipe.

    1. Open a new text file 
    2. Copy the text in the left and paste it in the text file
    3. Save the file as WISEKEYPILOTCA.cer 
    ¬†3.CACertbefore ¬†In the Watson IoT console, go to the “Settings” menu and select “Security” > “CA Certificates”
     4.CACertAdd
    1. Click on Add
    2. Select the file containing the CA certificate we created above
    3. Enter some description
    5.CACertafter Now the WISeKey Pilot CA is configured in Watson to be accepted as Root of Trust for TLS authentication
  3. Configure Device Types

    6.DeviceTypesBefore

    We need to configure a Device Type for our tests, so we can later define the authentication parameters for these devices.

    In the left Menu, select “Devices”, then in the top menu select “Device Types”

     7.DeviceTypesAdd1
    1. Click on “Add Device Type”
    2. Enter a name for the new type (in our case HSDevices)
    3. Enter a description
    4. Click on “Next”¬†
     8.DeviceTypesAdd2
    1. Enter some informational attributes for this device type (nothing in particular is required for this test)
    2. Click on “Done” to register the new device type¬†
    ¬†9.DeviceTypesAfter ¬†You can have as many Device Types as required. In the next section we’ll see how to configure a security level for a particular device type
  4. Configure the Device Authentication Settings

    5.CACertafter 
    1. ¬†In the “Setting” menu, select “Security” > “Connection Security”
    2. Click on “Open Connection Security Policy”
     10.ConnectionSecurity1
    1. Click on “Add Custom Rule”
    2. Select the Device Type for which you want to apply the rule
    3. Select the authentication type. In our example, let’s use “TLS with Client Certificate Authentication”¬†
    ¬†11.ConnectionSecurity2 The new Rule is ready to be used. The devices using the rule will apear in the “Compliance” and “# of Devices” columns¬†
  5. Create the Device Identity using the WISeKey MPKI API

    Now that the Watson IoT is ready, it’s time to create the identity for our devices, so they can authenticate to the platform with much higher security than a simple username/password (the default security level in MQTT).

    For issuing these certificates you have two options:

    • Deploy your own PKI, creating a Certification Authority that will sign these certificates
    • Use a cloud service that won’t require to deploy and maintain any dedicated infrastructure. Thse services are known typically as “Managed PKI” and is a convenient option reducing costs and complexity, specially in production environments where it’s required to support high number of devices.

     

    WISeKey offers a Managed PKI service that can issue certificates for people (i.e. Secure eMail, Digital Signature), Applications (i.e. SSL certificates) and Objects (for IoT, but also for other uses as anti-counterfeiting). There are two types of certificates depending on the trust level:

    • Privately Trusted Certificates. These certificates come from a Certification Authority which is not trusted by default by a “relying” party¬†(browsers, operating systems, etc). To accept these certificates, the user or the server administrator must explicitely add the new Root to the list of trusted Certification Authorities. This is sometimes unconvenient, as in some cases the end users can get warnings or errors informing that the certificates can’t be verified
    • Publicly Trusted Certificates. Some CAs, like WISeKey, are independently audited under international criteria like Webtrust, obtaining a “compliance seal” that is then accepted by the relying parties, so these CAs come pre-configured by default in all the popular applications

    The WISeKey Managed PKI (MPKI) service supports both private and public certificates. In this example we’ll be using a test CA, issuing privately trusted certificates.

    The MPKI service offers, like Watson, two interfaces:

    • A Web GUI, which allows to manage the PKI configuration (certificate templates, security settings…), generate device accounts and manage certificates (request, approve certificates, revoque…)
    • A RESTful API, which offers almost the same options than the GUI, but¬†allowing a convenient integration with application to automate tasks.

    In this tutorial, we’ll focus in the automation and the use of the WISeKey IoT API, which is a simplified layer over the generic MPKI API, as this will allow an easy integration later with the API of the Watson IoT platform, so both the device account and the device identity can be programatically generated.

     

    Steps to generate a certificate using the WISeKey IoT API:

    Illustrative Example: Requesting a certificate for a device named “smartmeter000876” of the type “HSDEVICES”)¬†

    Request: 

    [{
       "csr": "MIICezCCAWMCAQAwNjEfMB0GA1UEA...",
       "deviceid": "smartmeter000876",
       "devicetype": "HSDEVICES"
    }]
     
    Response:  [{
       "certificate": "QEBBQADggEPADCCAQoCggEBAJ6+dXza6hdMuEH1l9LSfoEBxXi...",
       "ca_certificates": null,
       "code": 200,
       "createdAt": "2018-02-01T05:02:14"
    }]
    Code Example: 

    public Certificate[] BulkSignUp(Request[] req)
    {
       Certificate[] lstCert = null;
       try {
          using (var client = new HttpClient()) {
             client.BaseAddress = new Uri(m_IoTApiHost);
             client.DefaultRequestHeaders.Accept.Clear();
             client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
             //bypass for SSL/TLS
             ServicePointManager.ServerCertificateValidationCallback += (sender, cert, chain, sslPolicyErrors) => true;
             HttpResponseMessage response = client.PostAsJsonAsync("signup/bulk", req).Result;
             if (response.IsSuccessStatusCode) {
                lstCert = response.Content.ReadAsAsync<Certificate[]>().Result;
             }
             else {
                throw new Exception(response.Content.ReadAsAsync<string>().Result);
             }
          }
       }
       catch (Exception e) {
          throw e;
       }
       return lstCert;
    }

    To access this API it’s required a Customer Key and an authentication¬†certificate. The connections details are reserved, please contact us to get access to the test platform and API (sales@wisekey.com).¬†

  6. Create the Device into the Watson IoT platform using the API

    Now the credentials for our device are ready, we only need to register the new device into the Watson IoT and we’d be able to start sending messages.

    Instead of using the Watson Web console, we’ll use also the API, as this is convenient and more close to a real-world scenario, where all these tasks must be automated and integrated with the business applications.

    Steps to generate a certificate using the WISeKey IoT API:

    Illustrative Example: Creating¬†a device named “smartmeter000876” of the type “HSDEVICES”)¬†

    Request: [{
      "typeId": "HSDevices",
      "deviceId": "smartmeter000876",
      "deviceInfo": {
        "serialNumber": "000876",
        "manufacturer": "",
        "model": "truck",
        "deviceClass": "",
        "description": null,
        "fwVersion": "v1.0",
        "hwVersion": "v1.0",
        "descriptiveLocation": ""
      },
      "location": {
        "longitude": 0,
        "latitude": 0,
        "elevation": 0,
        "accuracy": 0,
        "measuredDateTime": ""
      },
      "metadata": {
      },
      "authToken": "***************"
    }]
    Response:  [{
      "typeId": "HSDevices",
      "deviceId": "truck-100",
      "success": true,
      "authToken": "LQu@tsMBJOOAtI6(42"
    }]
    Code Example:  public static string RegisterDevices(BL.Models.Thing[] devices)
    {
      if (m_oClient == null)
        throw new Exception("ApiClient is not be set");
        try {
          int count = devices.Length;
          //Register multiple devices
          IBMWIoTP.RegisterDevicesInfo[] bulk = new IBMWIoTP.RegisterDevicesInfo[count * 2];
          int j = 0;
          for (int i = 0; i < count; i++) {
            var infoHS = new IBMWIoTP.RegisterDevicesInfo();
            infoHS.deviceId = devices[i].Name;
            infoHS.typeId = CommonIoT.DeviceProfile.HSDevices;
            devices[i].AuthToken;
            infoHS.deviceInfo = new IBMWIoTP.DeviceInfo {
              serialNumber = devices[i].SerialNumber,
              description = devices[i].Description,
              hwVersion = devices[i].HardwareVersion,
              fwVersion = devices[i].FirmwareVersion,
              model = devices[i].Model
            };
            infoHS.location = new IBMWIoTP.LocationInfo();
            infoHS.metadata = new { };
            bulk[j++] = infoHS;
          }
        FileLogger.Default.Info(new JavaScriptSerializer().Serialize(bulk));
        return new JavaScriptSerializer().Serialize(m_oClient.RegisterMultipleDevices(bulk));
      }
      catch (Exception ex) {
        throw ex;
      }
    }
  7. Bonus step: Hints on device provisioning techniques

    When it comes to provisioning a device with its identity, there are two main options:

    • Provisioning during the manufacture. The credentials are generated typically as part of a “production batch”. In this case, there’s full control and secure access to the device and it’s relatively simple to inject the keys and certificate (e.g. as part of the middleware load process)
    • Remote provisoning once the device is already deployed. In this case there are multiple¬†aspects that must be carefully studied, being the two more important:
      • How can we authenticate the device that is getting remotely the credential, to ensure that is the right one?
      • How can we ensure that the credentials aren’t intercepted while transmitted?

     

    A possible solution is to use two certificates in the device:

    • A “manufacturer certificate”, or “certificate of origin”
    • A “user certificate”, or “production certificate”

    Whith this approach, the device could still authenticate securely the first time using the manufacturer certificate, so we can ensure its identity and also the confidentiality during the¬†delivery of the new credentials, as this can be done with TLS and strong authentication. This initial certificate should be injected in a hardware “secure element”, which, together with the digital certificate, provides a full Root of Trust to ensure the security of all operations.

    vaulic-chip

    The injection of keys and use of a hardware secure element are subject of a separate recipe to be published soon. Stay tuned!

     

Join The Discussion