Quick-start guide - “Hello world”

Quick Start Guide – “Hello world”

12 July 2024 seperator dot clairet

Contents

The following sections provide a quick-start guide to building the DDKG library and the Credential Manager application from the source code hosted on GitHub. By the end of each section you will have completed a build for Ubuntu Linux!

 

DDKG

This guide walks through how to obtain the source code for DDKG, install pre-requisites, then build the DDKG library on a Ubuntu Linux platform.

What is DDKG?

The Dynamic Device Key Generator is our patented technology that provides a method to securely identify an IoT device. Using a challenge-response mechanism between the device and KeyScaler, the dynamic key is generated using a complex combination of device hardware attributes to ensure the device is authentic.

The DDKG library is cryptographically tied to a single secure KeyScaler tenanted instance. This requires a unique library to be built that contains key material exported from the KeyScaler tenant. DDKG for tenant A cannot communicate with DDKG built for tenant B due to the use of asymmetric cryptography.

For further information on the technology: https://deviceauthority.com/products/ddkg/

 

Linux build quick-start guide

The following steps assume you have a Ubuntu Linux host platform. This can be set-up in a virtual machine using a virtualisation platform such as VirtualBox or VMWare. We recommend Ubuntu 22.04 LTS for this guide.

 

Configure Ubuntu packages

The following packages are required to build DDKG on a typical Linux distribution:

  • git
  • build-essential
  • zliblg-dev
  • python3

 

Install packages

To install the required packages in Ubuntu we use the apt utility.

Simply run sudo apt install git build-essential zliblg-dev python python3 and, if prompted, enter the sudoer account password.

 

Clone repository from GitHub

The DDKG source code is hosted on GitHub in the DeviceAuthority/ddkg-public repository.

Verify git is installed

To ensure git is installed successfully, run git version and confirm a version is reported:

e.g., git version 2.34.1

Download the source code from the DDKG repository

Navigate to your working directory and run git clone git@github.com:DeviceAuthority/ddkg-public.git. The following output is expected:

Cloning into 'ddkg-public'...
remote: Enumerating objects: 814, done.
remote: Counting objects: 100% (814/814), done.
remote: Compressing objects: 100% (644/644), done.
remote: Total 814 (delta 127), reused 807 (delta 120), pack-reused 0
Receiving objects: 100% (814/814), 9.18 MiB | 7.65 MiB/s, done.
Resolving deltas: 100% (127/127), done.

 

Once complete, confirm that the DDKG source code has been downloaded successfully by running ls ddkg-public. The following output is expected:

include/ license.md makefile make_libnauddk_shared.mk make_ossp_uuid.mk make_tinyxml.mk readme.md resources/ scripts/ setenv.sh src/ tools/ version.txt

Obtain and build third-party dependencies

Within the scripts directory we provide utilities to download third-party resources and where applicable, build those dependencies.

ethtool

  • Run scripts/ethtool-download.sh
  • Check that third_party/ethtool exists.

openssl

  • Run scripts/openssl-build-linux.sh
  • Check that third_party/openssl/ exists and contains an include and lib directory.

ossp-uuid

  • Run scripts/ossp-uuid-download.sh
  • Check that third_party/ossp_uuid-1.6.2 exists.

rapidjson

To obtain the rapidjson source code we provide a script, rapidjson-download.sh.

  • Run scripts/rapidjson-download.sh
  • Check that third_party/rapidjson exists.

tinyxml

  • Run scripts/tinyxml-download.sh
  • Check that third_party/tinyxml exists.

 

Configure build environment to build DDKG for your KeyScaler tenant

To build DDKG, we first require a tenant file keyed to your KeyScaler tenant:

  1. Obtain a tenant_xyz.xml file from DeviceAuthority, typically downloaded from KeyScaler.
  2. Copy tenant_xyz.xml into the resources/ directory.
  3. Run . ./setenv.sh -t your_tenant_name where your_tenant_name is the name of your tenant. The tenant name is included in the tenant file filename; Tenant_abcdefg.xml indicates the tenant name is abcdefg.
    • Note that the first period character of the above command is required, followed by a space, to source the environment variables from this script in your local terminal session.
  4. Ensure no errors are reported by the script.

