Change keystore password with Java keytool

What is Java keytool?

The Java keytool is a command-line utility used to manage keystores in different formats containing keys and certificates. You can use the java keytool to change a keystore password, key password, or both. In many respects, it’s a competing utility with openssl for keystore, key, and certificate management.

When should you change the keystore password or key password in the keystore?

You should change the keystore password or key password as a regular practice, just like key rotation. The keys being protected by the keystore should also be rotated, separate of the keystore password. If you have encountered a compromise of your keystore password, you MUST immediately rotate all keys being protected by the keystore. Only changing the keystore password is not enough in this case.

You should strongly consider changing a private key password to match the keystore password as many utilities will not work if they are different.

What keytool command do I use to change keystore password?

This command changes the keystore password on a pkcs12 (p12) keystore. An common alternate file extension for a pkcs12 (p12) keystore is .pfx.

keytool -storepasswd \
 -new changed \
 -keystore example.p12 \
 -storepass changeit \
 -storetype PKCS12 \
 -v

Java keytool options:

-new – The new password. We recommend leaving this option off and letting keytool prompt you instead of writing your password in plain text here.

-keystore – The keystore file.

-storepass – The current keystore password. We recommend leaving this option off and letting keytool prompt you instead of writing your password in plain text here.

-storetype – Recommended keystore types include PKCS12 and JKS. In this case, the keystore was of type PKCS12.

-v – Verbose

What keytool command do I use to change key password in a JKS keystore?

Most of our examples work with PKCS12 store types. For this specific exercise, we are working with a JKS store type to demonstrate how to use the -keypasswd command as JKS is the only supported store type for this command.

keytool -keypasswd \
 -alias example.com \
 -keypass changeit \
 -new changed \
 -keystore example.jks \
 -storepass changed \
 -storetype JKS \
 -v

Java keytool options:

-alias – The alias of the key whose password is being changed

-keypass – The current key password. We recommend leaving this option off and letting keytool prompt you instead of writing your password in plain text here.

-new – The new key password. We recommend leaving this option off and letting keytool prompt you instead of writing your password in plain text here.

-keystore – The keystore file.

-storepass – The keystore password. We recommend leaving this option off and letting keytool prompt you instead of writing your password in plain text here.

-storetype – Recommended keystore types include PKCS12 and JKS. In this case, the keystore was of type JKS.

-v – Verbose

What keytool command do I use to change key password in a PKCS12 keystore?

Unfortunately, the -keypasswd command is not supported for PKCS12 passwords. If you try, you will receive the following error: “keytool error: java.lang.UnsupportedOperationException: -keypasswd commands not supported if -storetype is PKCS12”

Instead, you must import the PKCS12 keystore into a new keystore giving it a new password.

keytool -importkeystore \
 -srckeystore example.p12 \
 -srcstoretype PKCS12 \
 -srcstorepass changed \
 -destkeystore newexample.p12 \
 -deststoretype PKCS12 \
 -deststorepass changedagain \
 -destkeypass changedagain

Note that the deststorepass and destkeypass are the same value. If they are different the keystore will be considered corrupt by most applications using it.

On another note, both a keystore and key in the keystore should always have a password. Many applications cannot handle either a key or keystore with an empty password.

Java keytool options:

-srckeystore – The current keystore file.

-srcstoretype – The current keystore type. Recommended keystore types include PKCS12 and JKS. In this case, the keystore was of type PKCS12.

-srcstorepass – The current keystore password. We recommend leaving this option off and letting keytool prompt you instead of writing your password in plain text here.

-destkeystore – The new keystore file.

-deststoretype – The new keystore type. Recommended keystore types include PKCS12 and JKS. In this case, the keystore was of type PKCS12.

-deststorepass – The new keystore password. We recommend leaving this option off and letting keytool prompt you instead of writing your password in plain text here.

-destkeypass – The keystore password. This must be included and set to equal the -deststorepass, else the key password will not be updated and will cause a corrupt keystore.

Change keystore password with bash script

Remember that each private key must have the same password as the encapsulating keystore for applications to be able to make use of the private key entries. You can use bash or any other scripting language with keystore support to loop through each private key entry in the keystore and change the entry password, and finally change the keystore password. Note that this only works with a JKS keystore, because PKCS12 keystores do not support the -keypasswd flag.

#!/bin/bash
if [ $# -lt 3 ]; then
  echo "Usage : <keystore> <current_password> <new_password>"
  exit 1
else
aliasList="$(keytool -list -v -keystore $1 -storepass $2 | grep "Alias name" | cut -d':' -f2)"
# Change each private key entry password
for a in $aliasList; do
  keytool -keypasswd  -alias $a -keypass $2 -storepass $2 -new $3 -keystore $1
done
# Finally, change the encapsulating keystore password
keytool -storepasswd -keystore $1 -storepass $2 -new $3
fi

Conclusion

Let us know in the comments if you would like to see more examples of how to change a keystore and private key password in different keystore types.

Read all of our blog content.