PrivateKey Rust Reference Documentation

PrivateKey

Current Version: 11.6.1

PrivateKey

Load, inspect, export, save, and convert one private key.

PrivateKey is a key-container class. It holds one current RSA, DSA, EC, or Ed25519 private key and provides format conversion, persistence, JWK/XML access, raw EC and Ed25519 access, and public-key extraction. Cryptographic operations such as signing, decryption, TLS authentication, and SSH authentication are performed by other Chilkat classes that receive the loaded PrivateKey.

Content-based loading

Named load methods inspect the content and recognize supported unencrypted formats. Password-taking loaders also recognize encrypted PKCS #8 and unencrypted input.

Standard export choices

Use PKCS #8 for modern algorithm-independent interchange, encrypted PKCS #8 for password-protected storage, JWK for JOSE, and traditional PEM only when required by a legacy consumer.

One-key state

A successful load replaces the current key. A failed load leaves the object empty. Check KeyType and BitLength after loading when the expected algorithm matters.

Independent public key

ToPublicKey creates an independent PublicKey that is unaffected when this object is reloaded with another key.

Key generation

Generate new keys with Rsa, Ecc, or EdDSA, which can place the generated key into a PrivateKey.

Certificates are separate

A private key does not contain a certificate or chain. Use Cert or Pfx when certificate association is required.

Recommended format selection: Prefer unencrypted PKCS #8 for transient interchange, encrypted PKCS #8 with aes256 and a strong password for stored key files, JWK for JWT/JWS/JWE workflows, and traditional RSA or EC PEM only when the receiving software requires it.
Protect private material: Base64, hexadecimal, PEM, JWK, and XML are encodings or containers, not encryption. Avoid exporting a private key unless necessary, and protect every unencrypted representation as sensitive data.

For an extended overview, see PrivateKey Class Overview.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::PrivateKey;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let private_key = PrivateKey::new();
// ... the native object is freed when `private_key` goes out of scope.
pub fn new() -> PrivateKey

Creates the underlying native Chilkat object (PrivateKey also implements Default). Every method takes &self, so the object never needs to be declared mut. A PrivateKey is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for PrivateKey

The native object is freed when the PrivateKey is dropped — when it goes out of scope, or explicitly with drop(private_key). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<PrivateKey>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match private_key.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

BitLength
// read-only
pub fn bit_length(&self) -> i32
Introduced in version 9.5.0.49

Returns the nominal size of the loaded private key, in bits. The value is 0 when the object is empty. For RSA it is the modulus size; for DSA it is the size of p; for EC it is the named-curve field size; and for Ed25519 it is 256.

Comparing strength: Bit lengths are meaningful only within the context of the algorithm. A 256-bit EC key and a 256-bit RSA key do not provide comparable security.

top
DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

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
Example showing how to use DebugLogFilePath.
top
KeyType
// read-only
pub fn key_type(&self) -> String
Introduced in version 9.5.0.52

Identifies the algorithm of the currently loaded key. The value is one of empty, rsa, dsa, ecc, or ed25519. empty means that no usable private key is loaded.

One-key state model: A PrivateKey object holds one current key. Loading another key replaces it; a failed load leaves the object empty.

top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

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
// read-only
pub fn last_error_text(&self) -> String

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.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> String

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
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: 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
Pkcs8EncryptAlg
// read/write
pub fn pkcs8_encrypt_alg(&self) -> String
pub fn set_pkcs8_encrypt_alg(&self, value: &str)
Introduced in version 9.5.0.49

Controls the block cipher used by encrypted PKCS #8 export methods. Supported values are 3des, aes128, aes192, and aes256. Values are case-insensitive and are normalized to lowercase. The default is 3des. Assigning an empty or unrecognized value resets the property to 3des. All choices use CBC mode.

Encrypted PKCS #8 output uses PBES2 with PBKDF2. The generated parameters use an 8-byte salt, 2048 PBKDF2 iterations, and the default PBKDF2 PRF (HMAC-SHA-1). The selected cipher uses CBC mode with a newly generated IV.

Recommended setting: Prefer aes256 for new output unless an older consumer requires 3DES. This property selects encryption parameters only; password quality remains essential.

top
UncommonOptions
// read/write
pub fn uncommon_options(&self) -> String
pub fn set_uncommon_options(&self, value: &str)
Introduced in version 9.5.0.96

