Chilkat.Pem Class Overview

Chilkat.Pem represents a collection of PEM items such as certificates, private keys, public keys, certificate signing requests, and CRLs. It can load PEM or PKCS#7 .p7b data, add certificate and key objects, retrieve individual items, remove items, control PEM output formats, export to PEM, convert to PFX/PKCS#12, and convert to a Java KeyStore object.

What the Class Is Used For

Use Chilkat.Pem when an application needs to parse, build, convert, or inspect PEM-formatted cryptographic material. A PEM can contain one or more items, including certificates, certificate chains, private keys, public keys, CSRs, and CRLs. The class is especially useful for converting between PEM, PFX/PKCS#12, PKCS#7 certificate bundles, and Java KeyStore workflows.

Load PEM and P7B Load PEM strings, PEM files, in-memory PKCS#7 containers, or .p7b/.p7c files.
Collect Certs and Keys Add certificates, private keys, public keys, CSRs, certificate chains, and PKCS#7 certificate bundles.
Retrieve and Remove Items Access certificates, private keys, public keys, encoded item data, or remove selected certs and private keys.
Convert Formats Export PEM, create a PFX/PKCS#12 object, or convert to a Java KeyStore object.

Typical Workflow

  1. Create a Pem object.
  2. Decide whether loading should replace existing contents or append to them by setting AppendMode.
  3. Load content with LoadPem, LoadPemFile, LoadP7b, or LoadP7bFile, or add items manually with AddCert, AddPrivateKey, AddPublicKey, or AddItem.
  4. Inspect item counts with NumCerts, NumPrivateKeys, NumPublicKeys, NumCsrs, and NumCrls.
  5. Retrieve specific objects with CertAt, PrivateKeyAt, or PublicKeyAt.
  6. Configure output with PrivateKeyFormat, PublicKeyFormat, or ToPemEx options.
  7. Export with ToPem or ToPemEx, convert to PFX with ToPfxObj, or convert to JKS with ToJksObj.
  8. Check LastErrorText after failures or unexpected behavior.

Core Concepts

Concept Meaning Important Members
PEM Container Holds one or more PEM items, such as certificates, keys, CSRs, and CRLs. LoadPem, ToPem, Clear
PEM Item Types Items can include certificates, private keys, public keys, and certificate signing requests. AddItem, GetEncodedItem, NumCerts
Append vs Replace Loading Load methods either append to existing contents or replace them, depending on AppendMode. AppendMode, LoadPem, LoadPemFile
Private/Public Key Output Format Controls whether unencrypted private keys and public keys are written in PKCS#1 or PKCS#8 PEM format. PrivateKeyFormat, PublicKeyFormat
PKCS#7 Certificate Bundle A .p7b or .p7c file may contain certificates and optional CRLs, but no private key. AddP7b, LoadP7b, LoadP7bFile
Format Conversion PEM content can be converted to PFX/PKCS#12 or Java KeyStore objects. ToPfxObj, ToJksObj

Core Properties

Property Purpose Guidance
AppendMode Controls whether Load* methods append to or replace the current PEM contents. Default is false, meaning load methods replace current contents. Set to true to accumulate items from multiple loads.
HeartbeatMs Interval in milliseconds between AbortCheck event callbacks. Default is 0, meaning no callbacks. Use when long-running operations should be abortable by the application.
NumCerts Number of certificates in the loaded PEM. Use CertAt(0) to retrieve the first certificate.
NumPrivateKeys Number of private keys in the loaded PEM. Use PrivateKeyAt(0) to retrieve the first private key.
NumPublicKeys Number of public keys in the loaded PEM. Use PublicKeyAt(0) to retrieve the first public key.
NumCsrs Number of certificate signing requests in the loaded PEM. Useful for PEM data containing CSR blocks.
NumCrls Number of certificate revocation lists in the loaded PEM. Useful after loading PEM or PKCS#7 data that includes CRLs.
PrivateKeyFormat Controls the format used for unencrypted private keys when writing PEM. Possible values are pkcs1 and pkcs8. Default is pkcs8. Encrypted private-key PEM is always PKCS#8.
PublicKeyFormat Controls the format used for public keys when writing PEM. Possible values are pkcs1 and pkcs8. Default is pkcs8.
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.

PEM Headers and Key Formats

Item Format Setting PEM Header Notes
Unencrypted private key PrivateKeyFormat = pkcs1 BEGIN RSA PRIVATE KEY PKCS#1 private-key output.
Unencrypted private key PrivateKeyFormat = pkcs8 BEGIN PRIVATE KEY Default private-key output. OpenSSL typically uses PKCS#8.
Encrypted private key Always PKCS#8 BEGIN ENCRYPTED PRIVATE KEY When writing encrypted private keys, the output format is always PKCS#8.
Public key PublicKeyFormat = pkcs1 BEGIN RSA PUBLIC KEY PKCS#1 public-key output.
Public key PublicKeyFormat = pkcs8 BEGIN PUBLIC KEY Default public-key output. OpenSSL typically uses PKCS#8.

