Chilkat.JavaKeyStore Class Overview

Chilkat.JavaKeyStore represents a Java keystore containing private-key entries, trusted certificate entries, and secret-key entries. It can load keystores from files, bytes, encoded strings, or BinData; add material from certificates, PFX/PKCS#12, symmetric keys, and trusted certs; retrieve private keys, certificate chains, trusted certs, and aliases; change key passwords; remove entries; and convert to PEM, PFX, JWK Set, binary data, encoded strings, or files.

What the Class Is Used For

Use Chilkat.JavaKeyStore when an application needs to read, create, modify, or convert Java keystore data. The class supports the common keystore entry types: private keys with aliases and certificate chains, trusted certificates with aliases, and secret keys such as AES keys. It also bridges Java keystores with Chilkat Pfx, Pem, Cert, CertChain, PrivateKey, BinData, StringBuilder, and JsonObject workflows.

Load and Save Keystores Load from files, memory, encoded text, or BinData; write to files, bytes, BinData, or encoded strings.
Manage Private Keys Add private-key entries, import private keys from PFX, retrieve private keys by index or alias, get certificate chains, and change key passwords.
Manage Trusted Certs Add trusted certificates, retrieve trusted certificates by index or alias, rename aliases, and remove entries.
Convert Formats Convert Java keystore contents to PEM, PFX, or JWK Set format, and load keys from a JWK Set.

Typical Workflow

  1. Create a JavaKeyStore object.
  2. Decide whether loading must validate the keystore keyed digest by setting VerifyKeyedDigest.
  3. Load an existing keystore using LoadFile, LoadBinary, LoadEncoded, or LoadBd; or build one by adding entries.
  4. Add entries with AddPrivateKey, AddPfx, AddTrustedCert, or AddSecretKey.
  5. Use UseCertVault when additional certificates may be needed to build private-key certificate chains.
  6. Inspect counts with NumPrivateKeys, NumTrustedCerts, and NumSecretKeys.
  7. Retrieve aliases, private keys, certificate chains, trusted certificates, or secret keys as needed.
  8. Export the keystore with ToFile, ToBinary, ToBd, or ToEncodedString, or convert it with ToPemObj, ToPfxObj, or ToJwkSet.
  9. Check LastErrorText after failures or unexpected behavior.

Core Concepts

Concept Meaning Important Members
Private-Key Entry A private key stored with an alias and an associated certificate chain. AddPrivateKey, PrivateKeyAt, PrivateKeyOf, CertChainAt
Trusted Certificate Entry A trusted certificate stored with an alias. AddTrustedCert, TrustedCertAt, TrustedCertOf
Secret-Key Entry A symmetric key, such as an AES key, stored with an alias. AddSecretKey, GetSecretKey, GetSecretKeyAlias
Alias A name used to identify a private key, trusted certificate, or secret key entry in the keystore. GetPrivateKeyAlias, GetTrustedCertAlias, SetAlias
Complete Certificate Chain A certificate chain that reaches a trusted CA root or a self-signed root certificate. RequireCompleteChain, UseCertVault, AddPrivateKey, AddPfx
Keystore Integrity Password The password used to validate or write the keyed digest of the entire keystore file. Private keys may also have their own passwords. VerifyKeyedDigest, LoadFile, ToFile, ChangePassword

Core Properties

Property Purpose Guidance
NumPrivateKeys Number of private keys contained in the keystore. Each private key has an alias and an associated certificate chain.
NumTrustedCerts Number of trusted certificates contained in the keystore. Each trusted certificate has an alias.
NumSecretKeys Number of secret keys contained in the keystore. Secret keys are symmetric keys, such as AES keys, and may have aliases.
RequireCompleteChain Controls whether private-key entries require a certificate chain completed to a root certificate. Default is true. If true, adding a private key fails when the chain cannot be completed. If false, incomplete chains are allowed.
VerifyKeyedDigest Controls whether the keystore keyed digest must validate during load. Default is true. If false, a keystore may be loaded without password validation when a null or empty password is supplied to a load method.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected results. Diagnostic information may be available regardless of success or failure.

Loading Java Keystores

Input Source Method Behavior
File LoadFile Loads a Java keystore from a file using the supplied password.
Byte array LoadBinary Loads a Java keystore from in-memory byte data.
Encoded string LoadEncoded Loads a Java keystore from encoded text, such as Base64 or hex.
BinData LoadBd Loads a Java keystore from the contents of a BinData object.
JWK Set LoadJwkSet Loads the Java keystore from a JSON Web Key Set held in a JsonObject.
Password validation: If VerifyKeyedDigest is true, the keystore keyed digest must pass validation when loading. If false, a keystore can be loaded without password validation when the load method receives a null or empty password.

Adding Entries