Provides a catch-all string for specialized compatibility options that are not exposed as ordinary properties. The default is the empty string, which is appropriate for normal use.

Leave empty unless instructed: Set this property only when a Chilkat example, release note, or support response documents a specific option needed for an unusual interoperability case.

top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: 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
// read-only
pub fn version(&self) -> String

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

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

GetJwk
pub fn get_jwk(&self) -> Result<String>
Introduced in version 9.5.0.66

Exports the key as a compact JWK (JSON Web Key). Binary integers and byte strings use Base64url without padding.

Key typeMembers emitted
RSAkty, n, e, d, p, q, dp, dq, qi
ECkty, crv, x, y, d
Ed25519kty=OKP, crv=Ed25519, x, d, and use=sig
Key material only: Optional JOSE metadata loaded from a JWK, such as kid, alg, key_ops, or a caller-supplied use, is not retained for re-export. The Ed25519 use=sig member is emitted by Chilkat.
Private output: The returned JSON contains private key material and must be protected accordingly.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Export a Private Key as a JWKGet RSA Private Key in JWK Format (JSON Web Key)Get ECC Private Key in JWK Format (JSON Web Key)
top
GetJwkThumbprint
pub fn get_jwk_thumbprint(&self, hash_alg: &str) -> Result<String>
Introduced in version 9.5.0.66

Computes the RFC 7638 thumbprint of the public portion of the loaded key using the hash algorithm named by hash_alg. Supported values include md5, sha1, sha256, sha384, and sha512. An unsupported name causes the method to fail. The returned digest is Base64url-encoded without padding.

Public-key identity: The canonical thumbprint input contains only the required public JWK members. Private members and optional metadata such as kid, use, and alg are excluded, so the result matches the thumbprint of the corresponding PublicKey.
Recommended hash: Use sha256 for normal RFC 7638 interoperability. MD5 and SHA-1 are available for compatibility but should not be chosen for new security-sensitive identifiers.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Compute a Private Key's JWK ThumbprintCompute JWK Thumbprint for RSA and EC Private Keys
top
GetPkcs1ENC
pub fn get_pkcs1_enc(&self, encoding: &str) -> Result<String>
Introduced in version 9.5.0.52

Exports the key as the traditional or preferred unencrypted DER representation and encodes the DER as text using the binary encoding named by encoding. The binary bytes are the same as returned by GetPkcs1.

Historical method name: PKCS #1 is specifically an RSA standard. For non-RSA key types, this method returns the applicable traditional structure or a PKCS #8 fallback.
Key typeReturned representation
RSARSAPrivateKey DER from PKCS #1.
DSAThe traditional six-integer DSA private-key structure.
ECECPrivateKey DER from RFC 5915.
Ed25519PKCS #8 PrivateKeyInfo DER using the Ed25519 OID 1.3.101.112, because Ed25519 has no traditional PKCS #1 form.

For RSA, the DER contains:

RSAPrivateKey ::= SEQUENCE {
    version           Version,
    modulus           INTEGER,  -- n
    publicExponent    INTEGER,  -- e
    privateExponent   INTEGER,  -- d
    prime1            INTEGER,  -- p
    prime2            INTEGER,  -- q
    exponent1         INTEGER,  -- d mod (p-1)
    exponent2         INTEGER,  -- d mod (q-1)
    coefficient       INTEGER,  -- (inverse of q) mod p
    otherPrimeInfos   OtherPrimeInfos OPTIONAL
}

For EC, the traditional structure is:

ECPrivateKey ::= SEQUENCE {
    version        INTEGER { ecPrivkeyVer1(1) },
    privateKey     OCTET STRING,
    parameters [0] ECParameters OPTIONAL,
    publicKey  [1] BIT STRING OPTIONAL
}
Encoding validation: An unsupported encoding encoding name causes the method to fail; it does not silently select another encoding.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Export a Traditional Private Key as Encoded TextSupported Binary Encodings
top
GetPkcs1Pem
pub fn get_pkcs1_pem(&self) -> Result<String>
Introduced in version 9.5.0.58

Exports the key as unencrypted PEM, preferring the traditional algorithm-specific representation when one exists.

