Package com.chilkatsoft.chilkat2

Class Pfx

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Pfx
All Implemented Interfaces:
AutoCloseable
public class Pfx extends ChilkatObject
<section class="pfx-summary">

Load, inspect, build, export, convert, and import PFX / PKCS#12 containers.

Chilkat.Pfx is the Chilkat class for working with PFX / PKCS#12 containers, which commonly hold certificates together with their associated private keys and certificate chains. It can load certificate/private-key bundles from files, memory, encoded data, BinData, or PEM; add certificates and private keys; inspect contained certificates and keys; manage safe-bag attributes; export to PFX, PEM, encoded strings, binary data, files, or Java KeyStore format; and import contents into Windows or macOS/iOS key stores.

Load PFX / PKCS#12 data

Load password-protected certificate and private-key bundles from files, memory, encoded strings, BinData, or PEM input.

Inspect certificates and keys

Enumerate contained certificates, private keys, and certificate chains to locate the identity or trust material needed by the application.

Build PFX containers

Add certificates and private keys to create a PKCS#12 bundle for TLS, S/MIME, signing, authentication, or platform import workflows.

Safe-bag attributes

Read and manage PKCS#12 safe-bag attributes such as friendly names or local key identifiers when interoperability requires them.

Export and convert

Export PFX content as binary data, encoded text, files, PEM, or Java KeyStore format depending on the target system.

Import to key stores

Import certificates and private keys into Windows certificate stores or macOS/iOS keychains when platform-backed access is required.

Common pattern: Use Pfx when certificate material includes private keys packaged in a PKCS#12 container. Load the PFX with its password, inspect or retrieve the needed certificate and private key, then export, convert, or import the contents into the format or platform store required by the application. Use Chilkat.Cert and PrivateKey when working directly with individual certificate or key objects.

