User's Guide: Plugin Library

1.0 Introduction

This document describes the features of the Fortanix-Data-Security-Manager (DSM) Plugins and Plugin Library.

The Plugin Library is a feature of Fortanix DSM that allows users to view a list of commonly used plugins in one centralized location. Fortanix DSM users can create local copies of the plugins they intend to use and start invoking them. The Fortanix DSM Plugin Library is stored in a Git repository that contains the plugin code. Fortanix DSM users will have access to updated and new plugins whenever the repository is updated by Fortanix.

It also contains the information related to:

• Creating a new plugin

• Accessing Fortanix DSM Plugin Library

• Installing a plugin from the Plugin Library

• Reviewing plugin source code before installation

• Modifying plugin source code after installation

• Upgrading plugins to newer versions

2.0 Creating a Plugin

You can add a new plugin by uploading a file containing the plugin code or by typing the code inline.

Perform the following steps to create a new plugin:

1. In the Fortanix DSM UI, navigate to Plugins menu item and click + NEW PLUGIN to create, import, or browse a new plugin.

2. On the NEW PLUGIN dialog box, select the CREATE/IMPORT A NEW PLUGIN tile.

   NOTE

   Fortanix DSM currently supports plugins in Lua.

   

3. In the Adding new plugin form, do the following:

   1. Plugin name: Enter a name that identifies your plugin. For example: Demo Plugin.

   2. In the Assigning the new plugin to groups section, assign the new plugin to an existing group. You can also create a new group by clicking CREATE NEW GROUP and assigning the plugin to the new group.

   3. Click Next.

   

4. On the next screen, enter the source code for your plugin using one of the following methods:

   1. Select EDIT INLINE to use the editor to type your source code directly into the template.

   2. Select UPLOAD A FILE to upload the source code as a file and then edit it. Optionally, add a Plugin signature.

   3. Click CREATE.

   

3.0 Accessing Fortanix Data Security Manager Plugin Library

In the Fortanix DSM UI, navigate to Plugins → PLUGIN LIBRARY tab to access the Fortanix Plugin Library and view the list of all the available plugins with a short description of their functionality.

Clicking a plugin tile in the Plugin Library displays the associated plugin page, which provides detailed information including common use cases, setup instructions, and the format of plugin inputs and outputs.

4.0 Installing a Plugin from the Plugin Library

Perform the following steps to install a plugin from the Fortanix Plugin Library:

1. On the Plugin Library page, select a plugin as explained in the previous section and click GET PLUGIN.

2. In the Adding new plugin form, do the following:

   1. Plugin Name: Review and update the plugin name if required.

   2. In the Assigning the new plugin to groups section, assign the new plugin to a group. You can also create a new group by clicking CREATE NEW GROUP and assign the plugin to the new group.

3. Click SAVE.

4.1 Review Plugin Source Code Before Installation

You can review the plugin source code before installation by clicking the link provided on the plugin page. The link redirects to the official Fortanix Plugin Library repository on GitHub: https://github.com/fortanix/sdkms-plugin-registry.

4.2 Modify Plugin Source Code After Installation

After installing a plugin, you can manage it the same way as a plugin created through the Create/Import New Plugin page. You can modify the original source code after creation to meet specific requirements.

Go to the plugin’s detailed view and click the CODE tab. Edit the source code of the plugin as needed, and then click SAVE.

5.0 Upgrading Plugins to New Versions

Plugins in the Plugin Library are versioned. When a new version becomes available, an option to upgrade appears on both the Plugin Library list page and the plugin's detailed view page.

Click Upgrade to V1.3 to upgrade the plugin version from 1.2 to 1.3.

When you upgrade a plugin, the system displays the release notes for the new version and provides an option to create a backup copy of the currently installed version.

6.0 List of Plugins in the Plugin Library

6.1 AWS BYOK Plugin

6.1.1 Introduction

The cloud services provide many advantages, but the major disadvantage of cloud providers has been security because physically your data resides with the cloud provider. To keep your data secure in a cloud provider environment, enterprises use encryption. So, securing their encryption keys become significantly important. Bring Your Own Key (BYOK) allows enterprises to encrypt their data and retain control and management of their encryption keys. This plugin provides an implementation to use the AWS cloud BYOK model.

