Using Fortanix Data Security Manager for Block Storage Encryption on Linux Server

1.0 Introduction

This article describes the steps to encrypt block devices using Fortanix-Data-Security-Manager (DSM) on cloud platforms (Amazon AWS, Microsoft Azure, Google GCE) or local Linux instances. You can manage key permissions, review audit logs, and disable keys anytime through the Fortanix DSM REST APIs or web interface.

2.0 Definitions

Linux Unified Key Setup (LUKS) - Linux Unified Key Setup (LUKS) provides tools that simplify managing encrypted devices. With LUKS, you can encrypt block devices and enable multiple user keys to decrypt a master key. For bulk encryption of the partition, use this master key. Fortanix provides connectors for the user to integrate LUKS with the Fortanix DSM.

3.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

3.1 Signing Up

To get started with the Fortanix DSM cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

3.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

For more information on how to set up an account in Fortanix DSM, refer to the User's Guide: Getting Started with Fortanix Data Security Manager - UI.

3.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.

   

2. On the Adding new group page, do the following:

   1. Title: Enter a title for your group.

   2. Description (optional): Enter a short description of the group.

3. Click SAVE to create the new group.

The new group is added to the Fortanix DSM successfully.

3.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the + button to create a new app.

   

2. On the Adding new app page, enter the following details:

   1. App name: Enter the name for your application.

   2. ADD DESCRIPTION (optional): Enter a short description of the application.

   3. Authentication method: Select the default API Key as the authentication method from the drop down menu. For more information on these authentication methods, refer to the User's Guide: Authentication documentation.

   4. Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.

3. Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

3.5 Copying the API Key

Perform the following steps to copy the API key from the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the app created in Section 3.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click VIEW API KEY DETAILS.

3. From the API Key Details dialog box, copy the API Key of the app to be used later.

3.6 Copying the App UUID

Perform the following steps to copy the app UUID from the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the app created in Section 3.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click VIEW API KEY DETAILS.

3. Click the USERNAME/PASSWORD tab.

4. From the Credentials Details dialog box, copy the Username (app UUID) and Password of the app to be used later.

4.0 Importing the Key into Fortanix DSM

Run the following command to Base64 encode your passphrase or key before importing it into Fortanix DSM:

$ echo "MyEncryptedKey" | base64
RUMyRW5jcnlwdGVkS2V5Cg==

This import will be assigned a UUID (KEY_UUID) to uniquely identify the passphrase. You can use the Fortanix DSM web app or REST APIs sample script (below) to import a key (more examples in Fortanix SDK)

#!/bin/bash

#example run  ./sdkm_script.sh KeyName bXlwYXNzd29yZAo=

# API ENDPOINT

API_ENDPOINT=https://<fortanix_dsm_url>

#API_KEY for your APP
api_key=NjdkNmRkYmEtYmMwMy00ODFhLWIwMTMtYWY1N2...

# log in app
log_in_app() {
curl -s -X POST -H "Content-Type: application/json" -H "Authorization: Basic $api_key" -d '' "$API_ENDPOINT/sys/v1/session/auth" \
| sed -e 's/[{}]/''/g' | awk -v RS=',"' -F: '/^access_token/ {print $2}' | tr -d \"
}

# get your secret passphrase
get_secret() {
secret=`curl -s -X GET -H "Authorization: Bearer $app_bearer_token" \
"$API_ENDPOINT/crypto/v1/keys/${key_uuid}/export" \
| sed -e 's/[{}]/''/g' | awk -v RS=',"' -F: '/^value/ {print $2 "\n" }' \
| tr -d \" | base64 --decode`
}

# generate secret key
create_secret() {
#json_params='{"alg": "'$alg'", "cipher": "'$cipher'", "mode": "'$mode'", "iv":"'$iv'" }'
json_params='{"name": "'$1'", "description": "Ec2 Encryp", "obj_type": "SECRET", "value": "'$2'","enabled": true}'
key_resp=`curl -s -X PUT -H "Authorization: Bearer ${app_bearer_token}" -d \
"${json_params}" "${API_ENDPOINT}/crypto/v1/keys"`

echo "DSM Key generation request response:"
echo $key_resp
key_uuid=`echo $key_resp | jq ".kid" | tr -d \"`
}

