1.0 Introduction
This article describes how to integrate Fortanix-Data-Security-Manager (DSM) with Zoho Bring Your Own Key (BYOK) feature to use a key from Fortanix DSM as the Key Encryption Key (KEK) in place of Zoho's default KEK.
Zoho offers a suite of cloud-based applications for managing various business functions such as Customer Relationship Management (CRM), finance, and human resources. By integrating Zoho with Fortanix DSM, you maintain full control over your encryption keys, which ensures that your data remains secure and complies with regulatory requirements.
2.0 Prerequisites
Ensure the following
Fortanix DSM is accessible. For more information, refer to Section 5.1: Signing Up and Section 5.2: Creating an Account.
3.0 Product Tested Version
Fortanix DSM version 4.23 and above.
4.0 Architecture Diagram
Figure 1: Architecture Diagram
You can configure Fortanix DSM as your external key manager to manage KEKs for encrypting and decrypting the Data Encryption Keys (DEKs) used by Zoho. By integrating with Fortanix DSM, you maintain full control over your encryption operations, enhancing the security of your data.
After you configure the key in Zoho Directory, Zoho sends a request to Fortanix DSM to encrypt its DEKs using the KEK. Fortanix DSM processes this request, encrypts the DEK, and securely returns the encrypted DEK to Zoho. Zoho then stores the encrypted DEK in its internal Key Management Service (KMS).
When Zoho requires the plaintext DEK for operations, it sends a decryption request to Fortanix DSM along with the encrypted DEK. Fortanix DSM decrypts the DEK and securely provides the plaintext DEK to Zoho. Zoho temporarily caches the plaintext DEK for the duration, specified by you. Once this caching period ends, Zoho sends a fresh request to Fortanix DSM for encrypting or decrypting the DEK, repeating the process as needed.
5.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:
5.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.
5.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.
Figure 2: Logging In
5.3 Creating a Group
Perform the following steps to create a group in the Fortanix DSM:
Click the Groups menu item in the DSM left navigation panel and click the + button on the Groups page to add a new group.
Figure 3: Add Groups
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.
Click the SAVE button to create the new group.
The new group has been added to the Fortanix DSM successfully.
5.4 Creating an Application
Perform the following steps to create an application (app) in the Fortanix DSM:
Click the Apps menu item in the DSM left navigation panel and click the + button on the Apps page to add a new app.
Figure 4: Add Application
On the Adding new app page, enter the following details:
App name: Enter the name of your application.
Interface (optional): Select the REST 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 5.3: Creating a Group from the list.
Click the SAVE button to add the new application.
The new application has been added to the Fortanix DSM successfully.
5.5 Copying the API Key
Perform the following steps to copy the API key from the Fortanix DSM:
Click the Apps menu item in the DSM left navigation panel and click the app created in Section 5.4: Creating an Application to go to the detailed view of the app.
On the INFO tab, click the VIEW API KEY DETAILS button.
From the API Key Details dialog box, copy the API Key of the app to be used in Section 6.1: Adding a Key from an External Key Management (EKM) Provider.
6.0 Configuring Zoho
In this section, you will configure Zoho to work with Fortanix DSM as the EKM for securing your DEKs. This process includes adding keys from Fortanix DSM and potentially uploading a key through Zoho Directory.
6.1 Adding a Key from an External Key Management (EKM) Provider
Perform the following steps:
Log into the Zoho directory with your administrative credentials.
Click the Admin Panel menu item from the left navigation panel and navigate to the Security option.
Select the BYOK option → Setup button.
If you already have a key added, click Add Key from the top-right of the screen.
Figure 5: Add BYOK
On the Add Key page, enter the following:
Key Name: Enter a name for the key.
Available Applications: Select the applications you want to secure with this key.
Key Type: Select the Fortanix DSM radio button, then enter the following key details:
Key provider: Select the Google KMS option from the drop down menu.
API key: Enter the API Key as copied in Section 6.5: Copying the API Key.
Key ID: Provide the Key ID.
Domain: Specify the Domain.
NOTE
You can retrieve the necessary details such as the API Key, Key ID, and Domain from the Fortanix DSM user interface (UI).
Figure 6: Fortanix DSM Key Type
Cache Duration: Select the required duration from the drop-down menu. This setting determines how long the decrypted DEK will be cached before the system needs to send encrypt/decrypt requests to the EKM again.
Figure 7: Cache Duration
Click the Add button to finish the setup process.
NOTE
When configuring BYOK for a specific service, the application is removed from the default key. If the BYOK key is deleted, the application will be added back to the default key.
6.2 Uploading a Key Through Zoho Directory
If you prefer to upload your own key instead of using an external key manager (EKM), follow these steps:
6.2.1 Prerequisites
Ensure you have the following:
A BYOK certificate.
An encrypted KEK.
A Hashed KEK.
6.2.2 Adding a BYOK Certificate
Perform the following steps to add and download a certificate in the Zoho directory:
Click the Admin Panel menu item from the left navigation panel and then navigate to the Security option.
Click the BYOK menu item, then select the View Certificates button from the top-right corner of the screen.
Click the Add Certificates button and provide a unique name for your certificate.
Click the Add button.
NOTE
You can add up to two certificates.
Hover over the added certificate and click the download icon to download it for key generation.
6.2.3 Generating an Encrypted Key Encryption Key (KEK)
This section outlines the steps to generate an encrypted KEK by extracting a public key from a certificate, encrypting the AES key with it, and generating a hash for the AES key.
Perform the following steps in a local environment:
Run the following command to extract the public key from the downloaded certificate file:
public static String getPublicKeyFromFile(String fileName) throws IOException, CertificateException { PemReader reader = new PemReader(new FileReader(new File(fileName))); PemObject pemObject = reader.readPemObject(); byte[] content = pemObject.getContent(); reader.close(); InputStream fin = new ByteArrayInputStream(content); CertificateFactory f = CertificateFactory.getInstance("X.509"); X509Certificate certificate = (X509Certificate)f.generateCertificate(fin); PublicKey pk = certificate.getPublicKey(); return Base64.getEncoder().encodeToString(pk.getEncoded()); }Run the following command to encrypt the AES key using the RSA public key you extracted from the certificate:
public static String encryptKeyWithPublicKey(String publicKey, byte[] plainKeyBytes) throws Exception{ byte[] publicKeyBytes = Base64.getDecoder().decode(publicKey); X509EncodedKeySpec keySpec = new X509EncodedKeySpec(publicKeyBytes); KeyFactory keyFactory = KeyFactory.getInstance("RSA"); PublicKey publicKey = keyFactory.generatePublic(keySpec); Cipher encryptCipher = Cipher.getInstance("RSA/ECB/OAEPWITHSHA- 256ANDMGF1PADDING"); OAEPParameterSpec oaepParams = new OAEPParameterSpec("SHA- 256", "MGF1", new MGF1ParameterSpec("SHA-256"), PSource.PSpecified.DEFAULT); encryptCipher.init(Cipher.ENCRYPT_MODE, publicKey, oaepParams); byte[] encryptedBytes = encryptCipher.doFinal(plainKeyBytes); return Base64.getEncoder().encodeToString(encryptedBytes); }Run the following command to generate the AES key hash value:
public static String getHashValue(byte[] plainKeyBytes) throws NoSuchAlgorithmException { MessageDigest digest = MessageDigest.getInstance("SHA- 256"); byte[] hashed = digest.digest(plainKeyBytes); return Base64.getEncoder().encodeToString(hashed); }
6.2.4 Uploading a Key
Perform the following steps to add a key:
Click the Admin Panel menu item from the left navigation panel and then navigate to the Security option.
Click the BYOK → Setup option.
If you already have a key added, click the Add Key button from the top-right of the screen.
On the Add Key page, enter the following details:
Key Name: Enter a name for the key.
Available Applications: Select the applications you want to secure with this key.
Key Type: Choose the appropriate key type such as External Key Manager, Upload Key.
BYOK Certificates: Select the BYOK certificates you have uploaded.
Hashed KEK: Browse and upload the generated hashed KEK.
Encrypted KEK: Browse and upload the generated encrypted KEK.
Figure 8: Add BYOK Certificates
Click the Add button to finalize the key upload process.
6.2.5 Managing the Keys
To edit, change, or delete a key, refer to Zoho’s official documentation.