6.1.2 Use cases

The plugin can be used to:

• Push Fortanix DSM key in AWS KMS.

• List Fortanix DSM AWS BYOK key.

• Rotate Fortanix DSM AWS BYOK key.

• Disable AWS BYOK key from Fortanix DSM.

• Enable AWS BYOK key from Fortanix DSM.

• Delete AWS BYOK key from Fortanix DSM.

• Reimport key material from Fortanix DSM to AWS CMK.

6.2 Azure BYOK HSM Plugin

6.2.1 Introduction

The cloud services provide many advantages, but the major disadvantage of cloud providers has been security because physically your data resides with the cloud provider. To keep your data secure in a cloud provider environment, enterprises use encryption. So, securing their encryption keys become significantly important. Bring Your Own Key (BYOK) allows enterprises to encrypt their data and retain control and management of their encryption keys. This plugin provides an implementation to use the Azure cloud BYOK model.

6.2.2 Use Cases

The plugin can be used to:

• Push Fortanix DSM key in Azure HSM key vault.

• List Azure BYOK key.

• Delete key in Fortanix DSM and corresponding key in Azure key vault.

6.3 Azure BYOK Plugin

6.3.1 Introduction

The cloud services provide many advantages, but the major disadvantage of cloud providers has been security because physically your data resides with the cloud provider. To keep your data secure in a cloud provider environment, enterprises use encryption. So, securing their encryption keys become significantly important. Bring Your Own Key (BYOK) allows enterprises to encrypt their data and retain control and management of their encryption keys. This plugin provides an implementation to use the Azure cloud BYOK model.

6.3.2 Use Cases

The plugin can be used to:

• Push Fortanix DSM key in Azure key vault.

• List Azure BYOK key.

• Rotate key in Fortanix DSM and corresponding key in Azure key vault.

• Delete key in Fortanix DSM and corresponding key in Azure key vault.

• Backup Azure key vault key.

• Recover Azure key vault key.

• Restore Azure key vault key.

• Purge Azure key vault key.

6.4 DUKPT Plugin

6.4.1 Introduction

DUKPT plugin is a Fortanix DSM implementation of the Derived Unique Key Per Transaction process that's described in Annex A of ANS X9.24-2009. This module provides DUKPT decryption using the 3DES scheme. It decrypts the encrypted card information using the KSN and BDK-ID as inputs to the plugin and generates decrypted/plain card information.

Initially, there is a Base Derivation Key (BDK) that is used to generate the "Initial PIN Encryption Key" (IPEK). The BDK always stays in the HSM and is never injected into the devices. It is known only by the manufacturer and the merchant. The "Key Serial Number" (KSN) and IPEK are injected into each device. The KSN is sent with the "crypt" material so that the receiving end can also decrypt it. The last 21 bits of the KSN are a counter that gets incremented every transaction.

There is a single DUKPT plugin, with three supported operations: import, encrypt, and decrypt.

6.4.2 Use Cases

As described above in the Introduction, the value of DUKPT is the ability to secure many independent messages in such a way that compromising the keys for any individual message does not endanger other messages while still minimizing the number of keys that need to be stored and managed. The canonical example of this, and the use case for which this procedure was developed, is to encrypt payment information during transactions.

6.5 Google Cloud BYOK Plugin

6.5.1 Introduction

The cloud services provide many advantages, but the major disadvantage of cloud providers has been security because physically your data resides with the cloud provider. To keep your data secure in a cloud provider environment, enterprises use encryption. So, securing their encryption keys become significantly important. Bring Your Own Key (BYOK) allows enterprises to encrypt their data and retain control and management of their encryption keys. This plugin provides an implementation to use the Google cloud BYOK model.

6.5.2 Use Cases

The plugin can be used to:

• Push Fortanix DSM key in Google Cloud KMS.

• List Fortanix DSM Google Cloud BYOK key.

• Rotate Fortanix DSM Google Cloud BYOK key.

• Disable Google Cloud BYOK key from Fortanix DSM.

• Enable Google Cloud BYOK key from Fortanix DSM.

• Delete Google Cloud BYOK key from Fortanix DSM.

• Reimport key material from Fortanix DSM to Google Cloud CMK.

6.6 HD Wallet Plugin

6.6.1 Introduction

