Secure Java KeyStores in Azure based WSO2 Product Deployments
By: Chiranga Alwis
Tags: Wso2, Azure Key Vault, Java, Cryptography, Azure

Before proceeding with this tutorial, we recommend you to first dig into WSO2 product official documentation which contains in-depth details of asymmetric key encryption involvement including,

Usage scenarios

Default key stores and certificate trust store

How to customize the default key stores and trust store

Recommended best practices for a production grade deployment

Why do we need to involve a more secure option like Azure Key Vault?

Photo by Victoriano Izquierdo on Unsplash

Most importantly, a secure, centralized location to store the resource files outside of the deployment environment (which could be a VM based environment or a container based environment like Kubernetes).

You may consider storing these resources in a private GitHub repository.

Anyone who has access to the stored repository will be able to clone the resources, hence making them available in one’s local machine.

From there onward, anything is possible!!!

It also suggests that we are maintaining deployment resources, especially resources as important as security resources, outside of one’s Azure account.

If you have evaluated the section on recommended best practices on maintaining resources for asymmetric encryption, you may have encountered the recommendations to maintain a key store per the specific purpose.

Thus, higher the effort you need to invest compared to maintaining a single key store, for all purposes.

Maintenance of resource versions

Azure Key Vault maintains the history of versions of each resource stored.

This feature will come in handy when you are required to rollback to an older version of the key stores, you had stored (e.g. for debugging purposes).

Photo by Davide Cantelli on Unsplash

What Azure Key Vault features are we going to use?

Azure Key Vault primarily supports storage of three types of objects, namely, Keys, Secrets and Certificates.

Out of these,

We will use Certificate resource storage service to store the required key stores.

When exporting the stored, key store object from the Key Vault, we are required to export it as a Secret resource since, we are required to obtain both private and public keys to load the original key store, to be used alongside the product.

Photo by Kristina Flour on Unsplash

Complications you may face

Storing the key stores used for a WSO2 product deployment at the Azure Key Vault is not a mere walk in the park.

Photo by Sebastian Herrmann on Unsplash

Incompatible key store formats

WSO2 products support key stores of the Java KeyStore (JKS) format, only.

But, the Azure Key Vault Certificate service does not support importing key stores of JKS format. Instead, it only supports uploading certificate resources and key stores in the form of PEM and PFX (i.e. PKCS12) files.

With PEM format, it was noticed that the public-private key pairs reside outside of the protection of a key store/repository. Furthermore, the back and forth conversions between JKS and PFX formats are pretty easy.

Thus, we recommend using the PKCS12 format.

When a key store resource file (in PKCS12 format) is imported to the Certificate service, the original key store and key pair passwords get stripped off.

Thus, once exported from the Azure Key Vault, the key store and key pair passwords were observed to be empty strings.

Hence, we need to reset the original key store and key pair passwords, prior to usage alongside the product.

Basic steps for generating a key store and storing it at Key Vault

Let us go through the steps involved in this procedure.

Generate a key store of PKCS12 format

keytool -genkey -alias <KEY_PAIR_ALIAS> \

-validity 10950 -keyalg RSA -keysize 4096 \

-keypass <KEY_PAIR_PASSWORD> \

-dname "CN=<IDENTITY_SERVICE_HOSTNAME>,OU=Dev,O=WSO2 Inc,L=SL,S=WS,C=LK" \

-storetype PKCS12 \

-keystore keyStore.pfx \

-storepass <KEY_STORE_PASSWORD>

The following is a sample key store generated based on the above keytool command.

Generate a key store of PKCS12 format

The above command generates a new key store of PKCS12 format (with .pfx file extension and defined using the storetype argument) which will contain a public-private key entry with the alias wso2carbon (protected by a password defined using the keypass argument). The key store itself, is protected by a password defined using the argument storepass .

You may refer to the official Oracle documentation on the Java keytool for more advanced options available with the command.

Plus, the official WSO2 documentation provides instructions for numerous use cases associated with constructing key stores.

Import the generated key store to Key Vault as a Certificate resource

