SSHKeyManager Class

Properties   Methods   Events   Config Settings   Errors  

The SSHKeyManager class provides access to SSH key management functions.

Class Name

SecureBlackbox_SSHKeyManager

Procedural Interface

 secureblackbox_sshkeymanager_open();
 secureblackbox_sshkeymanager_close($res);
 secureblackbox_sshkeymanager_register_callback($res, $id, $function);
 secureblackbox_sshkeymanager_get_last_error($res);
 secureblackbox_sshkeymanager_get_last_error_code($res);
 secureblackbox_sshkeymanager_set($res, $id, $index, $value);
 secureblackbox_sshkeymanager_get($res, $id, $index);
 secureblackbox_sshkeymanager_do_config($res, $configurationstring);
 secureblackbox_sshkeymanager_do_createnew($res);
 secureblackbox_sshkeymanager_do_doaction($res, $actionid, $actionparams);
 secureblackbox_sshkeymanager_do_exportbytes($res, $format, $privatekey, $password);
 secureblackbox_sshkeymanager_do_exporttocert($res);
 secureblackbox_sshkeymanager_do_exporttocryptokey($res);
 secureblackbox_sshkeymanager_do_exporttofile($res, $filename, $format, $privatekey, $password);
 secureblackbox_sshkeymanager_do_generate($res, $keyalgorithm, $scheme, $schemeparams, $keybits);
 secureblackbox_sshkeymanager_do_generatecert($res, $keyalgorithm, $scheme, $schemeparams, $keybits, $serialnumber, $role, $identifier, $principals, $validfrom, $validto, $pars);
 secureblackbox_sshkeymanager_do_getkeyparam($res, $name);
 secureblackbox_sshkeymanager_do_getkeyparamstr($res, $name);
 secureblackbox_sshkeymanager_do_importbytes($res, $bytes, $password);
 secureblackbox_sshkeymanager_do_importfromcert($res);
 secureblackbox_sshkeymanager_do_importfromcryptokey($res);
 secureblackbox_sshkeymanager_do_importfromfile($res, $path, $password);
 secureblackbox_sshkeymanager_do_reset($res);
 secureblackbox_sshkeymanager_do_setkeyparam($res, $name, $value);
 secureblackbox_sshkeymanager_do_setkeyparamstr($res, $name, $valuestr);

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.

CAAlgorithm Property (SecureBlackbox_SSHKeyManager Class)

Specifies the key algorithm.

Object Oriented Interface

public function getCAAlgorithm();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 1 );

Default Value

''

Remarks

Specifies the key algorithm.

The following key algorithms are currently supported and can be returned by this property:

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

This property is read-only and not available at design time.

Data Type

String

CABits Property (SecureBlackbox_SSHKeyManager Class)

The number of bits in the key: the more the better, 2048 or 4096 are typical values.

Object Oriented Interface

public function getCABits();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 2 );

Default Value

0

Remarks

The number of bits in the key: the more the better, 2048 or 4096 are typical values.

This property is read-only and not available at design time.

Data Type

Integer

CAComment Property (SecureBlackbox_SSHKeyManager Class)

The comment for the public key.

Object Oriented Interface

public function getCAComment();
public function setCAComment($value);

Procedural Interface

secureblackbox_sshkeymanager_get($res, 3 );
secureblackbox_sshkeymanager_set($res, 3, $value );

Default Value

''

Remarks

The comment for the public key.

This property is not available at design time.

Data Type

String

CACurve Property (SecureBlackbox_SSHKeyManager Class)

Specifies the elliptical curve when EC cryptography is used.

Object Oriented Interface

public function getCACurve();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 4 );

Default Value

''

Remarks

Specifies the elliptical curve when EC cryptography is used.

The following curves are currently supported:

• NISTP256
• NISTP384
• NISTP521
• NISTK163
• NISTP192
• NISTP224
• NISTK233
• NISTB233
• NISTK283
• NISTK409
• NISTB409
• NISTK571
• CURVE25519 (EdDSA curve)
• CURVE448 (EdDSA curve)

This property is read-only and not available at design time.

Data Type

String

CAExtractable Property (SecureBlackbox_SSHKeyManager Class)

Whether the key is extractable (e.

Object Oriented Interface

public function getCAExtractable();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 5 );

Default Value

false

Remarks

Whether the key is extractable (e.g., from a security token), or not.

This property is read-only and not available at design time.

Data Type

Boolean

