Chilkat.SshKey Class Overview

Chilkat.SshKey represents an SSH public or private key. It can import, export, generate, inspect, and convert SSH keys in common formats such as OpenSSH, PuTTY, RFC 4716, and XML. It also supports encrypted private keys, fingerprints, comments, PKCS#11-backed keys, and SSH user certificates for public-key authentication workflows.

What the Class Is Used For

Use Chilkat.SshKey when an application needs to load an SSH key, generate a new key pair, convert between SSH key formats, export a public key for installation on an SSH server, or provide a private key to Chilkat.Ssh, Chilkat.SFtp, or Chilkat.SshTunnel for public-key authentication.

Import SSH Keys Load private or public keys from OpenSSH, PuTTY, RFC 4716, or XML text.
Export and Convert Convert loaded or generated keys to OpenSSH, PuTTY, RFC 4716, or XML output.
Generate Key Pairs Generate RSA, DSA, ECDSA, or Ed25519 SSH key pairs.
Use Hardware Keys Reference private keys held in PKCS#11 devices such as smart cards or HSMs.

Typical Workflow: Load an Existing Private Key

  1. Create an SshKey object.
  2. If the private key is encrypted, set the Password property before importing.
  3. Load the key text from a file using LoadText, or obtain the key text from another source.
  4. Import the key with FromOpenSshPrivateKey, FromPuttyPrivateKey, or FromXml.
  5. Inspect KeyType, IsPrivateKey, and Comment.
  6. Use the key for SSH public-key authentication, export it in another format, or generate its fingerprint with GenFingerprint.
  7. Check LastErrorText if import or export fails.

Typical Workflow: Generate and Export a New Key

  1. Create an SshKey object.
  2. Generate a key pair with GenerateRsaKey, GenerateDsaKey, GenerateEcdsaKey, or GenerateEd25519Key.
  3. Optionally set Comment.
  4. If exporting an encrypted private key, set Password.
  5. Export the private key with ToOpenSshPrivateKey, ToPuttyPrivateKey, or ToXml.
  6. Export the public key with ToOpenSshPublicKey, ToRfc4716PublicKey, or ToXml.
  7. Save exported text with SaveText if needed.
Important: Import methods such as FromOpenSshPrivateKey and FromPuttyPrivateKey expect the actual key text, not a filename. Use LoadText first when loading from disk.

Core Concepts

Concept Meaning Important Members
Key Type The algorithm type held by the object: RSA, DSA, ECDSA, Ed25519, or none. KeyType, IsRsaKey, IsDsaKey
Private vs Public Key The object may contain either a private key or a public key. IsPrivateKey
Encrypted Private Key Some private key formats may be password-protected. Password, FromOpenSshPrivateKey, FromPuttyPrivateKey, ToOpenSshPrivateKey, ToPuttyPrivateKey
Key Format Conversion A loaded or generated key can be exported in another supported format. ToOpenSshPrivateKey, ToOpenSshPublicKey, ToPuttyPrivateKey, ToRfc4716PublicKey, ToXml
Fingerprint A compact text representation used to identify an SSH key. GenFingerprint
External Private Key A key can reference a private key stored in a PKCS#11 device. UsePkcs11

Properties

Property Purpose Guidance
Comment Holds a comment if supported by the key file format. Useful when preserving or setting descriptive text in formats that support comments.
KeyType Indicates the key type currently held by the object. Values can include rsa, dsa, ecdsa, ed25519, or none.
IsPrivateKey Indicates whether the object contains a private key. Returns false when the object contains only a public key.
IsRsaKey Indicates whether the object contains an RSA key. Use KeyType for the most complete key-type check.
IsDsaKey Indicates whether the object contains a DSA key. Use KeyType for the most complete key-type check.
Password Password used when importing or exporting encrypted private keys. Ignored for unencrypted private keys. Set before importing encrypted keys or exporting with encryption enabled.
UncommonOptions Comma-separated keywords for uncommon behavior. Normally empty. DES-EDE3-CBC uses older Triple-DES encryption instead of the default AES-128-CBC when creating encrypted OpenSSH private keys.
LastErrorText Diagnostic information for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Import Methods

