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 at any time through the Fortanix DSM REST APIs or web interface.

2.0 Definitions

Linux Unified Key Setup (LUKS) - Linux Unified Key Setup (LUKS) provides a set of 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 Data Security Manager (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 the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.

3.3 Creating a Group

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

1. Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.

   

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

   • Title: Enter a title for your group.

   • Description (optional): Enter a short description for the group.

3. Click the SAVE button to create the new group.

The new group has been 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. Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.

   

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

   • App name: Enter the name of your application.

   • Interface (optional): Select the REST API option as interface type from the drop down menu.

   • ADD DESCRIPTION (optional): Enter a short description for the application.

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

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

3. Click the SAVE button to add the new application.

The new application has been 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. Click the Apps menu item in the DSM left navigation bar and 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 the VIEW API KEY DETAILS button.

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. Click the Apps menu item in the DSM left navigation bar and 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 the VIEW API KEY DETAILS button.

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

Base64 encode your passphrase/key and import it in your app group as a security object.

$ 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

Note down the API_KEY and KEY_UUID for the secret, you created and update the launch script (below).

#!/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

We tested this script on Ubuntu 16.04 LTS server image which has cryptsetup package installed. Please install cryptset on your Linux servers.

This script can be used on Amazon AWS, Azure Compute, Google GCE, or as a post-install script inside the Linux environment in your data center.

This solution uses a loop-back device /dev/loop0 but any block device /dev/sd(id) or /dev/xvd(id) attachments is a valid use case.

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

For Google Compute Engine the above script is used in the startup script section of the GCE portal or use gcloud start-script cmdline.

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

7.0 Verify Encryption and Mount the Block Device

Now you can verify and mount the encrypted block device and see the key operation on the Fortanix DSM web interface. Fortanix DSM logs all key operations in a tamper-proof audit log.

To check the status of the device-mapper secretfs and see encryption details:

$cryptsetup status secretfs

To verify the passphrase see the key slot id for encrypted device

$sudo cryptsetup luksDump /dev/loop0

To verify your password works (enter the password when prompted):

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

To mount the encrypted block device:

$mkfs.ext4 /dev/mapper/secretfs

$mkdir /mnt/encrypted

$mount /dev/mapper/secretfs /mnt/encrypted

To clean up your secret storage:

$sudo cryptsetup luksClose /dev/mapper/secretfs

$sudo losetup -d /dev/loop0

$rm secretfs