ssh-broker-g3 — SSH Connection Broker - Generation 3
ssh-broker-g3
[-f, --config-file=
FILE
] [-D, --debug=
LEVEL
] [-l, --debug-log-file=
FILE
] [--exit
] [--reconfig
] [--no-gui
] [--start-gui
] [-h
] [-V
]
ssh-broker-g3 (ssh-broker-g3.exe on Windows) is a component of SSH Tectia Client. It handles all cryptographic operations and authentication-related tasks for the SSH Tectia Client programs sshg3, scpg3, sftpg3, and ssh-client-g3.exe (on Windows only).
ssh-broker-g3 uses the Secure Shell version 2 protocol to communicate with a Secure Shell server.
You can start the Connection Broker manually by using the ssh-broker-g3 command. This starts ssh-broker-g3 in the background and all following uses of sshg3, sftpg3, or scpg3 will connect via this instance of the Connection Broker instead of starting a new Broker session.
If a command-line client (sshg3, sftpg3, or scpg3) is started when the Connection Broker is not running in the background, the client starts the Broker in run-by-need mode. In this mode, ssh-broker-g3 will exit after the last client has disconnected.
If there is an ssh-broker-g3 process running in the run-by-need mode and the Connection Broker is started from the command line, the new ssh-broker-g3 process sends a message to the old ssh-broker-g3 process to change from the run-by-need mode to the background mode, keeping the Broker running after the clients disconnect.
The Connection Broker operates automatically as an authentication agent, storing
user's public keys and forwarding the authentication over Secure Shell
connections. Key pairs can be created with ssh-keygen-g3
.
The public key pairs used for user authentication are by default stored in
the $HOME/.ssh2
directory ("%USERPROFILE%\Application Data\SSH\UserKeys
" on Windows).
See the section called “Files” for more information.
The Connection Broker automatically maintains and checks a database containing the
public host keys used for authenticating Secure Shell servers. When logging
in to a server host for the first time, the host's public key is stored in
the user's $HOME/.ssh2/hostkeys
directory ("%USERPROFILE%\Application Data\SSH\HostKeys
" on Windows).
See the section called “Files” for more information.
The most important options of ssh-broker-g3 are the following:
-f, --config-file=
FILE
Reads the Connection Broker configuration file from
FILE
instead of the default location.
-D, --debug=
LEVEL
Sets the debug level string to LEVEL
.
-l, --debug-log-file=
FILE
Dumps debug messages to FILE
.
--exit
Make the currently running Connection Broker exit. This will terminate all connections.
--reconfig
Re-reads the configuration file
(ssh-broker-config.xml
) and takes it into use.
--no-gui
On Windows, starts the Connection Broker but does not start the GUI.
This option is used internally when a command-line client is started when the Connection Broker is not running.
--start-gui
On Windows, starts the Connection Broker GUI if it is not already running.
-V, --version
Displays program version and exits.
-h, --help
Displays a short summary of command-line options and exits.
On Windows, the help is only shown when running
"ssh-broker-cli.exe -h
" directly from the "C:\Program Files\SSH Communications Security\SSH Tectia\SSH
Tectia AUX\Support Binaries
" directory. Normally,
ssh-broker-cli.exe
is never run by the user, but it is
automatically called by ssh-broker-g3.exe
.
ssh-broker-g3 uses the following files:
$HOME/.ssh2/ssh-broker-config.xml
This is the user-specific configuration file used by ssh-broker-g3 (and sshg3, scpg3, and sftpg3). The format of this file is described in ssh-broker-config(5). This file does not usually contain any sensitive information, but the recommended permissions are read/write for the user, and not accessible for others.
On Windows, the user-specific configuration file is
located in "%USERPROFILE%\Application Data\SSH\ssh-broker-config.xml
".
$HOME/.ssh2/random_seed
This file is used for seeding the random number generator. It contains sensitive data and its permissions should be read/write for the user and not accessible for others. This file is created the first time the program is run and it is updated automatically. You should never need to read or modify this file.
On Windows, the random seed file is located in
"%USERPROFILE%\Application Data\SSH\random_seed
".
$HOME/.ssh2/identification
This file contains information on public keys and certificates used for user authentication when contacting remote hosts.
With SSH Tectia Client 5.x, using the identification
file is not
necessary if all user keys are stored in the default directory and you allow
all of them to be used for public-key and/or certificate authentication. If
the identification
file does not exist, the Connection Broker attempts to
use each key found in the $HOME/.ssh2
directory. If the
identification
file exists, the keys listed in it are
attempted first.
The identification file contains a list of private key filenames each
preceded by the keyword IdKey
(or
CertKey
). An example file is shown below:
IdKey mykey
This directs the Connection Broker to use $HOME/.ssh2/mykey
when attempting login using public-key authentication.
The files are by default assumed to be in the
$HOME/.ssh2
directory, but also a path to the key file can be
given. The path can be absolute or relative to the $HOME/.ssh2
directory. If there is more than one IdKey
, they are tried
in the order that they appear in the identification file.
On Windows, the identification file is located in
"%USERPROFILE%\Application Data\SSH\identification
". Key paths
in the file can be absolute or relative to the
%USERPROFILE%\Application Data\SSH
directory. The default user
key directory is "%USERPROFILE%\Application Data\SSH\UserKeys
"
and the default user certificate directory is
"%USERPROFILE%\Application Data\SSH\UserCertificates
".
$HOME/.ssh2/hostkeys
This is the user-specific directory for storing the public keys of
server hosts. You are prompted to accept new or changed keys automatically
when you connect to a server, unless you have set
strict-host-key-checking
to yes
in the
ssh-broker-config.xml
file. You should verify the key
fingerprint before accepting new or changed keys.
When the host key is received during the first connection to a remote host (or when the host key has changed) and you choose to save the key, its filename is stored in hashed format. The hashed host key format is a security feature to make address harvesting on the hosts difficult.
If you are adding the keys manually, the keys should be named with
key_<port>_<host>.pub
pattern, where
<port>
is the port the Secure Shell server
is running on and <host>
is the hostname
you use when connecting to the server (for example,
key_22_alpha.example.com.pub
).
If both the hashed and clear-text format keys exist, the hashed format takes precedence.
Note that the identification is different based on the host and port
the client is connecting to. For example, the short hostname
alpha
is considered different from the fully
qualified domain name alpha.example.com
. Also a
connection with an IP, for example 10.1.54.1
, is
considered a different host, as is a connection to the same host but
different port, for example
alpha.example.com#222
.
On Windows, the user-specific host key files are located in
"%USERPROFILE%\Application Data\SSH\HostKeys
".
For more information on host keys, see Server Authentication with Public Keys.
$HOME/.ssh2/hostkeys/salt
This is the initialization file for hashed host key names.
On Windows, the salt file is located in
"%USERPROFILE%\Application Data\SSH\HostKeys\salt
".
/etc/ssh2/hostkeys
If a host key is not found in the user-specific
$HOME/.ssh2/hostkeys
directory, this is the next location to be
checked for all users. Host key files are not automatically put here but
they have to be updated manually by the system administrator
(root
) or by using SSH Tectia Manager.
If the administrator obtains the host keys by connecting to each host,
the keys will be in the hashed format. In this case, also the
administrator's $HOME/.ssh2/hostkeys/salt
file has to be copied
to the /etc/ssh2/hostkeys
directory.
On Windows, the system-wide host key files are located in
%ALLUSERSPROFILE%\Application Data\SSH\HostKeys
.
/etc/ssh2/hostkeys/salt
This is the initialization file for hashed host key names. The file has to be copied here manually by the same administrator that obtains the host keys.
On Windows, the salt file for all users is located in
"%ALLUSERSPROFILE%\Application Data\SSH\HostKeys\salt
".
$HOME/.ssh/known_hosts
This is the default file used by OpenSSH clients that contains the
public key data of known server hosts. It is supported also by SSH Tectia Client from
version 5.1 onwards. The location of the file must be defined in
the ssh-broker-config.xml
file by using the
known-hosts
element.
See known-hosts.
The file is never automatically updated by SSH Tectia Client. New host keys
are always stored in the SSH Tectia $HOME/.ssh2/hostkeys
directory.
The file contains one known host per row. The format of each row is the following:
hostnames bits exponent modulus comment
The hostname(s) in the file must be in clear-text format. Hashed hostnames are not supported.
For more information on the format of this file, see the OpenSSH sshd(8) man page.
$HOME/.ssh2/authorized_keys
(on the server host)This directory is the default location used by SSH Tectia Server 5.x for the user public keys that are authorized for login.
On SSH Tectia Server 5.x on Windows, the default directory for user
public keys is %USERPROFILE%\.ssh2\authorized_keys
.
$HOME/.ssh2/authorization
(on the server host)This is the default file used by SSH Tectia Server 4.x (and SSH Secure Shell server 3.x) that lists the user public keys that are authorized for login. The file can be optionally be used with SSH Tectia Server 5.x as well.
On Windows, the authorization file is by default located in
%USERPROFILE%\.ssh2\authorization
.
For information on the format of this file, see User Authentication with Public Keys.
$HOME/.ssh/authorized_keys
(on the server host)This is the default file used by OpenSSH server that contains the user public keys that are authorized for login.
For information on the format of this file, see the OpenSSH sshd(8) man page.