The plugin allows to derive child key (xprv, xpub) from a master key in a deterministic way, and/or sign transaction hashes for UTXO and ethereum type crypto coin.

6.6.2 Use Cases

The plugin can be used to:

• Derive child key for UTXO.

• Derive child key for ethereum.

• Sign transaction for UTXO.

• Sign transaction for ethereum.

6.7 JWS+JWE Decrypt Plugin

6.7.1 Introduction

This plugin performs decrypt using JWE standards: enc: A256CBC-HS512 alg: RSA-OAEP-256.

6.7.2 Use Cases

• Assert one’s identity, given that the recipient of the JWE trusts the asserting party.

• Transfer data securely between interested parties over an unsecured channel.

6.8 JWS+JWE Encrypt Plugin

6.8.1 Introduction

This plugin performs encrypt using JWE standards: enc: A256CBC-HS512 alg: RSA-OAEP-256.

6.8.2 Use Cases

• Assert one’s identity, given that the recipient of the JWE trusts the asserting party.

• Transfer data securely between interested parties over an unsecured channel.

6.9 Key/Value Pair Plugin

6.9.1 Introduction

Every day, application teams come to rely on numerous secrets in their development and operational (DevOps) processes. Secrets ranging from passwords, tokens, certificates, SSH keys, and database credentials simply cannot be hard-coded or statically configured.

Fortanix DSM is the most secure KMS in the market. With this Plugin, DevOps can now easily manage their build and deployment secrets to maintain confidentiality throughout their CI/CD pipelines as well as during application runtime.

6.9.2 Use Cases

• Set and retrieve keys and corresponding values.

  • keys and values are comma-separated parameters inside JSON.

• Namespace support prevents secret path collisions.

  • Names of Fortanix DSM Secrets are unique within a Fortanix DSM Account.

  • Plugin prefixes KV secrets paths with a namespace to allow path reuse.

  • Allows multiple secrets with the same path inside a Fortanix DSM Account.

• Versioning support for keys such that:

  • Key update/delete automatically creates a new version.

  • Key update/delete does not delete other keys.

  • Uses Fortanix DSM custom metadata to validate versions.

• Deletion truncates the latest version (LIFO) or purges all versions.

6.10 Automated BYOK for Salesforce Cloud Plugin

6.10.1 Introduction

This plugin implements the Bring your own key (BYOK) model for Salesforce. Using this plugin, you can keep your key inside Fortanix DSM and use Shield Platform Encryption features of Salesforce.

6.10.2 Use Cases

The plugin can be used to:

• Upload a key from Fortanix DSM to Salesforce.

• Search tenant secrets (Salesforce encryption keys) using Salesforce Sobject Query Language (SSQL).

• Check the current status of any key or key version.

• Destroy the archived keys in Salesforce.

• Restore a previously destroyed key.

6.11 Cache-only BYOK for Salesforce Cloud Plugin

6.11.1 Introduction

Salesforce's Shield Platform Encryption is introducing a new pilot feature called Cache-Only Keys. This capability enhances the existing Bring Your Own Key (BYOK) capability by allowing customers to host their key material in a wrapped format which Salesforce will fetch as required. While this will be cached in an encrypted form, Salesforce will not retain or persist the key material in any system of record or backups.

6.11.2 Use Cases

• Generate encryption keys.

• Use Fortanix DSM key in Salesforce as Cache-only Key at runtime.

6.12 SSH CA Plugin

6.12.1 Introduction

SSH certificates are a method for authenticating users and/or servers in the SSH protocol. Instead of bare public keys (the usual method of SSH authentication), an authority issues a certificate which can then be used to authenticate to an SSH server.
SSH certificates were originally added to OpenSSH in version 5.6 (released in 2010).

6.12.2 Use Cases

• Authenticate clients to servers or servers to clients using a trusted third party hosted on Fortanix DSM.

6.13 X.509 CA plugin

6.13.1 Introduction

The X.509 CA plugin allows Fortanix DSM users to issue certificates for keys stored in Fortanix DSM. The plugin requires the CA key and certificate to be stored in Fortanix DSM as well.

6.13.2 Use Cases

• Generate certificates for keys stored in Fortanix DSM.

6.14 X.509 TBS CA Plugin

