SshKey SQL Server Reference Documentation
SshKey
Current Version: 11.6.0
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
DECLARE @hr int
DECLARE @sshKey int
EXEC @hr = sp_OACreate 'Chilkat.SshKey', @sshKey OUT
IF @hr <> 0
BEGIN
PRINT 'Failed to create ActiveX component'
RETURN
END
-- ... use @sshKey ...
EXEC @hr = sp_OADestroy @sshKeyT-SQL uses the Chilkat ActiveX through the OLE Automation stored procedures. They must be enabled once on the server (EXEC sp_configure 'Ole Automation Procedures', 1; RECONFIGURE;), and the Chilkat ActiveX registered must match the bitness of the SQL Server instance (64-bit for a 64-bit SQL Server). To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as sp_OACreate 'Chilkat.SshKey.11' for Chilkat v11.*.*.
sp_OACreate returns an object token (an int) that is passed as the first argument of every sp_OAMethod, sp_OAGetProperty and sp_OASetProperty call, and released with sp_OADestroy. Objects returned by methods (such as an HttpResponse or JsonObject) are also tokens received through an int OUT parameter; they must likewise be destroyed, and the OUT parameter is NULL when the method fails to return an object. Objects passed as arguments are passed by their token. When an OLE Automation procedure itself fails (non-zero @hr), sp_OAGetErrorInfo describes the error.
Data types: strings are nvarchar(4000); integers, booleans (1 or 0) and object tokens are int; dates are datetime. In the signatures on this page, @success, @iResult, @sResult and the like are the OUT variables receiving a method's return value, @iValue / @sValue receive or supply a property value, and the remaining @ variables are the method's arguments in order.
A string returned through an OUT parameter is limited to 4000 characters. For longer values, retrieve the result as a result set into a table variable instead of an OUT parameter, for example DECLARE @tmp TABLE (outputLine ntext) followed by INSERT INTO @tmp EXEC sp_OAGetProperty @sshKey, 'LastErrorText'. See string length limitations for strings returned by sp_OAMethod calls.
Methods that pass or return raw byte arrays are not shown on this page, because varbinary(max) values cannot be exchanged through sp_OAMethod (see varbinary(max) limitation). Use the BinData-based alternatives (methods ending in Bd) or the base64 / hex string-encoded variants instead. Binary properties (such as LastBinaryResult) can be retrieved as a result set into a table variable, as shown in their signatures. Asynchronous (*Async) methods and event callbacks are not available from SQL Server.
Properties
Comment
EXEC sp_OASetProperty @sshKey, 'Comment', @sValue
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
EXEC sp_OASetProperty @sshKey, 'DebugLogFilePath', @sValue
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
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
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
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
Returns the type of key currently held by this object. A newly constructed object returns none.
LastBinaryResult
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.
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
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
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
EXEC sp_OASetProperty @sshKey, 'LastMethodSuccess', @iValue
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.
LastStringResult
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.
LastStringResultLen
The length, in characters, of the string contained in the LastStringResult property.
topPassword
EXEC sp_OASetProperty @sshKey, 'Password', @sValue
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
EXEC sp_OASetProperty @sshKey, 'UncommonOptions', @sValue
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
EXEC sp_OASetProperty @sshKey, 'VerboseLogging', @iValue
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
Methods
FromOpenSshPrivateKey
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 1 for success, 0 for failure.
FromOpenSshPublicKey
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 1 for success, 0 for failure.
FromPuttyPrivateKey
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 1 for success, 0 for failure.
FromRfc4716PublicKey
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 1 for success, 0 for failure.
FromXml
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 1 for success, 0 for failure.
topGenerateDsaKey
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 1 for success, 0 for failure.
GenerateEcdsaKey
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 1 for success, 0 for failure.
topGenerateEd25519Key
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 1 for success, 0 for failure.
GenerateRsaKey
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 1 for success, 0 for failure.
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 NULL on failure
LoadText
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 NULL on failure
SaveText
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 1 for success, 0 for failure.
topToOpenSshPrivateKey
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 NULL on failure
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 NULL on failure
ToPuttyPrivateKey
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 NULL on failure
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 NULL on failure
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 NULL on failure
UsePkcs11
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 1 for success, 0 for failure.
UseSshCertificate
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 1 for success, 0 for failure.