BW6.X - BWCE - Security - How to Encrypt and Decrypt Secrets in BusinessWorks and BusinessWorks Container Edition

In digital environments, security is a high priority and this is very common to use secrets, tokens or keys to connect to APIs or Saas solutions available in the Cloud.

This means that in an integration solution like BusinessWorks there is need to be able to encrypt the secrets (and not just obfuscate them), persist such encrypted secrets (‘encrypt at rest’) and decrypt them when needed.

This functionality is available as part of the Confidentiality Plugin and this article goal is to explain how to use the Plugin capabilities to encrypt and decrypt secrets (note that use of the Confidentiality Plugin requires a license).

Logical view

To encrypt and decrypt secrets in a secure way you need to use a private key, issued by a Certification Authority, and its corresponding public certificates.

The private key and the public certificates needs to be managed in separate KeyStores.

In the BusinessWorks projects two different ‘ConfidentialityConfiguration’ resources should be created, one pointing to the key store containing the private key and the other pointing to Key Store containing the Public Certificates.

The ‘encrypt’ XPATH function of the Plugin must use the resource pointing to the Key Store containing the Public Certificates, the ‘decrypt’ XPATH function must use the resource pointing to the Key Store containing the Private Key.

Pre-requisites

To use encryption and decryption in BusinessWorks applications you need the following elements:

· A keystore file in jceks or pkcs12 format and containing a private key

· The alias of the private key

· The password of the private key

Additional elements

You can refer to the attached project. Note that the confidentiality plugin needs to be installed for the project to be valid.

· The password of the private key Keystore file

You also need :

· A keystore file in jceks or pkcs12 format and containing the public certificates related to the private key

· The alias of the public certificate used to encrypt the secret

· The password of the public certificates Keystore file

Example of a Keystore containing a private key as seen in KeyStore Explorer, the private key alias is ‘myservice’ :

Example of a Keystore containing public certificates as seen in KeyStore Explorer, the alias used for encryption is ‘my test service (software view certificate authority)’ :

Confidentiality Configuration Resource referring the KeyStore containing the Private Key

The following parameters have to be set (using properties when possible):
. Security provider (In Linux and Windows environment it can be SunJCE or Bouncy Castle BWFIPS)
. The ‘Keystore Provider as TrustStore’ option should be unchecked
. Path to the Private Key Keystore
. Keystore type (JCEKS or PKCS12)
. The Private Key Keystore password
. The private key alias name
. The private key password
. The Encryption Type (when using RSA key only RSA/ECB/PKCS1Padding is available)

Example configuration:

Confidentiality Configuration Resource referring the KeyStore containing the Public Certificates

The following parameters have to be set (using properties when possible):
. Security provider (In Linux and Windows environment it can be SunJCE or Bouncy Castle BWFIPS)
. The ‘Keystore Provider as TrustStore’ option *should* be checked
. Path to the Public Certificates Keystore
. Keystore type (JCEKS or PKCS12)
. The Public Certificates Keystore password
. The Public Certificate alias name
. The Encryption Type (when using RSA key only RSA/ECB/PKCS1Padding is available)

Example configuration:

Encrypting a secret

The xpath function encrypt() can be used with the following syntax :

encrypt(<< secret in plaintext >>, << connectionSharedResource >>, << applicationName >>, << applicationVersion >>)

Example :

confidentiality:encrypt(“MySecret”,”demoencryptdecrypt.ConfidentialityPublicCertificates”,bw:getModuleProperty(“BW.APPLICATION.NAME”),bw:getModuleProperty(“BW.APPLICATION.VERSION”))

Note that the application name and application version fields have to be set to the actual application name and version (of the application doing the encryption), this can be easily managed using the getModuleProperty() function of BusinessWorks as shown above.

Decrypting a secret

The xpath function decrypt() can be used with the following syntax :

decrypt(<< encryptedText >>, << connectionSharedResource >>, << applicationName >>, << applicationVersion >>)

Example :

confidentiality:decrypt($Encrypt/EncryptedSecret,”demoencryptdecrypt.ConfidentialityPrivateKey”,bw:getModuleProperty(“BW.APPLICATION.NAME”),bw:getModuleProperty(“BW.APPLICATION.VERSION”))

Note that the application name and application version fields have to be set to the actual application name and version (of the application doing the decryption), this can be easily managed using the getModuleProperty() function of BusinessWorks as shown above.

Note that the applications names and versions do not need to match between the encrypting application and the decrypting application (for example application App2 in version 1.2 can decrypt a secret encrypted by application App1 in version 2.3).

Useful elements

The KeyStore Explorer tool can be downloaded at the following URL : https://keystore-explorer.org/

ConfidentialityPluginDemo.zip