Entry Type Method Important Details
Private key from certificate AddPrivateKey Adds a private-key entry. The private key and certificate chain are obtained from the supplied Cert object.
Private keys from PFX / PKCS#12 AddPfx Adds one JKS entry per private key found in the PFX. Certificates in the PFX are used to build certificate chains. This method does not add trusted certificate entries.
Secret key AddSecretKey Adds a symmetric key entry from encoded key bytes. The algorithm describes the key’s intended use, such as AES.
Trusted certificate AddTrustedCert Adds a trusted certificate entry with an alias.
Certificate-chain helper source UseCertVault Adds an XmlCertVault to the internal list of certificate sources used to help build chains to a root certificate.
Chain-building rule: If RequireCompleteChain is true, adding a private-key entry fails unless the certificate chain can be completed to a trusted CA root or self-signed root. Use UseCertVault and available trusted roots when additional certificates may be needed.

Alias Behavior

Operation Alias Behavior Fallback Preference
AddPrivateKey Uses the supplied alias when non-empty. If empty, an alias is chosen from the certificate. Subject common name, then subject email address, then serial number.
AddPfx Applies the supplied alias to the first private key. Other private keys get automatically assigned aliases. Subject common name, subject email address, PKCS#9 friendly name, then serial number.
AddTrustedCert Adds a trusted certificate using the supplied alias. No fallback behavior is described for this method.
SetAlias Changes the alias for a trusted certificate or private-key entry. entryType identifies the entry category: 1 = trusted certificate, 2 = private key.
ToJwkSet Exports private keys as a JWK Set. The JWK kid value is set from the key alias in the store.

Retrieving Private Keys and Certificate Chains

Need Method Behavior
Get private-key alias by index GetPrivateKeyAlias Returns the alias for the Nth private key. The first private key is index 0.
Get private key by index PrivateKeyAt Returns the private key at the specified index into a supplied PrivateKey object. Requires the key password.
Get private key by alias PrivateKeyOf Returns the private key associated with an alias, with optional case-sensitive alias matching.
Get certificate chain by index CertChainAt Returns the certificate chain for the Nth private key.
Get certificate chain by alias CertChainOf Returns the certificate chain for the private key identified by alias.
Change private-key password ChangePassword Changes the password for a private key at the specified index.

Retrieving Trusted Certificates

Need Method Behavior
Get trusted certificate alias GetTrustedCertAlias Returns the alias for the Nth trusted certificate. The first certificate is index 0.
Get trusted certificate by index TrustedCertAt Returns the Nth trusted certificate into a supplied Cert object.
Get trusted certificate by alias TrustedCertOf Finds and returns the trusted certificate with the specified alias, with optional case-sensitive alias matching.

Secret-Key Entries

Task Method Important Details
Add secret key AddSecretKey Adds a symmetric key from encoded key bytes. The encoding describes how the bytes are encoded, such as Base64, hex, or Base64Url. The algorithm describes the key usage, such as AES.
Get secret key alias GetSecretKeyAlias Returns the alias for the Nth secret key. The first secret key is index 0.
Get secret key bytes GetSecretKey Returns the Nth secret key bytes in the requested encoding, such as hex, Base64, or Base64Url.
Secret-key note: The algorithm describes the intended use of the key bytes. For example, if the encoded bytes contain a 128-bit AES key, use AES. The documentation notes that secret-key bytes are sealed within the keystore using PBEWithMD5AndTripleDES as part of the JCEKS behavior.

Removing Entries and Renaming Aliases

Task Method Entry Type Values
Remove entry RemoveEntry 1 = trusted certificate entry, 2 = private-key entry.
Set alias SetAlias 1 = trusted certificate entry, 2 = private-key entry.
Indexing rule: Entry indexes begin at 0. Use the appropriate count property before removing or renaming entries.

Writing Java Keystores

Output Target Method Behavior
BinData ToBd Writes the keystore to a supplied BinData object.
Byte array ToBinary Writes the keystore to in-memory bytes.
Encoded string ToEncodedString Writes the keystore to an encoded string, such as Base64 or hex.
File ToFile Writes the keystore to a file.
Keystore password: The password supplied to write methods is used for the keyed hash of the entire keystore file. Private-key entries may have separate passwords assigned when the private key is added.

Format Conversion

Conversion Method Result
Java KeyStore to PEM ToPemObj Returns the Java keystore as a Pem object.
Java KeyStore to PFX ToPfxObj Returns the Java keystore as a Pfx object.
Java KeyStore to JWK Set ToJwkSet Exports private keys in JSON JWK Set format into a StringBuilder. The JWK kid is set from the key alias.
JWK Set to Java KeyStore LoadJwkSet Loads a Java keystore from a JSON Web Key Set held in a JsonObject.
PFX / PKCS#12 to Java KeyStore AddPfx Adds private-key entries from a PFX. One entry is added per private key.

