Table of Contents

1 This Document

1.1 Document History

Item 1 – Document Version Control

1.2 Related Documents

Item 2 – Related Documents

1.3 Glossary of Terms

Item 3 – Glossary of Terms

1.4 Pre-Requisites

• Administrative access to the following:

  • DA KeyScaler system v6.7.3 or greater

  • Microsoft Azure Account and KeyVault Services and ‘Owner’ privileges for KeyVault creation and Administration

  • IoT device (Linux or Windows) with compatible DA Credential Manager software agent installed and running

• KeyScalerCAclient Application to test REST API connectivity

• Device (Laptop Registered with above KeyScaler System.

• Python scripts for KeyScaler API for HSM Access Controller for some functions e.g., Gen Key, List Key etc.

2 Introduction

2.1 Overview

This user guide is intended for System Administrators who need to set up KeyScaler to use HSM Access Controller (HAC) functionality and integrate with the Azure Key Vault Services.

Azure Key Vault is a cloud service used to manage keys, secrets, and certificates. Key Vault eliminates the need for developers to store security information in their code. It allows you to centralize the storage of your application secrets which greatly reduces the chances that secrets may be leaked. Key Vault also allows you to securely store secrets and keys backed by Hardware Security Modules or HSMs.

The KeyScaler’ s HSM Access Controller (HAC) delivers granular authentication, authorization and audit controls for IoT devices, servers, and applications. Enterprise applications and services connecting to HSMs will authenticate to KeyScaler and use KeyScaler REST APIs to consume common HSM operations, such as key generation, data signing, data crypto, and general public key storage.

This integration of KeyScaler HAC functions with Azure KeyVault enables Microsoft team and Microsoft customers to:

• Prevents unauthorized access to critical HSM infrastructure

• Mitigates security risks and liability exposure

• Implements granular access policies for HSM to support key use cases

• Provides an audit trail for compliance

• Protects brand reputation

• Cost savings (operational and financial) derived from avoiding security breaches

• Eliminates custom development, accelerate time to market

• IoT Ready - Only solution to support headless and constrained devices

This document outlines all the steps required to set up and configure KeyScaler to use service using Azure KeyVault for RSA Key Generation and

2.1 How it works

Figure 1. below provide an overview of the Solution Integration. The HAC uses the KeyScaler registration control policies to enrol entities, patented Dynamic Device Key Generation (DDKG) and JSON Web Tokens (JWT) authentication methods to attest to the identity of the requesting entity. Authorization policies are configured as part of key management policy. The new HAC Connector extends this functionality to 3^rd Party Key Storage - Azure KeyVault services allowing users to store their keys in their own Azure Cloud.

The Solution leverage the EPIC framework to integrate HSM Access Controller into Azure Key Vault and uses a synchronous and secure HTTP/S APIs, instead of the existing Kafka/MQTT model.

• Instead of sending messages to Kafka, it deliver directly from the DAE to the service connector.

• Utilise AES-256 encryption to secure data end-to-end.

• Keep all client-to-KeyScaler APIs the same – to prevent device-side code changes.

Key Management Functions Supported by Azure KeyVault (for Authenticated and Authorized entities)

• Generate keys – Generate a new key inside Azure KeyVault for later use

• List keys – Returns a list of available keys

• Delete key – Deletes a specific key from the Azure KeyVault

• Export Public Key – Export the public part of a given key pair

• Rotate Key – Generate a new key pair for a given key alias stored inside the HSM.

• Data Encryption – Pass data to the KeyScaler service for encryption using the public stored in the Azure KeyVault

• Data Decryption – Pass encrypted data to the KeyScaler service for decryption using the private key stored in Azure KeyVault

• Data Signing – Cryptographically sign data using a private key stored in the HSM – not tested

• Key Vault \Connector Architecture:

All communication from IoT device all the way to Azure KeyVault is secure over HTTPS port 443, including all comms internal to KeyScaler.

3 Set up and configuration of Azure Key Vault

This section show the steps to set up and configure an Azure KeyVault Key and how to access them using an Azure Service Principal.

Note: Admin access to an Azure KeyVault account with Application Administration level permissions will be required for this activity.

3.1 Create an RSA Key Pair Azure Key Vault

3.1.1 Create Key Vault

Examples are provided below on how to create the KeyVault using Azure Portal or Azure CLI.

3.1.1.1 Azure Portal

Login to the Azure portal and ‘Create’ a new KeyVault:

Next, select Subscription, Resource Group, KeyVault Name, Region, Pricing Tier. Example entries for these are shown below:

Next, for Access Policies, select Azure role-based access control, then go to next section for Networking. We will be setting up a Service Principal to access these Keys in the next section.

note

Note: RBAC will be configured when the Service Principal is configured in the next section.

For Networking, use the default connectivity method:

For Tags, add any informative Tags that may apply to your KeyVault:

Check all the settings and Create the Key Vault:

The Key Vault will get created and deployed in Azure:

Once created you can go to the Resource:

3.1.1.2 KeyVault via Azure CLI command

Alternatively, you can create a KeyVault Via the CLI command:

192:~ fbnilsen$ az keyvault create --location uksouth --name HACKV001--resource-group dalab

Figure 12 – Creating a KeyVault via Azure CLI

3.1.2 Create Key Pair

3.1.2.1 Azure Portal

Now that the Key Vault is set up, we can Generate a Key Pair inside the Key Vault. Next navigate to Keys on the Left-side menu: and click on +Generate/Import:

Fill in the Create Key option details as shown below:

Verify Key is successfully created:

This completes the Key Pair Generation process in Azure Key Vault.

To access these Key programmatically via REST API calls from KeyScaler Platform, we need to create an Azure Service Principal which has Role Based Access Control (rbac) to access these keys. This is described in the next section.

3.1.2.2 Azure CLI Command to Create Keys

The above can also be done using Azure CLI command:

az keyvault key create --kty RSA --name HSMACKeyPairTest --vault-name HACKV001--size 2048

Figure 16 – Azure CLI command to create RSA Key Pair

3.2 Create Service Principal in Azure

There are two ways to create a Service Principal (SP):

1. SP via the Azure Portal

2. SP via Azure CLI Interface (Not in scope for this document)

3.2.1 SP in Azure Portal

3.2.1.1 Azure Active Directory

Navigate to Azure dashboard and select Azure Active Directory as shown below:

3.2.1.1.1 App registration

Next select App registration from the Manage List and Select New Registration as shown:

Figure 18 – Azure Portal Dashboard>App registration>New registrations

Enter a Name, select the Supported account type and then Click Register:

Figure 19 – Azure Portal Dashboard>App registration>Register

Make a note of the Application (client) ID and the Directory (tenant) ID, these will be used later for connectivity tests:

Optionally you can configure your SP to have your own branding and upload a Logo Image, as shown below:

Next, need to create a new client secret for your SP: Navigate to Certificates and Secrets:

Add a Client Secret Description, Expiry and click the Add button:

Next Expose an API for this Application as shown below:

Add a scope, using the default value for Application ID URI, as shown:

Fill in the Scope details and click Add Scope. The figure below provides example entries:

Next, Navigate to API permissions, and then click Add a permission as shown below:

Next and Add Azure KeyVault:

Next, click the check box to allow permissions to user_impersonations and the Add Permissions:

Verify that user_impersonation is added to have full access to Key Vault service:

The next sections show the configuration for Access control (IAM) for the SP and the Key Vault you are going to use.

3.3 Configure Access Control for Key Vault

3.3.1 Azure Portal

Navigate to the KeyVault set up in the beginning of this Section. Select Access control (IAM) from the left-hand menu and then click on + Add > Add role assignment, as shown below:

Add a new role assignment Key Vault Administrator and add the new SP; SPHACKV001 that was created and then save the changes.

Next Navigate to View access to this Resource for HACKV001:

Check that the SP has been added as a KeyVault Administrator to this Key Vault as shown below:

3.3.2 Test SP Connectivity

To test the SP connectivity and access to the KeyVault the following pre-requisites are required:

• Application (client) ID, Directory (tenant) ID and the Client Secret for the SP

• KeyScaler CA client Java Application[1]: i.e. keyscalerCAClient.bat or keyscalercaclient.sh and associated files (keyscaler-ca-client.jar, lib directory, .DS_Store, README.txt)

• Azure PowerShell with access to AZ account

On a Windows platform edit the keyscalerCAClient.bat with the SP variables as shown below:

[1] Please Contact Device Authority Customer Support for the Java test utility.

Next, from a Windows Command Prompt or PowerShell window login to your Azure account and navigate to the directory where your Java Application is located:

Execute the following command to fetch the KeyVault public Key:

> .\keyScalerCAClient.bat -get -alias HSMACKeyPairTest

Figure 38 – CLI command to fetch KeyVault Public Key of an existing Key in KeyVault using SP

This will return the public key of the Key you specify in the command, for example:

This shows that the SP is able to successfully access the Azure Key Vault key HSMACKeyPair and export its public key via the exposed API set up.

Note: Full details of SP configuration can be found in the following Microsoft documentation:

https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal

4 Configure KeyScaler with HSM KeyVault Service Connector

4.1 KeyScaler Control Panel Configuration

4.1.1 Configure Connector for HSM KeyVault

Login to KeyScaler with control Panel credentials:

and navigate to the Manage Service Connectors screen as shown below:

Click on +Add New:

Next select the Service Provider KeyVault for HSM Access from the pull-down menu and fill in the details for the connector as per below, and Click the SAVE button:

• Profile Name: <Name of new Service Connector>

• URL: <url of the Service Connector>, this will be used in the properties file later in this section

• KeyVault Name: <Name of the KeyVault being used in association with this connector>

• API Secret: <API Secret – Leave this blank as this will be a 32-bit value that is auto generated>

• Service Connector Uses TLS: <Check Box for TLS >, TLS Set up is described in Section 6.

Once Saved, View the Service connector and confirm that the API Secret has been generated and populated in the configuration, as shown. Make a note of the value for later.

4.1.2 Configure Connector for CA

Check ? do I need this?

Next, create another Service Connector for the KeyVault called HACKV001 that used the EPIC framework to connect to Azure KeyVault. This time use the connector for KeyVault for CA.

4.1.3 Configure HSM Policy

Next on CP, navigate to the HSM Access Controller Policies, as shown:

Next, click on +New Policy:

Fill in the Policy form as shown in the example below. Note here to Check the box for Service Connector and select the Service connector from the pull-down menu created in the previous step.

This completes the one-time Control Panel configurations.

4.2 Configuration of KeyScaler System

SSH to the KeyScaler Instance and navigate to the following Directory: and list the files:

[root@keyscaler-672-001 conf]# cd/var/dfactor/conf/
[root@keyscaler-672-001 conf]# ls -al
[root@keyscaler-672-001 conf]# nano epic-service-connector-key-vault.properties

Item 4 – KeyScaler System – Edit the Key Vault service properties file

Edit the epic-service-connector-key-vault.properties file as shown below:

# Optional
# Server port, default from Spring Boot (8080)
# Should be specified for 'real world' cases
server.port=8888
# Optional
# Endpoint on which service requests will be expected, default in the base configuration
# Should be specified for 'real world' cases
# Included in the URL defined in the CP service connector, e.g. https://someserver:8080/sc/keyvault
hsm-access.endpoint=/keyvault
# Optional
# Whether TLS (https) is enabled, default is true
# Set to false only for development or testing
server.ssl.enabled=false
# Required, when server.ssl.enabled=true
server.ssl.key-store-type=
server.ssl.key-store=
server.ssl.key-store-password=
server.ssl.key-alias=
management.endpoints.web.exposure.include=loggers
management.endpoint.loggers.enabled=true

Item 5 - Configure epic-service-connector-key-vault.properties

Next make a new directory keyvault/HACKV001/ from the home directory and copy the HSM KeyVault Files as shown:

[root@keyscaler-672-001 conf]# cd/home/devuser/keyvault/HACKV001/
[root@keyscaler-672-001 conf]# ls -al

Item 6 – KeyScaler System –list the HSM Key Vault files

[root@keyscaler-672-001 HACKV001]# nano set-env.sh

Item 8 – KeyScaler System – edit set-env.sh

Copy the same Environmental Variables as used in the connectivity test adding the API Secret value for the additional variable for EPIC_SC_KEY_VAULT_SECRET:

#keyvault HACKV001 settings using SP = SPforHACKV001
export EPIC_SC_KEY_VAULT_SECRET=WeXdAxX/DfFzSwzmFBLLac5EoypkbjpwNL0uZPNUBqA=
export AZURE_TENANT_ID=10ebeb0d-e7ea-43f2-84da-966998200c07
export AZURE_CLIENT_SECRET=r.S7Q~c7zrRlQpMOnVPs.Qr~_oWrlWwBM_-QI
export AZURE_CLIENT_ID=039d04fe-036e-46ab-90ca-31ed966fda3e

echo EPIC_SC_KEY_VAULT_SECRET = $EPIC_SC_KEY_VAULT_SECRET
echo AZURE_TENANT_ID = $AZURE_TENANT_ID
echo AZURE_CLIENT_SECRET = $AZURE_CLIENT_SECRET
echo AZURE_CLIENT_ID = $AZURE_CLIENT_ID

Item 9 – Configure file set-env.sh

Check all the Environmental Variable are correct. Next, run the script run-service-connector.sh. The script checks that the environmental variables are set before it is executed.

if [[ -z "${AZURE_TENANT_ID}" ]]; then
  echo "AZURE_TENANT_ID environment variable not set!"
  exit
fi

if [[ -z "${AZURE_CLIENT_SECRET}" ]]; then
  echo "AZURE_CLIENT_SECRET environment variable not set!"
  exit
fi

if [[ -z "${AZURE_CLIENT_ID}" ]]; then
  echo "AZURE_CLIENT_ID environment variable not set!"
  exit
fi

if [[ -z "${EPIC_SC_KEY_VAULT_SECRET}" ]]; then
  echo "EPIC_SC_KEY_VAULT_SECRET environment variable not set!"
  exit
fi

java -jar service-connector-key-vault.war

Item 11 – run-service-connector.sh

Execute the run-service-connector.sh script

[root@keyscaler-672-001 HACKV001]# . run-service-connector.sh

Item 12 – Run the KeyVault Connector-script > run-srvice-connector.sh

The KeyVault service is now running, this can be checked with the following command:

[root@keyscaler-672-001 HACKV001]# ps aux | grep service-connector-key-vault.war

Item 14 – Run the KeyVault Connector-script > run-srvice-connector.sh

Ensure there is a process for service-connector-key-vault.war in the output:

4.2.1 Change Logging Level

The output logs for the connector have the log levels set to ‘WARN’. This can be changed to provide more detailed logging level e.g., ‘TRACE’ using another script file provided called set-trace-logging.sh. Similarly, the logging level can be reduced back to WARN by editing the script.

curl -i -X POST -H 'Content-Type: application/json' -d '{"configuredLevel": "TRACE"}' http://azure.epic.connector.com:8888/actuator/loggers/com.deviceauthority
curl http://azure.epic.connector.com:8888/actuator/loggers/com.deviceauthority

Item 16 – set-trace-logging.sh

Run the script with the following command:

The curl command output the current logging level for the connector:

Item 18 – Check logging level with curl command

This completes the setup of the HSM Connector on the KeyScaler System.

5 Testing

To test the KeyVault connector set up in the above section, use the Python scripts[1] to invoke the REST API calls to:

1. Generate a keypair

2. Encrypt Data

3. Decrypt Data

[1] Please contact Device Authority Support for Sample Python Scripts

Also , before the python script can be run, ensure you have your device (Laptop) executing the scripts are registered with KeyScaler.

5.1 Generate an RSA Key Pair (4096) in KeyVault

To generate a new Key with Key Alias: ENCRYPTKEY001KVKey27092021, configure the python script with the correct KeyScaler Endpoint, Policy (with service connector to HSM KeyVault).

Following a REST API Call to gen key, a sample response from KeyScaler would look like the following:

{
    "assets": [],
    "httpCode": 200,
    "message": {
        "status": true
    },
    "requestId": "54711bd1-3f35-4ca2-b5de-bfd037052794",
    "responseTimestamp": 1632778197037,
    "statusCode": 0
}

Item 19 – Sample JSON response of API for Generate RSA Key

Refresh the KeyVault page to show the new Key ENCRYPTKEY001KVKey27092021 created in HACKV001 KeyVault:

Click on the Key, and this will allow the user to set the Activation and Expiry date via the Azure portal, as shown below:

Also, the same key can be viewed in via KeyScaler Control Panel:

Figure 53 – New RSA Key Generated in KeyVault and viewed from KeyScaler CP

The expected Logs output from /var/dfactor/logs/epic-service-key-vault.log, could look like this the following:

Item 20 – Sample log output from /var/dfactor/logs/epic-service-key-vault.log

The expected Logs output from /var/dfactor/logs/dae.log, could look like this the following:

Item 21 – Sample log output from /var/dfactor/logs/dae.log

6 SSL Configuration

For Production Systems it is highly recommended to configure the KeyScaler System with SSL enabled. This chapter described the SSL connection settings required to enable and test it.

6.1 KeyScaler Control Panel

Navigate to the Manage Service Connectors setting as shown below:

Select to Edit the required connector:

Next, check the Box for Service Connector uses TLS and copy a the Service Connector Public Certificate into the text box called Service Connector Certificate. The next step describes how to create this public certificate.

Create a p12 keystore called, e.g., hsmkeyvault.p12 either using keytool or Keystore Explorer application.

In that keystore generate an RSA KeyPair with alias e.g., hsmkeyvault and password hsmkeyvault.

Generate a CSR and get that signed ( self-signed) and import the signed certificate back into the p12 key store for your key.

Export the public key of your certificate and paste the public key into the KeyScaler Control panel as shown in the Figure below and Save the settings:

Now make the following modification in the /var/dfactor/conf/epic-service-connector-key-vault.properties file to match the settings you have created in the p12 keystore:

# Optional
# Server port, default from Spring Boot (8080)
# Should be specified for 'real world' cases
# 
server.port=8888

# Optional
# Endpoint on which service requests will be expected, default in the base configuration
# Should be specified for 'real world' cases
# 
# Included in the URL defined in the CP service connector, e.g. https://someserver:8080/sc/keyvault
# 
hsm-access.endpoint=/keyvault

# Optional
# Whether TLS (https) is enabled, default is true
# Set to false only for development or testing
# 
server.ssl.enabled=true

# Required, when server.ssl.enabled=true
# 
server.ssl.key-store-type=PKCS12
server.ssl.key-store=hsmkeyvault.p12
server.ssl.key-store-password=hsmkeyvault
server.ssl.key-alias=hsmkeyvault

management.endpoints.web.exposure.include=loggers
management.endpoint.loggers.enabled=true

Item 22 – Edit epic-service-connector-key-vault.properties file for SSL connection

Copy the hsmkeyvault.p12 keystore file to the same directory as the KeyVault connector war file. Restart the service-connector-key-vault.war application for the above properties file changes to take effect.

Retest the RSA Key Generation as shown in Section 5 to confirm that the SSL connection is being made to the Azure KeyVault to generate a keyvault Key.

------------------------ End of Document -------------------------