For an extended overview, see Pfx Class Overview.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Pfx

      public Pfx()
      Creates a new Pfx object.

  • Method Details

    • getAlgorithmId

      public String getAlgorithmId()
      Gets or sets the password-based encryption scheme used for PKCS#8 shrouded private-key bags when writing a PFX. After a PFX is loaded, this property reports the scheme found for the loaded shrouded key bag.

      The default is pbeWithSHAAnd3_KeyTripleDES_CBC for backward compatibility. Set this property to pbes2 to use the cipher and PBKDF2 HMAC choices specified by getPbes2CryptAlg() and getPbes2HmacAlg().

      Scope: This property selects protection for private-key bags. It does not select the certificate's public-key algorithm, the private key's algorithm, or the signature algorithm used by a certificate. Compatibility versus modern encryption: The Triple-DES default supports older consumers. For new PFX output, prefer pbes2 with AES when every target platform supports it.

      Returns:
      the value of the AlgorithmId property

    • setAlgorithmId

      public void setAlgorithmId​(String value)
      Sets the AlgorithmId property; see getAlgorithmId().
      Parameters:
      value - the new value (not null)

    • getNumCerts

      public int getNumCerts()
      Returns the number of certificates currently contained in this PFX object. This count includes end-entity certificates and any available intermediate or root CA certificates.

      Certificate indexes range from 0 through NumCerts - 1 for use with certAt(int, Cert).

      Indexes are independent: Certificates and private keys are stored in separate collections. Certificate index i has no positional relationship to private-key index i. In particular, CertAt(i) must not be assumed to return the certificate for privateKeyAt(int, PrivateKey). Do not infer meaning from order: No end-entity-first, CA-last, or load/export/reload ordering guarantee is documented. Use certificate properties to determine each certificate's role, and use localKeyId to associate a private key with its certificate when that attribute is present.

      Returns:
      the value of the NumCerts property (read-only)

    • getNumPrivateKeys

      public int getNumPrivateKeys()
      Returns the number of private keys currently contained in this PFX object.

      Private-key indexes range from 0 through NumPrivateKeys - 1 for use with privateKeyAt(int, PrivateKey).

      Indexes are independent: Private keys and certificates are stored in separate collections. Private-key index i has no positional relationship to certificate index i. A PFX commonly has more certificates than private keys because intermediate and root CA certificates are also included. Finding the matching certificate: When the private key has a localKeyId, retrieve it with getSafeBagAttr(boolean, int, String) and pass the value to certByLocalKeyId(String, String, Cert). Do not pair a key and certificate by using the same index. Secret material: A nonzero value means the object contains private keys in memory. Handle the object and any exported form accordingly.

      Returns:
      the value of the NumPrivateKeys property (read-only)

    • getPbes2CryptAlg

      public String getPbes2CryptAlg()
      Gets or sets the content-encryption cipher used when getAlgorithmId() is pbes2. After loading a PBES2-protected PFX, this property reports the cipher used by the loaded shrouded key bag.

      Value Cipher

      aes256-cbc AES-256 in CBC mode; the default for new PBES2 output.

      aes192-cbc AES-192 in CBC mode.

      aes128-cbc AES-128 in CBC mode.

      3des-cbc Triple DES in CBC mode for compatibility.

      PBES2 components: This property chooses the cipher. getPbes2HmacAlg() chooses the HMAC-based PBKDF2 pseudorandom function used to derive the encryption key from the password.

      Returns:
      the value of the Pbes2CryptAlg property

    • setPbes2CryptAlg

      public void setPbes2CryptAlg​(String value)
      Sets the Pbes2CryptAlg property; see getPbes2CryptAlg().
      Parameters:
      value - the new value (not null)

    • getPbes2HmacAlg

      public String getPbes2HmacAlg()
      Gets or sets the HMAC algorithm used by PBKDF2 when getAlgorithmId() is pbes2. After loading a PBES2-protected PFX, this property reports the HMAC choice found in the loaded shrouded key bag.
      • hmacWithSha256 — default for new PBES2 output.
      • hmacWithSha384
      • hmacWithSha512
      • hmacWithSha1 — primarily for compatibility with older consumers.

      Not the container-integrity MAC: This setting is part of PBES2 key derivation for private-key encryption. It should not be confused with the separate integrity protection that a PKCS#12 container may use.

      Returns:
      the value of the Pbes2HmacAlg property

    • setPbes2HmacAlg

      public void setPbes2HmacAlg​(String value)
      Sets the Pbes2HmacAlg property; see getPbes2HmacAlg().
      Parameters:
      value - the new value (not null)

    • getUncommonOptions

      public String getUncommonOptions()
      Provides specialized compatibility options for unusual PFX interoperability requirements. The default is an empty string, which is appropriate for normal use. Multiple options are separated by commas.

      Option Effect

      LegacyOrder Writes internal PKCS#12 ContentInfo objects in the ordering traditionally used by older Chilkat versions.

      NoTruncatePfxPassword64 Prevents Chilkat's default compatibility behavior of truncating an extremely long PFX password to 64 characters.

      Leave empty unless required: These options can reduce interoperability with software that expects the default behavior. Enable one only for a documented compatibility case.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • addCert

      public void addCert​(Cert cert, boolean includeChain)
      Adds cert to this PFX as an identity. The certificate must have an associated private key that Chilkat can obtain and copy. This requirement applies whether includeChain is true or false; AddCert does not provide a certificate-only mode.

      includeChain controls only whether Chilkat also attempts to add the certificate chain:

      Certificate/private-key state includeChain Result

      No private key false or true Fails. A certificate cannot be added by this method without its private key.

      Private key exists but cannot be obtained or exported false or true Fails. Chilkat does not fall back to adding the certificate without the key.

      Usable private key false Adds the private key and cert only. Intermediate and root certificates are not added.

      Usable private key; complete chain locatable true Adds the private key, cert, and the locatable intermediate and root certificates.

      Usable private key; chain incomplete true Succeeds with a partial chain. Missing intermediate or root certificates do not cause failure.

      Chain construction: When includeChain is true, Chilkat searches the certificates already associated with cert and certificates made available for chain building, principally through useCertVault(XmlCertVault). Each intermediate or root certificate is included when it can be located. The chain does not need to terminate at a root, and trust is not evaluated by this operation. Snapshot semantics: The certificate, associated private key, and any locatable chain certificates are copied at the time of the call. Chilkat does not retain a live reference to cert. After this method returns, modifying, reloading, or destroying the source Cert does not affect the material already stored in the PFX, and later changes to the PFX do not affect the source object. Duplicate handling: A private key already present in the object is not added again. The primary certificate and any certificate that has a private key are always inserted, even if an equivalent certificate is already present. Other intermediate or CA certificates are skipped when they are duplicates. Not atomic: After the certificate and key have passed the initial requirements, certificates are merged first and the private key is added afterward. If the key-add step fails, the method returns false but certificates already merged remain in the object. Treat failure as a possible partial modification. A missing or unobtainable private key is rejected before this merge begins. Automatic association: If the private key does not already have a localKeyId, Chilkat generates one and assigns the same value to the key's primary certificate. This identifier associates the key and leaf certificate without relying on collection indexes. Intermediate and root CA certificates may be shared across multiple identities and are not paired by position.

      Parameters:
      cert - the cert argument (not null)
      includeChain - the includeChain argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addPrivateKey

      public void addPrivateKey​(PrivateKey privKey, CertChain certChain)
      Adds privKey and the certificate chain in certChain to this PFX object. The chain must contain at least one certificate. The certificate at index 0 is treated as the end-entity certificate associated with privKey; the remaining entries are additional certificates to include with the identity. The chain does not need to contain a root certificate and may consist only of the end-entity certificate.

      Caller responsibility: Chilkat does not verify that privKey mathematically matches the public key in the certificate at index 0. The association is positional. A mismatch is not rejected and can produce a PFX identity that later fails during signing, decryption, or client authentication. Copy and lifetime behavior: Chilkat immediately copies the private key and every certificate in the supplied chain. It retains neither source object. Modifying, reloading, or destroying the source PrivateKey or CertChain after this method returns does not affect the PFX. Duplicates and automatic association: A private key already present in the PFX is not added again, and duplicate certificates are skipped. If the private key does not already have a localKeyId, Chilkat generates one. The same identifier is assigned to the certificate at index 0, linking that certificate to the key. Other safe-bag attributes are not generated automatically. Failure and partial modification: An empty certificate chain is rejected before anything is added. For later failures, the operation is not atomic: certificates are merged before the private key is added, so the method can return false after leaving some certificates in the PFX.

      Parameters:
      privKey - the privKey argument (not null)
      certChain - the certChain argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • certAt

      public void certAt​(int index, Cert cert)
      Copies the certificate at the zero-based index index into cert. The first certificate is at index 0; valid indexes are less than getNumCerts().

      On success, cert is replaced with an independent, detached copy of the selected certificate. The method does not merge with or append to any certificate already held by cert. The returned copy does not remain linked to the PFX: changing either object later does not affect the other, and the copied certificate remains usable even if the PFX is subsequently modified or destroyed.

      Failure leaves the destination unchanged: If index is out of range or the certificate cannot be returned, the method returns false without modifying cert. When reusing a Cert object in a loop, always use its contents only after this method returns true; otherwise cert may still contain the certificate from an earlier successful call. Do not pair by index: Certificate indexes and private-key indexes are independent. CertAt(i) is not necessarily the certificate associated with privateKeyAt(int, PrivateKey). To associate a key with its certificate, obtain the key's localKeyId with getSafeBagAttr(boolean, int, String) and use certByLocalKeyId(String, String, Cert).

      Parameters:
      index - the index argument
      cert - the cert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • certByLocalKeyId

      public void certByLocalKeyId​(String localKeyId, String encoding, Cert cert)
      Searches for a certificate whose certificate-bag localKeyId attribute matches localKeyId and copies it into cert. encoding names the binary representation used for localKeyId, such as decimal, base64, or hex.

      On success, cert is replaced with the matching certificate. The method does not merge with any certificate already held by cert.

      Failure leaves the destination unchanged: If encoding is invalid, localKeyId cannot be decoded, or no matching certificate is found, the method returns false without modifying cert. Always use cert only after a true return, because a reused destination may still contain a certificate from an earlier call. Recommended association workflow: For a private key at index i, call getSafeBagAttr(boolean, int, String) with localKeyId = true, encoding = i, and cert = localKeyId. That method returns the identifier in decimal representation, so pass the returned value as localKeyId and decimal as encoding here. Do not use matching indexes: Certificates and private keys are stored in independent collections. CertAt(i) is not the certificate for PrivateKeyAt(i) unless that happens coincidentally. Scope: This method returns the matching primary certificate. It does not return an associated certificate chain as a separate object.

      Parameters:
      localKeyId - the localKeyId argument (not null)
      encoding - the encoding argument (not null)
      cert - the cert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getLastJsonData

      public void getLastJsonData​(JsonObject json)
      Replaces the entire contents of json with structured JSON information from the most recent operation. The data is copied as a complete replacement; it is never merged with members already present in json.

      The exact members depend on the preceding method. After loading a PFX, the JSON may describe authenticated-safe content, safe bags, encryption information, and bag attributes. If no JSON data is available, json is cleared to an empty JSON object.

      Destination behavior: The previous contents of json are never preserved by this call. Reusing a JsonObject is safe without clearing it first, but do not expect older members to remain. Diagnostics: Call this method immediately after the operation being inspected. Not every method produces JSON detail, and this information supplements rather than replaces LastErrorText.

      Parameters:
      json - the json argument (not null)

    • getSafeBagAttr

      public String getSafeBagAttr​(boolean forPrivateKey, int index, String attrName)
      Reads a recognized safe-bag attribute from a private key or certificate contained in this PFX. forPrivateKey is true for a private key and false for a certificate. index is the zero-based index within the selected collection. attrName is the attribute name and is matched case-insensitively.

      Empty values are treated as failure: The method succeeds only when the requested attribute is recognized, readable, set, and nonempty. If the attribute is unset or its stored value is an empty string, the method reports failure. An empty string is therefore never a successful attribute result.

      Logical attribute Accepted attrName names Read behavior

      Friendly name friendlyName, keyContainerName, or keyName All three names read the same underlying text attribute. The read succeeds only when the attribute contains a nonempty value; an unset or empty value causes failure.

      Storage provider storageProvider or msStorageProvider Both names read the same underlying text attribute. The read succeeds only when the attribute contains a nonempty value; an unset or empty value causes failure.

      Local key ID localKeyId The read succeeds only when a nonempty local key ID is present. The value is always returned in decimal encoding as one big-endian integer, regardless of the encoding used when it was set.

      Enhanced key usage enhancedKeyUsage Not readable through this method. The operation reports failure even if the attribute was previously set with setSafeBagAttr(boolean, int, String, String, String).

      An unrecognized attrName name, an invalid index, an unreadable attribute, or any recognized attribute whose value is unset or empty causes the read to fail.

      Decimal localKeyId representation: The raw bytes are interpreted as one unsigned big-endian integer. For example, bytes 01 02 03 04 05 06 07 08 are returned as 72623859790382856. Leading zero bytes are not preserved by a set-read-set round trip because 00 01 02 03 and 01 02 03 represent the same integer. Pairing a key with its certificate: For private-key index i, read localKeyId with forPrivateKey = true and index = i. If a nonempty value is returned successfully, pass it to certByLocalKeyId(String, String, Cert) using the encoding decimal. Never assume that certificate index i matches private-key index i.

      Parameters:
      forPrivateKey - the forPrivateKey argument
      index - the index argument
      attrName - the attrName argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • importToKeychain

      public void importToKeychain​(JsonObject opts)
      Imports all certificates and private keys currently held by this Pfx object into the application's default keychain. This method is available only on macOS and iOS. On other platforms it returns false and reports that the method is macOS/iOS only.

      The method does not accept a password. Any required password must already have been supplied when loading the PFX or PEM data; the objects presently contained in the Pfx are what this method imports.

      opts is reserved for future use: The JsonObject currently has no defined members and does not affect the import. Pass an empty JsonObject. Any JSON members supplied today are ignored. The destination keychain, access group, key accessibility, iCloud synchronization, and replacement behavior are not configurable through this method.

      The certificates and private keys are imported into the application's platform-default keychain without assigning special access-group, accessibility, or synchronization attributes. Normal macOS or iOS keychain-access rules and application entitlements still apply.

      Duplicates and atomicity: An item already present in the keychain does not cause failure and is not added again or replaced, so re-importing the same identity is safe. The import is all-or-nothing: if the method fails, it does not leave only a subset of the PFX contents imported.

      The calling sequence is the same on macOS and iOS: load or build the Pfx, create an empty JsonObject, and pass it as opts.

      Parameters:
      opts - the opts argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • importToWindows

      public void importToWindows​(boolean exportable, boolean userProtected, boolean machineKeyset, boolean allowOverwriteKey, boolean allowExport, String leafStore, String intermediateStore, String rootStore, String extraOptions)
      Imports the certificates and private keys in this PFX into Windows certificate stores and Windows key storage. This method is available only on Microsoft Windows.

      Argument Name Meaning

      exportable exportable Controls the legacy CryptoAPI exportability setting. This is the companion setting for the older certificate-import path; it is not the setting that determines exportability of the CNG-persisted key.

      userProtected userProtected When true, enables Windows strong key protection, which can display an interactive prompt when the key is imported or used. When false, key import and use are silent.

      machineKeyset machineKeyset Selects the scope for both private-key storage and certificate stores. true uses Local Machine; false uses Current User. Local Machine imports generally require elevation.

      allowOverwriteKey allowOverwriteKey When true, an existing private key having the same key-container name may be overwritten. When false, the import fails if that key already exists.

      allowExport allowExport Controls the private key as persisted by the CNG Microsoft Software Key Storage Provider. When true, the key is marked plaintext-exportable and can later be exported, including as raw private-key material. This is the effective exportability control for the key installed by this method.

      leafStore leafStore Destination store for end-entity (leaf) certificates.

      intermediateStore intermediateStore Destination store for intermediate CA certificates.

      rootStore rootStore Destination store for root or self-signed certificates.

      extraOptions extraOptions Currently unused. It has no effect for any value. Pass an empty string.

      Two different exportability settings: exportable applies to the legacy CryptoAPI path. allowExport applies to the CNG Key Storage Provider used to persist the private key and determines whether that installed key can actually be exported later. Set allowExport to true only when later private-key export is required, because it permits plaintext export.

      Store names are case-insensitive. Standard names include My for leaf certificates, CA or CertificationAuthority for intermediate certificates, and Root for trusted roots. For any certificate class, pass None, Nothing, or an empty string to skip importing that class. Other Windows store names, such as AddressBook, AuthRoot, TrustedPeople, and TrustedPublisher, may also be used when appropriate.

      If a certificate already exists, it is updated or replaced rather than causing an error. Existing private keys are handled separately: when a key having the same key-container name exists, allowOverwriteKey determines whether it is overwritten or causes the import to fail. The key-container name comes from the private key's friendly name; if no friendly name exists, Chilkat generates a unique name.

      Overwrite risk: Enabling allowOverwriteKey can replace an unrelated existing key when its container name matches the imported key's friendly name. Enable overwrite only when that name is known to identify the key that should be replaced. Not atomic: Keys are imported one at a time, followed by certificates one at a time. Items imported before a later failure remain installed. A private-key failure stops key processing, while a certificate failure does not necessarily prevent later certificates from being attempted. A false return can therefore leave partial results in Windows; applications requiring all-or-nothing behavior must inspect and clean up the target stores themselves. Interactive protection: Do not set userProtected to true in a Windows service or another noninteractive process. The required protection prompt cannot be displayed and the operation may fail or hang. Use false for silent service and server operation. Trust-store impact: Importing a root certificate into the Windows Root store makes it a trust anchor for the selected Current User or Local Machine scope. Import only roots that the application or administrator intentionally trusts. Use None for rootStore when root installation is not required.

      Common configurations:

      Scenario Typical settings

      Per-user, silent import exportable=false, userProtected=false, machineKeyset=false, allowOverwriteKey=false, allowExport=false, leaf My, intermediate CA, root None.

      Machine-wide service/server Use the silent settings above with machineKeyset=true and run elevated.

      Key must be exportable later Set allowExport=true. Also set exportable=true when legacy CryptoAPI exportability is wanted.

      Leaf certificate only Use a real leaf store such as My and pass None for both intermediate and root stores.

      Replace an existing key Set allowOverwriteKey=true only after confirming that the key-container name cannot collide with an unrelated key.

      Parameters:
      exportable - the exportable argument
      userProtected - the userProtected argument
      machineKeyset - the machineKeyset argument
      allowOverwriteKey - the allowOverwriteKey argument
      allowExport - the allowExport argument
      leafStore - the leafStore argument (not null)
      intermediateStore - the intermediateStore argument (not null)
      rootStore - the rootStore argument (not null)
      extraOptions - the extraOptions argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPem

      public void loadPem​(String pemStr, String password)
      Loads one or more certificate/private-key identities from the PEM-formatted text in pemStr and builds the contents of this Pfx object. password supplies the password when the PEM contains encrypted private keys.

      The supported PEM block types are:

      PEM block Meaning

      BEGIN CERTIFICATE An X.509 certificate.

      BEGIN PRIVATE KEY An unencrypted PKCS #8 private key.

      BEGIN ENCRYPTED PRIVATE KEY A password-encrypted PKCS #8 private key.

      BEGIN RSA PRIVATE KEY A traditional RSA private key, either unencrypted or password-encrypted.

      Multiple independent identities are supported. Each private key is paired with the certificate whose public key cryptographically matches it, and its chain is assembled from the other certificates in the PEM. Block order is therefore irrelevant; keys and certificates are not paired by position.

      Required content: The PEM must contain at least one private key, and every private key must have a matching certificate. The method fails if any key lacks its certificate or if the PEM contains certificates but no private key. Certificates that do not belong to any loaded key's certificate chain are not carried into the PFX. Duplicates: Repeated private-key or certificate blocks are accepted and de-duplicated. They do not cause an error and do not create duplicate entries in the resulting PFX. Replacement and failure behavior: A successful call replaces all existing contents. If the PEM cannot be parsed, the previous contents are preserved because replacement has not begun. If parsing succeeds but conversion fails while the parsed items are being added, the object has already been cleared and may contain only the items processed before the failure. Therefore, a failed call can mean either unchanged or partially replaced state, depending on where the failure occurred.

      Parameters:
      pemStr - the pemStr argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPfxBd

      public void loadPfxBd​(BinData bd, String password)
      Loads a PFX / PKCS#12 container from the bytes currently held in bd. password is the password argument.

      Password and JSON options: password accepts either a literal password, which is used for both integrity verification and all private-key bags, or a JSON object that can separately provide integrity, privKeys, and skipPrivateKeys. See loadPfxFile(String, String) for the exact JSON-detection rules, member types, defaults, and edge cases.Destructive replacement: This method always replaces the current contents. The object is cleared before the import is attempted, so a failed load leaves the Pfx object empty; previously loaded certificates and keys are not preserved.

      Parameters:
      bd - the bd argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPfxEncoded

      public void loadPfxEncoded​(String encodedData, String encoding, String password)
      Decodes the text in encodedData using the binary encoding named by encoding, then loads the resulting bytes as a PFX / PKCS#12 container. Common encodings include base64 and hex.

      password is the password argument.

      Password and JSON options: password accepts either a literal password, which is used for both integrity verification and all private-key bags, or a JSON object that can separately provide integrity, privKeys, and skipPrivateKeys. See loadPfxFile(String, String) for the exact JSON-detection rules, member types, defaults, and edge cases.Binary encoding is not a charset: encoding describes how binary PFX bytes were represented as text. It does not control certificate-name character encoding or password interpretation.Destructive replacement: This method always replaces the current contents. The object is cleared before the import is attempted, so a decoding error, bad password, or malformed PFX leaves the Pfx object empty; previously loaded certificates and keys are not preserved.

      Parameters:
      encodedData - the encodedData argument (not null)
      encoding - the encoding argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadPfxFile

      public void loadPfxFile​(String path, String password)
      Loads a PFX / PKCS#12 container from the file path in path. password follows the password contract below. The same contract is used by LoadPfxBytes, loadPfxBd(BinData, String), and loadPfxEncoded(String, String, String); it does not apply to loadPem(String, String).

      The password argument has two modes:

      • Plain password: For any non-JSON value P, Chilkat uses P for both integrity verification and all private-key bags. skipPrivateKeys is false.
      • JSON options: After trimming leading and trailing whitespace, JSON mode is used only when the value begins with {, ends with }, and parses as valid JSON. All three recognized members are optional and case-sensitive. 
      {
   "integrity": "integrity-password",
   "privKeys": "private-key-password",
   "skipPrivateKeys": false
 }

      Member Accepted value Default when omitted

      integrity String Integrity verification is skipped.

      privKeys String The empty string is used as the password for every private-key bag.

      skipPrivateKeys JSON Boolean true, or a string equal to true without regard to case false

      Unknown JSON members are silently ignored. A misspelled member such as privkeys therefore does not produce a JSON error; the documented default is used instead. The single privKeys password applies to every private-key bag. Per-bag passwords are not supported.

      Certificate-only loading: When skipPrivateKeys is true, private-key bags are not processed and the privKeys password is irrelevant. Integrity verification is still performed when an integrity member is supplied.Empty versus omitted integrity password: A plain empty string requests integrity verification using an empty password. To intentionally skip integrity verification, use JSON and omit integrity, for example {"skipPrivateKeys":true} or {}.Literal-password collision: A real password that, after trimming, is a valid JSON object text is interpreted as options, and there is no force-literal escape. Text enclosed in braces that is not valid JSON falls back to literal-password handling.Independent protection roles: PKCS#12 can use one password for the container integrity MAC and another for encrypted private-key bags. A correct integrity password does not validate the privKeys password. If integrity verification succeeds but private-key decryption fails, the load still fails unless private keys were skipped.Destructive replacement: This method always replaces the current contents. The object is cleared before opening and importing the file, so any failure—including a missing file, invalid password, or malformed PFX—leaves the Pfx object empty. Load into a new object when the previously loaded contents must be preserved on failure.

      Parameters:
      path - the path argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • privateKeyAt

      public void privateKeyAt​(int index, PrivateKey privKey)
      Copies the private key at the zero-based index index into privKey. The first private key is at index 0; valid indexes are less than getNumPrivateKeys().

      On success, privKey is replaced with an independent, detached copy of the selected private key. The method does not merge with or append to any key already held by privKey. The returned copy does not remain linked to the PFX: changing either object later does not affect the other, and the copied key remains usable even if the PFX is subsequently modified or destroyed.

      Failure leaves the destination unchanged: If index is out of range or the private key cannot be returned, the method returns false without modifying privKey. When reusing a PrivateKey object, use its contents only after this method returns true; otherwise privKey may still contain a key from an earlier successful call. Do not pair by index: Private-key indexes and certificate indexes are independent. PrivateKeyAt(i) is not necessarily associated with certAt(int, Cert). Finding the matching certificate: Call getSafeBagAttr(boolean, int, String) with index set to true, privKey set to this private-key index, and ARG3 set to localKeyId. If the attribute is present, pass the returned value to certByLocalKeyId(String, String, Cert) using decimal as the encoding. Sensitive material: Treat privKey as secret key material. Avoid unnecessary serialization, logging, or long-lived copies.

      Parameters:
      index - the index argument
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSafeBagAttr

      public void setSafeBagAttr​(boolean forPrivateKey, int index, String name, String value, String encoding)
      Sets a safe-bag attribute on a private key or certificate contained in this PFX. A safe-bag attribute is metadata attached to an item inside a PKCS#12/PFX container; it does not change the certificate or private-key material itself.
      • forPrivateKey is true to address a private key and false to address a certificate.
      • index is the zero-based index within the selected collection.
      • name is the attribute name. Attribute names are matched case-insensitively.
      • value is the value to set.
      • encoding specifies how value is decoded only when setting localKeyId. It is ignored for all text-valued attributes.

      Setting a recognized attribute replaces its existing value; it never creates a duplicate attribute. The method returns false and makes no change if name is not one of the recognized names listed below.

      Logical attribute Accepted name names Value and behavior

      Friendly name friendlyName, keyContainerName, or keyName These names refer to the same underlying text attribute. value is stored as text, and encoding is ignored. Setting through any alias replaces the value visible through every alias.

      Storage provider storageProvider or msStorageProvider The two names refer to the same underlying text attribute. value is stored as text, and encoding is ignored.

      Local key ID localKeyId A binary identifier commonly used to associate a private-key bag with its certificate bag. encoding specifies the encoding of value, such as hex, base64, or decimal. An empty value removes the attribute.

      Enhanced key usage enhancedKeyUsage value is a comma-separated text list. Each item may be a recognized usage name, such as serverAuth, clientAuth, codeSigning, or emailProtection, or a dotted OID such as 1.3.6.1.5.5.7.3.1. Unrecognized items that are not valid OIDs are silently skipped. encoding is ignored. An empty value removes the attribute. This attribute is write-only through the safe-bag attribute API.

      Encoding applies only to localKeyId: Friendly name, storage provider, and enhanced key usage are text values. Supplying hex, base64, or another encoding for those attributes has no effect.

      Parameters:
      forPrivateKey - the forPrivateKey argument
      index - the index argument
      name - the name argument (not null)
      value - the value argument (not null)
      encoding - the encoding argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toBd

      public void toBd​(String password, BinData bd)
      Serializes the current PFX contents as PKCS#12 data and writes the bytes to bd, using password as the output password.

      bd is cleared before serialization begins. On success, it contains only the newly generated PFX data; the method replaces the previous BinData contents and never appends to them.

      Clear-first failure behavior: If the method returns false, the contents that bd held before the call are not restored. bd may be empty or may contain partially generated data. Use the destination only after a true return when complete output is required.

      The private-key encryption scheme is controlled by getAlgorithmId() and, for PBES2, the related algorithm properties.

      Sensitive output: bd may contain encrypted private-key material. Keep the password and resulting bytes protected even though they are stored only in memory.

      Parameters:
      password - the password argument (not null)
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toEncodedString

      public String toEncodedString​(String password, String encoding)
      Serializes the current PFX contents using password as the output password, then returns the PKCS#12 bytes encoded as text using encoding. Common choices for encoding are base64 and hex.

      The PFX encryption settings are controlled by getAlgorithmId() and the PBES2 properties.

      Encoding does not add protection: Base64, hexadecimal, and similar encodings only represent binary bytes as text. The confidentiality of private keys depends on the PFX password and encryption settings.

      Parameters:
      password - the password argument (not null)
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toFile

      public void toFile​(String password, String path)
      Serializes the current PFX contents and writes the resulting PKCS#12 data to path, using password as the output password.

      .pfx and .p12 are the conventional filename extensions for PKCS#12 containers. The private-key protection scheme is controlled by getAlgorithmId() and the PBES2 properties.

      File security: A PFX commonly contains private keys. In addition to choosing a strong password, protect the file with appropriate filesystem permissions and avoid leaving unnecessary backup copies.

      Parameters:
      password - the password argument (not null)
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toJksObj

      public void toJksObj​(String aliasName, String password, JavaKeyStore jksObj)
      Populates jksObj with a Java KeyStore (JKS) representation of this PFX. One private-key entry is created for each private key, and certificates in the PFX are used to construct the corresponding certificate chains. password protects the generated private-key entries.

      jksObj is cleared before conversion begins. On success, it contains only the newly converted key store; the method replaces the destination's previous entries rather than merging with them.

      Clear-first failure behavior: If conversion returns false, the key store that jksObj held before the call is not restored. jksObj may be empty or partially populated. Use the destination only after a true return when a complete conversion is required.

      If aliasName is nonempty, it becomes the alias for the first private key. Otherwise, the alias is selected in this order:

      1. Certificate subject common name.
      2. Certificate subject email address.
      3. PKCS#9 friendly-name attribute.
      4. Certificate serial number.

      Aliases for additional private keys are selected automatically using the same preference order.

      Container conversion: PKCS#12 and JKS are different keystore formats. Conversion preserves available key-and-certificate relationships, but provider-specific PKCS#12 attributes may not have an equivalent JKS representation.

      Parameters:
      aliasName - the aliasName argument (not null)
      password - the password argument (not null)
      jksObj - the jksObj argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toPem

      public String toPem()
      Exports all private keys and certificates currently held by this object as PEM-formatted text. Certificates are written as standard BEGIN CERTIFICATE blocks.

      Every private key is exported as unencrypted PKCS #8 in a BEGIN PRIVATE KEY block. This method does not emit PKCS #1 RSA, SEC 1 EC, traditional DSA, or legacy OpenSSL encrypted-private-key blocks.

      Private keys are unencrypted: The returned text contains cleartext private-key material. Use toPemEx(boolean, boolean, boolean, boolean, String, String) to produce encrypted PKCS #8 private-key blocks or to omit selected categories of objects.

      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toPemEx

      public String toPemEx​(boolean extendedAttrs, boolean noKeys, boolean noCerts, boolean noCaCerts, String encryptAlg, String password)
      Exports selected PFX contents as PEM-formatted text. Certificates are written as standard BEGIN CERTIFICATE blocks. Private keys are always written in PKCS #8 form: BEGIN PRIVATE KEY when unencrypted, or BEGIN ENCRYPTED PRIVATE KEY when encrypted. Traditional PKCS #1 RSA, SEC 1 EC, DSA, and legacy OpenSSL encrypted-key PEM formats are not produced.

      The arguments control the output as follows:

      Argument Effect

      extendedAttrs When true, emits OpenSSL-style bag and key attribute text in addition to the PEM blocks.

      noKeys When true, omits private-key blocks.

      noCerts When true, omits all certificate blocks.

      noCaCerts When true, omits intermediate and root CA certificates while retaining applicable end-entity certificates.

      encryptAlg Selects private-key encryption. Recognized keywords are aes128, aes192, aes256, des3, and 3des. Leave empty for unencrypted private keys. An unrecognized nonempty value falls back to triple-DES rather than silently producing unencrypted output.

      password The password for encrypted private-key output. Encryption is applied only when both encryptAlg and password are nonempty.

      Encryption format: AES choices use CBC mode with a 16-byte IV. des3 and 3des use triple-DES in CBC mode with an 8-byte IV. The result is an encrypted PKCS #8 BEGIN ENCRYPTED PRIVATE KEY block. Security note: If private keys are included and either encryptAlg or password is empty, the output contains unencrypted PKCS #8 private-key material. Prefer aes256 for new encrypted output unless the receiving system requires another supported choice.

      Parameters:
      extendedAttrs - the extendedAttrs argument
      noKeys - the noKeys argument
      noCerts - the noCerts argument
      noCaCerts - the noCaCerts argument
      encryptAlg - the encryptAlg argument (not null)
      password - the password argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • useCertVault

      public void useCertVault​(XmlCertVault vault)
      Adds the certificates currently contained in vault to the set of certificate sources available for later chain-building operations, such as addCert(Cert, boolean).

      The call captures a point-in-time snapshot of the vault's certificates. Chilkat retains its own lifetime-safe references to those individual certificates and does not retain a reference to the XmlCertVault object itself. After this method returns, vault may be released, destroyed, or allowed to go out of scope; its contributed certificates remain available to this Pfx object.

      Snapshot, not live synchronization: Certificates added to or removed from vault after this call are not automatically reflected here. Call UseCertVault again to capture certificates added later. Additive behavior: Repeated calls accumulate certificate sources; a later call does not replace or clear certificates contributed by earlier vaults. The vault certificates are made available for chain construction and are not, merely by this call, added to the PFX's exported certificate collection.

      Parameters:
      vault - the vault argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why