User's Guide: Plugin Library

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.

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.
   Figure 1: New Plugin Page Figure 2: Create 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.
   Figure 3: Adding New Plugin
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. Figure 4: Add Plugin Code

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.

Figure 5: Plugin Library

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.

Figure 6: Plugin Detailed View

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.
   Figure 7: Review Plugin Details

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

Figure 8: Review Plugin Code Before Installation

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.

Figure 9: Modify Plugin Code After Installation

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.

Figure 10: Upgrade Plugin

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.

Figure 11: Plugin Upgrade Screen

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.
Figure 12: Legacy Plugins

List of Plugins in the Plugin Library

AWS BYOK Plugin

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.

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.

Azure BYOK HSM Plugin

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.

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.

Azure BYOK Plugin

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.

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.

DUKPT Plugin

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.

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.

Google Cloud BYOK Plugin

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.

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.

HD Wallet Plugin

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.

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.

JWS+JWE Decrypt Plugin

Introduction

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

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.

JWS+JWE Encrypt Plugin

Introduction

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

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.

Key/Value Pair Plugin

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.

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.

Automated BYOK for Salesforce Cloud Plugin

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.

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.

Cache-only BYOK for Salesforce Cloud Plugin

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.

Use Cases

1. Generate encryption keys.
2. Use Fortanix DSM key in Salesforce as Cache-only Key at runtime.

SSH CA Plugin

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

Use Cases

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

X.509 CA plugin

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.

Use Cases

<TBD>

X.509 TBS CA Plugin

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.

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.

SAP Data Custodian BYOK Plugin

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.

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.

OCI Vault BYOK Plugin

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.

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.

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.