TPrivateKey

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.

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.

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.

This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.

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.

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.

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.

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

In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.

The length, in characters, of the string contained in the LastStringResult property.

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.

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.

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

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

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

Returns a zero-length WideString on failure

Computes the RFC 7638 thumbprint of the public portion of the loaded key using the hash algorithm named by hashAlg. 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.

Returns a zero-length WideString on failure

Exports the key as the traditional or preferred unencrypted binary DER representation.

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
}

Returns a zero-length byte array (as an OleVariant) on failure.
An empty array will have a VarArrayHighBound of -1 meaning 0 elements.

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.

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
}

Returns a zero-length WideString on failure

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

Returns a zero-length WideString on failure

Exports the key as unencrypted PKCS #8 DER. 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
}

Returns a zero-length byte array (as an OleVariant) on failure.
An empty array will have a VarArrayHighBound of -1 meaning 0 elements.

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
}

Returns a zero-length WideString on failure

Exports the key as password-protected PKCS #8 DER using password as the password. The block cipher is selected by Pkcs8EncryptAlg.

EncryptedPrivateKeyInfo ::= SEQUENCE {
    encryptionAlgorithm  AlgorithmIdentifier,
    encryptedData        OCTET STRING
}

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.

Returns a zero-length byte array (as an OleVariant) on failure.
An empty array will have a VarArrayHighBound of -1 meaning 0 elements.

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.

Returns a zero-length WideString on failure

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.

Returns a zero-length WideString on failure

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

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

PrivateKeyInfo ::= SEQUENCE {
    version                   Version,
    privateKeyAlgorithm       AlgorithmIdentifier,
    privateKey                OCTET STRING,
    attributes           [0]  IMPLICIT Attributes OPTIONAL
}

Returns a zero-length WideString on failure

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

Returns 1 for success, 0 for failure.

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

Returns a zero-length WideString on failure

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>

Returns a zero-length WideString on failure

Loads a private key from the data in privKeyData 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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Loads an Ed25519 key pair from raw hexadecimal values. privKey is the 32-byte Ed25519 private seed. pubKey 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. pubKey may be empty, in which case Chilkat derives the public key from the seed.

Returns 1 for success, 0 for failure.

Loads a private key from the PEM text in pemStr. 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-----

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Loads a private key from the JWK JSON in jsonStr. 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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Loads a private key from the in-memory data in data. Despite the historical PKCS #1 name, Chilkat examines the content and accepts supported unencrypted RSA, DSA, EC, Ed25519, PKCS #8, PEM, JWK, and XML representations.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Loads a private key from the in-memory data in data. Although this method is named for unencrypted PKCS #8 DER, Chilkat examines the content and accepts other supported unencrypted private-key representations.

Returns 1 for success, 0 for failure.

Loads a private key from the in-memory data in data, using password when the detected key is encrypted. The method can load encrypted PKCS #8 and other supported encrypted or unencrypted representations.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

Loads a private key from the in-memory data in data, 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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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.

Returns 1 for success, 0 for failure.

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
}

Returns 1 for success, 0 for failure.

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
}

Returns 1 for success, 0 for failure.

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

Returns 1 for success, 0 for failure.

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

Returns 1 for success, 0 for failure.

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

Returns 1 for success, 0 for failure.

Creates an asynchronous task to call the UploadToCloud method with the arguments provided.

Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.

Returns nil on failure

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.

Delphi ActiveX Event callback implementation:

procedure TForm1.privatekeyAbortCheck(ASender: TObject;  out abort: Integer);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  privatekey: TPrivateKey;

begin
  privatekey := TPrivateKey.Create(Self);
  privatekey.OnAbortCheck := privatekeyAbortCheck;
  // ...

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 pctDone 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 pctDone 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 1. This will cause the method to terminate and return a failure status or corresponding failure value.

Delphi ActiveX Event callback implementation:

procedure TForm1.privatekeyPercentDone(ASender: TObject;  pctDone: Integer; out abort: Integer);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  privatekey: TPrivateKey;

begin
  privatekey := TPrivateKey.Create(Self);
  privatekey.OnPercentDone := privatekeyPercentDone;
  // ...

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.

Delphi ActiveX Event callback implementation:

procedure TForm1.privatekeyProgressInfo(ASender: TObject;  const name: WideString; const value: WideString);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  privatekey: TPrivateKey;

begin
  privatekey := TPrivateKey.Create(Self);
  privatekey.OnProgressInfo := privatekeyProgressInfo;
  // ...

Called from the background thread when an asynchronous task completes.

Delphi ActiveX Event callback implementation:

procedure TForm1.privatekeyTaskCompleted(ASender: TObject;  const task: IChilkatTask);
begin
    // Application code goes here...
end;


procedure TForm1.Button1Click(Sender: TObject);
var
  privatekey: TPrivateKey;

begin
  privatekey := TPrivateKey.Create(Self);
  privatekey.OnTaskCompleted := privatekeyTaskCompleted;
  // ...

Deprecated. Use ToPublicKey instead. This method creates and returns a PublicKey containing an independent copy of the public portion corresponding to the loaded private key.

Returns nil on failure