Key typePEM labelBody
RSARSA PRIVATE KEYPKCS #1 DER
DSADSA PRIVATE KEYTraditional DSA DER
ECEC PRIVATE KEYRFC 5915 DER
Ed25519PRIVATE KEYPKCS #8 DER
Generated PEM formatting: PEM output uses CRLF line endings, Base64 lines of at most 64 characters, and a final CRLF.
Security note: The returned private key is not encrypted.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Export a Private Key as Traditional PEM
top
GetPkcs8ENC
pub fn get_pkcs8_enc(&self, encoding: &str) -> Result<String>
Introduced in version 9.5.0.52

Exports the key as unencrypted PKCS #8 DER and encodes the DER as text using the binary encoding named by encoding. PKCS #8 is an algorithm-independent private-key container. Chilkat emits the classic version-0 PrivateKeyInfo structure, with the algorithm-specific private-key DER in an OCTET STRING.

PrivateKeyInfo ::= SEQUENCE {
    version                   Version,
    privateKeyAlgorithm       AlgorithmIdentifier,
    privateKey                OCTET STRING,
    attributes           [0]  IMPLICIT Attributes OPTIONAL
}
Encoding validation: An unsupported encoding encoding name causes the method to fail; it does not silently select another encoding.
Encoding is not encryption: Base64, hexadecimal, and similar encodings only represent the DER bytes as text. They do not protect the private key.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Export a PKCS #8 Private Key as Encoded TextSupported Binary EncodingsGenerate RSA Key and return Base64 PKCS8 Private Key
top
GetPkcs8EncryptedENC
pub fn get_pkcs8_encrypted_enc(&self, encoding: &str, password: &str) -> Result<String>
Introduced in version 9.5.0.52

Exports the key as password-protected PKCS #8 DER, then encodes the encrypted DER as text. encoding names the binary encoding and password supplies the password. The cipher is selected by Pkcs8EncryptAlg.

Encrypted PKCS #8 output uses PBES2 with PBKDF2. The generated parameters use an 8-byte salt, 2048 PBKDF2 iterations, and the default PBKDF2 PRF (HMAC-SHA-1). The selected cipher uses CBC mode with a newly generated IV.

Encoding validation: An unsupported encoding encoding name causes the method to fail.
Empty passwords: A nonempty, strong password should be used. An empty password is accepted but provides no meaningful password protection.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Export an Encrypted PKCS #8 Private Key as Encoded TextSupported Binary Encodings
top
GetPkcs8EncryptedPem
pub fn get_pkcs8_encrypted_pem(&self, password: &str) -> Result<String>

Exports the key as password-protected PKCS #8 PEM using password as the password. The cipher is selected by Pkcs8EncryptAlg. The output uses:

-----BEGIN ENCRYPTED PRIVATE KEY-----
...
-----END ENCRYPTED PRIVATE KEY-----

Encrypted PKCS #8 output uses PBES2 with PBKDF2. The generated parameters use an 8-byte salt, 2048 PBKDF2 iterations, and the default PBKDF2 PRF (HMAC-SHA-1). The selected cipher uses CBC mode with a newly generated IV.

Generated PEM formatting: PEM output uses CRLF line endings, Base64 lines of at most 64 characters, and a final CRLF.
Empty passwords: An empty password is accepted and still produces encrypted PKCS #8, but it provides no meaningful password protection.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Export an Encrypted PKCS #8 Private Key as PEMGenerate RSA Key and Export to Encrypted PEM
top
GetPkcs8Pem
pub fn get_pkcs8_pem(&self) -> Result<String>

Exports the key as unencrypted PKCS #8 PEM. For RSA, EC, and Ed25519, the PEM armor is:

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
PKCS #8 is an algorithm-independent private-key container. Chilkat emits the classic version-0 PrivateKeyInfo structure, with the algorithm-specific private-key DER in an OCTET STRING.
PrivateKeyInfo ::= SEQUENCE {
    version                   Version,
    privateKeyAlgorithm       AlgorithmIdentifier,
    privateKey                OCTET STRING,
    attributes           [0]  IMPLICIT Attributes OPTIONAL
}
Generated PEM formatting: PEM output uses CRLF line endings, Base64 lines of at most 64 characters, and a final CRLF.
Security note: This output is not password-protected.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Export a Private Key as PKCS #8 PEM
top
GetPkcsBd
pub fn get_pkcs_bd(&self, pkcs1: bool, password: &str, bd: &BinData) -> Result<()>
Introduced in version 11.0.0

Exports the key as DER and replaces the contents of the BinData in bd.

