JavaKeyStore Chilkat2 Perl Reference Documentation
Chilkat2::JavaKeyStore
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.JavaKeyStore
Read Java keystore data into memory, inspect or modify its contents, and
save the updated keystore when changes are complete.
Work with private keys stored under aliases, including their associated
certificate chains and entry-specific passwords.
Add, retrieve, and manage trusted certificate entries used for trust
stores, TLS validation, and Java-based security configuration.
Store and retrieve symmetric secret keys when the keystore is used for
application key material in addition to certificates.
Import private-key entries from PFX/P12 and export or convert keystore
contents to PEM, PFX, or JWK Set format.
Enumerate aliases, locate entries, rename or manage entry names, and
organize keys and certificates by application-specific identifiers.
For an extended overview, see
JavaKeyStore Class Overview.
Load, inspect, modify, convert, and save Java keystore data.
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 certificates
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.
Load and save keystores
Private-key entries
Trusted certificates
Secret-key entries
Import and convert
Alias management
JavaKeyStore when the data is
organized as a Java keystore; use Cert, PrivateKey,
Pfx, or TrustedRoots when working directly with
individual certificate or key objects.
Object Creation
use Chilkat2;
my $javaKeyStore = Chilkat2::JavaKeyStore->new;
# or set properties (and RaiseError) at creation:
# my $javaKeyStore = Chilkat2::JavaKeyStore->new(VerboseLogging => 1, RaiseError => 1);Creates the object. The optional pairs set writable properties (and RaiseError) in order, as if set one by one; an unknown or read-only name croaks. use Chilkat2; loads every class; the Chilkat2/JavaKeyStore.pm file holds only this class's documentation (perldoc Chilkat2::JavaKeyStore).
Perl frees the object when its last reference goes (undef $javaKeyStore, or the variable going out of scope); there is nothing to close. Objects returned by methods are independent and freed the same way. The class may be subclassed (use parent -norequire, 'Chilkat2::JavaKeyStore';): an object is a blessed hash reference whose hash is free for the subclass's own fields.
When false (the default), a method that fails returns false (or undef), and the reason is in LastErrorText. When true, it dies with a Chilkat2::Error instead, as DBI does with its RaiseError. Objects returned by a method inherit the value of the object that returned them.
Errors
A Chilkat2::Error stringifies to the failed call's full LastErrorText, and has the methods text, class ('Chilkat2::JavaKeyStore'), method (the method name) and object. Methods that look something up and find nothing return undef without dying (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain boolean, and property reads and writes never fail for Chilkat reasons.
Misuse always croaks, with your file and line, whatever RaiseError is: a wrong number of arguments, a reference or undef where a string or number is expected, an object of the wrong class, an out-of-range integer, a string containing a NUL character, a wide character in a byte string, or a write to a read-only property.
Strings are Perl character strings in both directions (length, regexes and :encoding layers see characters); binary data (BinData) is a byte string. Unlocking: call Chilkat2::Global->new->UnlockBundle('...') once at startup.
Properties
DebugLogFilePath
my $strVal = $javaKeyStore->DebugLogFilePath;
$javaKeyStore->DebugLogFilePath($strVal);
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
LastErrorHtml
my $strVal = $javaKeyStore->LastErrorHtml;
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
my $strVal = $javaKeyStore->LastErrorText;
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
my $strVal = $javaKeyStore->LastErrorXml;
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
my $boolVal = $javaKeyStore->LastMethodSuccess;
$javaKeyStore->LastMethodSuccess($boolVal);
Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
NumPrivateKeys
my $intVal = $javaKeyStore->NumPrivateKeys;
Returns the number of private-key entries currently contained in the keystore. Each private-key entry has an alias, a protected private key, and an associated certificate chain. Valid private-key indexes range from 0 through NumPrivateKeys - 1.
PrivateKeyAt and PrivateKeyOf. It is distinct from the store password used when loading or saving the complete keystore.NumSecretKeys
my $intVal = $javaKeyStore->NumSecretKeys;
Returns the number of symmetric secret-key entries currently contained in the keystore. Examples include AES, HMAC, Blowfish, and ChaCha key material. Valid indexes range from 0 through NumSecretKeys - 1.
NumTrustedCerts
my $intVal = $javaKeyStore->NumTrustedCerts;
Returns the number of trusted-certificate entries currently contained in the keystore. Each entry contains one certificate and an alias. Valid indexes range from 0 through NumTrustedCerts - 1.
RequireCompleteChain
my $boolVal = $javaKeyStore->RequireCompleteChain;
$javaKeyStore->RequireCompleteChain($boolVal);
Controls whether a complete certificate chain is required when a private-key entry is added. The default is 1AddPrivateKey and AddPfx fail if Chilkat cannot build the chain through the issuing certificates to a root or self-signed certificate. When set to 0
UseCertVault to make additional certificates available for chain construction. Trusted CA roots supplied through Chilkat trusted-root facilities may also help complete the chain. This property affects chain construction while adding entries; it does not perform application trust-policy validation.VerboseLogging
my $boolVal = $javaKeyStore->VerboseLogging;
$javaKeyStore->VerboseLogging($boolVal);
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
VerifyKeyedDigest
my $boolVal = $javaKeyStore->VerifyKeyedDigest;
$javaKeyStore->VerifyKeyedDigest($boolVal);
Controls validation of the keystore-level integrity digest when a JKS or JCEKS store is loaded. The default is 1
When set to 0
Version
my $strVal = $javaKeyStore->Version;
Methods
AddPfx
# $aliasName is a string
# $password is a string
# $success is true or false
my $success = $javaKeyStore->AddPfx($pfx, $aliasName, $password);
Imports the private-key entries found in the Pfx object supplied in $pfx. One Java keystore private-key entry is added for each private key in the PFX/PKCS #12 data. Certificates from the PFX are used to construct the certificate chain associated with each imported private key.
$aliasName specifies the alias for the first imported private key. If it is empty, Chilkat chooses an alias in this order:
- The subject common name of the private key certificate.
- The subject email address.
- The PKCS #12 friendly-name attribute.
- The certificate serial number.
If the PFX contains additional private keys, their aliases are chosen automatically using the same preference order. $password becomes the entry password used to protect the imported private keys in the Java keystore.
AddTrustedCert separately when a certificate should become an explicit trust entry.RequireCompleteChain is enabled, the method fails when any imported private-key chain cannot be completed. UseCertVault can supply additional issuer certificates.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddPrivateKey
# $aliasName is a string
# $password is a string
# $success is true or false
my $success = $javaKeyStore->AddPrivateKey($cert, $aliasName, $password);
Adds a private-key entry using the certificate in $cert. The Cert object must have access to its associated private key. Chilkat obtains that private key and builds the certificate chain beginning with $cert.
$aliasName is the entry alias. If it is empty, Chilkat chooses an alias from the certificate in this order: subject common name, subject email address, then certificate serial number. $password is the password used to protect the private key inside the keystore.
RequireCompleteChain is enabled, the method fails unless the chain can be completed. Use UseCertVault when additional issuer certificates are needed.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddSecretKey
# $encoding is a string
# $algorithm is a string
# $aliasName is a string
# $password is a string
# $success is true or false
my $success = $javaKeyStore->AddSecretKey($encodedKeyBytes, $encoding, $algorithm, $aliasName, $password);
Adds a symmetric secret-key entry. $encodedKeyBytes contains the key bytes encoded as text, and $encoding names that encoding, such as hex, base64, or base64url. $algorithm records the key algorithm, such as AES, HMAC_SHA256, or CHACHA. $aliasName is the alias, and $password is the password used to protect the key entry.
The algorithm value describes the intended key type; it does not transform the supplied key bytes. For example, a 128-bit AES key is supplied as exactly 16 decoded bytes and $algorithm is set to AES.
PBEWithMD5AndTripleDES mechanism defined by that format. Use this format when interoperability requires JCEKS, and protect both the entry password and the resulting file.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AddTrustedCert
# $aliasName is a string
# $success is true or false
my $success = $javaKeyStore->AddTrustedCert($cert, $aliasName);
Adds $cert as a trusted-certificate entry under the alias supplied in $aliasName. A trusted-certificate entry contains the certificate only; it does not contain a private key or a certificate chain.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
CertChainAt
# $certChain is a Chilkat2::CertChain
# $success is true or false
my $success = $javaKeyStore->CertChainAt($index, $certChain);
Loads $certChain with the certificate chain belonging to the private-key entry at zero-based index $index. Valid indexes range from 0 through NumPrivateKeys - 1. The first certificate contains the public key corresponding to the private key; subsequent certificates are issuing certificates toward the root.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
CertChainOf
# $caseSensitive is a boolean
# $certChain is a Chilkat2::CertChain
# $success is true or false
my $success = $javaKeyStore->CertChainOf($aliasName, $caseSensitive, $certChain);
Searches the private-key entries for an alias equal to $aliasName and loads the matching certificate chain into $certChain. $caseSensitive controls whether the alias comparison is case-sensitive. The first certificate in the chain contains the public key corresponding to the private key.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ChangePassword
# $oldPassword is a string
# $newPassword is a string
# $success is true or false
my $success = $javaKeyStore->ChangePassword($index, $oldPassword, $newPassword);
Changes the password protecting the private-key entry at $index. Indexing begins at 0. $oldPassword is the current entry password and $newPassword is the new entry password.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetPrivateKeyAlias
# $str is a string or undef
my $str = $javaKeyStore->GetPrivateKeyAlias($index);
Returns the alias of the private-key entry at $index. Indexing begins at 0; valid indexes range from 0 through NumPrivateKeys - 1.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetSecretKey
# $index is an integer
# $encoding is a string
# $str is a string or undef
my $str = $javaKeyStore->GetSecretKey($password, $index, $encoding);
Recovers the secret-key entry at $index and returns its raw key bytes encoded using $encoding. $password is the password protecting that entry. Indexing begins at 0. Common output encodings include hex, base64, and base64url.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetSecretKeyAlias
# $str is a string or undef
my $str = $javaKeyStore->GetSecretKeyAlias($index);
Returns the alias of the secret-key entry at $index. Indexing begins at 0; valid indexes range from 0 through NumSecretKeys - 1.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetTrustedCertAlias
# $str is a string or undef
my $str = $javaKeyStore->GetTrustedCertAlias($index);
Returns the alias of the trusted-certificate entry at $index. Indexing begins at 0; valid indexes range from 0 through NumTrustedCerts - 1.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadBd
# $bd is a Chilkat2::BinData
# $success is true or false
my $success = $javaKeyStore->LoadBd($password, $bd);
Loads a JKS or JCEKS keystore from the bytes currently contained in $bd. $password is the store password used for integrity verification when VerifyKeyedDigest is enabled.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadEncoded
# $jksEncData is a string
# $encoding is a string
# $success is true or false
my $success = $javaKeyStore->LoadEncoded($password, $jksEncData, $encoding);
Decodes the serialized keystore text in $jksEncData using the binary encoding named by $encoding, then loads the resulting JKS or JCEKS bytes. Common encodings include base64, hex, and base64url. $password is the store password used for integrity verification.
$encoding describes how binary keystore bytes are represented as text. It does not name the keystore format and does not protect the data cryptographically.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadFile
# $path is a string
# $success is true or false
my $success = $javaKeyStore->LoadFile($password, $path);
Loads a JKS or JCEKS keystore from the file at $path. $password is the store password used to verify the keystore-level integrity digest when VerifyKeyedDigest is enabled.
Chilkat.Pfx when the input is a .p12 or .pfx container.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadJwkSet
# $jwkSet is a Chilkat2::JsonObject
# $success is true or false
my $success = $javaKeyStore->LoadJwkSet($password, $jwkSet);
Loads supported keys from the JWK Set in $jwkSet into this Java keystore object. $password is used to protect imported private-key and secret-key entries. A JWK kid value is used as the entry alias when present.
$jwkSet should contain a JSON object with a keys array. Private asymmetric JWKs contain private parameters such as d; symmetric JWKs use kty: "oct" and contain the key in k. Treat the input as sensitive whenever it contains private or symmetric key material.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
PrivateKeyAt
# $index is an integer
# $privKey is a Chilkat2::PrivateKey
# $success is true or false
my $success = $javaKeyStore->PrivateKeyAt($password, $index, $privKey);
Loads $privKey with the private key at zero-based index $index. $password is the password protecting that private-key entry. Valid indexes range from 0 through NumPrivateKeys - 1.
$password is not necessarily the password used to load the complete keystore. Java keystores can protect each private-key entry with a different password.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
PrivateKeyOf
# $aliasName is a string
# $caseSensitive is a boolean
# $privKey is a Chilkat2::PrivateKey
# $success is true or false
my $success = $javaKeyStore->PrivateKeyOf($password, $aliasName, $caseSensitive, $privKey);
Searches the private-key entries for an alias equal to $aliasName and loads the matching private key into $privKey. $password is the password protecting that key entry, and $caseSensitive controls whether the alias comparison is case-sensitive.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
RemoveEntry
# $index is an integer
# $success is true or false
my $success = $javaKeyStore->RemoveEntry($entryType, $index);
Removes an entry selected by type and zero-based index. $entryType uses the following documented values:
$entryType | Entry selected |
|---|---|
1 | Trusted-certificate entry; $index indexes the trusted-certificate list. |
2 | Private-key entry; $index indexes the private-key list. |
$index is an index within the selected entry category, not an index across all entries in the keystore.
ToFile, ToBd, or another To* method to persist the updated keystore.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetAlias
# $index is an integer
# $aliasName is a string
# $success is true or false
my $success = $javaKeyStore->SetAlias($entryType, $index, $aliasName);
Changes the alias of an entry selected by type and zero-based index. $entryType uses the following documented values:
$entryType | Entry selected |
|---|---|
1 | Trusted-certificate entry; $index indexes the trusted-certificate list. |
2 | Private-key entry; $index indexes the private-key list. |
$aliasName is the new alias. The index is relative to the selected category, not the complete set of keystore entries.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToBd
# $bd is a Chilkat2::BinData
# $success is true or false
my $success = $javaKeyStore->ToBd($password, $bd);
Serializes the current Java keystore and writes the complete JKS or JCEKS file image to $bd. $password is the store password used to create the keystore-level integrity digest.
$password does not automatically change those entry passwords.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToEncodedString
# $encoding is a string
# $str is a string or undef
my $str = $javaKeyStore->ToEncodedString($password, $encoding);
Serializes the current Java keystore and returns the resulting JKS or JCEKS bytes encoded as text using $encoding. Common choices include base64, hex, and base64url. $password is the store password used to create the keystore-level integrity digest.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToFile
# $path is a string
# $success is true or false
my $success = $javaKeyStore->ToFile($password, $path);
Serializes the current Java keystore and writes the complete JKS or JCEKS file image to $path. $password is the store password used to create the keystore-level integrity digest.
ChangePassword for private-key entries when needed.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToJwkSet
# $sbJwkSet is a Chilkat2::StringBuilder
# $success is true or false
my $success = $javaKeyStore->ToJwkSet($password, $sbJwkSet);
Exports supported private-key and secret-key entries as a JSON Web Key Set and writes the JSON to $sbJwkSet. $password is used to recover protected key entries. Each exported JWK receives a kid value derived from the keystore alias.
d or symmetric parameter k contains secret key material. Protect the resulting JSON as carefully as the original keystore and do not log or transmit it over an untrusted channel.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToPemObj
# $pemObj is a Chilkat2::Pem
# $success is true or false
my $success = $javaKeyStore->ToPemObj($password, $pemObj);
Converts the keystore material supported by the Pem class and loads the result into $pemObj. $password is used to decrypt private-key entries during the conversion.
Pem object receives the converted material in memory. Its own export methods and properties control whether later PEM text is encrypted and how it is formatted. Treat unencrypted private-key PEM as sensitive data.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToPfxObj
# $pfxObj is a Chilkat2::Pfx
# $success is true or false
my $success = $javaKeyStore->ToPfxObj($password, $pfxObj);
Converts the certificates and recoverable private-key entries in the Java keystore and loads the result into $pfxObj. $password is used to decrypt private-key entries during the conversion.
$password is an input password for recovering the Java keystore entries. It is not automatically the password that will protect a later serialized PFX; use the destination Pfx export method to choose the PFX password.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
TrustedCertAt
# $cert is a Chilkat2::Cert
# $success is true or false
my $success = $javaKeyStore->TrustedCertAt($index, $cert);
Loads $cert with the trusted certificate at the zero-based index $index. Valid indexes range from 0 through NumTrustedCerts - 1. The returned certificate is the single certificate stored in the trust entry and has no private key merely by virtue of being trusted.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
TrustedCertOf
# $caseSensitive is a boolean
# $cert is a Chilkat2::Cert
# $success is true or false
my $success = $javaKeyStore->TrustedCertOf($aliasName, $caseSensitive, $cert);
Searches the trusted-certificate entries for an alias equal to $aliasName and loads the matching certificate into $cert. $caseSensitive controls whether the alias comparison is case-sensitive.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UseCertVault
# $success is true or false
my $success = $javaKeyStore->UseCertVault($vault);
Adds $vault to the certificate sources Chilkat searches when it needs issuer certificates to build a private-key certificate chain. This is useful before calling AddPrivateKey or AddPfx when the supplied certificate material does not already contain the complete chain.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.