Method Input Format Important Details
FromOpenSshPrivateKey OpenSSH private key text. If encrypted, set Password before calling. The argument is key content, not a filename.
FromOpenSshPublicKey OpenSSH public key text. OpenSSH public keys are typically a single line beginning with a key type such as ssh-rsa or ssh-dss.
FromPuttyPrivateKey PuTTY private key text. If encrypted, set Password before calling. The argument is key content, not a filename.
FromRfc4716PublicKey RFC 4716 SSH2 public key text. Loads public keys in the ---- BEGIN SSH2 PUBLIC KEY ---- format.
FromXml XML SSH key text. Loads an SSH key from XML. The argument is XML content, not a filename.
Loading from files: The import methods receive strings containing key data. Use LoadText to read a key file into a string, then pass that string to the appropriate From* method.

Export Methods

Method Output Format Important Details
ToOpenSshPrivateKey OpenSSH private key text. Pass true to encrypt the output using Password.
ToOpenSshPublicKey OpenSSH public key text. Produces an OpenSSH public key string suitable for public-key installation workflows.
ToPuttyPrivateKey PuTTY private key text. Pass true to encrypt the output using Password.
ToRfc4716PublicKey RFC 4716 SSH2 public key text. Exports the public key in RFC 4716 format.
ToXml XML key text. Exports the current SSH key to XML.
Private-key encryption: For methods that accept bEncrypt, set Password before exporting if encrypted output is desired.

Key Generation Methods

Method Generates Parameters / Accepted Values
GenerateRsaKey RSA public/private key pair. numBits can range from 384 to 4096. The exponent is commonly 65537.
GenerateDsaKey DSA public/private key pair. numBits should be at least 1024 and a multiple of 64.
GenerateEcdsaKey ECDSA / ECC private key. Accepted curves are secp256r1 (P-256 / prime256v1), secp384r1 (P-384), and secp521r1 (P-521).
GenerateEd25519Key Ed25519 public/private key pair. Takes no parameters.

Supported Formats at a Glance

Format Import Export Typical Use
OpenSSH private key FromOpenSshPrivateKey ToOpenSshPrivateKey Common private-key format for SSH/SFTP clients and servers.
OpenSSH public key FromOpenSshPublicKey ToOpenSshPublicKey Public-key text commonly installed in authorized_keys.
PuTTY private key FromPuttyPrivateKey ToPuttyPrivateKey PuTTY-style private key format.
RFC 4716 public key FromRfc4716PublicKey ToRfc4716PublicKey SSH2 public-key format with BEGIN SSH2 PUBLIC KEY markers.
XML key FromXml ToXml XML representation of SSH key material.

PKCS#11 and SSH Certificates

Method Purpose Use When
UsePkcs11 Uses a private key in a PKCS#11 session for SSH public-key authentication. Use when the private key is stored on an HSM, smart card, or hardware token. Both public and private key handles must be provided, along with the key type.
UseSshCertificate Loads an SSH certificate into the object. Use when SSH/SFTP public-key authentication should use an SSH certificate in place of a raw key.
SSH certificate note: An SSH certificate is not itself a public or private key, but it can be used as an SSH key for public-key authentication.

Utility Methods

Method Purpose Typical Use
GenFingerprint Generates an SSH key fingerprint. Use to display or compare a compact key identifier.
LoadText Loads an entire text file into a string. Use before calling an import method that expects key text.
SaveText Saves a string to a file. Use after exporting a key to text.

Method Summary by Category

