SSHKeyManager Class

Properties   Methods   Events   Config Settings   Errors  

The SSHKeyManager class provides access to SSH key management functions.

Syntax

secureblackbox.SSHKeyManager

Remarks

SSHKeyManager provides the capabilities of generating, storing, importing, and exporting SSH keys.

The SSHKeyManager class serves the following typical purposes:

• Loading private keys to be used with client-side 'public key' authentication.
• Loading private keys to be used as server host keys.
• Loading known public keys for peer authenticity validation.
• Generating new keypairs for client or server authentication.
• Changing passwords on existing keys.

Importing keys

To import a key, call one of the Import*() methods. Apart from importing from a buffer or file, SSHKeyManager lets you import keys from X.509 certificates (ImportFromCert) and raw cryptographic keys (ImportFromCryptoKey).

SSHKeyManager supports most of the widely used key formats: OpenSSH (v1 and v2), Putty (including v3), IETF, and binary.

Generating keypairs

To generate a keypair, call CreateNew, followed by Generate. The details of the newly generated key will become available in the Key object.

Once the key has been generated, save it to a file (ExportToFile) or elsewhere. Make sure to save both parts of the keypair (public and private).

Using SSHKeyManager with SSHClient and SFTPClient

One of the uses of SSHKeyManager with client-side SSH classes is for setting up private keys for client authentication. Use the component as following:

• Import the private key as described above.
• Make sure the details of the key in the Key object are correct.
• Assign the Key object to the SSH or SFTP client's Key property.

Using SSHKeyManager with SFTPServer

In a similar way, SSHKeyManager can be used to configure the host key on the server side:

• Import the private key as described above.
• Make sure the details of the Key are correct.
• Add the Key object to the SFTPServer's ServerKeys collection.

Note: you can have more than one host key attached to the server. This is often the case where the server owner wants it to support various public key algorithms.

Supported algorithms

SSHKeyManager supports all popular SSH public key algorithms: RSA, ECDSA, EdDSA, and DSS.

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

CA Property (SSHKeyManager Class)

The CA key to be used with the OpenSSH certificate.

Syntax

public SSHKey getCA();
public void setCA(SSHKey CA);

Remarks

When generating a new OpenSSH certificate, assign a private key-bearing CA key to this property.

When loading an existing OpenSSH certificate, this property will be populated with the public CA key contained in that certificate.

This property is not available at design time.

Please refer to the SSHKey type for a complete list of fields.

Certificate Property (SSHKeyManager Class)

A container for the X.509 certificate object.

Syntax

public Certificate getCertificate();
public void setCertificate(Certificate certificate);

Remarks

Use this property to set or access the properties of the certificate object on which an import or export action is to be performed.

Note that this container can only be used to access the parameters of X.509 certificates. For accessing OpenSSH certificates, please use GetKeyParamStr and SetKeyParamStr methods.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

CryptoKey Property (SSHKeyManager Class)

The key object that the manager is currently working with.

Syntax

public CryptoKey getCryptoKey();
public void setCryptoKey(CryptoKey cryptoKey);

Remarks

Use this property to pass a key to the manager (for example, for importing), or to obtain a key from the manager (e.g., after exporting to it).

This property is not available at design time.

Please refer to the CryptoKey type for a complete list of fields.

FIPSMode Property (SSHKeyManager Class)

Reserved.

Syntax

public boolean isFIPSMode();
public void setFIPSMode(boolean FIPSMode);

Default Value

False

Remarks

This property is reserved for future use.

Key Property (SSHKeyManager Class)

The key which is currently being processed.

Syntax

public SSHKey getKey();
public void setKey(SSHKey key);

Remarks

This property contains the key on which the class could operate now.

This property is not available at design time.

Please refer to the SSHKey type for a complete list of fields.

