CkoSshKey

Gets or sets the optional comment associated with the key.

• OpenSSH public keys, RFC 4716 public keys, and PuTTY PPK files can contain a comment. Importing one of these formats sets this property from the imported text.
• Importing an OpenSSH or RFC 4716 public key that has no comment sets this property to an empty string.
• Changing the comment does not change the key or the value returned by GenFingerprint.
• Exports that support comments use this value. Do not include carriage-return or line-feed characters because they are written into the exported text and can make the key file invalid.

OpenSSH import note: For a one-line OpenSSH public key, the first whitespace-delimited word following the Base64 key data is stored as the comment.

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.

Indicates whether the object currently contains a DSA key.

Returns true for either a DSA public key or a DSA private key. Returns false for RSA, ECDSA, Ed25519, or when no key is loaded. Use KeyType to distinguish among all supported key types.

Indicates whether the current key includes a private key.

Returns true after importing or generating a private key. Returns false for a public-only key and for a newly constructed object that does not yet contain a key.

This property describes whether private-key operations are available; it does not reveal or return the private-key material.

Indicates whether the object currently contains an RSA key.

Returns true for either an RSA public key or an RSA private key. Returns false for DSA, ECDSA, Ed25519, or when no key is loaded. Use KeyType to distinguish among all supported key types.

Returns the type of key currently held by this object. A newly constructed object returns none.

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

Gets or sets the password used when importing or exporting an encrypted private key. The default is an empty string.

• Set this property before importing an encrypted OpenSSH, PKCS #8, or PuTTY private key.
• An empty or incorrect password causes an encrypted-key import to fail.
• The property remains set until the application changes it; Chilkat does not automatically clear it after an import or export.
• When ToOpenSshPrivateKey is called with bEncrypt equal to true, an empty password produces a private key encrypted with an empty passphrase. Applications should normally require a nonempty password.
• When ToPuttyPrivateKey is called with bEncrypt equal to true, this property must be nonempty.

Provides optional settings for uncommon compatibility requirements. The default is an empty string.

The value is a comma-separated list of keywords. Keyword matching is case-insensitive, surrounding whitespace is ignored, and unknown keywords are ignored.

• DES-EDE3-CBC — When ToOpenSshPrivateKey exports an encrypted traditional RSA, DSA, or ECDSA private key, use Triple-DES instead of the default AES-128-CBC encryption.

This option does not change Ed25519 output, which uses the modern OPENSSH PRIVATE KEY container. Use legacy encryption only when required by older software.

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.

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

Loads a private key from an OpenSSH-compatible, PEM, PKCS #8, or PuTTY private-key string.

Supported key types: RSA, DSA, ECDSA, and Ed25519.

contains the key text, not a filesystem path. If the key is encrypted, set Password before calling this method. To read the text from a file, call LoadText first.

Chilkat tolerates a UTF-8 BOM, leading or trailing whitespace, and unrelated text surrounding a PEM/OpenSSH key. If contains more than one recognized private key, the first key is loaded.

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

Returns true for success, false for failure.

Loads an SSH public key from a string.

The method accepts:

• A one-line OpenSSH public key for RSA, DSA, ECDSA, or Ed25519.
• An RFC 4716 / PuTTY SSH2 public key, which is detected automatically.

contains the public-key text, not a filesystem path. For a one-line key, the first field is the algorithm name, the second field is the Base64 key data, and the first whitespace-delimited word after the key data is stored in Comment.

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... user@example

A UTF-8 BOM, surrounding whitespace, CRLF, and LF line endings are accepted. If multiple public-key lines are supplied, the first key is loaded.

Returns true for success, false for failure.

Loads a private key from PuTTY PPK format. PPK versions 2 and 3 are supported.

If contains an OpenSSH, traditional PEM, or PKCS #8 private key instead, Chilkat automatically detects and imports that format.

• contains the complete key text, not a filesystem path.
• If the private key is encrypted, set Password before calling this method.
• The PPK integrity MAC is verified.
• A UTF-8 BOM is accepted. For a PPK input, the PPK header must otherwise be at the beginning of ; leading whitespace or unrelated text is not accepted.
• Trailing text after a single PPK is tolerated, but concatenated PPK files are not accepted.