Method Summary by Category

Category Methods Purpose
Load keystore LoadFile, LoadBinary, LoadEncoded, LoadBd, LoadJwkSet Load keystore data from files, memory, encoded strings, BinData, or JWK Set JSON.
Add entries AddPrivateKey, AddPfx, AddTrustedCert, AddSecretKey, UseCertVault Add private keys, PFX private-key entries, trusted certificates, secret keys, and chain-building certificate sources.
Retrieve private-key data GetPrivateKeyAlias, PrivateKeyAt, PrivateKeyOf, CertChainAt, CertChainOf Retrieve private-key aliases, private keys, and their certificate chains.
Retrieve trusted certificates GetTrustedCertAlias, TrustedCertAt, TrustedCertOf Retrieve trusted certificate aliases and certificates.
Retrieve secret keys GetSecretKeyAlias, GetSecretKey Retrieve secret-key aliases and encoded key bytes.
Modify entries ChangePassword, RemoveEntry, SetAlias Change private-key passwords, remove entries, or rename aliases.
Write keystore ToFile, ToBinary, ToEncodedString, ToBd Export keystore data to files, memory, encoded strings, or BinData.
Convert formats ToPemObj, ToPfxObj, ToJwkSet Convert Java keystore contents to PEM, PFX, or JWK Set format.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Load failed LoadFile, LoadBinary, VerifyKeyedDigest, LastErrorText Check the keystore password, keyed digest validation setting, file path, input bytes, or encoded data.
Private key cannot be added RequireCompleteChain, UseCertVault, AddPrivateKey Confirm the certificate has a private key and that the certificate chain can be completed to a root when required.
PFX import does not add trusted cert entries AddPfx This method adds one private-key entry per private key found in the PFX. It does not add trusted certificate entries to the JKS.
Alias lookup fails PrivateKeyOf, TrustedCertOf, CertChainOf Confirm the alias spelling and choose the correct case-sensitive or case-insensitive matching option.
Secret key cannot be retrieved GetSecretKey Confirm the password, key index, and requested output encoding.
Written keystore fails later validation ToFile, ToBinary, ToBd Confirm the keystore password used for writing and any separate private-key passwords used when entries were added.

Common Pitfalls

Pitfall Better Approach
Assuming the keystore password and private-key passwords are always the same. Treat the keystore password as the password for the keyed hash of the entire file, and treat private-key passwords separately.
Adding a private key without a complete certificate chain when complete chains are required. Keep RequireCompleteChain in mind and use UseCertVault to provide additional chain certificates when needed.
Expecting AddPfx to create trusted certificate entries. Use AddTrustedCert when trusted certificate entries are needed.
Trying to remove or rename an entry without using the correct entry type. Use 1 for trusted certificates and 2 for private keys with RemoveEntry and SetAlias.
Loading without password validation unintentionally. Leave VerifyKeyedDigest set to its default of true unless intentionally loading without keyed-digest validation.
Misinterpreting the secret-key algorithm argument. The algorithm describes the intended use of the key bytes, such as AES; it is not the same as the internal sealing algorithm used by the keystore.

Best Practices

Recommendation Reason
Check entry counts after loading. NumPrivateKeys, NumTrustedCerts, and NumSecretKeys confirm what the keystore contains.
Use aliases consistently. Aliases are the primary way to retrieve private keys, trusted certificates, certificate chains, and JWK kid values.
Use UseCertVault when building private-key entries. It gives Chilkat additional certificate sources for completing certificate chains to a root.
Keep RequireCompleteChain enabled for stricter keystores. The default helps ensure private-key entries have complete chains.
Use AddTrustedCert explicitly for trust entries. Importing PFX data adds private-key entries but does not add trusted certificate entries.
Use format-conversion methods for interoperability. ToPemObj, ToPfxObj, and ToJwkSet make the same key material usable in PEM, PKCS#12, and JSON-based workflows.
Check LastErrorText after failures. It provides the most useful diagnostic detail for loading, adding, exporting, chain-building, alias lookup, password, and conversion problems.

Summary

Chilkat.JavaKeyStore is the Chilkat class for working with Java keystore data. It supports private-key entries with aliases and certificate chains, trusted certificate entries, and secret-key entries. It can load and save keystores, import private-key entries from PFX, add trusted certs and symmetric keys, retrieve private keys and certificate chains, manage aliases, change private-key passwords, and convert keystore contents to PEM, PFX, or JWK Set format.

The most important practical guidance is to distinguish the keystore password from private-key passwords, keep certificate-chain requirements in mind when adding private keys, use aliases consistently, and explicitly add trusted certificate entries when trust anchors are needed.