CAFingerprintMD5 Property (SecureBlackbox_SSHKeyManager Class)

Contains the MD5 fingerprint (hash) of the key.

Object Oriented Interface

public function getCAFingerprintMD5();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 6 );

Default Value

''

Remarks

Contains the MD5 fingerprint (hash) of the key.

This property is read-only and not available at design time.

Data Type

String

CAFingerprintSHA1 Property (SecureBlackbox_SSHKeyManager Class)

Contains the SHA-1 fingerprint (hash) of the key.

Object Oriented Interface

public function getCAFingerprintSHA1();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 7 );

Default Value

''

Remarks

Contains the SHA-1 fingerprint (hash) of the key.

This property is read-only and not available at design time.

Data Type

String

CAFingerprintSHA256 Property (SecureBlackbox_SSHKeyManager Class)

Contains the SHA-256 fingerprint (hash) of the key.

Object Oriented Interface

public function getCAFingerprintSHA256();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 8 );

Default Value

''

Remarks

Contains the SHA-256 fingerprint (hash) of the key.

This property is read-only and not available at design time.

Data Type

String

CAHandle Property (SecureBlackbox_SSHKeyManager Class)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Object Oriented Interface

public function getCAHandle();
public function setCAHandle($value);

Procedural Interface

secureblackbox_sshkeymanager_get($res, 9 );
secureblackbox_sshkeymanager_set($res, 9, $value );

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

This property is not available at design time.

Data Type

Long64

CAKeyFormat Property (SecureBlackbox_SSHKeyManager Class)

Specifies the format in which the key is stored.

Object Oriented Interface

public function getCAKeyFormat();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 10 );

Possible Values

SSHKEYMANAGER_CAKEYFORMAT_OPEN_SSH(0), 
SSHKEYMANAGER_CAKEYFORMAT_OPEN_SSH2(1), 
SSHKEYMANAGER_CAKEYFORMAT_IETF(2), 
SSHKEYMANAGER_CAKEYFORMAT_PU_TTY(3), 
SSHKEYMANAGER_CAKEYFORMAT_X509(4), 
SSHKEYMANAGER_CAKEYFORMAT_BINARY(5), 
SSHKEYMANAGER_CAKEYFORMAT_SSH1(6), 
SSHKEYMANAGER_CAKEYFORMAT_PGP(7), 
SSHKEYMANAGER_CAKEYFORMAT_PKCS8(8), 
SSHKEYMANAGER_CAKEYFORMAT_PU_TTY3(9), 
SSHKEYMANAGER_CAKEYFORMAT_OPEN_SSHCERT(10)

Default Value

0

Remarks

Specifies the format in which the key is stored.

This property is read-only and not available at design time.

Data Type

Integer

CAKeyProtectionAlgorithm Property (SecureBlackbox_SSHKeyManager Class)

Specifies the key protection algorithm.

Object Oriented Interface

public function getCAKeyProtectionAlgorithm();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 11 );

Default Value

''

Remarks

Specifies the key protection algorithm.

This property is read-only and not available at design time.

Data Type

String

CAPrivate Property (SecureBlackbox_SSHKeyManager Class)

Whether this key is a private key or not.

Object Oriented Interface

public function getCAPrivate();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 12 );

Default Value

false

Remarks

Whether this key is a private key or not.

This property is read-only and not available at design time.

Data Type

Boolean

CAPublic Property (SecureBlackbox_SSHKeyManager Class)

Whether this key is a public key or not.

Object Oriented Interface

public function getCAPublic();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 13 );

Default Value

false

Remarks

Whether this key is a public key or not.

This property is read-only and not available at design time.

Data Type

Boolean

CASubject Property (SecureBlackbox_SSHKeyManager Class)

Specifies the public key owner (subject).

Object Oriented Interface

public function getCASubject();
public function setCASubject($value);

Procedural Interface

secureblackbox_sshkeymanager_get($res, 14 );
secureblackbox_sshkeymanager_set($res, 14, $value );

Default Value

''

Remarks

Specifies the public key owner (subject). This property is used only for IETF-keys.

This property is not available at design time.

Data Type

String

CertBytes Property (SecureBlackbox_SSHKeyManager Class)

Returns the raw certificate data in DER format.

Object Oriented Interface

public function getCertBytes();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 15 );

Remarks

Returns the raw certificate data in DER format.

This property is read-only and not available at design time.

Data Type

Byte Array

CertHandle Property (SecureBlackbox_SSHKeyManager Class)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Object Oriented Interface