if [ $# -lt 2 ]; then
echo "./usage Kyename Base64keyvalue"
exit 1
fi

# get session token
app_bearer_token=$(log_in_app)
echo "Session token"
echo $app_bearer_token

create_secret $1 $2 $3 key_uuid
echo "New Key UUDID"
echo $key_uuid

echo "get secret"
get_secret $key_uuid secret
echo $secret

5.0 Customize the Deployment Script

After creating the secret in Fortanix DSM, run the following script and ensure to note down the API_KEY and KEY_UUID associated with it:

#!/bin/bash

## Initial setup to be executed on boot
##====================================

# Create an empty file. This file will be used to host the file system.
# In this example we create a 2 GB file called secretfs (Secret File System).
dd of=secretfs bs=1G count=0 seek=2
# Lock down normal access to the file.
chmod 600 secretfs
# Associate a loopback device with the file.
losetup /dev/loop0 secretfs



API_ENDPOINT=https://<fortanix_dsm_url>

## Copy paste your api_key and uuid here.

api_key=NjdkNmRkYmEtYmMwMy00ODFhLWIwMTMtYWY1N2UyMGUxOWVjOnRqUWN5VFdfN0ZncHVjVmxmblVGVkppMmRYaGp0OGktWndGM2ZWb3E1Y3BXZ01XS25ldE0tT3ZMRTluTml2SS1SSHlGX3BLQW5GSUhLTUVNUHZXRl
key_uuid=dd61b89c-e761-41ee-a700-4f3e4915f7c9


log_in_app() {
curl -s -X POST -H "Content-Type: application/json" -H "Authorization: Basic $api_key" -d '' "$API_ENDPOINT/sys/v1/session/auth" \
| sed -e 's/[{}]/''/g' | awk -v RS=',"' -F: '/^access_token/ {print $2}' | tr -d \"
}
get_secret() {
LuksClearTextKey=`curl -s -X GET -H "Authorization: Bearer $app_bearer_token" \
"$API_ENDPOINT/crypto/v1/keys/${key_uuid}/export" \
| sed -e 's/[{}]/''/g' | awk -v RS=',"' -F: '/^value/ {print $2 "\n" }' \
| tr -d \" | base64 --decode`
}

# get session token
app_bearer_token=$(log_in_app)
echo $app_bearer_token
get_secret LuksClearTextKey
echo $LuksClearTextKey

# Encrypt storage in the device. cryptsetup will use the Linux
# device mapper to create, in this case, /dev/mapper/secretfs.
# Initialize the volume and set an initial key.
echo "$LuksClearTextKey" | cryptsetup -y luksFormat /dev/loop0
# Open the partition, and create a mapping to /dev/mapper/secretfs.
echo "$LuksClearTextKey" | cryptsetup luksOpen /dev/loop0 secretfs
# Clear the LuksClearTextKey variable because we don't need it anymore.
unset LuksClearTextKey
# Check its status (optional).
cryptsetup status secretfs

This script has been tested on Ubuntu 16.04 LTS Server, which includes the cryptsetup package by default. Ensure that the cryptsetup package is installed on your Linux servers before running the script.

The script is compatible with multiple cloud platforms, including Amazon AWS, Microsoft Azure Compute, Google Compute Engine (GCE), or it can be executed as a post-installation script within on-premises Linux environments.

The solution primarily utilizes a loopback device (/dev/loop0) for encryption and mounting operations. However, any valid block device such as /dev/sdX or /dev/xvdX can be used, depending on your infrastructure and device attachments.

6.0 Use the Deployment Script for Block Device Encryption

• Amazon Ec2

• Azure

• Google Compute Engine

6.1 Amazon Ec2

For Amazon Ec2 use the above script as input in advance details of EC2 instance launch section and launch the instance.

6.2 Microsoft Azure

For Azure compute use the above script as input to custom script for Linux on Azure compute portal or use Azure custom extension cmdline.

You can also add a custom extension from the Azure command line, Upload the above script on your web server or cloud storage as sdkms_azure.sh for this example.

az vm extension set ' --resource-group exttest `
--vm-name exttest ` --name customScript `
--publisher Microsoft.Azure.Extensions `
--settings '{"fileUris": ["https://your-script-server/sdkms_azure.sh"],
"commandToExecute": " sudo sh sdkms_azure.sh"}'

6.3 Google Compute Engine

To automate the execution of your encryption verification and mounting script (or any initialization commands) on GCE virtual machine instances, you can use the startup script feature. This script runs automatically when the instance boots.

You have two primary options to provide the startup script:

• Through the GCE Console Portal:

  When creating a new VM instance, under the Management, security, disks, networking, sole tenancy section, go to the Automation tab and paste your shell script into the Startup script text box.

• Through the gcloud CLI tool:

  Use the --metadata-from-file flag to pass the startup script file during instance creation.

gcloud compute instances create example-instance \
    --metadata-from-file startup-script="scripts/sdkms_gcloud.sh"

7.0 Verify Encryption and Mount the Block Device

Run the following command to verify and mount the encrypted block device on your Nutanix node:

This operation will also trigger key usage events that can be monitored on the Fortanix DSM web interface. Fortanix DSM logs all key operations in a tamper-proof audit log for full traceability and security compliance.

1. Run the following command to check the status of the device-mapper secretfs and see encryption details:

   $cryptsetup status secretfs

2. Run the following command to verify the passphrase, see the key slot ID for the encrypted device:

   $sudo cryptsetup luksDump /dev/loop0

3. Run the following command to verify your password works (enter the password when prompted):

   $cryptsetup luksOpen --test-passphrase --key-slot 0 /dev/loop0 && echo correct

4. Run the following command to mount the encrypted block device:

   $mkfs.ext4 /dev/mapper/secretfs
   $mkdir /mnt/encrypted
   $mount /dev/mapper/secretfs /mnt/encrypted

5. Run the following command to clean up your secret storage:

   $sudo cryptsetup luksClose /dev/mapper/secretfs
   $sudo losetup -d /dev/loop0
   $rm secretfs