pkcs1passwordOutput
trueIgnored for encryption.RSA PKCS #1, traditional DSA, RFC 5915 EC, or PKCS #8 for Ed25519.
falseEmpty string.Unencrypted PKCS #8 DER.
falseNonempty password.Encrypted PKCS #8 DER using Pkcs8EncryptAlg.
Output state: A successful call replaces any existing bd content. If the call fails, bd is cleared.
Password behavior: When pkcs1 is true, password does not encrypt the output. To obtain encrypted output, set pkcs1 to false and provide a nonempty password.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Export a Private Key as DER into a BinData
top
GetRawHex
pub fn get_raw_hex(&self, pub_key: &StringBuilder) -> Result<String>
Introduced in version 9.5.0.83

Exports the raw private value as lowercase hexadecimal and replaces the contents of the StringBuilder in pub_key with the corresponding raw public key.

Key typeReturned private valuePublic value in pub_key
Ed25519The 32-byte seed accepted by LoadEd25519, as 64 hex characters.The 32-byte public key, as 64 hex characters.
ECThe private scalar, padded to the curve size as needed.The uncompressed point 04 || HEX(x) || HEX(y).
Applicable key types: This method supports Ed25519 and ordinary EC keys. RSA and DSA keys do not have a single simple raw representation and cause the method to fail.
Output on failure: If the method fails, pub_key is cleared.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Get a Private Key's Raw Hex ValueGet an EC Key in Raw Hex FormatGet an Ed25519 Key in Raw Hex Format
top
GetXml
pub fn get_xml(&self) -> Result<String>

Exports the key in Chilkat-compatible XML. The XML is not encrypted. RSA and DSA components use ordinary Base64.

RSA keys use:

<RSAKeyValue>
  <Modulus>...</Modulus>
  <Exponent>...</Exponent>
  <D>...</D>
  <P>...</P>
  <Q>...</Q>
  <DP>...</DP>
  <DQ>...</DQ>
  <InverseQ>...</InverseQ>
</RSAKeyValue>

DSA keys use:

<DSAKeyValue>
  <P>...</P>
  <Q>...</Q>
  <G>...</G>
  <Y>...</Y>
  <X>...</X>
</DSAKeyValue>

EC keys place the named curve in the curve attribute and Base64-encode the RFC 5915 ECPrivateKey DER in the element content:

<ECCKeyValue curve="secp256r1">...</ECCKeyValue>

Ed25519 keys Base64-encode 64 bytes consisting of the 32-byte private seed followed by the 32-byte public key:

<Ed25519KeyValue>...</Ed25519KeyValue>
Round-trip support: XML produced by this method can be loaded by LoadXml, LoadXmlFile, or the general format-detection methods.
Interoperability note: These XML forms are Chilkat-compatible representations. Prefer PKCS #8, PEM, or JWK when interoperating with systems that expect standard key containers.

Returns Err(chilkat::Error) on failure.

More Information and Examples
Export a Private Key as XMLGet RSA Key Modulus from .cer or .key
top
LoadAnyFormat
pub fn load_any_format(&self, priv_key_data: &BinData, password: &str) -> Result<()>
Introduced in version 9.5.0.75

Loads a private key from the data in priv_key_data by inspecting its contents. Recognized representations include RSA PKCS #1 DER, traditional DSA and EC DER, PKCS #8 DER, encrypted PKCS #8, PEM, JWK, Chilkat-compatible XML, Microsoft PVK, and supported Ed25519 representations. password supplies the password when the detected representation is encrypted; otherwise it may be empty.

Text and binary input: priv_key_data contains the exact bytes to inspect. Textual PEM, JWK, and XML are detected from those bytes; a filename extension is not involved.
Trailing DER data: If the input begins with one complete supported DER key followed by extra bytes or another DER object, the first key is loaded and trailing data is ignored.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from BinData (Any Format)Use HTTPS Client Certificate from .cer and .key Files
top
LoadAnyFormatFile
pub fn load_any_format_file(&self, path: &str, password: &str) -> Result<()>
Introduced in version 9.5.0.83

Loads a private key from the file at path by inspecting its contents. Recognized representations include RSA PKCS #1 DER, traditional DSA and EC DER, PKCS #8 DER, encrypted PKCS #8, PEM, JWK, Chilkat-compatible XML, Microsoft PVK, and supported Ed25519 representations. password supplies the password when needed.

Filename extensions are advisory: The file content determines the format; a nonstandard or misleading extension does not prevent recognition.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from a File (Any Format)
top
LoadEd25519
pub fn load_ed25519(&self, priv_key: &str, pub_key: &str) -> Result<()>
Introduced in version 9.5.0.83