public function getCertHandle();
public function setCertHandle($value);

Procedural Interface

secureblackbox_sshkeymanager_get($res, 23 );
secureblackbox_sshkeymanager_set($res, 23, $value );

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

This property is not available at design time.

Data Type

Long64

CryptoKeyHandle Property (SecureBlackbox_SSHKeyManager Class)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Object Oriented Interface

public function getCryptoKeyHandle();
public function setCryptoKeyHandle($value);

Procedural Interface

secureblackbox_sshkeymanager_get($res, 59 );
secureblackbox_sshkeymanager_set($res, 59, $value );

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

This property is not available at design time.

Data Type

Long64

FIPSMode Property (SecureBlackbox_SSHKeyManager Class)

Reserved.

Object Oriented Interface

public function getFIPSMode();
public function setFIPSMode($value);

Procedural Interface

secureblackbox_sshkeymanager_get($res, 69 );
secureblackbox_sshkeymanager_set($res, 69, $value );

Default Value

false

Remarks

This property is reserved for future use.

Data Type

Boolean

KeyAlgorithm Property (SecureBlackbox_SSHKeyManager Class)

Specifies the key algorithm.

Object Oriented Interface

public function getKeyAlgorithm();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 70 );

Default Value

''

Remarks

Specifies the key algorithm.

The following key algorithms are currently supported and can be returned by this property:

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

This property is read-only and not available at design time.

Data Type

String

KeyBits Property (SecureBlackbox_SSHKeyManager Class)

The number of bits in the key: the more the better, 2048 or 4096 are typical values.

Object Oriented Interface

public function getKeyBits();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 71 );

Default Value

0

Remarks

The number of bits in the key: the more the better, 2048 or 4096 are typical values.

This property is read-only and not available at design time.

Data Type

Integer

KeyComment Property (SecureBlackbox_SSHKeyManager Class)

The comment for the public key.

Object Oriented Interface

public function getKeyComment();
public function setKeyComment($value);

Procedural Interface

secureblackbox_sshkeymanager_get($res, 72 );
secureblackbox_sshkeymanager_set($res, 72, $value );

Default Value

''

Remarks

The comment for the public key.

This property is not available at design time.

Data Type

String

KeyCurve Property (SecureBlackbox_SSHKeyManager Class)

Specifies the elliptical curve when EC cryptography is used.

Object Oriented Interface

public function getKeyCurve();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 73 );

Default Value

''

Remarks

Specifies the elliptical curve when EC cryptography is used.

The following curves are currently supported:

• NISTP256
• NISTP384
• NISTP521
• NISTK163
• NISTP192
• NISTP224
• NISTK233
• NISTB233
• NISTK283
• NISTK409
• NISTB409
• NISTK571
• CURVE25519 (EdDSA curve)
• CURVE448 (EdDSA curve)

This property is read-only and not available at design time.

Data Type

String

KeyExtractable Property (SecureBlackbox_SSHKeyManager Class)

Whether the key is extractable (e.

Object Oriented Interface

public function getKeyExtractable();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 74 );

Default Value

false

Remarks

Whether the key is extractable (e.g., from a security token), or not.

This property is read-only and not available at design time.

Data Type

Boolean

KeyFingerprintMD5 Property (SecureBlackbox_SSHKeyManager Class)

Contains the MD5 fingerprint (hash) of the key.

Object Oriented Interface

public function getKeyFingerprintMD5();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 75 );

Default Value

''

Remarks

Contains the MD5 fingerprint (hash) of the key.

This property is read-only and not available at design time.

Data Type

String

KeyFingerprintSHA1 Property (SecureBlackbox_SSHKeyManager Class)

Contains the SHA-1 fingerprint (hash) of the key.

Object Oriented Interface

public function getKeyFingerprintSHA1();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 76 );

Default Value

''

Remarks

Contains the SHA-1 fingerprint (hash) of the key.

This property is read-only and not available at design time.

Data Type

String

KeyFingerprintSHA256 Property (SecureBlackbox_SSHKeyManager Class)

Contains the SHA-256 fingerprint (hash) of the key.

Object Oriented Interface

public function getKeyFingerprintSHA256();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 77 );

Default Value

''

Remarks

Contains the SHA-256 fingerprint (hash) of the key.

This property is read-only and not available at design time.

Data Type

String

KeyHandle Property (SecureBlackbox_SSHKeyManager Class)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Object Oriented Interface

