SshKey Chilkat2 Perl Reference Documentation
Chilkat2::SshKey
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.SshKey
Load public or private SSH keys from OpenSSH, PuTTY, RFC 4716, XML, and
other supported SSH key representations.
Convert SSH keys between supported formats for use with SSH servers,
clients, key files, configuration tools, or other systems.
Generate SSH key pairs when an application needs new authentication key
material.
Determine whether a key is public or private, identify the key type, read
comments, and compute fingerprints for verification or display.
Load or export password-protected private keys when SSH key material
must be stored securely.
Use PKCS#11-backed keys and SSH user certificates for authentication
workflows where the private key may be token-backed or certificate-based.
For an extended overview, see
SshKey Class Overview.
Import, export, generate, inspect, convert, and use SSH public or private keys.
Chilkat.SshKey represents an SSH public or private key used for
SSH authentication and key-management workflows. 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, key
comments, fingerprints, RSA, DSA, ECDSA, and Ed25519 key types, PKCS#11-backed
keys, and SSH user certificates for public-key authentication.
Import SSH keys
Export and convert
Generate key pairs
Inspect key details
Encrypted private keys
PKCS#11 and certificates
SshKey to load, generate, inspect, or convert SSH key
material, then pass the key to Chilkat.Ssh,
Chilkat.SFtp, or another SSH-based Chilkat class for public-key
authentication. Use Password when importing or exporting
encrypted private keys, and use UsePkcs11 or
UseSshCertificate when the authentication workflow depends on a
token-backed key or SSH user certificate.
Object Creation
use Chilkat2;
my $sshKey = Chilkat2::SshKey->new;
# or set properties (and RaiseError) at creation:
# my $sshKey = Chilkat2::SshKey->new(VerboseLogging => 1, RaiseError => 1);Creates the object. The optional pairs set writable properties (and RaiseError) in order, as if set one by one; an unknown or read-only name croaks. use Chilkat2; loads every class; the Chilkat2/SshKey.pm file holds only this class's documentation (perldoc Chilkat2::SshKey).
Perl frees the object when its last reference goes (undef $sshKey, or the variable going out of scope); there is nothing to close. Objects returned by methods are independent and freed the same way. The class may be subclassed (use parent -norequire, 'Chilkat2::SshKey';): an object is a blessed hash reference whose hash is free for the subclass's own fields.
When false (the default), a method that fails returns false (or undef), and the reason is in LastErrorText. When true, it dies with a Chilkat2::Error instead, as DBI does with its RaiseError. Objects returned by a method inherit the value of the object that returned them.
Errors
A Chilkat2::Error stringifies to the failed call's full LastErrorText, and has the methods text, class ('Chilkat2::SshKey'), method (the method name) and object. Methods that look something up and find nothing return undef without dying (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain boolean, and property reads and writes never fail for Chilkat reasons.
Misuse always croaks, with your file and line, whatever RaiseError is: a wrong number of arguments, a reference or undef where a string or number is expected, an object of the wrong class, an out-of-range integer, a string containing a NUL character, a wide character in a byte string, or a write to a read-only property.
Strings are Perl character strings in both directions (length, regexes and :encoding layers see characters); binary data (BinData) is a byte string. Unlocking: call Chilkat2::Global->new->UnlockBundle('...') once at startup.
Properties
Comment
my $strVal = $sshKey->Comment;
$sshKey->Comment($strVal);
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.
topDebugLogFilePath
my $strVal = $sshKey->DebugLogFilePath;
$sshKey->DebugLogFilePath($strVal);
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.
IsDsaKey
my $boolVal = $sshKey->IsDsaKey;
Indicates whether the object currently contains a DSA key.
Returns 1 for either a DSA public key or a DSA private key. Returns 0 for RSA, ECDSA, Ed25519, or when no key is loaded. Use KeyType to distinguish among all supported key types.
IsPrivateKey
my $boolVal = $sshKey->IsPrivateKey;
Indicates whether the current key includes a private key.
Returns 1 after importing or generating a private key. Returns 0 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.
topIsRsaKey
my $boolVal = $sshKey->IsRsaKey;
Indicates whether the object currently contains an RSA key.
Returns 1 for either an RSA public key or an RSA private key. Returns 0 for DSA, ECDSA, Ed25519, or when no key is loaded. Use KeyType to distinguish among all supported key types.
KeyType
my $strVal = $sshKey->KeyType;
Returns the type of key currently held by this object. A newly constructed object returns none.
LastErrorHtml
my $strVal = $sshKey->LastErrorHtml;
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.
topLastErrorText
my $strVal = $sshKey->LastErrorText;
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.
LastErrorXml
my $strVal = $sshKey->LastErrorXml;
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.
topLastMethodSuccess
my $boolVal = $sshKey->LastMethodSuccess;
$sshKey->LastMethodSuccess($boolVal);
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.
Password
my $strVal = $sshKey->Password;
$sshKey->Password($strVal);
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
ToOpenSshPrivateKeyis called withbEncryptequal to1, an empty password produces a private key encrypted with an empty passphrase. Applications should normally require a nonempty password. - When
ToPuttyPrivateKeyis called withbEncryptequal to1, this property must be nonempty.
UncommonOptions
my $strVal = $sshKey->UncommonOptions;
$sshKey->UncommonOptions($strVal);
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— WhenToOpenSshPrivateKeyexports 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.
VerboseLogging
my $boolVal = $sshKey->VerboseLogging;
$sshKey->VerboseLogging($boolVal);
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
my $strVal = $sshKey->Version;
Methods
FromOpenSshPrivateKey
# $success is true or false
my $success = $sshKey->FromOpenSshPrivateKey($keyStr);
Loads a private key from an OpenSSH-compatible, PEM, PKCS #8, or PuTTY private-key string.
Supported key types: RSA, DSA, ECDSA, and Ed25519.
$keyStr 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 $keyStr contains more than one recognized private key, the first key is loaded.
-----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY-----
SshKey object when an application must preserve an existing key.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromOpenSshPublicKey
# $success is true or false
my $success = $sshKey->FromOpenSshPublicKey($keyStr);
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.
$keyStr 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.
authorized_keys note: $keyStr must begin with the key algorithm. A complete authorized_keys entry having options such as restrict or from="..." before the algorithm is not accepted. Remove those options before calling this method.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromPuttyPrivateKey
# $success is true or false
my $success = $sshKey->FromPuttyPrivateKey($keyStr);
Loads a private key from PuTTY PPK format. PPK versions 2 and 3 are supported.
If $keyStr contains an OpenSSH, traditional PEM, or PKCS #8 private key instead, Chilkat automatically detects and imports that format.
$keyStrcontains the complete key text, not a filesystem path.- If the private key is encrypted, set
Passwordbefore 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
$keyStr; 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 on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromRfc4716PublicKey
# $success is true or false
my $success = $sshKey->FromRfc4716PublicKey($keyStr);
Loads a public key from RFC 4716 SSH2 public-key format.
$keyStr 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 on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromXml
# $success is true or false
my $success = $sshKey->FromXml($xmlKey);
Loads an SSH public or private key from an XML string.
$xmlKey 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 on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenerateDsaKey
# $success is true or false
my $success = $sshKey->GenerateDsaKey($numBits);
Generates a new DSA public/private key pair.
$numBits 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 on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenerateEcdsaKey
# $success is true or false
my $success = $sshKey->GenerateEcdsaKey($curveName);
Generates a new ECDSA public/private key pair.
$curveName selects the curve. Matching is case-insensitive. Accepted names include:
secp256r1,P-256, orprime256v1secp384r1orP-384secp521r1orP-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 on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenerateEd25519Key
my $success = $sshKey->GenerateEd25519Key();
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 on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenerateRsaKey
# $exponent is an integer
# $success is true or false
my $success = $sshKey->GenerateRsaKey($numBits, $exponent);
Generates a new RSA public/private key pair.
$numBitsspecifies the requested key size in bits. Tested supported sizes range from512through4096. For new applications, use at least2048.- The
exponentargument is ignored. Chilkat always generates RSA keys using the public exponent65537. 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 on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenFingerprint
my $str = $sshKey->GenFingerprint();
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
Commentdoes 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 undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadText
# $str is a string or undef
my $str = $sshKey->LoadText($filename);
Reads an entire text file and returns its contents as a string.
$filename 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
BinDataorFileAccessinstead.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SaveText
# $filename is a string
# $success is true or false
my $success = $sshKey->SaveText($strToSave, $filename);
Writes a string to a text file.
$strToSavecontains the text to write.$filenameis 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 on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToOpenSshPrivateKey
# $str is a string or undef
my $str = $sshKey->ToOpenSshPrivateKey($bEncrypt);
Exports the current private key as an OpenSSH-compatible private-key string.
$bEncryptequal to0returns an unencrypted private key.$bEncryptequal to1returns an encrypted private key usingPassword.- 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.
$bEncrypt is 1 and Password is empty, the method still returns a key encrypted with an empty passphrase.The output uses CRLF line endings and ends with CRLF.
-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToOpenSshPublicKey
my $str = $sshKey->ToOpenSshPublicKey();
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 undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToPuttyPrivateKey
# $str is a string or undef
my $str = $sshKey->ToPuttyPrivateKey($bEncrypt);
Exports the current private key as a PuTTY PPK string.
$bEncryptequal to0returns an unencrypted PPK.$bEncryptequal to1returns an encrypted PPK using AES-256-CBC and requires a nonemptyPassword.- 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 undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToRfc4716PublicKey
my $str = $sshKey->ToRfc4716PublicKey();
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 undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToXml
my $str = $sshKey->ToXml();
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 undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UsePkcs11
# $privKeyHandle is an integer
# $pubKeyHandle is an integer
# $keyType is a string
# $success is true or false
my $success = $sshKey->UsePkcs11($session, $privKeyHandle, $pubKeyHandle, $keyType);
Configures this object to use a private key held in a PKCS#11 token, smart card, or HSM for SSH public-key authentication.
$sessionis thePkcs11session containing the key objects.$privKeyHandleis the PKCS#11 handle of the private key.$pubKeyHandleis the PKCS#11 handle of the corresponding public key.$keyTypeidentifies the key type and must beRSAorEC.
The private-key operation is performed by the PKCS#11 device, allowing the private key to remain on the token.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
UseSshCertificate
# $success is true or false
my $success = $sshKey->UseSshCertificate($sshCert);
Associates an OpenSSH user certificate with this object for SSH or SFTP public-key authentication.
$sshCert 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 on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.