Loads an Ed25519 key pair from raw hexadecimal values. priv_key is the 32-byte Ed25519 private seed. pub_key is the 32-byte public key. Each nonempty value must contain exactly 64 hexadecimal digits. Uppercase hexadecimal and an optional 0x prefix are accepted; embedded whitespace is not accepted. pub_key may be empty, in which case Chilkat derives the public key from the seed.

Supplied public key is not verified: When pub_key is nonempty, Chilkat stores the supplied public value without checking that it corresponds to priv_key. Pass an empty pub_key when the public key should be derived and guaranteed to match the private seed.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load an Ed25519 Key from Raw HexLoad an Ed25519 Private Key from Hex
top
LoadEncryptedPem
pub fn load_encrypted_pem(&self, pem_str: &str, password: &str) -> Result<()>

Loads a private key from the PEM text in pem_str. password supplies the password when the PEM is encrypted. The method accepts encrypted PKCS #8 PEM and also loads supported unencrypted PEM.

-----BEGIN ENCRYPTED PRIVATE KEY-----
...
-----END ENCRYPTED PRIVATE KEY-----
Content auto-detection: Chilkat examines the content rather than relying on the method name or filename extension. This password-taking method can load both encrypted and unencrypted supported private-key representations.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.
Password failure: An incorrect password causes loading to fail and leaves this object empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load an Encrypted Private Key from PEM TextCompute JWK Thumbprint for RSA and EC Private Keys
top
LoadEncryptedPemFile
pub fn load_encrypted_pem_file(&self, path: &str, password: &str) -> Result<()>

Loads a private key from the file at path, using password when the detected key is encrypted. The file may contain encrypted PKCS #8 PEM or another supported encrypted or unencrypted representation.

Content auto-detection: Chilkat examines the content rather than relying on the method name or filename extension. This password-taking method can load both encrypted and unencrypted supported private-key representations.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load an Encrypted Private Key from a PEM FileDuplicate OpenSSL smime Command
top
LoadJwk
pub fn load_jwk(&self, json_str: &str) -> Result<()>
Introduced in version 9.5.0.66

Loads a private key from the JWK JSON in json_str. Supported private JWK key types are RSA (kty=RSA), EC (kty=EC), and Ed25519 (kty=OKP, crv=Ed25519). An unsupported kty causes the method to fail.

Private key material required: A JWK containing only public members belongs in a PublicKey. This method is for JWKs that contain private key material.
Metadata handling: Optional JOSE metadata such as kid, use, alg, and key_ops may be present but is not retained by PrivateKey.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from a JWKLoad RSA Private Key from JWK Format (JSON Web Key)Load ECC Private Key from JWK Format (JSON Web Key)JWE using RSAES-OAEP and AES GCM
top
LoadPem
pub fn load_pem(&self, str: &str) -> Result<()>

Loads a private key from the PEM text in str. This method has no password argument and therefore cannot load password-protected PEM. Use LoadEncryptedPem for encrypted input.

Content auto-detection: The method name identifies the expected or traditional use, but Chilkat examines the content and can load other supported unencrypted private-key representations. Encrypted input requires a load method that accepts a password.
PEM block selection: If the text contains multiple PEM blocks, Chilkat selects the first supported private-key block. It skips preceding public-key or unrelated PEM blocks.
Accepted surrounding content: Leading and trailing whitespace, a UTF-8 BOM, and trailing non-PEM text are accepted.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from PEM TextCompute JWK Thumbprint for RSA and EC Private Keys
top
LoadPemFile
pub fn load_pem_file(&self, path: &str) -> Result<()>

Loads a private key from the file at path. This method has no password argument and therefore cannot load a password-protected key. Use LoadEncryptedPemFile or LoadAnyFormatFile when a password may be required.

Content auto-detection: The method name identifies the expected or traditional use, but Chilkat examines the content and can load other supported unencrypted private-key representations. Encrypted input requires a load method that accepts a password.
PEM block selection: For a file containing multiple PEM blocks, Chilkat selects the first supported private-key block and skips preceding public-key or unrelated blocks.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from a PEM FileCreate PKCS1 RSA Signature with PEM Private Key
top
LoadPkcs1File
pub fn load_pkcs1_file(&self, path: &str) -> Result<()>
Introduced in version 9.5.0.58