public function getKeyHandle();
public function setKeyHandle($value);

Procedural Interface

secureblackbox_sshkeymanager_get($res, 78 );
secureblackbox_sshkeymanager_set($res, 78, $value );

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

This property is not available at design time.

Data Type

Long64

KeyFormat Property (SecureBlackbox_SSHKeyManager Class)

Specifies the format in which the key is stored.

Object Oriented Interface

public function getKeyFormat();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 79 );

Possible Values

SSHKEYMANAGER_KEYFORMAT_OPEN_SSH(0), 
SSHKEYMANAGER_KEYFORMAT_OPEN_SSH2(1), 
SSHKEYMANAGER_KEYFORMAT_IETF(2), 
SSHKEYMANAGER_KEYFORMAT_PU_TTY(3), 
SSHKEYMANAGER_KEYFORMAT_X509(4), 
SSHKEYMANAGER_KEYFORMAT_BINARY(5), 
SSHKEYMANAGER_KEYFORMAT_SSH1(6), 
SSHKEYMANAGER_KEYFORMAT_PGP(7), 
SSHKEYMANAGER_KEYFORMAT_PKCS8(8), 
SSHKEYMANAGER_KEYFORMAT_PU_TTY3(9), 
SSHKEYMANAGER_KEYFORMAT_OPEN_SSHCERT(10)

Default Value

0

Remarks

Specifies the format in which the key is stored.

This property is read-only and not available at design time.

Data Type

Integer

KeyProtectionAlgorithm Property (SecureBlackbox_SSHKeyManager Class)

Specifies the key protection algorithm.

Object Oriented Interface

public function getKeyProtectionAlgorithm();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 80 );

Default Value

''

Remarks

Specifies the key protection algorithm.

This property is read-only and not available at design time.

Data Type

String

KeyPrivate Property (SecureBlackbox_SSHKeyManager Class)

Whether this key is a private key or not.

Object Oriented Interface

public function getKeyPrivate();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 81 );

Default Value

false

Remarks

Whether this key is a private key or not.

This property is read-only and not available at design time.

Data Type

Boolean

KeyPublic Property (SecureBlackbox_SSHKeyManager Class)

Whether this key is a public key or not.

Object Oriented Interface

public function getKeyPublic();

Procedural Interface

secureblackbox_sshkeymanager_get($res, 82 );

Default Value

false

Remarks

Whether this key is a public key or not.

This property is read-only and not available at design time.

Data Type

Boolean

KeySubject Property (SecureBlackbox_SSHKeyManager Class)

Specifies the public key owner (subject).

Object Oriented Interface

public function getKeySubject();
public function setKeySubject($value);

Procedural Interface

secureblackbox_sshkeymanager_get($res, 83 );
secureblackbox_sshkeymanager_set($res, 83, $value );

Default Value

''

Remarks

Specifies the public key owner (subject). This property is used only for IETF-keys.

This property is not available at design time.

Data Type

String

Config Method (SecureBlackbox_SSHKeyManager Class)

Sets or retrieves a configuration setting.

Object Oriented Interface

public function doConfig($configurationstring);

Procedural Interface