You may follow the official Azure documentation for this purpose.

Note:

At the time of publishing this article, the above documentation fails to define the minimum permissions required for the attempted task.

In a Key Vault instance using Azure RBAC, for granting permissions for the data plane of the Key Vault to the user, we can use Key Vault Certificates Officer predefined role.

In a Key Vault instance using Access Policies, to grant permissions, you need permissions for Certificate Management actions Get , List and Import .

Key Store file generated in the previous step being uploaded to the Key Vault

Uploaded key store file as an imported Certificate entry

The initial, uploaded version corresponding to the current version of the Certificate entry

You can upload a new version of the key store, under the same Certificate entry as per your preference. The most recent upload will be marked as the current version while, you will also be able to see the history of versions you have maintained.

After uploading a new version of the same key store

Basic steps for using the uploaded key store in a WSO2 product deployment

Let us go through the steps for downloading the key store resource and preparing it for usage in a WSO2 product deployment.

Export the stored key store from Key Vault Certificates, in the form of its mapping Secret

You may follow the official Azure documentation for this purpose.

Note:

In a Key Vault instance using Azure RBAC, for granting permissions for the data plane of the Key Vault to the user, we can use Key Vault Secrets User predefined role.

In a Key Vault instance using Access Policies, to grant permissions, you need permissions only for Secret Management Get action.

The following screenshot shows the download action of the previously uploaded key store instance.

Downloaded key store resource file

Convert the downloaded key store file from PKCS12 format to JKS format

You can use the Java keytool for this purpose as follows:

keytool -importkeystore -srckeystore keyStore.pfx \

-srcstoretype PKCS12 \

-srcstorepass "" \

-srcalias <KEY_PAIR_ALIAS> \

-srckeypass "" \

-destkeystore keyStore.jks \

-deststoretype JKS \

-deststorepass <KEY_PAIR_PASSWORD> \

-destalias <KEY_PAIR_ALIAS> \

-destkeypass <KEY_STORE_PASSWORD>

As you may have noticed, the key store and key pair passwords of the source PKCS12 key store are empty strings. This is due to the drawback which was highlighted in the previous section Complications you may face.

Converted key store in JKS format

You may refer to the official Oracle documentation on the Java keytool for more advanced options available with the command.

Now, you can use the prepped key store resource in a WSO2 product deployment, based on your requirements. For example in a Kubernetes based product deployment, you may create a Kubernetes Secret packaging the above key store resource file.

A few suggestions…

Photo by Patrick Tomasso on Unsplash

We recommend you to use native Azure features such as, DevOps Pipelines for managing production grade, WSO2 product deployments in Azure.

Using Pipelines, you can perform the same steps as in the aforementioned Basic steps for using the uploaded key store in a WSO2 product deployment section, without having to download the resource into your local machine.

section, without having to download the resource into your local machine. You may choose to store the key store and key pair credentials at the Azure Key Vault in the form of Secret resources.

You may choose to use Azure DevOps Pipeline predefined task for Azure Key Vault for secure resource retrieval, to use the key store credentials in order to load and prep the key stores.

You may prepare the product public key trust store in the Pipeline, by loading the public keys of the key pairs (contained in the key stores stored at the Azure Key Vault).

Detailed steps for these suggestions are beyond the scope of this article.

Winding up…

WSO2 products use Java KeyStores for securely storing asymmetric key pairs used by the products.

In Microsoft Azure based WSO2 product deployments, we recommend you to use the Azure Key Vault service to securely store, the used key stores and associated sensitive data such as, key store and key pair credentials.

This article is a concise guide for storing the key stores in Azure Key Vault.

Plus, it could be used as a generic guide for storing Java KeyStore resources in Azure Key Vault, as Certificate resources.

Photo by Cristina Gottardi on Unsplash

👋 Join FAUN today and receive similar stories each week in your inbox! ️ Get your weekly dose of the must-read tech stories, news, and tutorials.

Follow us on Twitter 🐦 and Facebook 👥 and Instagram 📷 and join our Facebook and Linkedin Groups 💬