Loads a private key from the file at path. Despite the historical PKCS #1 name, the method examines the content and accepts supported unencrypted private-key representations.

Content auto-detection: The method name identifies the expected or traditional use, but Chilkat examines the content and can load other supported unencrypted private-key representations. Encrypted input requires a load method that accepts a password.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from a PKCS #1 File
top
LoadPkcs8EncryptedFile
pub fn load_pkcs8_encrypted_file(&self, path: &str, password: &str) -> Result<()>

Loads a private key from the file at path, using password when the detected key is encrypted. The method can load encrypted PKCS #8 DER or PEM and also supported unencrypted representations.

Content auto-detection: Chilkat examines the content rather than relying on the method name or filename extension. This password-taking method can load both encrypted and unencrypted supported private-key representations.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load an Encrypted PKCS #8 Private Key FileRSA Sign with PKCS8 Encrypted Key
top
LoadPkcs8File
pub fn load_pkcs8_file(&self, path: &str) -> Result<()>

Loads a private key from the file at path. Although named for unencrypted PKCS #8, the method examines the file content and accepts other supported unencrypted private-key representations.

Content auto-detection: The method name identifies the expected or traditional use, but Chilkat examines the content and can load other supported unencrypted private-key representations. Encrypted input requires a load method that accepts a password.
Trailing DER data: When the file begins with a complete supported DER private-key object, trailing bytes or a second concatenated DER object are ignored; the first key is loaded.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from a PKCS #8 File
top
LoadPvkFile
pub fn load_pvk_file(&self, path: &str, password: &str) -> Result<()>

Loads a private key from the file at path, using password if the detected representation is encrypted. This Windows-only method supports Microsoft PVK and also participates in Chilkat private-key content auto-detection.

Content auto-detection: Chilkat examines the content rather than relying on the method name or filename extension. This password-taking method can load both encrypted and unencrypted supported private-key representations.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from a Microsoft PVK FileLoad Certificate (.cer) and Private Key (.pvk) generated from makecert
top
LoadXml
pub fn load_xml(&self, xml: &str) -> Result<()>

Loads a private key from the XML text in xml. Supported Chilkat-compatible XML roots include RSAKeyValue, DSAKeyValue, ECCKeyValue, and Ed25519KeyValue.

Content auto-detection: The method name identifies the expected or traditional use, but Chilkat examines the content and can load other supported unencrypted private-key representations. Encrypted input requires a load method that accepts a password.
Ed25519 XML: The Ed25519KeyValue content is ordinary Base64 for the 32-byte private seed followed by the 32-byte public key.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from XML Text
top
LoadXmlFile
pub fn load_xml_file(&self, path: &str) -> Result<()>

Loads a private key from the file at path. Chilkat recognizes RSA, DSA, EC, and Ed25519 XML produced by GetXml, and also auto-detects other supported unencrypted private-key representations.

Content auto-detection: The method name identifies the expected or traditional use, but Chilkat examines the content and can load other supported unencrypted private-key representations. Encrypted input requires a load method that accepts a password.
Object state: A successful load replaces any key already held by this object. If loading fails, this object is left empty.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Load a Private Key from an XML File
top
SavePemFile
pub fn save_pem_file(&self, path: &str) -> Result<()>
Introduced in version 9.5.0.58

Saves the key at path as unencrypted PEM, preferring a traditional algorithm-specific representation when one exists. RSA uses RSA PRIVATE KEY, DSA uses DSA PRIVATE KEY, EC uses EC PRIVATE KEY, and Ed25519 uses the PKCS #8 PRIVATE KEY form.

Generated PEM formatting: PEM output uses CRLF line endings, Base64 lines of at most 64 characters, and a final CRLF.
File behavior: An existing destination file is replaced. Parent directories are not created; the parent directory must already exist.
PKCS #8 alternative: Use SavePkcs8PemFile to always request the algorithm-independent PKCS #8 PRIVATE KEY form.
Security note: The file is not password-protected.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Save a Private Key as a Traditional PEM File
top
SavePkcs1File
pub fn save_pkcs1_file(&self, path: &str) -> Result<()>
Introduced in version 9.5.0.58

Saves the key at path using the traditional or preferred unencrypted DER representation.

