Using Fortanix Data Security Manager for Kernel Module Signing Guide

1.0 Introduction

Welcome to the Fortanix-Data-Security-Manager (DSM) integration guide. This article provides step-by-step instructions on how to sign the Linux kernel module files using the sign-file utility, Fortanix DSM, and the Fortanix Public-Key Cryptography Standards (PKCS#11) client.

When utilizing an external Key Management Service (KMS) such as Fortanix, the sign-file utility offers two alternatives:

• Utilize the PKCS#11 URI to transmit the signing request to the remote key. Although this feature might not be accessible in older Linux kernel versions.

• Retrieve the signature from the remote key, save it in a file, and supply it as input to the sign-file utility to append it to the file.

This document covers the following:

• Configuring Fortanix DSM

• Setting up the PKCS#11 client in the signing server

• Creating kernel signing public certificates

• Signing kernel modules using the Fortanix DSM key

• Troubleshooting tips

2.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:

2.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.

2.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.

2.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 panel 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.

2.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 panel 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 2.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.

2.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 panel and click the app created in Section 2.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 use it later.

2.6 Creating a Security Object

Perform the following steps to generate an RSA key in the Fortanix DSM:

1. Click the Security Objects menu item in the DSM left navigation panel and click the + button on the Security Objects page to add a security object.

   

2. On the Add new Security Object page, enter the following details:

   • Security Object Name: Enter the name of your security object. For example, KernelSigningRSA.

   • Group: Select the group as created in Section 2.3: Creating a Group.

   • Select the GENERATE radio button.

   • Choose a type: Select the RSA key type to generate.

   • Exponent: Select the value used in RSA key from the drop down menu.

   • Key operations permitted: Select the required operations to define the actions that can be performed with the cryptographic keys. The key must have a minimum set of permissions, including Sign, Verify, and App Manageable.

   • Ensure to select the PKCS1v15 signature option for Encryption in the Padding Policy column.

3. Click the GENERATE button to create the new security object.

3.0 Set Up Fortanix PKCS#11 Client

This section illustrates the procedures for configuring the Fortanix PKCS#11 client on the signing server.

3.1 Download the Fortanix PKCS#11 Client

Download the latest .so file for the PKCS#11 client and copy it to the signing server.

3.2 Integrate the Fortanix PKCS#11 Client

Perform the following steps for integrating the Fortanix PKCS#11 client with the signing server:

1. Install the OpenSSL PKCS#11 engine:

   1. For Debian-based Linux distributions (including Ubuntu), run the following command:

      sudo apt install libengine-pkcs11-openssl

   2. For CentOS, RHEL, or Fedora (with EPEL repository available), run the following command:

      yum install engine_pkcs11

   3. Run the following command to verify if the PKCS#11 engine is installed:

      adminguy@ubuntu:~$ openssl engine pkcs11
      (pkcs11) pkcs11 engine

2. Create an OpenSSL configuration file, such as openssl.conf, with the following content:

   openssl_conf = openssl_def
   [openssl_def]
   engines = engine_section
   [req]
   distinguished_name = req_distinguished_name
   [req_distinguished_name]
   # empty.
   [engine_section]
   pkcs11 = pkcs11_section
   [pkcs11_section]
   PIN = file://</path/to/pkcs11.conf file>
   engine_id = pkcs11
   dynamic_path = </path/to/pkcs11 engine>
   MODULE_PATH = </path/to/fortanix pkcs11 file>
   init = 0

   Here,

   • PIN: Specifies the pkcs11.conf file path.

     For example, PIN= file:///etc/fortanix/pkcs11.conf

     For more details on creating the pkcs11.conf file, refer to the Section 3.3.1: API Key Based Authentication.

   • dynamic_path: Specifies the dynamic path (the file location) of the PKCS#11 engine library that OpenSSL should load. This will be a shared object that implements the PKCS#11 interface.

     For example, dynamic_path = /usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so

   • MODULE_PATH: Sets the module path for a Fortanix PKCS#11 module. This points to a file or library that provides the cryptographic functionality.

     For example, MODULE_PATH = /usr/local/lib/fortanix/fortanix_pkcs11_4.36.2530.so

3.3 Create the PKCS#11 Configuration File

You can create and configure the PKCS#11 file for the PKCS#11 client using any of the following authentication methods:

• API Key

• Certificate

3.3.1 API Key Based Authentication

Perform the following steps:

1. Create the /etc/fortanix directory.

2. Run the following command in /etc/fortanix directory to create the configuration file with the parameters listed below:

   vi pkcs11.conf

   api_endpoint = "<ENDPOINT URL>"
   api_key= "<API_KEY>"
   
   [log]
   file = "</path/to/log/file>"
   level = "info"

   Here,

   • api_key: This is the API key used for authentication. Use the value copied in the Section 2.5: Copying an API Key.

   • api_endpoint: This parameter defines the endpoint URL to which the PKCS#11 client connects. The default endpoint is https://apps.smartkey.io, but it can be customized by specifying a different URL. For more details on the different Fortanix DSM endpoint URLs, refer to the Fortanix DSM SaaS Global Availability Map.

   • [log]: For more details, refer to the PKCS#11 Library: Logging.

3.3.2 Certificate Based Authentication

NOTE

• If you have already completed the API key based authentication, certificate-based authentication is not required.

• If you want to use certificate-based authentication, ensure to follow the steps mentioned in Section 3.3.1: API Key Based Authentication before proceeding.

1. Perform the following steps to create a self-signed certificate with a key in Fortanix DSM:

   1. Run the following command to set the Fortanix DSM App UUID:

      export FORTANIX_APP_UUID=<Fortanix DSM App UUID>

      Where, <Fortanix DSM App UUID> refers to the UUID of the Fortanix DSM app created in Section 2.4: Creating an Application.

   2. Run the following command to set the location of OpenSSL configuration file:

      export OPENSSL_CONF=/location/of/openssl conf file

   3. Run the following command to generate a self-signed certificate with key:

      openssl req -newkey rsa:2048 -nodes -keyout private.key -x509 -days 365 -out certificate.crt -subj "/C=US/ST=California/L=Mountain View/O=Fortanix, Inc./OU=SE/CN=$FORTANIX _APP_UUID"

2. Run the following OpenSSL command to convert the private key file to PKCS#8 .pem format:

   openssl pkcs8 -topk8 -in private.key -out private.pem -nocrypt

   This command will take the input private key file (private.key), convert it to PKCS#8 format, and save the result in the output file (private.pem). The -nocrypt option ensures that the conversion process does not encrypt the private key with a passphrase.

3. After creating the client certificate, upload the client certificate created in Step 1 to the Fortanix DSM app created in Section 2.4: Creating an Application.

   To upload the client certificate, perform the following steps:

   1. Go to the detailed view of the Fortanix DSM app and click Change authentication method.

   2. Select the Certificate option to change the authentication method to Certificate.

   3. Click SAVE.

   4. On the Add certificate dialog box, click UPLOAD NEW CERTIFICATE to upload the certificate file or paste the content of the certificate generated in Step 1.

   5. Select both the check boxes to confirm your understanding about the action.

   6. Click UPDATE to save the changes.

4. Update the PKCS#11 configuration file (pkcs11.conf) using the following command with the parameters listed below:

   vi pkcs11.conf

   api_endpoint = "<ENDPOINT URL>"
   cert_file = "</path/to/cert.pem>" # X.509 PEM client certificate
   key_file = "</path/to/key.pem>" # PKCS#8 PEM client private key
   app_id = "<APP_UUID>"       
   
   [log]
   file = "</path/to/log/file>"
   level = "info"

   Here,

   • app_id refers to the UUID of the Fortanix DSM app created in the Section 2.4: Creating an Application.

   • For more details on the cert_file and key_file, refer to PKCS#11: Configuration File Format.

4.0 Create the Fortanix Kernel Signing Public Certificate

Run the following commands to generate the kernel signing public certificate using the PKCS#11 URI from the key located in Fortanix:

export FORTANIX_PKCS11_NUM_SLOTS=1
export OPENSSL_CONF=/location/of/openssl/conf/file
openssl req -new -x509 -days 365 -sha256 -engine pkcs11 -keyform engine -key pkcs11:object=KernelSigningRSA -outform der -out Kernelsigningcert.der -subj "/CN=test.example.com"

Where, KernelSigningRSA refers to the name of the key created in the Section 2.6: Creating a Security Object.

Alternatively, run the following command if PKCS#11 URI is not supported in your OpenSSL version:

openssl req -engine pkcs11 -keyform engine -new -key 1:<ID> -nodes -days 365 -x509 -sha256 -out test.pem -subj "/CN=test.example.com"

Where, <ID> refers to the UUID of the Fortanix DSM key created in Section 2.6: Creating a Security Object.

5.0 Sign the Fortanix Kernel Modules

5.1 Sign Using PKCS#11 URI

Perform the following steps only if signing the kernel modules using the PKCS#11 URI.

Run the following command to invoke the sign-file utility for signing:

./sign-file sha256 <pkcs11 uri for key> <public certificate> <module file for signing> <destination of signed file>

Where,

• <pkcs11 uri for key> refers to the PKCS#11 URI for the Fortanix DSM key.

• <public certificate> refers to the public certificate used for signing.

• <module file for signing> refers to the kernel module file that you want to sign.

• <destination of signed file> refers to the location where the signed module file will be saved.

For example,

./sign-file sha256 pkcs11:object=KernelSigningRSA?pin-value=file:///etc/fortanix/pkcs11.conf /etc/fortanix/Kernelsigningcert.der /etc/fortanix/mfe_aac_100713218.ko /etc/fortanix/mfe_aac_100713218_signed.ko

5.2 Sign Using Signature File

Perform the following steps only if signing the kernel modules using a signature file.

1. Run the following command to obtain the signature from Fortanix using a sample script:

   hashbase64=`sha256sum hello.ko | awk '{printf $1}' | xxd -r -p | base64`
   json='{
   "hash_alg": "sha256",
   "hash": "",
   "mode": {
   "PKCS1_V15": {}
   },
   "deterministic_signature": true
   }'
   json=$( jq --arg value "$hashbase64" '.hash= $value' <<< "$json")
   echo $json
   signature=`curl --location --request POST 'https://<URL>/crypto/v1/keys/<key UUID>/sign' --header 'Authorization: Basic <API Key>' --data "$json" | jq -r '.signature'`
   echo -n $signature | base64 -d > signature.raw

   Where,

   • <hello.ko> refers to the specific .ko file for which you want to obtain the signature.

   • <URL> refers to the endpoint where you can access Fortanix DSM for signature retrieval.

   • <key UUID> refers to the unique identifier assigned to your Fortanix DSM key.

   • <API Key> refers to the authentication key needed for authorization in the curl request.

2. Run the following command to sign:

   export FORTANIX_PKCS11_NUM_SLOTS=1
   ./sign-file -s <signature file> <public certificate> <module file for signing> <destination of signed file> 

   Where,

   • <signature file> refers to the file obtained in Step 1.

   • <public certificate> refers to the public certificate used for signing.

   • <module file for signing> refers to the kernel module file that you want to sign.

   • <destination of signed file> refers to the location where the signed module file will be saved.

   For example,

   sign-file -s /etc/fortanix/signature.raw sha256 /etc/fortanix/Kernelsigningcert.der /etc/fortanix/hello.ko /etc/fortanix/hello_signed.ko.

6.0 Troubleshooting

If you encounter any issues, refer to the PKCS#11 Library - Troubleshooting.