Pfx Swift Reference Documentation

CkoPfx

Current Version: 11.5.0

Chilkat.Pfx

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.

Object Creation

let obj = CkoPfx()!

Properties

AlgorithmId
algorithmId: String!
Introduced in version 9.5.0.83

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 Pbes2CryptAlg and Pbes2HmacAlg.

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.

More Information and Examples
top
DebugLogFilePath
debugLogFilePath: String!

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.

More Information and Examples
top
LastErrorHtml
lastErrorHtml: String! (read-only)

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.

top
LastErrorText
lastErrorText: String! (read-only)

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.

top
LastErrorXml
lastErrorXml: String! (read-only)

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.

top
LastMethodSuccess
lastMethodSuccess: Bool

Indicates the success or failure of the most recent method call: true means success, false 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.

top
NumCerts
numCerts: Int (read-only)
Introduced in version 9.5.0.40

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.

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(i).
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.

top
NumPrivateKeys
numPrivateKeys: Int (read-only)
Introduced in version 9.5.0.40

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.

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 and pass the value to CertByLocalKeyId. 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.

top
Pbes2CryptAlg
pbes2CryptAlg: String!
Introduced in version 9.5.0.83

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

ValueCipher
aes256-cbcAES-256 in CBC mode; the default for new PBES2 output.
aes192-cbcAES-192 in CBC mode.
aes128-cbcAES-128 in CBC mode.
3des-cbcTriple DES in CBC mode for compatibility.
PBES2 components: This property chooses the cipher. Pbes2HmacAlg chooses the HMAC-based PBKDF2 pseudorandom function used to derive the encryption key from the password.

More Information and Examples
top
Pbes2HmacAlg
pbes2HmacAlg: String!
Introduced in version 9.5.0.83

Gets or sets the HMAC algorithm used by PBKDF2 when AlgorithmId 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.

More Information and Examples
top
UncommonOptions
uncommonOptions: String!
Introduced in version 9.5.0.83

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.

OptionEffect
LegacyOrderWrites internal PKCS#12 ContentInfo objects in the ordering traditionally used by older Chilkat versions.
NoTruncatePfxPassword64Prevents 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.

top
VerboseLogging
verboseLogging: Bool

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
version: String! (read-only)

Version of the component/library, such as "10.1.0"

More Information and Examples
top

Methods

AddCert
addCert(cert: CkoCert, includeChain: Bool) -> Bool
Introduced in version 9.5.0.44

Adds 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 only. Intermediate and root certificates are not added.
Usable private key; complete chain locatable true Adds the private key, , 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 and certificates made available for chain building, principally through UseCertVault. 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 . 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.

Returns true for success, false for failure.

More Information and Examples
top
AddPrivateKey
addPrivateKey(privKey: CkoPrivateKey, certChain: CkoCertChain) -> Bool
Introduced in version 9.5.0.44

Adds 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 ; 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 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.

Returns true for success, false for failure.

top
CertAt
cert(at: Int, cert: CkoCert) -> Bool
Introduced in version 11.0.0

Copies the certificate at the zero-based index at into cert. The first certificate is at index 0; valid indexes are less than NumCerts.

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 at 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(i). To associate a key with its certificate, obtain the key's localKeyId with GetSafeBagAttr and use CertByLocalKeyId.

Returns true for success, false for failure.

More Information and Examples
top
CertByLocalKeyId
cert(byLocalKeyId: String, encoding: String, cert: CkoCert) -> Bool
Introduced in version 11.0.0

Searches for a certificate whose certificate-bag localKeyId attribute matches byLocalKeyId and copies it into cert. encoding names the binary representation used for byLocalKeyId, 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, byLocalKeyId 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 with byLocalKeyId = true, encoding = i, and cert = localKeyId. That method returns the identifier in decimal representation, so pass the returned value as byLocalKeyId 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.

Returns true for success, false for failure.

More Information and Examples
top
GetLastJsonData
getLastJsonData(json: CkoJsonObject)
Introduced in version 11.0.0

Replaces the entire contents of 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 .

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, is cleared to an empty JSON object.

Destination behavior: The previous contents of 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.

Returns true for success, false for failure.

More Information and Examples
top
GetSafeBagAttr
getSafeBagAttr(forPrivateKey: Bool, index: Int, attrName: String) -> String
Introduced in version 9.5.0.83