PuTTY-User-Key-File-3: ssh-ed25519
Encryption: aes256-cbc
Comment: example-key
Public-Lines: ...

Returns true for success, false for failure.

Loads a public key from RFC 4716 SSH2 public-key format.

contains the key text, not a filesystem path. RSA, DSA, ECDSA, and Ed25519 public keys are supported.

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "optional comment"
AAAAB3NzaC1yc2EAAAADAQABAAABAQ...
---- END SSH2 PUBLIC KEY ----

The parser accepts a UTF-8 BOM, surrounding whitespace, long or continued comments, and additional RFC 4716 header fields. It also tolerates unrelated text before or after the key. If multiple RFC 4716 keys are supplied, the first key is loaded.

The Comment: header, when present, is stored in Comment. If it is absent, the comment is empty.

Returns true for success, false for failure.

Loads an SSH public or private key from an XML string.

contains the XML itself, not a filesystem path. The key is public-only when the XML contains only public components and is private when private components are present.

<RSAKeyValue>
  <Modulus>...</Modulus>
  <Exponent>AQAB</Exponent>
  ...
</RSAKeyValue>

A UTF-8 BOM, surrounding whitespace, and an XML declaration are accepted. Root-element name matching is case-insensitive. These XML representations do not contain the SSH comment; set Comment separately when needed.

Returns true for success, false for failure.

Generates a new DSA public/private key pair.

specifies the requested key size in bits. For maximum interoperability with SSH implementations that still allow DSA, use 1024.

Nonstandard sizes may be accepted, and the resulting key size may differ from the value requested. DSA is a legacy algorithm and should generally be avoided for new systems.

On success, the generated private key replaces the previous key. Existing values of Comment, Password, and UncommonOptions are not used as key-generation parameters.

Returns true for success, false for failure.

Generates a new ECDSA public/private key pair.

selects the curve. Matching is case-insensitive. Accepted names include:

• secp256r1, P-256, or prime256v1
• secp384r1 or P-384
• secp521r1 or P-521

An empty or unrecognized curve name causes the method to fail. If generation fails, the previous key is not guaranteed to remain available.

On success, the generated private key replaces the previous key while the writable properties remain set. P-521 is shown as 528 bits by GenFingerprint.

Returns true for success, false for failure.

Generates a new Ed25519 public/private key pair.

On success, the generated private key replaces the previous key. Existing values of Comment, Password, and UncommonOptions remain set.

Ed25519 private keys are exported by ToOpenSshPrivateKey using the modern OPENSSH PRIVATE KEY container.

Returns true for success, false for failure.

Generates a new RSA public/private key pair.

• specifies the requested key size in bits. Tested supported sizes range from 512 through 4096. For new applications, use at least 2048.
• The exponent argument is ignored. Chilkat always generates RSA keys using the public exponent 65537. The argument is retained for backward compatibility.

On success, the generated private key replaces the previous key. The writable properties Comment, Password, and UncommonOptions remain set to their existing values.

If generation fails, the previous key is not guaranteed to remain available. Use a fresh object when preserving an existing key is important.

Returns true for success, false for failure.

Returns a printable fingerprint for the key currently held by this object.

The fingerprint is calculated from the public portion of the key. Therefore:

• The public and private representations of the same key return the same fingerprint.
• OpenSSH, PuTTY, RFC 4716, and XML representations of the same key return the same fingerprint.
• Changing Comment does not change the fingerprint.

The returned string contains the SSH algorithm name, the reported key size when applicable, and a colon-separated 16-byte hexadecimal digest:

ssh-rsa 2048 4c:98:46:ba:46:33:ba:9e:39:11:5c:a5:a3:9c:6b:ee
ssh-ed25519  b7:71:3f:81:d6:fd:1d:b1:ff:87:18:63:f6:32:3f:67

Ed25519 has no numeric size field. A P-521 ECDSA key is reported as 528 bits because of its SSH point encoding. If no usable key is loaded, an empty string is returned.

Returns nil on failure