Loading PEM and PKCS#7 Data

Input Source Method Behavior
PEM string LoadPem Loads PEM content from a string. If encrypted, the password is required for decryption. Otherwise, an empty string or any string may be passed.
PEM file LoadPemFile Loads PEM content from a file. If encrypted, the password is required.
PKCS#7 bytes LoadP7b Loads an in-memory PKCS#7 container, commonly a .p7b certificate bundle.
PKCS#7 file LoadP7bFile Loads the contents of a .p7b file.
Async task result LoadTaskCaller Loads the caller of the task's async method.
Append behavior: If AppendMode is true, each Load* method appends to existing PEM contents. If false, loading replaces the current contents.

Adding Items to a PEM

Item to Add Method Notes
Certificate AddCert Adds a certificate and optionally its chain of authentication up to and including the root.
Private key AddPrivateKey Adds a private key to the PEM object.
Private key with certificate chain AddPrivateKey2 Adds a private key and its associated certificate chain.
Public key AddPublicKey Adds a public key to the PEM object.
Generic encoded item AddItem Adds a certificate, private key, public key, or CSR from encoded ASN.1 data.
PKCS#7 certificate bundle AddP7b Loads certificates and optional CRLs from a PKCS#7 container held in BinData.
PKCS#7 / P7B note: A .p7b or .p7c file can contain one or more X.509 certificates and optionally CRLs. It does not contain a private key.

AddItem and GetEncodedItem

Method Purpose Key Arguments
AddItem Adds an encoded ASN.1 item to the PEM. itemType can be certificate / cert, privateKey, publicKey, or csr.
GetEncodedItem Returns encoded contents of the Nth item of a specified type. itemType is case-insensitive. itemSubType may be der or pkcs8 for private keys, and der or pkcs1 for public keys.
Encoding choices: Supported encodings include Base64, modBase64, Base32, Base58, QP, URL, Hex, url_oauth, url_rfc1738, url_rfc2396, and url_rfc3986, depending on the method.

Inspecting and Retrieving Items

Need Method / Property Behavior
Count certificates NumCerts Returns the number of certificates in the loaded PEM.
Count private keys NumPrivateKeys Returns the number of private keys in the loaded PEM.
Count public keys NumPublicKeys Returns the number of public keys in the loaded PEM.
Count CSRs NumCsrs Returns the number of certificate signing requests in the loaded PEM.
Count CRLs NumCrls Returns the number of certificate revocation lists in the loaded PEM.
Get certificate CertAt Returns the Nth certificate into a supplied Cert object. The first certificate is index 0.
Get private key PrivateKeyAt Returns the Nth private key into a supplied PrivateKey object. The first private key is index 0.
Get public key PublicKeyAt Returns the Nth public key into a supplied PublicKey object. The first public key is index 0.
Get encoded item data GetEncodedItem Returns an encoded representation of a selected certificate, private key, public key, or CSR.

Removing and Clearing Content

Task Method Behavior
Clear all PEM content Clear Removes all content from the PEM object.
Remove certificate RemoveCert Removes the Nth certificate. The first certificate is index 0.
Remove private key RemovePrivateKey Removes the Nth private key. The first private key is index 0.

Exporting PEM

Output Method Behavior
Standard PEM string ToPem Returns PEM-formatted text containing the private key and available certificates.
PEM string with options ToPemEx Returns PEM-formatted text with options for extended attributes, omitting keys, omitting certificates, omitting CA certificates, and encrypting private keys.
Output format properties: PrivateKeyFormat and PublicKeyFormat affect how unencrypted private keys and public keys are written in PEM output.

ToPemEx Options

Argument Purpose Notes
extendedAttrs Emits Bag Attributes and Key Attributes. Useful when preserving or inspecting metadata from certificate/key bundles.
noKeys Omits private keys. Use when exporting certificates only.
noCerts Omits certificates. Use when exporting private keys only.
noCaCerts Omits CA and intermediate CA certificates. Useful when the output should exclude chain certificates.
encryptAlg Encrypts private keys in the PEM output. Possible values are des3, aes128, aes192, and aes256. All use CBC mode.
password Password used for encrypted private-key output. Leave empty when private keys are not encrypted.

Converting to PFX / PKCS#12

Method Purpose Requirement
ToPfxObj Converts this PEM object to a Pfx object. The PEM must contain at least one private key. A typical PKCS#12 file includes one private key, its associated certificate, and the certificate chain.
Typical conversion: Use ToPfxObj when PEM material containing a private key and certificate chain needs to be packaged as PFX/PKCS#12.