Historical method name: RSA is saved as PKCS #1, EC as RFC 5915, DSA in its traditional structure, and Ed25519 as PKCS #8 because no traditional PKCS #1 form exists.
File behavior: An existing destination file is replaced. Parent directories are not created; the parent directory must already exist.
Security note: The file contains cleartext private-key material.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Save a Private Key as a Traditional DER File
top
SavePkcs8EncryptedFile
pub fn save_pkcs8_encrypted_file(&self, password: &str, path: &str) -> Result<()>

Saves the key as password-protected PKCS #8 DER. password supplies the password and path is the destination path. The cipher is selected by Pkcs8EncryptAlg.

Encrypted PKCS #8 output uses PBES2 with PBKDF2. The generated parameters use an 8-byte salt, 2048 PBKDF2 iterations, and the default PBKDF2 PRF (HMAC-SHA-1). The selected cipher uses CBC mode with a newly generated IV.

File behavior: An existing destination file is replaced. Parent directories are not created; the parent directory must already exist.
Empty passwords: An empty password is accepted but provides no meaningful password protection.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Save a Private Key as an Encrypted PKCS #8 DER File
top
SavePkcs8EncryptedPemFile
pub fn save_pkcs8_encrypted_pem_file(&self, password: &str, path: &str) -> Result<()>

Saves the key as password-protected PKCS #8 PEM. password supplies the password and path is the destination path. The file uses the ENCRYPTED PRIVATE KEY PEM label, and the cipher is selected by Pkcs8EncryptAlg.

Encrypted PKCS #8 output uses PBES2 with PBKDF2. The generated parameters use an 8-byte salt, 2048 PBKDF2 iterations, and the default PBKDF2 PRF (HMAC-SHA-1). The selected cipher uses CBC mode with a newly generated IV.

Generated PEM formatting: PEM output uses CRLF line endings, Base64 lines of at most 64 characters, and a final CRLF.
File behavior: An existing destination file is replaced. Parent directories are not created; the parent directory must already exist.
Empty passwords: An empty password is accepted but provides no meaningful password protection.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Save a Private Key as an Encrypted PKCS #8 PEM FileGenerate an RSA Key and Save to Encrypted PEM
top
SavePkcs8File
pub fn save_pkcs8_file(&self, path: &str) -> Result<()>

Saves the key as unencrypted PKCS #8 DER at path. PKCS #8 is an algorithm-independent private-key container. Chilkat emits the classic version-0 PrivateKeyInfo structure, with the algorithm-specific private-key DER in an OCTET STRING.

PrivateKeyInfo ::= SEQUENCE {
    version                   Version,
    privateKeyAlgorithm       AlgorithmIdentifier,
    privateKey                OCTET STRING,
    attributes           [0]  IMPLICIT Attributes OPTIONAL
}
File behavior: An existing destination file is replaced. Parent directories are not created; the parent directory must already exist.
macOS Keychain: Starting in Chilkat v10.0.0, path may be formatted as keychain:<label> to save the private key to the Apple Keychain.
Security note: The file contains cleartext private-key material.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Save a Private Key as a PKCS #8 DER FileApple Keychain - Import RSA Private KeyApple Keychain - Import ECDSA Private Key
top
SavePkcs8PemFile
pub fn save_pkcs8_pem_file(&self, path: &str) -> Result<()>

Saves the key as unencrypted PKCS #8 PEM at path. The PEM label is PRIVATE KEY for RSA, EC, Ed25519, and other supported PKCS #8 key types.PKCS #8 is an algorithm-independent private-key container. Chilkat emits the classic version-0 PrivateKeyInfo structure, with the algorithm-specific private-key DER in an OCTET STRING.

PrivateKeyInfo ::= SEQUENCE {
    version                   Version,
    privateKeyAlgorithm       AlgorithmIdentifier,
    privateKey                OCTET STRING,
    attributes           [0]  IMPLICIT Attributes OPTIONAL
}
Generated PEM formatting: PEM output uses CRLF line endings, Base64 lines of at most 64 characters, and a final CRLF.
File behavior: An existing destination file is replaced. Parent directories are not created; the parent directory must already exist.
Security note: The file is not password-protected.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Save a Private Key as a PKCS #8 PEM File
top
SaveXmlFile
pub fn save_xml_file(&self, path: &str) -> Result<()>

Saves the key as unencrypted Chilkat-compatible XML at path. The XML representation is the same as returned by GetXml.

File behavior: An existing destination file is replaced. Parent directories are not created; the parent directory must already exist.
Security note: The XML contains cleartext private-key material.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Save a Private Key as an XML File
top
ToPublicKey
pub fn to_public_key(&self, pub_key: &PublicKey) -> Result<()>
Introduced in version 11.0.0