Reads an entire text file and returns its contents as a string.

is the path of the file to read. This method is convenient for loading ASCII-armored SSH key text before calling an import method.

• If the file does not exist or cannot be read, the method returns null.
• This is a text operation, not a byte-preserving binary read. Non-ASCII data may be converted according to the platform and Chilkat string-encoding settings.
• For exact binary bytes, use a binary-oriented class such as BinData or FileAccess instead.

Returns nil on failure

Writes a string to a text file.

• contains the text to write.
• filename is the destination path.
• An existing file is overwritten.
• Missing parent directories are not created automatically.
• This is a text operation. ASCII key text is written as expected, but arbitrary non-ASCII bytes should be written with a binary-oriented API.

This method is commonly used to save the strings returned by the key-export methods.

Returns true for success, false for failure.

Exports the current private key as an OpenSSH-compatible private-key string.

• equal to false returns an unencrypted private key.
• equal to true returns an encrypted private key using Password.
• If the object contains only a public key, the method fails.

Encrypted traditional RSA, DSA, and ECDSA output uses AES-128-CBC by default. See UncommonOptions for the legacy Triple-DES option.

The output uses CRLF line endings and ends with CRLF.

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

Returns nil on failure

Exports the public portion of the current key in one-line OpenSSH public-key format.

The method works when the object contains either a private key or a public-only key. The returned string contains the algorithm name, Base64 key data, and the current Comment when it is nonempty:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ... user@example

The returned string does not include a final CRLF or LF. It contains a bare key entry and does not add authorized_keys options such as restrict or from="...".

Do not place CR or LF characters in Comment, because the comment is appended without newline sanitization.

Returns nil on failure

Exports the current private key as a PuTTY PPK string.

• equal to false returns an unencrypted PPK.
• equal to true returns an encrypted PPK using AES-256-CBC and requires a nonempty Password.
• If the object contains only a public key, the method fails.

The emitted format is PuTTY PPK version 2. FromPuttyPrivateKey can import both PPK version 2 and version 3.

The returned text includes the public and private sections, Comment, and the integrity MAC. It uses CRLF line endings and ends with CRLF.

PuTTY-User-Key-File-2: ssh-rsa
Encryption: aes256-cbc
Comment: example-key
Public-Lines: ...

Do not place CR or LF characters in Comment.

Returns nil on failure

Exports the public portion of the current key in RFC 4716 SSH2 public-key format.

The method works when the object contains either a private key or a public-only key. The returned text contains boundary lines, wrapped Base64 key data, and a Comment: header. When Comment is empty, the header is emitted as Comment: "".

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "optional comment"
AAAAB3NzaC1yc2EAAAADAQABAAABAQ...
---- END SSH2 PUBLIC KEY ----

The output uses CRLF line endings and ends with CRLF. Do not place CR or LF characters in Comment.

Returns nil on failure

Exports the current key as XML.

A public-only key produces a public-key XML representation. A private key produces XML containing private-key components and must therefore be protected as sensitive key material.

<RSAKeyValue>
  <Modulus>...</Modulus>
  <Exponent>AQAB</Exponent>
  ... private components ...
</RSAKeyValue>

The XML does not include Comment. The returned string does not have a final newline and can be loaded by FromXml.

Returns nil on failure

Configures this object to use a private key held in a PKCS#11 token, smart card, or HSM for SSH public-key authentication.

• is the Pkcs11 session containing the key objects.
• privKeyHandle is the PKCS#11 handle of the private key.
• pubKeyHandle is the PKCS#11 handle of the corresponding public key.
• keyType identifies the key type and must be RSA or EC.

The private-key operation is performed by the PKCS#11 device, allowing the private key to remain on the token.

Returns true for success, false for failure.

Associates an OpenSSH user certificate with this object for SSH or SFTP public-key authentication.

contains the complete certificate text, not a filesystem path. An SSH user certificate has the same one-line text structure as an OpenSSH public key, but its algorithm name ends in -cert-v01@openssh.com:

ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1yc2EAAAADAQAB... user@host

The certificate is used together with its corresponding private key during authentication.

Returns true for success, false for failure.