Spring Boot server.ssl.key-alias, Spring Boot SSL bundle key aliases, Tomcat certificateKeyAlias / keyAlias, and custom KeyManager code all reference a string alias inside your keystore. When that alias no longer matches your naming convention, or when you need to rotate passwords and retire old certificates, keytool provides four maintenance commands: -changealias, -storepasswd, -keypasswd, and -delete.
This guide runs each command on PKCS12 and JKS files on Ubuntu. You will see a successful alias rename (localhost → web-local), store password rotation, the PKCS12 limitation on -keypasswd, and permanent entry deletion.
Tested on: Ubuntu 26.04 LTS; OpenJDK 25.0.3; kernel 7.0.0-27-generic.
Prerequisites
keytoolinstalled — see Install keytool on Ubuntu.- A PKCS12 keystore with at least one
PrivateKeyEntry. Create a lab file or reuse one from list and inspect keystore entries.
Generate a PKCS12 lab keystore with two aliases so rename, password, and delete steps each have entries to work on:
keytool -genkeypair -alias localhost -keyalg RSA -keysize 2048 -validity 365 \
-storetype PKCS12 -keystore demo.p12 -storepass changeit \
-dname "CN=localhost, O=Demo, C=US" -noprompt
keytool -genkeypair -alias api-server -keyalg RSA -keysize 2048 -validity 365 \
-storetype PKCS12 -keystore demo.p12 -storepass changeit \
-dname "CN=api.example.com, O=Demo, C=US" -nopromptCopy the file before any destructive change so you can roll back a bad rename or delete:
cp demo.p12 demo.p12.bakKeep demo.p12.bak until you finish the lab and confirm the remaining aliases match your config.
Change alias with -changealias
Framework configs often expect a fixed alias (tomcat, 1, server). Rename instead of re-importing when the certificate and key are fine but the label is wrong.
Point -changealias at the old name and set -destalias to the label your server config will use:
keytool -changealias -alias localhost -destalias web-local \
-keystore demo.p12 -storetype PKCS12 -storepass changeit -nopromptList the keystore to confirm localhost became web-local and that api-server is unchanged:
keytool -list -keystore demo.p12 -storetype PKCS12 -storepass changeitThe renamed entry keeps the same certificate fingerprint — only the alias string changed:
Keystore type: PKCS12
Keystore provider: SUN
Your keystore contains 2 entries
api-server, Jul 2, 2026, PrivateKeyEntry,
Certificate fingerprint (SHA-256): 4C:EC:98:50:17:00:4A:9E:07:13:AE:2F:A8:22:0B:9F:80:83:13:5E:44:50:65:18:AE:EA:8D:B9:B4:B0:2E:38
web-local, Jul 2, 2026, PrivateKeyEntry,
Certificate fingerprint (SHA-256): AF:5A:E6:AE:08:11:C9:1A:85:A4:33:2D:C2:1F:49:5F:60:2D:C3:7C:32:88:A1:E9:F2:DE:B0:55:9F:4A:BA:EDThe SHA-256 fingerprint for web-local matches the old localhost entry — only the alias string changed. Update server.ssl.key-alias=web-local (or your equivalent) before restarting the service.
For Spring Boot 3.1+ SSL bundles, update the bundle key alias to match:
spring.ssl.bundle.jks.webserver.key.alias=web-localKeystore location and password for that bundle live under spring.ssl.bundle.jks.webserver.keystore.* — see Spring Boot HTTPS with keytool.
-destalias must not already exist. If the target alias is taken, delete or rename the conflicting entry first.
Change store password with -storepasswd
-storepasswd rotates the password that unlocks the entire keystore file. It works on both PKCS12 and JKS.
Pass the current password with -storepass and the new value with -new:
keytool -storepasswd -keystore demo.p12 -storetype PKCS12 -storepass changeit -new newstorepass -nopromptProve the new password unlocks the file:
keytool -list -keystore demo.p12 -storetype PKCS12 -storepass newstorepassA successful listing means the rotation stuck; aliases and fingerprints are unchanged:
Keystore type: PKCS12
Keystore provider: SUN
Your keystore contains 2 entries
api-server, Jul 2, 2026, PrivateKeyEntry,
Certificate fingerprint (SHA-256): 4C:EC:98:50:17:00:4A:9E:07:13:AE:2F:A8:22:0B:9F:80:83:13:5E:44:50:65:18:AE:EA:8D:B9:B4:B0:2E:38
web-local, Jul 2, 2026, PrivateKeyEntry,
Certificate fingerprint (SHA-256): AF:5A:E6:AE:08:11:C9:1A:85:A4:33:2D:C2:1F:49:5F:60:2D:C3:7C:32:88:A1:E9:F2:DE:B0:55:9F:4A:BA:EDThe listing still shows web-local from the earlier rename — only the store password changed. Confirm the old password no longer works:
keytool -list -keystore demo.p12 -storetype PKCS12 -storepass changeitkeytool error: java.io.IOException: keystore password was incorrectEvery deployment that reads this file must switch to newstorepass at the same time — partial updates cause the same error at startup.
Change key password with -keypasswd (JKS only)
Legacy JKS keystores can store a per-entry key password separate from the store password. PKCS12 cannot — the whole file shares one secret.
First, confirm PKCS12 rejects per-key password changes:
keytool -keypasswd -alias web-local -keystore demo.p12 -storetype PKCS12 -storepass newstorepass \
-keypass newstorepass -new keypass2 -nopromptPKCS12 store type triggers an immediate error — this is expected on modern keystores:
keytool error: java.lang.UnsupportedOperationException: -keypasswd commands not supported if -storetype is PKCS12On JKS the per-key password command succeeds. Create a separate JKS lab file — keep it apart from the PKCS12 demo.p12 used above:
keytool -genkeypair -alias localhost -keyalg RSA -keysize 2048 -validity 365 \
-storetype JKS -keystore demo.jks -storepass changeit -keypass changeit \
-dname "CN=localhost, O=Demo, C=US" -nopromptFor new projects, standardize on PKCS12 and treat the store password as the only secret. Migrate old JKS files into a new PKCS12 destination so you do not overwrite an existing keystore:
keytool -importkeystore \
-srckeystore demo.jks \
-destkeystore demo-from-jks.p12 \
-deststoretype PKCS12 \
-srcstorepass changeit \
-deststorepass changeit \
-nopromptAfter import, demo-from-jks.p12 holds the same PrivateKeyEntry under a single store password.
Rotate the per-key password on the original JKS file:
keytool -keypasswd -alias localhost -keystore demo.jks -storepass changeit \
-keypass changeit -new newkeypass -nopromptJKS operations print the proprietary-format warning; the key password still updates:
Warning:
The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format using "keytool -importkeystore -srckeystore demo.jks -destkeystore demo.jks -deststoretype pkcs12".If you change the JKS key password before migration, pass -srckeypass to -importkeystore or migrate while the key password still matches the store password.
Delete an entry with -delete
Remove retired certificates or aliases you no longer reference in application config. Deletion is permanent unless you kept a backup copy.
Delete api-server, then list what remains:
keytool -delete -alias api-server \
-keystore demo.p12 -storetype PKCS12 -storepass newstorepass -noprompt
keytool -list -keystore demo.p12 -storetype PKCS12 -storepass newstorepassOnly web-local should remain — the deleted alias is gone from the file:
Keystore type: PKCS12
Keystore provider: SUN
Your keystore contains 1 entry
web-local, Jul 2, 2026, PrivateKeyEntry,
Certificate fingerprint (SHA-256): AF:5A:E6:AE:08:11:C9:1A:85:A4:33:2D:C2:1F:49:5F:60:2D:C3:7C:32:88:A1:E9:F2:DE:B0:55:9F:4A:BA:EDDeletion is immediate and irreversible without a backup. Services still pointing at api-server will fail TLS startup until you update the alias or import a replacement entry.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Alias <name> does not exist |
Wrong -alias after a rename |
Run keytool -list and use the current alias |
UnsupportedOperationException on -keypasswd |
PKCS12 store type | Use -storepasswd only, or migrate to JKS for legacy key-password semantics |
destination alias already exists |
-destalias collision |
Pick a unique name or delete the conflicting entry |
| Service fails after password change | Config still has old password | Update javax.net.ssl.keyStorePassword, Spring server.ssl.key-store-password, and secrets together |
Cannot recover key |
Key password differs from store password, or config uses the wrong key password | For JKS, update javax.net.ssl.keyStorePassword and framework-specific key password settings; for PKCS12, use the store password |
| App still uses old certificate after rename | Framework still points to old alias or first alias in keystore | Update Spring Boot server.ssl.key-alias, SSL bundle key alias, or Tomcat certificateKeyAlias |
| Alias works on one system but not another | Alias case or store type behavior differs | Run keytool -list -v on the exact file used by the service |
| JKS proprietary format warning | Store type is JKS | Migrate to PKCS12 with -importkeystore |
References
- keytool — Java SE 21 documentation
- On-site: keytool cheat sheet, List and inspect keystore entries, Keystore vs truststore
Summary
Rename aliases with keytool -changealias, rotate the file password with -storepasswd, and remove entries with -delete — all three work on PKCS12. Per-key -keypasswd is JKS-only; PKCS12 rejects it with UnsupportedOperationException. Back up the keystore before deletes and password changes, and keep framework alias properties in sync after a rename.
