Chilkat.Pfx Class Overview
Chilkat.Pfx represents a PFX / PKCS#12 container that can hold certificates, private keys, and certificate chains. It can load PFX data from files, bytes, encoded strings, BinData, or PEM; add certificates and private keys; inspect certificates and private keys; manage safe-bag attributes; export to PFX, PEM, JKS, binary, encoded strings, or files; and import certificates and keys into Windows or macOS/iOS key stores.
What the Class Is Used For
Use Chilkat.Pfx when an application needs to work with password-protected certificate containers, typically files with .pfx or .p12 extensions. A PFX commonly contains a leaf certificate, its matching private key, and the certificate chain needed to establish trust. The class also supports conversion between PFX, PEM, and Java KeyStore formats, and can import the contained certificates and private keys into platform certificate stores.
Load PFX / PKCS#12
Load from file, bytes, encoded data, BinData, or
PEM-formatted certificate/key material.
Build PFX Containers
Add certificates, private keys, and certificate chains, optionally using a
certificate vault to help complete chains.
Inspect Contents
Retrieve certificates, private keys, safe-bag attributes, counts, and diagnostic
JSON from recent operations.
Export and Import
Write PFX, PEM, encrypted PEM, encoded strings, binary data, files, JKS objects,
Windows certificate stores, and macOS/iOS keychains.
Typical Workflow
- Create a Pfx object.
- Load an existing PFX with LoadPfxFile, LoadPfxBytes, LoadPfxBd, or LoadPfxEncoded, or load PEM material with LoadPem.
- Inspect NumCerts and NumPrivateKeys to confirm the expected contents.
- Retrieve individual certificates or keys with CertAt, CertByLocalKeyId, or PrivateKeyAt.
- Optionally add material with AddCert or AddPrivateKey.
- Configure PFX encryption output using AlgorithmId, Pbes2CryptAlg, and Pbes2HmacAlg when writing a new PFX.
- Export with ToFile, ToBinary, ToBd, ToEncodedString, ToPem, ToPemEx, or ToJksObj.
- Import to a platform store with ImportToWindows or ImportToKeychain when needed.
- Check LastErrorText and optionally GetLastJsonData after failures or unexpected behavior.
Core Concepts
| Concept | Meaning | Important Members |
|---|---|---|
| PFX / PKCS#12 | A container format used to package certificates, private keys, and certificate chains. PFX and PKCS#12 are essentially the same format. | LoadPfxFile, ToFile, ToBinary |
| Certificate + Private Key Pair | The private key should match the public key embedded in the corresponding certificate. | AddCert, AddPrivateKey, PrivateKeyAt |
| Certificate Chain | The ordered chain of certificates from the leaf certificate through intermediate certificates and possibly the root. | AddCert, AddPrivateKey, UseCertVault |
| Safe Bag Attributes | PKCS#12 attributes associated with certificate or private-key bags, such as localKeyId, keyContainerName, and storageProvider. | GetSafeBagAttr, SetSafeBagAttr, CertByLocalKeyId |
| Shrouded Key Bag Encryption | The private key inside the PFX is encrypted using the configured algorithm. | AlgorithmId, Pbes2CryptAlg, Pbes2HmacAlg |
| Platform Import | Certificates and private keys from a PFX can be imported into Windows certificate stores or the macOS/iOS keychain. | ImportToWindows, ImportToKeychain |
Core Properties
| Property | Purpose | Guidance |
|---|---|---|
| NumCerts | Number of certificates contained in the PFX. | Use after loading or building a PFX to confirm expected certificate count. |
| NumPrivateKeys | Number of private keys contained in the PFX. | A typical PFX contains one private key, but multiple private keys are possible. |
| AlgorithmId | Encryption algorithm used when writing a PFX, or the algorithm used by a loaded PFX. | Default is pbeWithSHAAnd3_KeyTripleDES_CBC. Set to pbes2 to use Pbes2CryptAlg and Pbes2HmacAlg. |
| Pbes2CryptAlg | Encryption algorithm used when AlgorithmId is pbes2. | Possible values are aes256-cbc, aes192-cbc, aes128-cbc, and 3des-cbc. Default for writing is aes256-cbc. |
| Pbes2HmacAlg | HMAC hash algorithm used when AlgorithmId is pbes2. | Possible values are hmacWithSha256, hmacWithSha384, hmacWithSha512, and hmacWithSha1. Default for writing is hmacWithSha256. |
| UncommonOptions | Comma-separated keywords for uncommon behavior. | Typically left empty. Supports LegacyOrder and NoTruncatePfxPassword64. |
| 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 PFX and PEM Data
| Input Source | Method | Behavior |
|---|---|---|
| PFX / P12 file | LoadPfxFile | Loads a PFX from a file path using the supplied password. |
| In-memory PFX bytes | LoadPfxBytes | Loads a PFX from a byte array. |
| BinData | LoadPfxBd | Loads a PFX from the contents of a BinData object. |
| Encoded PFX bytes | LoadPfxEncoded | Loads a PFX from encoded byte data, such as Base64, Base32, hex, quoted-printable, URL encoding, or other supported encodings. |
| PEM string | LoadPem | Loads PEM-formatted private key and certificate material, including the main certificate and optional chain certificates. |
Separate PFX passwords:
Starting in v9.5.0.75, a PFX/P12 with different passwords for integrity and
private keys can be loaded by passing JSON as the password, such as
{ "integrity": "password1", "privKeys": "password2" }.
To open the PFX without private-key access, include
"skipPrivateKeys": true.
Building a PFX
| Task | Method | Important Details |
|---|---|---|
| Add certificate and private key | AddCert | Adds a certificate, its private key if present, and optionally its certificate chain. |
| Add private key with chain | AddPrivateKey | Adds a private key and certificate chain. The private key should correspond to the first certificate in the chain. |
| Provide chain-building certificates | UseCertVault | Adds an XmlCertVault to the list of sources searched when building certificate chains to a root certificate. |
Chain-building rule:
When AddCert is called with
includeChain = true, the certificate must have a
private key, and the chain must be completed to the root for the operation to
succeed.
Inspecting Certificates and Private Keys
| Need | Method / Property | Behavior |
|---|---|---|
| Count certificates | NumCerts | Returns the number of certificates contained in the PFX. |
| Count private keys | NumPrivateKeys | Returns the number of private keys contained in the PFX. |
| Get certificate by index | CertAt | Returns the Nth certificate in a supplied Cert object. The first certificate is index 0. |
| Get certificate by local key ID | CertByLocalKeyId | Finds a certificate whose cert bag has a matching localKeyId attribute. The ID can be specified using an encoding such as decimal, Base64, or hex. |
| Get private key by index | PrivateKeyAt | Returns the Nth private key in a supplied PrivateKey object. The first private key is index 0. |
| Get operation details | GetLastJsonData | Writes JSON information about what happened in the last method call. |
Safe Bag Attributes
Safe bag attributes are optional attributes stored inside the PKCS#12 structure. They are often used to associate private keys with certificates or preserve platform-specific metadata.
| Attribute | Meaning | Access |
|---|---|---|
| localKeyId | Decimal representation of the local key ID used to associate a certificate bag with the corresponding private key. | GetSafeBagAttr, SetSafeBagAttr, CertByLocalKeyId |
| keyContainerName | Key container name, or key name, of the private key. | GetSafeBagAttr, SetSafeBagAttr |
| storageProvider | Name of the Cryptographic Storage Provider to be used for the key. | GetSafeBagAttr, SetSafeBagAttr |
Attribute note:
These attributes are optional. A PFX is not required to contain any of them.
To remove a safe bag attribute, call SetSafeBagAttr
with an empty value.
Writing and Exporting PFX Data
| Output Target | Method | Behavior |
|---|---|---|
| BinData | ToBd | Writes the PFX to a supplied BinData object. |
| Byte array | ToBinary | Writes the PFX to in-memory bytes. |
| Encoded string | ToEncodedString | Writes the PFX to an encoded string, such as Base64 or hex. |
| File | ToFile | Writes the PFX to a file. Standard extensions are .pfx and .p12. |
| PEM string | ToPem | Writes private key and available certificates as PEM-formatted text. |
| PEM string with options | ToPemEx | Writes PEM with options for extended attributes, omitting keys, omitting certificates, omitting CA certificates, and encrypting private keys. |
| Java KeyStore object | ToJksObj | Converts the PFX to a JavaKeyStore object, creating one JKS entry for each private key. |
PFX Encryption Options
| Setting | Applies When | Choices / Defaults |
|---|---|---|
| AlgorithmId | Writing a PFX, or inspecting the algorithm used by a loaded PFX. | Default is pbeWithSHAAnd3_KeyTripleDES_CBC. Set to pbes2 to use PBES2 options. |
| Pbes2CryptAlg | Only meaningful when AlgorithmId = pbes2. | aes256-cbc default, aes192-cbc, aes128-cbc, 3des-cbc. |
| Pbes2HmacAlg | Only meaningful when AlgorithmId = pbes2. | hmacWithSha256 default, hmacWithSha384, hmacWithSha512, hmacWithSha1. |
PBES2 usage:
Set AlgorithmId to
pbes2 before writing the PFX if you want
Pbes2CryptAlg and
Pbes2HmacAlg to control the encryption and HMAC
algorithms.
PEM Export Options
| ToPemEx Argument | Purpose | Notes |
|---|---|---|
| extendedAttrs | Emits Bag Attributes and Key Attributes. | Useful when preserving or inspecting PKCS#12 metadata. |
| noKeys | Omits private keys. | Use when only certificates should be exported. |
| noCerts | Omits certificates. | Use when only private keys should be exported. |
| noCaCerts | Omits CA and intermediate CA certificates. | Useful when exporting only the leaf certificate and key. |
| encryptAlg | Encrypts private keys in the PEM output. | Choices are des3, aes128, aes192, and aes256. All use CBC mode. |
| password | Password for encrypted private-key PEM output. | Leave empty if private keys are not encrypted. |
Importing to Platform Stores
| Platform | Method | Important Options |
|---|---|---|
| macOS / iOS keychain | ImportToKeychain | Imports certificates and private keys contained in the PFX to the keychain. Options are provided with a JsonObject. |
| Windows certificate stores | ImportToWindows | Supports key exportability, user protection, machine keyset storage, overwriting existing key containers, allowing re-export, and selecting stores for leaf, intermediate, and root certificates. |
Windows store choices:
Windows import store names include None,
AddressBook, AuthRoot,
CertificationAuthority,
My, Root,
TrustedPeople, and
TrustedPublisher. Leaf certificates are typically
imported into My.
Windows Import Options
| Argument | Meaning |
|---|---|
| exportable | Marks imported keys as exportable. |
| userProtected | Requests user notification or protection behavior when certain attempts are made to use the key. Exact behavior depends on the CSP. |
| machineKeyset | Stores private keys under the local computer instead of the current user. |
| allowOverwriteKey | Allows an existing key container with the same name to be overwritten. |
| allowExport | Marks the key as exportable so it can later be re-exported to a PFX. |
| leafStore | Store name for leaf certificates. A leaf certificate is not the issuer of any other certificate in the PFX. |
| intermediateStore | Store name for intermediate certificates. An intermediate is not root or self-signed but is the issuer of another certificate in the PFX. |
| rootStore | Reserved for future options. The documentation says to pass an empty string at this time. |
| extraOptions | Additional import options when needed. |
Java KeyStore Conversion
ToJksObj converts the PFX to a JavaKeyStore object. One JKS entry is created for each private key found in the PFX, and certificates are used to construct the certificate chain for each key.
| Alias Source Preference | Used When |
|---|---|
| Provided alias argument | Used for the first private key when a non-empty alias is supplied. |
| Certificate subject common name | First fallback when an alias is not provided. |
| Certificate subject email address | Second fallback. |
| PKCS#9 friendly name | Third fallback. |
| Certificate serial number | Final fallback. |
Multiple private keys:
If the PFX contains multiple private keys, aliases for keys after the first are
automatically assigned using the same preference order.
UncommonOptions
| Keyword | Added | Effect |
|---|---|---|
| LegacyOrder | v9.5.0.83 | Writes internal ContentInfos in the order Chilkat traditionally used in previous versions. |
| NoTruncatePfxPassword64 | v9.5.0.87 | Prevents Chilkat from truncating extremely long PFX passwords to 64 characters. By default, Chilkat truncates passwords to 64 characters for Microsoft compatibility. |
Default behavior:
UncommonOptions defaults to the empty string and
should typically remain empty unless one of these special behaviors is required.
Method Summary by Category
| Category | Methods | Purpose |
|---|---|---|
| Load PFX / PEM | LoadPfxFile, LoadPfxBytes, LoadPfxBd, LoadPfxEncoded, LoadPem | Load PFX/PKCS#12 or PEM certificate/key material from files, memory, encoded strings, BinData, or PEM text. |
| Add material | AddCert, AddPrivateKey, UseCertVault | Build a PFX from certificates, private keys, and certificate chains. |
| Inspect contents | CertAt, CertByLocalKeyId, PrivateKeyAt, GetLastJsonData | Retrieve certificates, private keys, and operation details. |
| Safe bag attributes | GetSafeBagAttr, SetSafeBagAttr | Read, set, or remove attributes on certificate or private-key safe bags. |
| Export PFX | ToBd, ToBinary, ToEncodedString, ToFile | Write the PFX to memory, encoded text, BinData, or a file. |
| Export PEM / JKS | ToPem, ToPemEx, ToJksObj | Convert PFX contents to PEM text or Java KeyStore entries. |
| Platform import | ImportToWindows, ImportToKeychain | Import certificates and private keys into Windows certificate stores or the macOS/iOS keychain. |
Diagnostics and Troubleshooting
| Problem Area | Member | What to Check |
|---|---|---|
| Load failed | LoadPfxFile, LoadPfxBytes, LastErrorText | Check the password, file path, input bytes, encoding, and whether the PFX uses separate integrity and private-key passwords. |
| Private keys are not available | NumPrivateKeys, LoadPfxFile | Confirm the PFX contains private keys and that private-key access was not skipped with skipPrivateKeys. |
| Certificate chain could not be added | AddCert, UseCertVault | Confirm the certificate has a private key and that the chain can be completed to the root using available certificate sources. |
| Output PFX uses unexpected encryption | AlgorithmId, Pbes2CryptAlg, Pbes2HmacAlg | Set encryption properties before writing the PFX. |
| Windows import fails or imports to wrong store | ImportToWindows | Check exportability flags, machine/user keyset choice, overwrite behavior, and the selected leaf/intermediate/root store names. |
| Safe bag attribute is missing | GetSafeBagAttr | Safe bag attributes are optional and may not be present in a given PFX. |
| Need more operation detail | GetLastJsonData | Retrieve JSON details about what happened in the last method call. |
Common Pitfalls
| Pitfall | Better Approach |
|---|---|
| Assuming every PFX uses one password for both integrity and private keys. | Use the JSON password form when a PFX/P12 uses separate integrity and private-key passwords. |
| Adding a certificate chain without the certificate’s private key. | For AddCert(includeChain=true), ensure the certificate has a private key. |
| Expecting chain building to succeed without available intermediate/root certificates. | Use UseCertVault or other available certificate sources so the chain can be completed. |
| Setting PBES2 encryption options without setting AlgorithmId to pbes2. | Pbes2CryptAlg and Pbes2HmacAlg are meaningful only when AlgorithmId = pbes2. |
| Assuming safe bag attributes are always present. | Treat localKeyId, keyContainerName, and storageProvider as optional metadata. |
| Using extremely long PFX passwords without considering Microsoft compatibility. | By default, Chilkat truncates to 64 characters for Microsoft compatibility. Use NoTruncatePfxPassword64 only when truncation must be prevented. |
Best Practices
| Recommendation | Reason |
|---|---|
| Confirm counts after loading. | Check NumCerts and NumPrivateKeys to verify that the expected material was loaded. |
| Use UseCertVault when building chains. | It gives Chilkat more certificate sources to complete chains to a root. |
| Use PBES2 when modern PFX encryption settings are required. | Set AlgorithmId = pbes2 and choose Pbes2CryptAlg and Pbes2HmacAlg. |
| Use ToPemEx for controlled PEM export. | It allows private keys, certificates, CA certificates, extended attributes, and private-key encryption to be included or omitted as needed. |
| Use platform import methods when keys must be installed into OS stores. | ImportToWindows and ImportToKeychain handle OS-specific certificate and private-key import. |
| Use GetLastJsonData for additional operation detail. | It can provide structured information about what happened during the previous method call. |
| Check LastErrorText after failures. | It provides the most useful diagnostic detail for loading, adding, exporting, importing, safe-bag, and conversion operations. |
Summary
Chilkat.Pfx is the Chilkat class for working with PFX / PKCS#12 containers. 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 JKS; and import contents into Windows or macOS/iOS key stores.
The most important practical guidance is to verify the number of certificates and private keys after loading, use the JSON password form for PFX files with separate integrity and private-key passwords, use certificate vaults when building complete chains, and configure PBES2 options before writing when modern PFX encryption is required.