Converting to Java KeyStore

Method Purpose Alias and Password Behavior
ToJksObj Converts this PEM object to a JavaKeyStore object. If an alias is provided, it is used for the first object in the PEM, either a private key or certificate. Subsequent objects receive autogenerated aliases. The JKS is encrypted with the supplied password unless the PEM contains only certificates, in which case the password is not used.

Method Summary by Category

Category Methods Purpose
Load PEM / P7B LoadPem, LoadPemFile, LoadP7b, LoadP7bFile, LoadTaskCaller Load PEM content, encrypted PEM content, PKCS#7 certificate bundles, or async task results.
Add items AddCert, AddItem, AddP7b, AddPrivateKey, AddPrivateKey2, AddPublicKey Add certificates, chains, keys, CSRs, encoded ASN.1 data, or PKCS#7 bundle contents.
Inspect contents CertAt, PrivateKeyAt, PublicKeyAt, GetEncodedItem Retrieve objects or encoded item data from the PEM.
Remove / clear RemoveCert, RemovePrivateKey, Clear Remove selected items or clear all content.
Export PEM ToPem, ToPemEx Write PEM-formatted text, with optional output controls and private-key encryption.
Convert formats ToPfxObj, ToJksObj Convert PEM content to PFX/PKCS#12 or Java KeyStore objects.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Load failed LoadPem, LoadPemFile, LastErrorText Check the PEM text, file path, password for encrypted items, and whether the input contains valid PEM blocks.
Loaded content replaced previous items AppendMode Set AppendMode = true before loading when new content should be appended rather than replacing current content.
Expected private key is missing NumPrivateKeys Confirm the PEM contains a private-key block. A .p7b file does not contain private keys.
Expected certificates are missing NumCerts Confirm certificate blocks are present, or that the PKCS#7 bundle actually contains certificates.
Conversion to PFX fails ToPfxObj Confirm the PEM contains at least one private key and the corresponding certificate material.
Unexpected key header in PEM output PrivateKeyFormat, PublicKeyFormat Set the desired format to pkcs1 or pkcs8 before exporting.
Long-running operation needs abort support HeartbeatMs Set a heartbeat interval so the application can receive AbortCheck event callbacks.

Common Pitfalls

Pitfall Better Approach
Expecting multiple loads to accumulate items by default. Set AppendMode = true if each load should append to the existing PEM contents.
Expecting a .p7b file to contain a private key. Remember that PKCS#7 certificate bundles may contain certificates and CRLs, but no private keys.
Trying to convert a PEM with only certificates to PFX. ToPfxObj requires at least one private key.
Using the wrong output key format for another tool. Set PrivateKeyFormat or PublicKeyFormat to pkcs1 or pkcs8 as required.
Assuming encrypted private-key output can be PKCS#1. Encrypted private keys are always written as PKCS#8 with BEGIN ENCRYPTED PRIVATE KEY.
Providing the wrong password for encrypted PEM input. Pass the required password to LoadPem or LoadPemFile. For unencrypted PEM, an empty string is acceptable.

Best Practices

Recommendation Reason
Check item counts after loading. NumCerts, NumPrivateKeys, NumPublicKeys, NumCsrs, and NumCrls confirm what the PEM contains.
Use AppendMode intentionally. It prevents accidental replacement when combining PEM material from multiple sources.
Use AddCert(includeChain=true) when a PEM should include the certificate chain. This adds the certificate and its chain of authentication up to and including the root when available.
Use ToPemEx for controlled PEM output. It allows omitting keys, certificates, CA certificates, emitting extended attributes, and encrypting private keys.
Use ToPfxObj when PEM material must become PKCS#12. PFX/PKCS#12 is commonly used to package a private key, certificate, and certificate chain.
Use ToJksObj for Java interoperability. It converts PEM content to a Java KeyStore object with aliases and optional password protection.
Check LastErrorText after failures. It provides the most useful diagnostic detail for loading, parsing, adding, removing, exporting, and conversion operations.

Summary

Chilkat.Pem is the Chilkat class for handling PEM-formatted certificate and key material. It can load PEM and PKCS#7 data, add certificates, private keys, public keys, CSRs, and certificate chains, retrieve individual items, remove content, control PKCS#1 vs PKCS#8 output, export PEM with optional encryption and extended attributes, and convert PEM material to PFX or Java KeyStore objects.

The most important practical guidance is to check item counts after loading, use AppendMode intentionally, remember that .p7b files do not contain private keys, and choose PKCS#1 or PKCS#8 output formats based on the expectations of the receiving tool or system.