Extracts the public portion of the loaded private key and stores an independent copy in the PublicKey supplied in pub_key. The resulting public key is unaffected if this PrivateKey is later reloaded with a different key.

Target state on failure: If extraction fails, an existing key already held by pub_key is preserved.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Get the Public Key from a Private Key
top
UploadToCloud
pub fn upload_to_cloud(&self, json_in: &JsonObject, json_out: &JsonObject) -> Result<()>
Introduced in version 9.5.0.96

Uploads or imports the private key to a supported cloud key-management service. json_in supplies service-specific input parameters as a JsonObject, and json_out receives service-specific result information.

Open-ended interface: The required JSON members and returned JSON depend on the target service and operation. Follow the corresponding Chilkat example for AWS KMS, Azure Key Vault, or another supported provider rather than assuming one common schema.
Security note: Cloud import operations may transmit private-key material. Use only the provider endpoint, authentication, and transport settings documented for the intended service.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top

Events

All Chilkat methods are synchronous: the call returns when the work is done. During a call, PrivateKey raises three events so your application can show progress and offer a way out. Implement the chilkat::EventHandler trait (every method has a do-nothing default, so implement only the events you need) and install it with set_event_handler:

use chilkat::{PrivateKey, EventHandler};

struct Progress;

impl EventHandler for Progress {
    fn percent_done(&mut self, pct: i32) -> bool {
        println!("{pct}%");
        false   // return true to abort the method in progress
    }
    fn progress_info(&mut self, name: &str, value: &str) {
        println!("{name}: {value}");
    }
}

let private_key = PrivateKey::new();
private_key.set_event_handler(Progress);
private_key.set_heartbeat_ms(250);   // raise abort_check 4 times per second during Chilkat calls

For a one-off handler the closure methods avoid writing a type; they may be combined, and each replaces the previously set closure for that one event (installing a closure removes a trait handler set earlier, and vice versa):

private_key.on_percent_done(|pct| { println!("{pct}%"); false });
private_key.on_progress_info(|name, value| println!("{name}: {value}"));
pub fn set_event_handler<H: EventHandler>(&self, handler: H)

Installs handler as the receiver of this object's events, replacing any handler or closures set earlier. The object owns the handler, which must be Send + 'static.

pub fn clear_event_handler(&self)

Removes the handler and any closures; events are no longer delivered.

AbortCheck fires at regular intervals controlled by the HeartbeatMs property (0, the default, disables it); PercentDone fires when an operation's completion percentage is known; ProgressInfo delivers named progress values. Returning true from abort_check or percent_done aborts the running method, which then returns Err.

Events fire on the thread that called the method, before that method returns. A panic inside a handler aborts the running method and is re-raised to the caller once the native library has returned, so it never unwinds through C frames. To abort a long operation from another thread, share an Arc<AtomicBool> with an abort_check handler, or set the object's AbortCurrent property to true.

AbortCheck
// EventHandler trait method; closure form: on_abort_check(FnMut() -> bool)
fn abort_check(&mut self) -> bool

Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

private_key.set_heartbeat_ms(250);   // call abort_check 4 times per second

let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let flag = stop.clone();
private_key.on_abort_check(move || flag.load(std::sync::atomic::Ordering::Relaxed));
// ... another thread may now abort the method in progress with stop.store(true, Ordering::Relaxed)
top
PercentDone
// EventHandler trait method; closure form: on_percent_done(FnMut(i32) -> bool)
fn percent_done(&mut self, pct: i32) -> bool

This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pct_done argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pct_done equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).

The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.

To abort the operation, set the abort output argument to true. This will cause the method to terminate and return a failure status or corresponding failure value.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

private_key.on_percent_done(|pct| {
    // pct ranges from 1 to 100.
    println!("Percent done: {pct}");
    false   // return true to abort the method in progress
});
top
ProgressInfo
// EventHandler trait method; closure form: on_progress_info(FnMut(&str, &str))
fn progress_info(&mut self, name: &str, value: &str)

This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.

Note: Some Chilkat methods don't fire any ProgressInfo events.

More Information and Examples
Chilkat Event Callback Examples

Example (closure form; the EventHandler trait method is equivalent):

private_key.on_progress_info(|name, value| println!("{name}: {value}"));
top