Config Method (SSHKeyManager Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateNew Method (SSHKeyManager Class)

Creates a template for a new keypair.

Syntax

public void createNew();

Remarks

This method pre-generates a template for a new key.

Adjust the properties of the Key object and call Generate to complete the generation.

DoAction Method (SSHKeyManager Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

Common ActionIDs:

ExportBytes Method (SSHKeyManager Class)

Writes the key to a memory buffer.

Syntax

public byte[] exportBytes(int format, boolean privateKey, String password);

Remarks

Use this method to save Key in the buffer. Format specifies the format in which the key should be stored, as following:

The PrivateKey parameter tells whether it the private (or public, otherwise) key should be exported. The Password defines the password that should be used to encrypt the private key.

ExportToCert Method (SSHKeyManager Class)

Exports the key to a certificate.

Syntax

public void exportToCert();

Remarks

Use this method to save the Key (both the public and secret parts) to the certificate specified in Certificate.

ExportToCryptoKey Method (SSHKeyManager Class)

Exports the key to a crypto key object.

Syntax

public void exportToCryptoKey();

Remarks

Use this method to save the Key (both the public and secret parts) to the crypto key provided via CryptoKey.

ExportToFile Method (SSHKeyManager Class)

Writes key to file.

Syntax

public void exportToFile(String fileName, int format, boolean privateKey, String password);

Remarks

Use this method to save Key in the file. Format specifies the format in which the key should be stored, as following:

The PrivateKey parameter tells whether it the private (or public, otherwise) key should be exported. Path designates the path to the file that the key should be written to, and Password defines the password that should be used to encrypt the private key.

ExportToStream Method (SSHKeyManager Class)

Writes the key to a stream.

Syntax

public void exportToStream(java.io.OutputStream stream, int format, boolean privateKey, String password);

Remarks

Use this method to save Key in the stream specified by Stream. Format specifies the format in which the key should be stored, as following:

The PrivateKey parameter tells whether it the private (or public, otherwise) key should be exported. The Password defines the password that should be used to encrypt the private key.

Generate Method (SSHKeyManager Class)

Generates a new SSH key.

Syntax

public void generate(String keyAlgorithm, String scheme, String schemeParams, int keyBits);

Remarks

Call this method to generate a new key or keypair with the desired KeyAlgorithm and KeyBits of length.

The generated key will be populated in the Key property.

The KeyAlgorithm parameter supports the following algorithm identifiers:

• RSA
• DSS
• ECDSA
• EDDSA
• MLDSA
• ECDSA-SK
• EDDSA-SK

If using ECDSA, the following curves are supported (to be passed as the Scheme parameter):

• NISTP256
• NISTP384
• NISTP521
• NISTK163
• NISTP192
• NISTP224
• NISTK233
• NISTB233
• NISTK283
• NISTK409
• NISTB409
• NISTK571

The following curves can also be used with EDDSA:

• CURVE25519
• CURVE448

The following ML-DSA variants are supported - or use blanket 'MLDSA' algorithm with explicit KeyBits setting:

• ML-DSA-44
• ML-DSA-65
• ML-DSA-87

Use the following algorithm names to generate OpenSSH certificates:

• RSA-cert, RSA-certv01
• ECDSA-cert, ECDSA-certv01
• EDDSA-cert, EDDSA-certv01

The "-cert" algorithms will generate a certificate with the standard name (e.g. ssh-rsa-cert). The "-certv01" algorithms will generate a certificate with the respective vendor-extension name (e.g. ssh-rsa-cert-v01@openssh.com). While the latter are widely use in real world, it is expected that once the standard is published implementations will switch to the standard naming.

// generating a curve25519 keypair KeyMgr.Generate("EDDSA", "CURVE25519", "", 0); // KeyBits is irrelevant for this fixed-length scheme // generating an ECDSA/P521 key KeyMgr.Generate("ECDSA", "NISTP521", "", 521); // generating an RSA key KeyMgr.Generate("RSA", "", "", 2048); // generating a Ed25519 OpenSSH certificate with vendor-extension name KeyMgr.Generate("EDDSA-certv01", "CURVE25519", "", 0); KeyMgr.ExportToFile(Path, ckfOpenSSHCert, false, ""); // exporting the certificate file KeyMgr.ExportToFile(Path + ".priv", ckfOpenSSH2, true, ""); // exporting the private key

GenerateCert Method (SSHKeyManager Class)

Generates a new OpenSSH certificate.

Syntax

public void generateCert(String keyAlgorithm, String scheme, String schemeParams, int keyBits, int serialNumber, int role, String identifier, String principals, String validFrom, String validTo, String pars);

Remarks

Call this method to generate a new OpenSSH certificate with the desired parameters.

OpenSSH certificates are extended cryptographic entities that, unlike generic SSH keys, can provide association between the cryptographic material of the key and the persona of their owner. Certificates include information about their holder, such as a username or a host name, can be constrained to a certain validity period, and include additional permissions or restrictions, such as which commands the holder is allowed to issue.

Every OpenSSH certificate must be signed by a separate private key, called a CA (certifying authority), at the time of its creation. A CA key is a generic OpenSSH key owned by the certificate issuer - for example, a server or network administrator. The public part of the CA key becomes part of the certificate and can be used by to validate the certificate:

• the validating party first checks that the CA key embedded in the certificate is trusted, in the same way as it does for generic keys (e.g. by checking the .ssh directory or confirming the fingerprint with the user).
• if the CA key is valid and trusted, it checks the integrity of its signature over the certificate data.
• finally, it validates that the information contained in the certificate - such as the hostname - matches the host they intend to connect to.

Certificates provide multiple benefits for SSH key ecosystem, such as capabilities to set up implicit trust relationships, manage users centrally, and include key usage policies within the keys themselves. Just like generic keys, certificates can be used for both host and user authentication.

Note that OpenSSH certificates are not related to PKI (X.509) certificates in any way. They offer a somewhat similar, yet entirely different authentication mechanism.

You can choose to use this method to generate a certificate over a fresh new cryptographic keypair or a pre-existing SSH key. In the latter case, load the existing SSH key into SSHKeyManager first using ImportFromFile or similar methods. When a certificate is generated over an existing key, the algorithm and scheme parameters are discarded.

The KeyAlgorithm parameter supports the following algorithm identifiers:

• RSA
• DSS
• ECDSA
• EDDSA
• MLDSA
• ECDSA-SK
• EDDSA-SK

If using ECDSA, the following curves are supported (to be passed as the Scheme parameter):

• NISTP256
• NISTP384
• NISTP521
• NISTK163
• NISTP192
• NISTP224
• NISTK233
• NISTB233
• NISTK283
• NISTK409
• NISTB409
• NISTK571

The following curves can also be used with EDDSA:

• CURVE25519
• CURVE448

The following ML-DSA variants are supported - or use blanket 'MLDSA' algorithm with explicit KeyBits setting:

• ML-DSA-44
• ML-DSA-65
• ML-DSA-87

Just as with using the Generate method, you can use certificate-related algorithm aliases:

• RSA-cert, RSA-certv01
• ECDSA-cert, ECDSA-certv01
• EDDSA-cert, EDDSA-certv01

The "-cert" algorithms will generate a certificate with the standard name (e.g. ssh-rsa-cert). The "-certv01" algorithms will generate a certificate with the respective vendor-extension name (e.g. ssh-rsa-cert-v01@openssh.com). While the latter are widely use in real world, it is expected that once the standard is published implementations will switch to the standard naming.

Unlike the Generate method, this method will always generate a certificate, even if a generic (e.g. RSA) algorithm name is provided to the Algorithm parameter. In that case the algorithm will be extended to the certificate-specific algorithm name (RSA-cert in this case). Note that the component will always apply the 'final' "-cert" algorithm name, so if you are looking to generate a certificate with an interim "-cert-v01@openssh.com" key, please use the RSA-certv01 syntax.

// generating a client-side Ed25519 OpenSSH certificate with vendor-extension ('draft') name KeyMgr.GenerateCert("EDDSA-certv01", "CURVE25519", "", 0, 12, 1 { user }, "John Peters Workstation", "johnp", "", "2029-12-31", ""); KeyMgr.ExportToFile(Path, ckfOpenSSHCert, false, ""); // exporting the certificate file KeyMgr.ExportToFile(Path + ".priv", ckfOpenSSH2, true, ""); // exporting the private key // generating a host-side RSA OpenSSH certificate with RFC name KeyMgr.GenerateCert("RSA", "", "", 2048, 1001, 2 { host }, "Local File Server", "fileserver", "192.168.1.91", "", ""); KeyMgr.ExportToFile(Path, ckfOpenSSHCert, false, ""); // exporting the certificate file KeyMgr.ExportToFile(Path + ".priv", ckfOpenSSH2, true, ""); // exporting the private key

GetKeyParam Method (SSHKeyManager Class)

Returns an key-specific key parameter.

Syntax

public byte[] getKeyParam(String name);

Remarks

Use this method to retrieve a binary key parameter.

The following parameters are currently supported:

GetKeyParamStr Method (SSHKeyManager Class)

Returns an algorithm-specific key parameter to a string.

Syntax

public String getKeyParamStr(String name);

Remarks

Use this method to get a key parameter to a string.

The following parameters are currently supported:

ImportBytes Method (SSHKeyManager Class)

Loads key from buffer.

Syntax

public void importBytes(byte[] bytes, String password);

Remarks

Use this method to read a key stored in a buffer. Password specifies a password to decrypt the private key.

This method automatically recognizes the format that the key is stored in.

ImportFromCert Method (SSHKeyManager Class)

Loads a key from an X.509 certificate.

Syntax

public void importFromCert();

Remarks

Use this method to load a key, either public or secret, from an X.509 certificate.

ImportFromCryptoKey Method (SSHKeyManager Class)

Imports a key from a crypto key.

Syntax

public void importFromCryptoKey();

Remarks

Use this method to load a key, either public or private, from a crypto key. Provide the key via CryptoKey property.

ImportFromFile Method (SSHKeyManager Class)

Loads key from file.

Syntax

public void importFromFile(String path, String password);

Remarks

Use this method to read a key stored in a file. Path specifies the full path to the file, Password is a password to decrypt the private key.

This method automatically recognizes the format that the key is stored in.

ImportFromStream Method (SSHKeyManager Class)

Loads key from stream.

Syntax

public void importFromStream(java.io.InputStream stream, String password);

Remarks

Use this method to read a key stored in a stream. Password specifies a password to decrypt the private key.

This method automatically recognizes the format that the key is stored in.

Reset Method (SSHKeyManager Class)

Resets the class settings.

Syntax

public void reset();

Remarks

Reset is a generic method available in every class.

SetKeyParam Method (SSHKeyManager Class)

Sets a key-specific key parameter.

Syntax

public void setKeyParam(String name, byte[] value);

Remarks

Use this method to set a key- or algorithm-specific key parameter.

The following parameters are currently supported:

SetKeyParamStr Method (SSHKeyManager Class)

Sets a key-specific key parameter.

Syntax

public void setKeyParamStr(String name, String valueStr);

Remarks

Use this method to set a key-specific or algorithm-specific key parameter provided in a string.

The following parameters are currently supported:

The below example shows the use of key parameters for setting up the details of an OpenSSH certificate: mgr.CreateNew(); mgr.SetKeyParamStr("CertSerialNumber", "1984"); mgr.SetKeyParamStr("CertRole", "user"); mgr.SetKeyParamStr("CertIdentifier", "New OpenSSH certificate"); mgr.SetKeyParamStr("CertPrincipals", "john\r\njane"); mgr.SetKeyParamStr("CertValidFrom", "2026-01-01 12:34:56"); mgr.SetKeyParamStr("CertValidTo", "2029-01-01 12:34:56"); // adding a critical option explicitly mgr.SetKeyParamStr("CertCriticalOptionCount", '1'); mgr.SetKeyParamStr("CertCriticalOptions[0]", 'force-command'); mgr.SetKeyParamStr("CertCriticalOptionValues[0]", "\x0\x0\x0\x5ls -l"); // adding a known critical option using a shortcut mgr.SetKeyParamStr("CertCriticalOptionValues[verify-required]", ""); mgr.SetKeyParamStr("CertCriticalOptionValues[source-address]", "\x0\x0\x0\x1D" + "127.0.0.1,127.0.0.2,127.0.0.3"); // same syntax applies to extensions mgr.SetKeyParamStr("CertExtensionCount", "1"); mgr.SetKeyParamStr("CertExtensions[0]", "permit-pty"); mgr.SetKeyParamStr("CertExtensionValues[permit-port-forwarding]", ""); // setting the private CA key bytes := otherMgr.ExportBytes(ckfOpenSSH2, true, ""); mgr.SetKeyParam("CertSigningKey", bytes); mgr.Generate("EDDSA-certv01", "CURVE25519", "", 0); mgr.ExportToFile(Path, ckfOpenSSHCert, false, ""); mgr.ExportToFile(Path + ".priv", ckfOpenSSH2, true, "");

Error Event (SSHKeyManager Class)

Information about errors during SSH key management.

Syntax

public class DefaultSSHKeyManagerEventListener implements SSHKeyManagerEventListener {
  ...
  public void error(SSHKeyManagerErrorEvent e) {}
  ...
}

public class SSHKeyManagerErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The event is fired in case of exceptional conditions during key management.

ErrorCode contains an error code and Description contains a textual description of the error.

Notification Event (SSHKeyManager Class)

This event notifies the application about an underlying control flow event.

Syntax

public class DefaultSSHKeyManagerEventListener implements SSHKeyManagerEventListener {
  ...
  public void notification(SSHKeyManagerNotificationEvent e) {}
  ...
}

public class SSHKeyManagerNotificationEvent {
  public String eventID;
  public String eventParam;
}

Remarks

The class fires this event to let the application know about some event, occurrence, or milestone in the class. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the class, the exact action it is performing, or the document being processed, one or both may be omitted.

Certificate Type

Encapsulates an individual X.509 certificate.

Remarks

This type keeps and provides access to X.509 certificate details.

• Bytes
• CA
• CAKeyID
• CertType
• CRLDistributionPoints
• Curve
• Fingerprint
• FriendlyName
• HashAlgorithm
• Issuer
• IssuerRDN
• KeyAlgorithm
• KeyBits
• KeyFingerprint
• KeyUsage
• KeyValid
• OCSPLocations
• OCSPNoCheck
• Origin
• PolicyIDs
• PrivateKeyBytes
• PrivateKeyExists
• PrivateKeyExtractable
• PublicKeyBytes
• Qualified
• QualifiedStatements
• Qualifiers
• SelfSigned
• SerialNumber
• SigAlgorithm
• Source
• Subject
• SubjectAlternativeName
• SubjectKeyID
• SubjectRDN
• Valid
• ValidFrom
• ValidTo

Fields

Constructors

public Certificate(byte[] bytes, int startIndex, int count, String password);

public Certificate(byte[] certBytes, int certStartIndex, int certCount, byte[] keyBytes, int keyStartIndex, int keyCount, String password);

public Certificate(byte[] bytes, int startIndex, int count);

public Certificate(String path, String password);

public Certificate(String certPath, String keyPath, String password);

public Certificate(String path);

public Certificate(java.io.InputStream stream);

public Certificate(java.io.InputStream stream, String password);

public Certificate(java.io.InputStream certStream, java.io.InputStream keyStream, String password);

public Certificate();

CryptoKey Type

This container represents a cryptographic key.

Remarks

This type is a universal placeholder for cryptographic keys.

Version 2026 upgrade note: granular key parameter properties (RSAModulus, EdPublic, DSSP and others) have been removed from this type and are now available via the CryptoKeyManager.GetKeyParam method.

• Algorithm
• Bits
• Curve
• Exportable
• Fingerprint
• ID
• IV
• Nonce
• Private
• Public
• Subject
• Symmetric
• Valid
• Value

Fields

Constructors

public CryptoKey();

SSHKey Type

SSHKey is used to store information about single compound public-key algorithm (such as RSA or DSA) key.

Remarks

SSH keys are used to secure the SSH protocol flow. They support different algorithms and key lengths, a very typical example being RSA-2048 bits.

• Algorithm
• Bits
• Comment
• Curve
• Extractable
• FingerprintMD5
• FingerprintSHA1
• FingerprintSHA256
• KeyFormat
• KeyProtectionAlgorithm
• Private
• Public
• Subject

Fields

Constructors

public SSHKey(byte[] bytes, int startIndex, int count, String password);

public SSHKey(byte[] bytes, int startIndex, int count);

public SSHKey(java.io.InputStream stream, String password);

public SSHKey(java.io.InputStream stream);

public SSHKey(String path, String password);

public SSHKey(String path);

public SSHKey();

Config Settings (SSHKeyManager Class)

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

SSHKeyManager Config Settings

Base Config Settings

Trappable Errors (SSHKeyManager Class)

SSHKeyManager Errors