Chilkat.PrivateKey Class Overview
Chilkat.PrivateKey represents a private key and provides methods for loading, exporting, saving, converting, inspecting, and uploading private keys. It supports common private-key formats including PKCS#1, PKCS#8, encrypted PKCS#8, PEM, encrypted PEM, JWK, XML, PVK, raw Ed25519/ECDSA key material, and general “load any format” workflows.
What the Class Is Used For
Use Chilkat.PrivateKey when an application needs to import, export, convert, persist, or inspect private keys used by other Chilkat cryptographic classes. It can load keys from files or memory, export them in binary DER, PEM, JWK, XML, or raw hex formats, save them to files, derive the public key, and upload private-key material to cloud key services such as AWS KMS or Azure Key Vault.
Load Many Formats
Load private keys from PKCS#1, PKCS#8, encrypted PKCS#8, PEM, encrypted PEM,
JWK, XML, PVK, and other recognized formats.
Export and Convert
Export private keys as DER, PEM, encrypted PEM, JWK, XML, raw hex, or encoded
strings such as Base64 or hex.
Support Multiple Key Types
Work with RSA, DSA, ECC/ECDSA, and Ed25519 private keys.
Integrate with Other Classes
Pass private keys to classes such as Rsa,
Ecc, signing classes, certificate workflows, and
cloud-key upload workflows.
Typical Workflow
- Load a private key from memory or file using LoadAnyFormat, LoadAnyFormatFile, or a format-specific Load* method.
- Check KeyType and BitLength to confirm the key was loaded as expected.
- Use ToPublicKey when the corresponding public key is needed.
- Export the key in the desired format using methods such as GetPkcs8Pem, GetPkcs8EncryptedPem, GetJwk, or GetXml.
- Save the key to disk with SavePkcs8File, SavePkcs8PemFile, SavePkcs8EncryptedFile, or another save method.
- For encrypted PKCS#8 output, set Pkcs8EncryptAlg before exporting or saving.
- Check LastErrorText after any failed load, export, save, conversion, or upload operation.
Core Concepts
| Concept | Meaning | Important Members |
|---|---|---|
| Private Key Object | Holds a loaded or generated private key in memory so it can be exported, saved, converted, or used by other Chilkat classes. | LoadAnyFormat, LoadAnyFormatFile, KeyType |
| Key Type | Identifies the private-key algorithm. | KeyType: rsa, dsa, ecc, ed25519 |
| DER vs PEM | DER is binary ASN.1. PEM is Base64 text with header and footer lines. | GetPkcs8, GetPkcs8Pem, LoadPem |
| PKCS#1 vs PKCS#8 | PKCS#1 is commonly associated with RSA private-key structure. PKCS#8 is a general private-key container format for multiple algorithms. | GetPkcs1, GetPkcs8, LoadPkcs8 |
| Encrypted PKCS#8 | A password-protected PKCS#8 private-key format. | GetPkcs8Encrypted, LoadPkcs8Encrypted, Pkcs8EncryptAlg |
| JWK | JSON Web Key format for representing RSA, ECC, and Ed25519 private keys in JSON. | LoadJwk, GetJwk, GetJwkThumbprint |
Core Properties
| Property | Purpose | Guidance |
|---|---|---|
| BitLength | Returns the bit length, or strength, of the private key. | Useful for confirming expected key size after loading or generating a key. |
| KeyType | Returns the private-key type. | Can be empty, rsa, dsa, ecc, or ed25519. |
| Pkcs8EncryptAlg | Selects the encryption algorithm used when exporting encrypted PKCS#8. | Default is 3des. Other choices include aes128, aes192, and aes256. All use CBC mode. |
| UncommonOptions | Catch-all property for uncommon needs. | Defaults to the empty string and should typically remain empty. |
| 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 Private Keys
| Input Format | Memory Method | File Method |
|---|---|---|
| Any recognized format | LoadAnyFormat | LoadAnyFormatFile |
| Unencrypted PEM | LoadPem | LoadPemFile |
| Encrypted PEM | LoadEncryptedPem | LoadEncryptedPemFile |
| PKCS#1 DER | LoadPkcs1 | LoadPkcs1File |
| PKCS#8 DER | LoadPkcs8 | LoadPkcs8File |
| Encrypted PKCS#8 DER | LoadPkcs8Encrypted | LoadPkcs8EncryptedFile |
| JWK | LoadJwk | Use file read + LoadJwk, or use LoadAnyFormatFile. |
| PVK | LoadPvk | LoadPvkFile |
| XML | LoadXml | LoadXmlFile |
| Raw Ed25519 key pair | LoadEd25519 | Not applicable. |
Auto-recognition:
The documentation notes that the private-key load methods auto-recognize content
and parse appropriately. In many cases, a key can still load successfully even if
the content is passed to a method whose name suggests a different format.
PEM and DER Format Guide
| Format | Typical PEM Header | Purpose |
|---|---|---|
| PKCS#1 PEM | -----BEGIN RSA PRIVATE KEY----- | Common unencrypted RSA private-key PEM format. |
| PKCS#8 PEM | -----BEGIN PRIVATE KEY----- | General unencrypted private-key container format. |
| Encrypted PKCS#8 PEM | -----BEGIN ENCRYPTED PRIVATE KEY----- | Password-protected PKCS#8 private-key format. |
| DER | Binary data, no PEM header. | Binary ASN.1 representation used by PKCS#1, PKCS#8, and encrypted PKCS#8. |
Encrypted PEM loading:
Use LoadEncryptedPem or
LoadEncryptedPemFile when the PEM contains an
encrypted private key. Use LoadPem for unencrypted
PKCS#1 or PKCS#8 PEM.
Exporting Private Keys
| Output Format | Binary / Encoded Method | PEM / Text Method |
|---|---|---|
| JWK | Not applicable. | GetJwk, GetJwkThumbprint |
| PKCS#1 DER | GetPkcs1, GetPkcs1ENC | GetPkcs1Pem |
| PKCS#8 DER | GetPkcs8, GetPkcs8ENC | GetPkcs8Pem |
| Encrypted PKCS#8 DER | GetPkcs8Encrypted, GetPkcs8EncryptedENC | GetPkcs8EncryptedPem |
| PKCS#1 or PKCS#8 into BinData | GetPkcsBd | Not applicable. |
| Raw Ed25519 / ECDSA hex | Not applicable. | GetRawHex |
| XML | Not applicable. | GetXml |
Encoded output:
Methods ending in ENC return binary key data as text
using the requested encoding, such as base64 or
hex.
Saving Private Keys
| Saved Format | Method | Notes |
|---|---|---|
| Unencrypted PKCS#1 PEM | SavePemFile | Saves the key to an unencrypted PKCS#1 PEM file. |
| Unencrypted PKCS#1 DER | SavePkcs1File | Saves binary PKCS#1 private-key data. |
| Unencrypted PKCS#8 DER | SavePkcs8File | Saves binary PKCS#8 private-key data. Starting in Chilkat v10.0.0 on macOS, keychain:<label> can be used to save to Apple Keychain. |
| Unencrypted PKCS#8 PEM | SavePkcs8PemFile | Saves a PKCS#8 PEM file. |
| Encrypted PKCS#8 DER | SavePkcs8EncryptedFile | Saves password-protected PKCS#8 DER. Encryption is controlled by Pkcs8EncryptAlg. |
| Encrypted PKCS#8 PEM | SavePkcs8EncryptedPemFile | Saves password-protected PKCS#8 PEM. Encryption is controlled by Pkcs8EncryptAlg. |
| XML | SaveXmlFile | Saves the private key in XML format. |
Encrypted PKCS#8 Options
| Property / Method | Purpose | Details |
|---|---|---|
| Pkcs8EncryptAlg | Chooses the encryption algorithm for encrypted PKCS#8 export. | Default is 3des. Also supports aes128, aes192, and aes256. All choices use CBC mode. |
| GetPkcs8Encrypted | Exports encrypted PKCS#8 DER as bytes. | Requires a password. |
| GetPkcs8EncryptedENC | Exports encrypted PKCS#8 DER as encoded text. | Requires an encoding and password. |
| GetPkcs8EncryptedPem | Exports encrypted PKCS#8 as PEM text. | Requires a password. |
| SavePkcs8EncryptedFile | Saves encrypted PKCS#8 DER to a file. | Requires a password and path. |
| SavePkcs8EncryptedPemFile | Saves encrypted PKCS#8 PEM to a file. | Requires a password and path. |
Best practice:
Use encrypted PKCS#8 when saving private keys to disk unless the application has a
specific reason to write an unencrypted private key.
JWK and JWK Thumbprints
| Method | Purpose | Supported Key Types |
|---|---|---|
| LoadJwk | Loads a private key from a JSON Web Key string. | RSA, ECC, and Ed25519 JWK examples are documented. |
| GetJwk | Exports the private key in JWK format. | RSA, ECC, and Ed25519. |
| GetJwkThumbprint | Returns the JWK thumbprint for the private key according to RFC 7638. | Hash algorithm is specified by the hashAlg argument. |
JWK structure:
RSA JWKs include values such as n,
e, d,
p, and q. ECC JWKs
include crv, x,
y, and d. Ed25519 JWKs
use kty: OKP and
crv: Ed25519.
Raw Hex Export for Ed25519 and ECDSA
| Method | Private Key Output | Public Key Output |
|---|---|---|
| GetRawHex | Returns the private key in lowercase raw hex. | Writes the public key to the supplied StringBuilder. |
Applicability:
GetRawHex applies only to Ed25519 and ECDSA keys.
RSA keys cannot be returned as a simple raw hex string because an RSA private key
is composed of multiple parts, including modulus, exponent, primes, and other
values.
Raw key details:
Ed25519 private and public keys are 32 bytes each, or 64 hex characters. For EC
keys, the private key length depends on the curve, and the public key is formatted
as 04 || HEX(x) || HEX(y).
Public Key Extraction
| Method | Purpose | Use Case |
|---|---|---|
| ToPublicKey | Extracts the public-key portion of the private key into a PublicKey object. | Use when the private key is loaded and the corresponding public key is needed for verification, encryption, publication, or comparison. |
Cloud Upload
| Method | Purpose | Inputs / Outputs |
|---|---|---|
| UploadToCloud | Uploads the private key to a cloud service, such as AWS KMS or Azure Key Vault. | Uses a JsonObject for input options and a JsonObject for output results. |
Open-ended design:
UploadToCloud is intentionally flexible so cloud-key
upload details can be supplied through JSON.
Method Summary by Category
| Category | Methods | Purpose |
|---|---|---|
| General loading | LoadAnyFormat, LoadAnyFormatFile | Load private keys from many recognized formats with optional password. |
| Format-specific loading | LoadPem, LoadEncryptedPem, LoadPkcs1, LoadPkcs8, LoadPkcs8Encrypted, LoadJwk, LoadPvk, LoadXml, LoadEd25519 | Load keys from a known format or key representation. |
| DER / PEM export | GetPkcs1, GetPkcs1Pem, GetPkcs8, GetPkcs8Pem, GetPkcs8Encrypted, GetPkcs8EncryptedPem | Export private keys in common binary or PEM formats. |
| Encoded export | GetPkcs1ENC, GetPkcs8ENC, GetPkcs8EncryptedENC | Return DER key data as encoded text. |
| JWK / XML / raw export | GetJwk, GetJwkThumbprint, GetXml, GetRawHex | Export private keys in JSON, XML, or raw key formats. |
| Saving to files | SavePemFile, SavePkcs1File, SavePkcs8File, SavePkcs8PemFile, SavePkcs8EncryptedFile, SavePkcs8EncryptedPemFile, SaveXmlFile | Persist the private key to disk, Apple Keychain, or XML. |
| Conversion / integration | ToPublicKey, UploadToCloud | Extract the public key or upload the private key to a cloud service. |
Diagnostics and Troubleshooting
| Problem Area | Member | What to Check |
|---|---|---|
| Key load failed | LastErrorText | Check the password, file path, input bytes, PEM text, and whether the key is encrypted. |
| Wrong key type after loading | KeyType | Confirm whether the loaded key is rsa, dsa, ecc, or ed25519. |
| Unexpected key strength | BitLength | Check the bit length after loading to ensure the expected key was imported. |
| Encrypted PKCS#8 output uses unexpected algorithm | Pkcs8EncryptAlg | Set Pkcs8EncryptAlg before calling encrypted PKCS#8 export or save methods. |
| Raw hex export fails | GetRawHex | Confirm the key is Ed25519 or ECDSA. RSA keys cannot be represented in this simple raw format. |
| Public key extraction fails | ToPublicKey, LastErrorText | Confirm the private key is valid and fully loaded. |
| Cloud upload fails | UploadToCloud, jsonIn, jsonOut | Inspect input JSON, output JSON, and LastErrorText for service-specific details. |
Common Pitfalls
| Pitfall | Better Approach |
|---|---|
| Using LoadPem for encrypted PEM. | Use LoadEncryptedPem or LoadEncryptedPemFile and provide the password. |
| Assuming PKCS#1 is the right output format for every key type. | Use PKCS#8 for a general private-key container format, especially when working with multiple key algorithms. |
| Saving private keys unencrypted without considering security requirements. | Prefer encrypted PKCS#8 output when storing private keys on disk. |
| Trying to export an RSA key using GetRawHex. | Use PKCS#1, PKCS#8, PEM, JWK, or XML for RSA keys. |
| Forgetting to set Pkcs8EncryptAlg before encrypted export. | Set it before calling encrypted PKCS#8 methods when a specific encryption algorithm is required. |
| Ignoring KeyType after using auto-recognition. | Confirm the loaded key type before passing the key to RSA, ECC, Ed25519, or other algorithm-specific operations. |
Best Practices
| Recommendation | Reason |
|---|---|
| Use LoadAnyFormat or LoadAnyFormatFile for flexible imports. | These methods are convenient when the key format may vary. |
| Check KeyType and BitLength after loading. | This confirms the key type and strength before using the key. |
| Use encrypted PKCS#8 for persisted private keys. | It provides password protection and supports multiple private-key types. |
| Set Pkcs8EncryptAlg explicitly when policy requires AES. | The default is 3des, while AES options include aes128, aes192, and aes256. |
| Use ToPublicKey instead of manually parsing key material. | It directly extracts the public-key portion into a PublicKey object. |
| Use JWK for JSON-based protocols and PKCS#8/PEM for general interoperability. | These formats are common in web, API, certificate, and cryptographic toolchain workflows. |
| Keep UncommonOptions empty unless a specific need exists. | It is intended as a catch-all for uncommon behavior and normally should not be used. |
| Check LastErrorText after failures. | It provides the most useful diagnostic detail for loading, parsing, exporting, saving, conversion, and cloud-upload operations. |
Summary
Chilkat.PrivateKey is the central Chilkat class for handling private-key material. It loads private keys from many formats, exports them to PKCS#1, PKCS#8, encrypted PKCS#8, PEM, JWK, XML, raw Ed25519/ECDSA hex, and encoded strings, saves them to files, extracts the corresponding public key, and supports cloud-key upload workflows.
The most important practical guidance is to load flexibly, verify the resulting KeyType and BitLength, and use encrypted PKCS#8 when storing private keys outside protected key stores.