secureblackbox_sshkeymanager_do_config($res, $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 (SecureBlackbox_SSHKeyManager Class)

Creates a template for a new keypair.

Object Oriented Interface

public function doCreateNew();

Procedural Interface

secureblackbox_sshkeymanager_do_createnew($res);

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 (SecureBlackbox_SSHKeyManager Class)

Performs an additional action.

Object Oriented Interface

public function doDoAction($actionid, $actionparams);

Procedural Interface

secureblackbox_sshkeymanager_do_doaction($res, $actionid, $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 (SecureBlackbox_SSHKeyManager Class)

Writes the key to a memory buffer.

Object Oriented Interface

public function doExportBytes($format, $privatekey, $password);

Procedural Interface

secureblackbox_sshkeymanager_do_exportbytes($res, $format, $privatekey, $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 (SecureBlackbox_SSHKeyManager Class)

Exports the key to a certificate.

Object Oriented Interface

public function doExportToCert();

Procedural Interface

secureblackbox_sshkeymanager_do_exporttocert($res);

Remarks

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

ExportToCryptoKey Method (SecureBlackbox_SSHKeyManager Class)

Exports the key to a crypto key object.

Object Oriented Interface

public function doExportToCryptoKey();

Procedural Interface

secureblackbox_sshkeymanager_do_exporttocryptokey($res);

Remarks

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

ExportToFile Method (SecureBlackbox_SSHKeyManager Class)

Writes key to file.

Object Oriented Interface

public function doExportToFile($filename, $format, $privatekey, $password);

Procedural Interface

secureblackbox_sshkeymanager_do_exporttofile($res, $filename, $format, $privatekey, $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.

Generate Method (SecureBlackbox_SSHKeyManager Class)

Generates a new SSH key.

Object Oriented Interface

public function doGenerate($keyalgorithm, $scheme, $schemeparams, $keybits);

Procedural Interface

secureblackbox_sshkeymanager_do_generate($res, $keyalgorithm, $scheme, $schemeparams, $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 (SecureBlackbox_SSHKeyManager Class)

Generates a new OpenSSH certificate.

Object Oriented Interface

public function doGenerateCert($keyalgorithm, $scheme, $schemeparams, $keybits, $serialnumber, $role, $identifier, $principals, $validfrom, $validto, $pars);

Procedural Interface

secureblackbox_sshkeymanager_do_generatecert($res, $keyalgorithm, $scheme, $schemeparams, $keybits, $serialnumber, $role, $identifier, $principals, $validfrom, $validto, $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 (SecureBlackbox_SSHKeyManager Class)

Returns an key-specific key parameter.

Object Oriented Interface

public function doGetKeyParam($name);

Procedural Interface

secureblackbox_sshkeymanager_do_getkeyparam($res, $name);

Remarks

Use this method to retrieve a binary key parameter.

The following parameters are currently supported:

GetKeyParamStr Method (SecureBlackbox_SSHKeyManager Class)

Returns an algorithm-specific key parameter to a string.

Object Oriented Interface

public function doGetKeyParamStr($name);

Procedural Interface

secureblackbox_sshkeymanager_do_getkeyparamstr($res, $name);

Remarks

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

The following parameters are currently supported:

ImportBytes Method (SecureBlackbox_SSHKeyManager Class)

Loads key from buffer.

Object Oriented Interface

public function doImportBytes($bytes, $password);

Procedural Interface

secureblackbox_sshkeymanager_do_importbytes($res, $bytes, $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 (SecureBlackbox_SSHKeyManager Class)

Loads a key from an X.509 certificate.

Object Oriented Interface

public function doImportFromCert();

Procedural Interface

secureblackbox_sshkeymanager_do_importfromcert($res);

Remarks

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

ImportFromCryptoKey Method (SecureBlackbox_SSHKeyManager Class)

Imports a key from a crypto key.

Object Oriented Interface

public function doImportFromCryptoKey();

Procedural Interface

secureblackbox_sshkeymanager_do_importfromcryptokey($res);

Remarks

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

ImportFromFile Method (SecureBlackbox_SSHKeyManager Class)

Loads key from file.

Object Oriented Interface

public function doImportFromFile($path, $password);

Procedural Interface

secureblackbox_sshkeymanager_do_importfromfile($res, $path, $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.

Reset Method (SecureBlackbox_SSHKeyManager Class)

Resets the class settings.

Object Oriented Interface

public function doReset();

Procedural Interface

secureblackbox_sshkeymanager_do_reset($res);

Remarks

Reset is a generic method available in every class.

SetKeyParam Method (SecureBlackbox_SSHKeyManager Class)

Sets a key-specific key parameter.

Object Oriented Interface

public function doSetKeyParam($name, $value);

Procedural Interface

secureblackbox_sshkeymanager_do_setkeyparam($res, $name, $value);

Remarks

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

The following parameters are currently supported:

SetKeyParamStr Method (SecureBlackbox_SSHKeyManager Class)

Sets a key-specific key parameter.

Object Oriented Interface

public function doSetKeyParamStr($name, $valuestr);

Procedural Interface

secureblackbox_sshkeymanager_do_setkeyparamstr($res, $name, $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 (SecureBlackbox_SSHKeyManager Class)

Information about errors during SSH key management.

Object Oriented Interface

public function fireError($param);

Procedural Interface

secureblackbox_sshkeymanager_register_callback($res, 1, array($this, 'fireError'));

Parameter List

 'errorcode'
 '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 (SecureBlackbox_SSHKeyManager Class)

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

Object Oriented Interface

public function fireNotification($param);

Procedural Interface

secureblackbox_sshkeymanager_register_callback($res, 2, array($this, 'fireNotification'));

Parameter List

 'eventid'
 '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.

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