skip to content

What is the difference between key-store-password and key-password, and PKCS12 vs JKS keystores?

level: middleimportance: nice to knowfreq 22%

answer

  1. store-password opens the file, key-password opens the entry
  2. JKS = per-entry password possible
  3. PKCS12 = one password, standard, JDK default
  4. key-alias picks the entry in multi-entry stores
  5. diverging key-password on PKCS12 -> unable to recover key

basics

~10 s

key-store-password opens the keystore file; key-password unlocks the individual private-key entry inside it. PKCS12 is the modern cross-platform format (Java's default); JKS is the older Java-only format.

solid answer

~40 s

A keystore is a password-protected container of key entries. server.ssl.key-store-password unlocks the container itself. server.ssl.key-password unlocks the specific private-key entry (selected by server.ssl.key-alias). With JKS these two passwords can legitimately differ. With PKCS12 the format doesn't support a per-entry password distinct from the store password, so you typically set only key-store-password; setting a different key-password can cause failures. On format: JKS is Sun/Oracle's proprietary Java-only store; PKCS12 (.p12/.pfx) is an RFC-standard, cross-platform format that OpenSSL, browsers, and Java all understand, and it's the JDK default since Java 9. Prefer PKCS12 for new keystores. Spring Boot infers the type from the extension or you set server.ssl.key-store-type explicitly (PKCS12 or JKS).

code

yaml · 16 lines
yaml
# JKS with a distinct key-entry password (legacy)
server:
  ssl:
    key-store: "file:/etc/katajob/keystore.jks"
    key-store-type: JKS
    key-store-password: "${STORE_PW}"
    key-password: "${KEY_PW}"   # may differ from store password in JKS
    key-alias: katajob
---
# PKCS12 (recommended): single password, no separate key-password
server:
  ssl:
    key-store: "file:/etc/katajob/keystore.p12"
    key-store-type: PKCS12
    key-store-password: "${STORE_PW}"
    key-alias: katajob

go deeper

for a junior

Know store-password opens the file and one password usually suffices for PKCS12.

for a middle

Explain the two password scopes and PKCS12 vs JKS trade-offs.

for a senior

Diagnose 'unable to recover key' and 'does not identify a key entry' errors.

for a principal

Standardize on PKCS12 org-wide, own keystore rotation/conversion tooling.

## Two passwords, two scopes A *keystore* is an encrypted file holding one or more *entries* (each a private key plus its certificate chain, or a trusted certificate). There are two independent secrets: - **`server.ssl.key-store-password`** — decrypts/integrity-checks the **whole keystore file**. Without it Spring Boot cannot open the store at all. - **`server.ssl.key-password`** — decrypts the **specific private-key entry** identified by `server.ssl.key-alias`. Only needed when that entry is protected by its own password different from the store password. If `key-password` is omitted, Spring Boot falls back to the store password for the key entry — which is why single-password setups work with only `key-store-password` set. ## Why the distinction exists per format - **JKS (Java KeyStore)**: legacy, Java-only, supports a **separate password per key entry**, so `key-store-password` and `key-password` can differ meaningfully. - **PKCS12 (`.p12`/`.pfx`)**: an OpenSSL/RFC 7292 standard understood everywhere (Java, browsers, curl, nginx). PKCS12 does **not** model a distinct per-entry key password separate from the store password in the way JKS does; tooling generally uses one password. Setting a diverging `key-password` on a PKCS12 store often triggers errors like `password was incorrect` / `unable to recover key`. Best practice: set only `key-store-password` for PKCS12. ## Choosing a type - `server.ssl.key-store-type` = `PKCS12` (recommended, JDK default since Java 9) or `JKS` (legacy). - If unset, the type is inferred from the file extension (`.p12`/`.pfx` -> PKCS12, `.jks` -> JKS) or the JVM default. ## Converting JKS to PKCS12 ``` keytool -importkeystore \ -srckeystore keystore.jks -srcstoretype JKS \ -destkeystore keystore.p12 -deststoretype PKCS12 ``` ## Gotchas - **`Alias name does not identify a key entry`** — the alias points at a trusted-cert entry (no private key) or the wrong alias; check with `keytool -list -keystore ...`. - **`unable to recover key`** on PKCS12 — you set a `key-password` that differs from the store password; remove it. - **Truststore vs keystore confusion** — `server.ssl.trust-store*` is a separate store used to validate *peer* certificates (for mTLS or the app acting as client), not to present the server's own identity. - Multi-entry keystores **require** `key-alias`, otherwise the chosen entry is nondeterministic. ## When to use which Use PKCS12 for anything new — one password, universal tooling, standards-based. Only stick with JKS for legacy keystores you can't regenerate, and even then converting is trivial.

  • Your PKCS12 keystore fails at startup with 'unable to recover key'. What's the likely cause?
    You set server.ssl.key-password to a value different from the store password. PKCS12 doesn't support a distinct per-entry password the way JKS does; remove key-password so it falls back to key-store-password.
  • When must you set server.ssl.key-alias?
    When the keystore holds more than one key entry — the alias disambiguates which private key/cert to present. With a single-entry store it's optional.

saying these in an interview costs you the question

  • Saying PKCS12 supports a separate per-entry key password like JKS.
  • Confusing truststore (validates peers) with keystore (server identity).
  • Claiming JKS is preferred for new keystores.
  • Forgetting key-alias on a multi-entry keystore.

context

resolving links…