Create New Keystores

This page explains how to create keystores using keytool commands. After creating keystores, you will need to configure them in the deployment.toml file — see Configure Keystores for the next steps.

There are two ways to create keystores for WSO2 Identity Server:

1. Generate a keystore with a new self-signed certificate
2. Generate a keystore using an existing CA-signed certificate

Note

If you are creating a new keystore for data encryption, make sure to acquire a public key certificate that contains the Data Encipherment key usage as explained here.

Create a keystore using a new certificate

Note

The pubic key certificate we generate for the keystore is self-signed. For a CA-signed certificate, either import it into the keystore or create a new keystore with a CA-signed certificate.

1. Navigate to the <IS_HOME>/repository/resources/security/ directory in a command prompt. All keystores should be stored here.

2. To create the keystore that includes the private key, execute the following command. Make sure to use the same password for both the keystore and private key.

   JKSPKCS12

   keytool -genkeypair -alias newcert -keyalg RSA -keysize 2048 -keystore newkeystore.jks -dname "CN=<testdomain.org>, OU=Home,O=Home,L=SL,S=WS,C=LK" -storepass mypassword -keypass mypassword 
   

   This command will create a keystore with the following details.

   • Keystore name: newkeystore.jks
   • Alias of public certificate: newcert
   • Keystore password: mypassword
   • Private key password: mypassword

   keytool -genkeypair -alias newcert -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore newkeystore.p12 -dname "CN=<testdomain.org>, OU=Home,O=Home,L=SL,S=WS,C=LK" -storepass mypassword -keypass mypassword 
   

   This command will create a keystore with the following details.

   • Keystore name: newkeystore.p12
   • Alias of public certificate: newcert
   • Keystore password: mypassword
   • Private key password: mypassword

   Tip

   • If you did not specify values for the -keypass and the -storepass, , you will be prompted to enter the keystore password (-storepass). It’s advisable to use a password generator to create a strong password. When prompted for -keypass, press Enter to use the same password for both the keystore and the key.
   • If you did not specify values for -dname, you will be asked to provide those details individually.

Create the internal keystore

The internal keystore is used for encrypting sensitive internal data such as admin passwords and other sensitive information in configuration files via the Cipher Tool.

It is recommended to use a symmetric AES key due to its resilience against post-quantum threats and better performance. However, if your Cipher Tool configuration requires asymmetric encryption, you can create the internal keystore with an RSA key pair instead.

Navigate to <IS_HOME>/repository/resources/security/ and run one of the following commands:

PKCS12JKS

Symmetric (AES) - RecommendedAsymmetric (RSA)

keytool -genseckey \
  -alias <internal-key-alias> \
  -keyalg AES \
  -keysize 256 \
  -keystore <internal-keystore-name>.p12 \
  -storetype PKCS12 \
  -storepass <internal-keystore-password> \
  -keypass <internal-keystore-password>

This command will create a keystore with the following details:

• Keystore name: <internal-keystore-name>.p12
• Alias of the secret key: <internal-key-alias>
• Keystore password: <internal-keystore-password>

keytool -genkeypair \
  -alias <internal-key-alias> \
  -keyalg RSA \
  -keysize 2048 \
  -keystore <internal-keystore-name>.p12 \
  -storetype PKCS12 \
  -storepass <internal-keystore-password> \
  -keypass <internal-keystore-password>

This command will create a keystore with the following details:

• Keystore name: <internal-keystore-name>.p12
• Alias of the key pair: <internal-key-alias>
• Keystore password: <internal-keystore-password>

Note

The public key certificate must have the Data Encipherment key usage to allow encryption of raw data. If using an asymmetric key for internal encryption, ensure your certificate includes this usage.

JKS keystores do not support symmetric (AES) keys. You can only use an RSA key pair.

keytool -genkeypair \
  -alias <internal-key-alias> \
  -keyalg RSA \
  -keysize 2048 \
  -keystore <internal-keystore-name>.jks \
  -storepass <internal-keystore-password> \
  -keypass <internal-keystore-password>

This command will create a keystore with the following details:

• Keystore name: <internal-keystore-name>.jks
• Alias of the key pair: <internal-key-alias>
• Keystore password: <internal-keystore-password>

Note

The public key certificate must have the Data Encipherment key usage to allow encryption of raw data. Ensure your certificate includes this usage.

Warning

Adding an internal keystore to an existing deployment will make already encrypted data unusable. This should be done during initial setup only.

Import a certificate into the truststore

After creating a new keystore (for example, a TLS keystore), export its certificate and import it into the truststore so that WSO2 Identity Server trusts it.

1. Export the certificate from the keystore:

   PKCS12JKS

   keytool -exportcert \
     -alias <key-alias> \
     -keystore <keystore-name>.p12 \
     -storetype PKCS12 \
     -storepass <keystore-password> \
     -file <certificate-name>.crt
   

   keytool -exportcert \
     -alias <key-alias> \
     -keystore <keystore-name>.jks \
     -storepass <keystore-password> \
     -file <certificate-name>.crt
   

2. Import the exported certificate into the truststore:

   PKCS12JKS

   keytool -importcert \
     -alias <key-alias> \
     -file <certificate-name>.crt \
     -keystore client-truststore.p12 \
     -storetype PKCS12 \
     -storepass <truststore-password> \
     -noprompt
   

   keytool -importcert \
     -alias <key-alias> \
     -file <certificate-name>.crt \
     -keystore client-truststore.jks \
     -storepass <truststore-password> \
     -noprompt
   

Create a keystore using an existing certificate

As SSL/TLS is widely used in many systems, certificates may already exist that can be reused. In such situations, you can use an already existing CA-signed certificate to generate your keystore for SSL by using OpenSSL and Java.

To export certificates of a trust chain into a PKCS12 keystore , execute the following command. Make sure to use the same password for both the keystore and private key.

openssl pkcs12 -export -in <certificate file>.crt -inkey <private>.key -name "<alias>" -certfile <additional certificate file> -out <pfx keystore name>.p12

Info

To convert the PKCS12 formatted keystore to a Java keystore, execute the following command.

keytool -importkeystore -srckeystore <pkcs12 file name>.pfx -srcstoretype PKCS12 -destkeystore <JKS name>.jks -deststoretype JKS