6.14.1 Introduction

X.509 certificates are a key element of many security architectures. It cryptographically ties a public key to the issuer of the certificate. Companies may wish to use their own input format.
This example plugin shows the flexibility of Fortanix's plugin framework. In this case, a basic JSON structure is accepted as input. After the input passes a user-specified verification function, any desired fields can be added and a valid X509 certificate is created. The signed certificate is returned in PEM format.

6.14.2 Use Cases

X.509 certificates are used in a wide variety of applications:

• Webservers use X.509 certificates as part of TLS to authenticate their identity.

• IPsec uses it to authenticate peers.

• Code signing systems such as Microsoft Authenticate enable verification of vendors of computer programs.

6.15 SAP Data Custodian BYOK Plugin

6.15.1 Introduction

The cloud services provide many advantages, but the major disadvantage of cloud providers has been security because physically your data resides with the cloud provider. To keep data secure in a cloud provider environment, enterprises use encryption. So, securing their encryption keys become significantly important. Bring Your Own Key (BYOK) allows enterprises to encrypt their data and retain control and management of their encryption keys. This plugin provides an implementation to use the SAP Data Custodian BYOK model.

6.15.2 Use Cases

The plugin can be used to:

• Import a Fortanix DSM key (AES or RSA) into SAP Data Custodian.

• Rotate a key in Fortanix DSM and import the new key version of an existing key into SAP Data Custodian.

• Import Fortanix DSM keys (AES and RSA) into Data Custodian groups or rotate them if they are already imported in both AWS and non-AWS keystore providers.

6.16 OCI Vault BYOK Plugin

6.16.1 Introduction

The cloud services provide many advantages but the major disadvantage of cloud providers has been security because physically your data resides with the cloud provider. To keep data secure in a cloud provider environment, enterprises use encryption. So securing their encryption keys become significantly important. Bring Your Own Key (BYOK) allows enterprises to encrypt their data and retain control and management of their encryption keys. This plugin provides an implementation to use the Oracle cloud BYOK model.

6.16.2 Use Cases

The plugin can be used to:

• List Vaults.

• List Keys in a Vault.

• Get information about a key or key version from a Vault.

• Enable or disable a key in a Vault.

• Schedule the deletion or cancel the scheduled deletion of a key or key version in a Vault.

• Import a Fortanix DSM Key into a Vault.

• Rotate the Fortanix DSM Key and import the new key version into the Vault.

6.17 Jenkins

6.17.1 Introduction

The Jenkins Plugin enables you to access and retrieve secrets (including keys) from the Fortanix Data Security Manager and utilize them within build environments.

6.17.2 Use Cases

• Encrypt sensitive environment variables and secrets.

• Store and manage build artifacts.

• Audit and compliance in CI/CD pipelines.

• Store and export secrets.

6.18 Cloud Trail

6.18.1 Introduction

The Cloud Trail plugin serves the purpose of synchronizing events originating from AWS Cloud Trail with the Fortanix DSM Audit log, particularly focusing on keys within DSM that have been integrated into AWS Cloud KMS through BYOK as part of Cloud-Data-Control. The combined events can then be uploaded to Amazon S3.

6.18.2 Use Cases

• Generate new secret with AWS IAM credentials.

• List DSM keys.

• List DSM events.

• List AWS keys and events.

• Retrieve all events from AWS CloudTrail and merge with the Fortanix DSM audit log.

• Upload a single file with output from Merge Events operation to Amazon S3.

6.19 ServiceNow

6.19.1 Introduction

The ServiceNow plugin facilitates the monitoring of key rotation schedules within Fortanix DSM and the generation of alerts using ServiceNow Incidents. It conducts scans across all keys within the Fortanix DSM Group(s) it belongs to. Depending on a specified time period input into the plugin, you can set at 90, 60, or 30 days before the current date, if a key's creation date exceeds this threshold, an Incident is generated in ServiceNow. Each key will generate a minimum of three Incidents in ServiceNow. No additional Incidents are created if the key's creation date surpasses the specified time period threshold. Furthermore, the plugin allows for querying ServiceNow to retrieve a list of Incidents relevant to this workflow.

6.19.2 Use Cases

• Generate a new secret using ServiceNow credentials and other parameters provided as input, storing it in a DSM security object with a randomly assigned name.