Reads a recognized safe-bag attribute from a private key or certificate contained in this PFX. 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 attributeAccepted attrName namesRead behavior
Friendly namefriendlyName, keyContainerName, or keyNameAll 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 providerstorageProvider or msStorageProviderBoth 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 IDlocalKeyIdThe 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 usageenhancedKeyUsageNot readable through this method. The operation reports failure even if the attribute was previously set with SetSafeBagAttr.

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 = true and index = i. If a nonempty value is returned successfully, pass it to CertByLocalKeyId using the encoding decimal. Never assume that certificate index i matches private-key index i.

Returns nil on failure

top
ImportToKeychain
import(toKeychain: CkoJsonObject) -> Bool
Introduced in version 10.0.0

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.

toKeychain 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 toKeychain.

Returns true for success, false for failure.

top
LoadPem
loadPem(pemStr: String, password: String) -> Bool
Introduced in version 9.5.0.47

Loads one or more certificate/private-key identities from the PEM-formatted text in 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 blockMeaning
BEGIN CERTIFICATEAn X.509 certificate.
BEGIN PRIVATE KEYAn unencrypted PKCS #8 private key.
BEGIN ENCRYPTED PRIVATE KEYA password-encrypted PKCS #8 private key.
BEGIN RSA PRIVATE KEYA 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.

Returns true for success, false for failure.

top
LoadPfxBd
loadBd(bd: CkoBinData, password: String) -> Bool
Introduced in version 11.0.0

Loads a PFX / PKCS#12 container from the bytes currently held in . 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 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.

Returns true for success, false for failure.

More Information and Examples
top
LoadPfxBytes
loadBytes(pfxData: NSData, password: String) -> Bool
Introduced in version 9.5.0.40

Loads a PFX / PKCS#12 container from the in-memory bytes in . 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 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.

Returns true for success, false for failure.

top
LoadPfxEncoded
loadEncoded(encodedData: String, encoding: String, password: String) -> Bool
Introduced in version 9.5.0.40

Decodes the text in 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 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.

Returns true for success, false for failure.

top
LoadPfxFile
loadFile(path: String, password: String) -> Bool
Introduced in version 9.5.0.40

Loads a PFX / PKCS#12 container from the file path in . password follows the password contract below. The same contract is used by LoadPfxBytes, LoadPfxBd, and LoadPfxEncoded; it does not apply to LoadPem.

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
}
MemberAccepted valueDefault when omitted
integrityStringIntegrity verification is skipped.
privKeysStringThe empty string is used as the password for every private-key bag.
skipPrivateKeysJSON Boolean true, or a string equal to true without regard to casefalse

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.

Returns true for success, false for failure.

top
PrivateKeyAt
privateKey(at: Int, privKey: CkoPrivateKey) -> Bool
Introduced in version 11.0.0

Copies the private key at the zero-based index at into privKey. The first private key is at index 0; valid indexes are less than NumPrivateKeys.

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 at 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(i).
Finding the matching certificate: Call GetSafeBagAttr with at 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 using decimal as the encoding.
Sensitive material: Treat privKey as secret key material. Avoid unnecessary serialization, logging, or long-lived copies.

Returns true for success, false for failure.

More Information and Examples
top
SetSafeBagAttr
setSafeBagAttr(forPrivateKey: Bool, index: Int, name: String, value: String, encoding: String) -> Bool
Introduced in version 9.5.0.83

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.

  • 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 attributeAccepted name namesValue and behavior
Friendly namefriendlyName, keyContainerName, or keyNameThese 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 providerstorageProvider or msStorageProviderThe two names refer to the same underlying text attribute. value is stored as text, and encoding is ignored.
Local key IDlocalKeyIdA 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 usageenhancedKeyUsagevalue 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.

Returns true for success, false for failure.

top
ToBd
toBd(password: String, bd: CkoBinData) -> Bool
Introduced in version 11.0.0

Serializes the current PFX contents as PKCS#12 data and writes the bytes to bd, using 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 AlgorithmId 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.

Returns true for success, false for failure.

More Information and Examples
top
ToBinary
toBinary(password: String) -> NSData
Introduced in version 9.5.0.44

Serializes the current PFX contents to PKCS#12 bytes in memory, using as the output password.

The private-key protection scheme is selected by AlgorithmId and, when PBES2 is selected, by Pbes2CryptAlg and Pbes2HmacAlg.

Protect the output: The returned bytes may contain private keys. Use a strong password, limit access to the data, and clear unnecessary copies from memory when practical.

Returns nil on failure

top
ToEncodedString
toEncodedString(password: String, encoding: String) -> String
Introduced in version 9.5.0.44

Serializes the current PFX contents using 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 AlgorithmId 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.

Returns nil on failure

