Skip to content

Migrate a whole keystore (PKCS#12, JKS)

Move the private keys and trusted certificates of a PKCS#12 or JKS keystore from a system you are leaving into your tenant, in one commit, after previewing what the keystore holds.

Who can do it

A tenant administrator, a tenant key manager, or a platform super administrator working inside the tenant. The console offers Import Key to a person who holds the permission to import a public key or the permission to import a keystore, and enables the Import from Keystore tab only with the permission to import a keystore. The preview requires the same permission as the import.

Before you start

  • The tenant has a key protection backend bound. Every private key is sealed under the tenant's key-encryption key before it is stored, so without a backend the import is refused.
  • A deployment licence is in effect, and the tenant's lifecycle state still permits key lifecycle operations.
  • The keystore is a PKCS#12 (.p12, .pfx) or JKS (.jks) file. Its format is detected from the file's bytes, not from its extension. Its size is limited by a deployment setting, 20 MB by default.
  • Every private key entry carries its certificate chain. A secret-key entry is never imported.
  • Keep your own copy of the keystore. A private key that enters the platform never comes back out: export returns public material only.
  • On a SaaS deployment, a platform operator working inside a support-access impersonation session cannot import.

Steps

  1. Open Import Key from your tenant's navigation.
  2. Select Import from Keystore.
  3. Under Step 1 — Configuration:
    1. Key ID Prefix: the base Key ID of the imported keys. It is required. It accepts letters, digits, ., _ and -, up to 255 characters, and may not be dots alone. A keystore holding one private key stores it under the prefix unchanged; with several, each key is stored as the prefix followed by its alias. A trusted certificate is stored as the prefix, then -trust-, then its alias.
    2. Keystore File: drag the keystore onto the drop area, or select it to browse.
    3. Keystore Password: the keystore's password. Leave it empty for a keystore without one.
  4. Select Analyze Keystore. The analysis is a read-only preview: it imports, stores and records nothing.
  5. Under Step 2 — Review purposes, check each alias and its algorithm, and set its purpose. A purpose is fixed for the life of the key.
    • A purpose derived from the certificate's key usage is preselected.
    • An alias marked Choice required has no derivable purpose: choose Encrypt / Decrypt or Sign / Verify.
    • Dual (two identities), offered only for an alias that holds a private key, mints two single-purpose keys from the one keypair, <kid>-enc and <kid>-sig.
    • Select Back to start again with another file, prefix or password.
  6. Select Import Keys. It is enabled only when the prefix is set and every alias has a purpose.

What you see when it worked

Import Results shows an overall result (FULL SUCCESS, PARTIAL SUCCESS, ALL SKIPPED, ALL FAILED or NO KEYS PROCESSED) and up to three lists:

  • Imported: each new Key ID with its type and algorithm.
  • Skipped: entries whose Key ID is already held by a live key, with the reason. The rest proceed.
  • Failed: entries that could not be imported, with the reason.

Each imported key and trusted certificate is recorded in the audit trail as its own key creation. Select View in Inventory to manage the keys, or Import Another to start again. Importing does not authorize anyone to use the keys: use is authorized separately.

If it fails

What you see Cause What to do
"A key ID prefix is required — every imported key is named with it." The prefix is empty Enter a prefix
The analysis or import is refused as invalid input Wrong password, a corrupt file, a format that is neither PKCS#12 nor JKS, a password over 4 KB, or a keystore cap exceeded Correct the input as the message says
"This keystore holds a secret-key entry. Only private keys and trusted certificates are imported, so nothing was imported. Remove the secret-key entry and try again." The keystore holds a secret-key entry Remove the entry and try again
"This keystore holds a private key without its certificate chain, so nothing was imported. Export the key together with its certificate and try again." A private key entry has no certificate chain Export the key with its certificate and try again
The preview says the keystore's key derivations run more iterations than one import may run The keystore is over the import's derivation budget, so Import Keys stays disabled Split it into smaller keystores and import each one
"No importable aliases were found in this keystore." The keystore holds nothing that can be imported Check that you chose the right file
The import is refused naming an alias and the algorithm policy An entry's algorithm is not admitted by the tenant's algorithm policy, which refuses the whole import Ask an administrator to review the algorithm policy, or remove the entry
The import is refused because no key protection backend is configured The tenant has no backend bound A tenant administrator configures the key protection backend, then you retry
The keystore is refused as too large It exceeds the deployment's keystore size limit Split the keystore, or ask a platform administrator to raise the limit
The import is refused for the licence No deployment licence is in effect A platform administrator installs a valid licence
The service is temporarily unavailable The platform is at its limit of concurrent keystore loads; nothing was read or imported Retry after a few seconds

Without the console

Surface How
Key management CLI ankasecure-km keys analyze-keystore to preview, then ankasecure-km keys import-keystore, each with --keystore-file <path> --metadata-file <json> and --password-stdin or --password-prompt. The password is never an option value
Admin SDK KeyOperations.analyzeKeystore(Path, String, SecretChars) and KeyOperations.importKeystore(Path, String, SecretChars)
API POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore/analyze (operation analyzeKeystore) and POST /api/v3/admin/tenants/{tenantId}/keys/import-keystore (operation importKeystore), both multipart/form-data with the parts metadata, keystore and an optional password
  • Import Key: what a keystore import commits you to and what the platform refuses.
  • Key Inventory: where the imported keys are managed.