• List all relevant keys that are due for rotation either 90, 60, or 30 days prior to the configured or specified schedule.

• List ServiceNow incidents.

• Notify ServiceNow incidents.

6.20 PKCS#10 Certification Request

6.20.1 Introduction

The PKCS#10 Certification Request plugin can generate a PKCS #10 Certification Signing Request (CSR) for an asymmetric security object within Fortanix DSM. The security object must belong to a group accessible by this plugin. For additional information on PKCS#10, refer to RFC 2986.

6.20.2 Use Cases

• Generate CSRs for requesting digital certificates from a Certificate Authority (CA).

• Secure internal and external communications with properly signed certificates.

• Manage generated CSRs.

6.21 Snowflake Tokenization

6.21.1 Introduction

The data protection in Snowflake is achieved by employing a Fortanix DSM Plugin that operates within the Fortanix Data Security Manager.

6.21.2 Use Cases

The authorized Snowflake users are granted the authority to invoke an external function, possess the ability to perform the following two main operations:

• Encrypting or tokenizing individual fields or multiple columns.

• Decrypting or detokenizing individual fields or multiple columns.

6.22 Tendermint One Time Signer

6.22.1 Introduction

The Tendermint One Time Signer plugin serves as a one-time signer for blockchains based on Tendermint. This plugin maintains specific state information, which it leverages to make decisions regarding message signing during the consensus process. Its primary goal is to prevent double signing, which can harm the blockchain network.

The Tendermint One-Time Signer incorporates the logic outlined in preventing double-signing, refer to https://docs.tendermint.com/master/spec/consensus/signing.html.

6.22.2 Use Cases

This plugin offers the capability to sign various types of blockchain consensus messages, including:

• Prevote (Type 1)

• Precommit (Type 2)

• Proposal (Type 32)

6.23 TOTP Etherum Signer

6.23.1 Introduction

The Time-based One-Time Passwords (TOTP) Entherum Signer plugin serves as an Ethereum Signer, where each Ethereum Signer is associated with a MASTER_KEY. The multiple wallets can be linked to each Ethereum Signer, and within each wallet, multiple keys can be added.

Additionally, it offers the option to register a wallet for 2FA (Two-Factor Authentication) support using TOTP. To enable TOTP functionality, this plugin incorporates the algorithms outlined in RFC 6238 (TOTP), with the code adapted from https://github.com/remjey/luaotp/blob/v0.1-6/src/otp.lua.

The customers of B2C cryptocurrency wallet providers can leverage this secure 2FA service provided by the plugin. This added layer of security ensures that a customer's assets cannot be spent without their direct involvement in the transaction, enhancing overall security measures.

6.23.2 Use Cases

This plugin offers the following functionalities:

• Optionally enroll a user for 2FA with TOTP.

• Calculate a derived public key.

• Sign data or Ethereum transactions.

6.24 Time Based OTP Plugin

6.24.1 Introduction

The Time Based One Time Password (OTP) plugin is designed for validating time-based one-time passwords, utilizing the algorithms outlined in RFC 6238 (TOTP). The underlying code for this functionality has been adapted from https://github.com/remjey/luaotp/blob/v0.1-6/src/otp.lua.

6.24.2 Use Cases

• Generate a new TOTP secret with default parameters and stores the HMAC key in a DSM security object named totp/<account>, where <account> is the value provided in the input field “account."

• Verify if the input code is valid for the specified TOTP account.

6.25 Technical Report (TR)-31

6.25.1 Introduction

This plugin operates on TR-31 key blocks, also known as cryptograms. It can create cryptograms, such as wrapping a key already stored in Fortanix DSM with specified TR-31 properties. Additionally, this plugin can open cryptograms, such as unwrapping a cryptogram created externally and importing the underlying key into Fortanix DSM.

6.25.2 Use Cases

The TR-31 plugin is an alternative to key wrapping that allows storing and transmitting a key securely by creating cryptograms, which are payment and Payment Card Industry (PCI) standards compliant.

7.0 Resources

To read more about plugins, go to the Fortanix plugin library and read the README file or access the plugins directly from https://github.com/fortanix/sdkms-plugin-library and read the README of the individual plugins.

8.0 Troubleshooting