Category Methods / Properties Purpose
Import keys FromOpenSshPrivateKey, FromOpenSshPublicKey, FromPuttyPrivateKey, FromRfc4716PublicKey, FromXml Load SSH key material from supported text formats.
Export keys ToOpenSshPrivateKey, ToOpenSshPublicKey, ToPuttyPrivateKey, ToRfc4716PublicKey, ToXml Export loaded or generated keys in supported formats.
Generate keys GenerateRsaKey, GenerateDsaKey, GenerateEcdsaKey, GenerateEd25519Key Generate new SSH public/private key pairs.
Inspect keys KeyType, IsPrivateKey, IsRsaKey, IsDsaKey, Comment, GenFingerprint Determine key type, public/private status, comments, and fingerprint.
Encrypted private keys Password, UncommonOptions Supply passwords for encrypted import/export and select uncommon encryption behavior when required.
Hardware-backed keys UsePkcs11 Use a private key that remains in a PKCS#11 device.
SSH certificates UseSshCertificate Use an SSH certificate for SSH/SFTP public-key authentication.
File helpers LoadText, SaveText Read key text from disk or save exported key text.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Import method fails FromOpenSshPrivateKey, FromPuttyPrivateKey, FromXml, LastErrorText Confirm that the argument is the full key text, not a filename, and that the correct import method is used for the format.
Encrypted private key cannot be loaded Password Set the password before calling the private-key import method.
Exported private key is not encrypted Password, ToOpenSshPrivateKey, ToPuttyPrivateKey Set Password and pass true for the encryption argument.
Wrong key type is loaded KeyType, IsRsaKey, IsDsaKey Inspect the key type after loading or generating the key.
Generated ECDSA key fails GenerateEcdsaKey Confirm the curve name is one of secp256r1, secp384r1, or secp521r1.
Generated DSA key fails GenerateDsaKey Use a bit length at least 1024 and a multiple of 64.
Need a public key from a private key ToOpenSshPublicKey, ToRfc4716PublicKey Load or generate the private key, then export the public portion in the desired format.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected import, export, generation, fingerprint, PKCS#11, SSH certificate, or file-helper operations.

Common Pitfalls

Pitfall Better Approach
Passing a filename to a From* import method. Pass the key text. Use LoadText first when the key is stored in a file.
Trying to import an encrypted key before setting Password. Set Password before calling the private-key import method.
Expecting Password to matter for unencrypted keys. The password is ignored when the private key format is not encrypted.
Exporting a private key with encryption requested but no password set. Set Password before calling ToOpenSshPrivateKey(true) or ToPuttyPrivateKey(true).
Using the RSA/DSA boolean properties as the only key-type test. Use KeyType when ECDSA, Ed25519, or none are possible.
Forgetting that an SSH certificate is not a raw key. Use UseSshCertificate when authentication should use an SSH certificate.
Ignoring diagnostics after a failed key operation. Check LastErrorText for details.

Best Practices

Recommendation Reason
Use the import method that matches the key’s actual format. OpenSSH, PuTTY, RFC 4716, and XML are different text formats.
Set Password immediately before encrypted private-key import or export. It keeps the import/export behavior clear and avoids accidental unencrypted output.
Use KeyType after loading or generating a key. It provides the clearest indication of whether the object holds RSA, DSA, ECDSA, Ed25519, or no key.
Use GenFingerprint when displaying or comparing keys. Fingerprints are easier to compare than full public key text.
Use UsePkcs11 for hardware-backed private keys. It allows public-key authentication while the private key remains on an HSM, smart card, or token.
Keep UncommonOptions empty unless a legacy encryption requirement applies. The default OpenSSH private-key export encryption is usually preferred unless older Triple-DES output is specifically needed.
Check LastErrorText after failures. It provides useful diagnostic detail for loading, saving, converting, generating, fingerprinting, and hardware/certificate key operations.

Summary

Chilkat.SshKey is the Chilkat class for SSH key import, export, conversion, generation, and inspection. It supports private and public SSH keys, encrypted private keys, OpenSSH, PuTTY, RFC 4716, and XML formats, RSA, DSA, ECDSA, and Ed25519 key types, fingerprints, comments, PKCS#11-backed private keys, and SSH certificates used for public-key authentication.

The most important practical guidance is to pass key text rather than filenames to import methods, set Password before working with encrypted private keys, use KeyType to identify the loaded key, choose the export format required by the target SSH tool or server, and inspect LastErrorText whenever an operation fails.