top
ToFile
toFile(password: String, path: String) -> Bool
Introduced in version 9.5.0.44

Serializes the current PFX contents and writes the resulting PKCS#12 data to path, using as the output password.

.pfx and .p12 are the conventional filename extensions for PKCS#12 containers. The private-key protection scheme is controlled by AlgorithmId 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.

Returns true for success, false for failure.

top
ToJksObj
toJksObj(alias: String, password: String, jksObj: CkoJavaKeyStore) -> Bool
Introduced in version 11.0.0

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 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.

Returns true for success, false for failure.

More Information and Examples
top
ToPem
toPem() -> String
Introduced in version 9.5.0.47

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 to produce encrypted PKCS #8 private-key blocks or to omit selected categories of objects.

Returns nil on failure

top
ToPemEx
toPemEx(extendedAttrs: Bool, noKeys: Bool, noCerts: Bool, noCaCerts: Bool, encryptAlg: String, password: String) -> String
Introduced in version 9.5.0.49

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:

ArgumentEffect
When true, emits OpenSSL-style bag and key attribute text in addition to the PEM blocks.
noKeysWhen true, omits private-key blocks.
noCertsWhen true, omits all certificate blocks.
noCaCertsWhen true, omits intermediate and root CA certificates while retaining applicable end-entity certificates.
encryptAlgSelects 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.
passwordThe 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.

Returns nil on failure

top
UseCertVault
useCertVault(vault: CkoXmlCertVault) -> Bool
Introduced in version 9.5.0.44

Adds the certificates currently contained in to the set of certificate sources available for later chain-building operations, such as AddCert.

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, 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 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.

Returns true for success, false for failure.

More Information and Examples
top

Deprecated

FindCertByLocalKeyId
findCert(byLocalKeyId: String, encoding: String) -> CkoCert
Introduced in version 9.5.0.83
This method is deprecated and replaced by CertByLocalKeyId

Deprecated. Use CertByLocalKeyId instead.

Searches for a certificate whose certificate-bag localKeyId attribute matches the binary value supplied in byLocalKeyId. encoding names the representation used for byLocalKeyId, such as decimal, base64, or hex.

Certificate/key association: When byLocalKeyId was obtained from GetSafeBagAttr using the attribute name localKeyId, pass decimal for encoding. This lookup is the reliable way to find a key's matching certificate; collection indexes do not correspond.

Returns nil on failure

top
GetCert
getCert(index: Int) -> CkoCert
Introduced in version 9.5.0.40
This method is deprecated and replaced by CertAt

Deprecated. Use CertAt instead.

Returns the certificate at the zero-based index specified by . The first certificate is at index 0. An invalid index causes the method to fail and return no object.

Do not pair by index: Certificate indexes and private-key indexes are independent. GetCert(i) is not necessarily the certificate associated with GetPrivateKey(i). Use a matching localKeyId when one is present.

Returns nil on failure

top
GetPrivateKey
getPrivateKey(index: Int) -> CkoPrivateKey
Introduced in version 9.5.0.40
This method is deprecated and replaced by PrivateKeyAt

Deprecated. Use PrivateKeyAt instead.

Returns the private key at the zero-based index specified by . The first private key is at index 0. An invalid index causes the method to fail and return no object.

Do not pair by index: Private-key indexes and certificate indexes are independent. GetPrivateKey(i) is not necessarily associated with GetCert(i). Use the private key's localKeyId and CertByLocalKeyId when that attribute is present.
Sensitive material: A returned PrivateKey object contains secret key material. Avoid logging, displaying, or exporting it unless the application explicitly requires that operation.

Returns nil on failure

top
LastJsonData
lastJsonData() -> CkoJsonObject
Introduced in version 9.5.0.83
This method is deprecated.

Deprecated. Use GetLastJsonData instead.

Returns structured JSON information produced by the most recent operation that generated such data. The exact JSON members depend on the preceding method.

Returns nil on failure

top
ToJavaKeyStore
toJavaKeyStore(alias: String, password: String) -> CkoJavaKeyStore
Introduced in version 9.5.0.44
This method is deprecated and replaced by ToJksObj

Deprecated. Use ToJksObj instead.

Creates a Java KeyStore object with one private-key entry for each private key in this PFX. Certificates in the PFX are used to construct the certificate chain for each entry. password is used to protect the generated private-key entries.

If is nonempty, it is used as the alias for the first private key. Otherwise, the alias is chosen using the following order:

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

Additional private keys receive automatically selected aliases using the same preference order.

Returns nil on failure

top