User's Guide: Plugin Library

1.0 Introduction

Plugin Library (PL) is a feature of the Fortanix-Data-Security-Manager (DSM) that allows users to view a list of frequently used plugins from a commonplace. Fortanix DSM users can create local copies of the plugins in the library that they intend to use and then they can start invoking them.

The Fortanix DSM PL is stored in a Git repository that contains the plugin code. Fortanix DSM users will be able to access updated and new plugins when the repository is updated by Fortanix.

2.0 Creating a Plugin

You can add a new plugin by uploading a file with a plugin code or type the code inline. The Fortanix DSM PL can be accessed by going to the Plugins  page in the Fortanix DSM GUI, and then clicking the New Plugin tab on this page.  

The following are the steps to create a new plugin: 

1. In the New Plugin page, click Create/Import a new plugin.

   

   

2. Fill in the Plugin Name field and using the ‘Assigning the new plugin to groups’ box, assign the new plugin to a group and click Next. You can also create a new group by clicking  CREATE NEW GROUP button and assign the plugin to the new group.

   

3. Provide the source code for your plugin. Use the editor to type in your source to the template on the EDIT INLINE tab. You can also upload the source code as a file and then edit it using the UPLOAD A FILE tab and click Create.  

   

3.0 Accessing Fortanix Data Security Manager Plugin Library

The Fortanix DSM PL can be accessed by going to the Plugins page in the Fortanix DSM GUI, and then clicking the Plugin Library tab on this page. This page contains a list of all the available plugins with a short description of their functionality.

When a user clicks on a plugin tile in the Plugin Library, the associated plugin page will be displayed with detailed information about the plugin, common use cases, setup, and format of the plugin inputs and outputs.

4.0 Installing a Plugin from the Plugin Library

To install a plugin from the PL, a user needs to click the Get Plugin button as shown in Figure 2 to go to the plugin creation page. From this page the user needs to follow the creation of plugin workflow as described below:

1. Click the GET PLUGIN

2. Review the plugin name and assign it to a group, and then click Save.  

   

4.1 Review Plugin Source Code Before Installation

Plugin source code may be reviewed before installing by clicking the link provided on the “Plugin page”. This link redirects to the official Fortanix Inc. Plugin Library repository hosted by GitHub

(https://github.com/fortanix/sdkms-plugin-registry).

4.2 Review / Modify Plugin Source Code After Installation

Once a plugin is installed, the management of the plugin is identical to plugins created by writing the source code in the Create/Import New Plugin page. Thus, after plugin creation, the user is able to modify the original code to meet specific requirements. As an example, the following image displays the source code of the “HD Wallet” that was installed from the PL.

5.0 Upgrading Plugins to New Versions

Plugin Library plugins are versioned. When a new version of the plugin becomes available an option to upgrade to the latest version will become available both in the Plugin Library list page and in the plugin main view page. For example, the following figure shows a plugin that is in version 1.0 and can be upgraded to version 2.0 by clicking the link UPGRADE TO V 2.0 on the mid-right of the screen.

When upgrading a plugin, a list of release notes for the new version is displayed along with the option to keep a backup copy of the currently installed version of the plugin, as shown in the following figure.

6.0 Legacy Plugins

Plugins that are created before Fortanix DSM version 3.16 are called Legacy plugins. For backward compatibility, these legacy plugins will be marked with a special icon that denotes that they are legacy plugins.

Fortanix has applied new security restrictions which will be applicable for plugins created in Fortanix DSM version 3.16 and above.

The following screenshots show a table view of legacy plugins.

7.0 List of Plugins in the Plugin Library

7.1 AWS BYOK Plugin

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

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

7.2 Azure BYOK HSM Plugin

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

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

7.3 Azure BYOK Plugin

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

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

7.4 DUKPT Plugin

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

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

7.5 Google Cloud BYOK Plugin

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

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

7.6 HD Wallet Plugin

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

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

7.7 JWS+JWE Decrypt Plugin

7.7.1 Introduction

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

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

7.8 JWS+JWE Encrypt Plugin

7.8.1 Introduction

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

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

7.9 Key/Value Pair Plugin

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

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

7.10 Automated BYOK for Salesforce Cloud Plugin

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

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

7.11 Cache-only BYOK for Salesforce Cloud Plugin

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

7.11.2 Use Cases

• Generate encryption keys.

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

7.12 SSH CA Plugin

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

7.12.2 Use Cases

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

7.13 X.509 CA plugin

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

7.13.2 Use Cases

• Generate certificates for keys stored in Fortanix DSM.

7.14 X.509 TBS CA Plugin

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

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

7.15 SAP Data Custodian BYOK Plugin

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

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

7.16 OCI Vault BYOK Plugin

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

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

7.17 Jenkins

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

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

7.18 Cloud Trail

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

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

7.19 ServiceNow

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

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

7.20 PKCS#10 Certification Request

7.20.1 Introduction

The PKCS#10 Certification Request plugin can generate a PKCS #10 Certification Request 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.

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

7.21 Snowflake Tokenization

7.21.1 Introduction

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

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

7.22 Tendermint One Time Signer

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

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

7.23 TOTP Etherum Signer

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

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

7.24 Time Based OTP Plugin

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

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

7.25 Technical Report (TR)-31

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

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

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

9.0 Troubleshooting