We are now ready to build DDKG for your KeyScaler tenant!

 

Build DDKG

To build a release version of DDKG, run the following command:

make BUILD_TARGET=Release -j4

On completion, the build is output into a newly created dist/ directory.

Congratulations. You have now built a release version of the DDKG for your KeyScaler tenant!

 

[Back to Top]

 

Credential Manager

This guide walks through how to obtain the source code for Credential Management, install pre-requisites, then build the Credential Management application on a Ubuntu Linux platform.

What is Credential Manager?

The Credential Manager Agent is the quickest and easiest way to connect IoT devices with your KeyScaler environment. Credential Manager automates the process of Registering and Authenticating with KeyScaler, and processing assets generated by policies configured in the groups the device is a member. Core functionality provided by the Credential Manager includes:

  • Key-pair generation (with TPM 2.0 support)
  • Certificate generation
  • Account password management
  • Secure asset transfer
  • Code signing
  • Configuration management

 

Linux build quick-start guide

The following steps assume you have a Ubuntu Linux host platform. This can be set-up in a virtual machine using a virtualisation platform such as VirtualBox or VMWare. We recommend Ubuntu 22.04 LTS for this guide.

 

Configure Ubuntu packages

The following packages are required to build Credential Manager on a typical Linux distribution:

  • git
  • build-essential
  • zliblg-dev

 

Install packages

To install the required packages in Ubuntu we use the apt utility.

Simply run sudo apt install git build-essential zliblg-dev and, if prompted, enter the sudoer account password.

 

Clone repository from GitHub

The Credential Manager source code is hosted on GitHub in the DeviceAuthority/credential-manager-public repository.

Verify git is installed

To ensure git is installed successfully, run git version and confirm a version is reported:

e.g., git version 2.34.1

Download the source code from the Credential Manager repository

Navigate to your working directory and run git clone git@github.com:DeviceAuthority/credential-manager-public.git. The following output is expected:

Cloning into 'credential-manager-public'...
remote: Enumerating objects: 569, done.
remote: Counting objects: 100% (569/569), done.
remote: Compressing objects: 100% (440/440), done.
remote: Total 569 (delta 81), reused 567 (delta 79), pack-reused 0
Receiving objects: 100% (569/569), 4.48 MiB | 5.56 MiB/s, done.
Resolving deltas: 100% (81/81), done.

 

Once complete, confirm that the Credential Manager source code has been downloaded successfully by running ls credential-manager-public. The following output is expected:

config/ include/ license.md make_agent.mk makefile readme.md scripts/ src/ third_party/

Obtain and build third-party dependencies

Within the scripts directory we provide utilities to download third-party resources and where applicable, build those dependencies.

rapidjson

To obtain the rapidjson source code we provide a script, rapidjson-download.sh.

  • Run scripts/rapidjson-download.sh
  • Check that third_party/rapidjson exists.

OpenSSL

To build openSSL we provide a script, openssl-build-linux.sh.

  • Run scripts/openssl-build-linux.sh --version <version number> where <version number> is the version of openSSL, e.g. 3.0.9.

This generates the required library and include files in the third_party/openssl/ directory.

cURL

To build cURL we provide the script curl-build-linux.sh.

  • Run scripts/curl-build-linux.sh --with-ssl

This generates the required library and include files in the third_party/curl/ directory.

Note that this requires openSSL to have been compiled as it utilises the paths third_party/openssl/lib and third_party/openssl/include in its build flags.

Now we are ready to build Credential Manager!

 

Build Credential Manager

To build a release version of Credential Manager, run the following command:

make BUILD_TARGET=Release -j4

On completion, the build is output into a newly created dist/ directory.

Congratulations. You have now built a release version of the Credential Manager!

 

[Back to Top]