ssh-keydist-g3

ssh-keydist-g3 — Key distribution tool

Synopsis

ssh-keydist-g3 [options...] host [ [options...] [host] ...]

Description

The ssh-keydist-g3 key distribution tool can be used for storing multiple remote host keys to a common key store and setting up public-key authentication to multiple hosts.

The tool uses sub-script ssh-keyfetch for fetching remote host keys.

The tool calls ssh-keygen-g3 when creating new key pairs.

Options

ssh-keydist-g3 accepts the following options:

-A, --accepted-host-key-log FILE

Specifies a log file listing the accepted new host keys. The default is ssh_host_keys.log in the user home directory.

-b, --key-bits NUMBER

Specifies the length of the generated key in bits (default 2048).

-d, --allow-keygen-overwrite

Allows ssh-keygen-g3 to overwrite an existing key pair.

-D, --debug LEVEL

Sets the debug level, where LEVEL is number from 1 to 99.

-f, --pubkey-file FILE

Disables key pair generation, and distributes the given key file instead.

-F, --accepted-host-key-filename-format plain|hashed

The accepted host keys are stored in the specified filename format. The default is hashed. See Section Host Key Storage Formats for more information.

-g, --accept-hostkeys-globally

The accepted host keys are copied to the system-wide store for trusted host keys (/opt/tectia/etc/hostkeys). This causes all users to trust the host key. Giving this option requires administrator privileges.

-H, --hostlist-file FILE

Specify a host list file that contains hostnames or username/hostname pairs.

The format of the host list file is as follows:

userid1/host1.example.com,passwordfile1
userid2/host2.example.com,passwordfile2
userid3/host3.example.com,passwordfile3

If the user name is omitted from the entry, the user name given with the -u option is used for the connection. If -u has not been given, the local user name is used.

If the password file is omitted from the entry, the password file given with the -p option is used for the connection. If -p has not been given, the password is prompted interactively from the user.

-i, --accept-host-keys-also-by-ip

Stores the accepted host keys also by their IP address. This option must be specified if the host will be accessed with Transparent FTP tunneling.

-I, --dont-accept-host-keys-also-by-ip

Does not store the accepted host keys also by their IP address (default).

-k, --continue-after-error

Do not exit if an operation for one host fails but continue with other hosts.

-l, --accept-hostkeys-locally

The accepted host keys are copied to the user specific store for accepted keys. This is the default.

-n, --do-not-execute

Prints the commands but does not execute them.

-N, --accept-host-keys

Accepts new host keys. Does not generate or distribute user keys.

-O, --openssh-unix

The remote host is running Unix and its Secure Shell server is OpenSSH. The public key is appended to the user's $HOME/.ssh/authorized_keys file.

-p, --password-file FILE

Specify a file or a data set containing the password for authenticating to remote server(s) during public key setup. Use with care!

-P, --empty-passphrase

Generate the key pair with an empty passphrase.

-S, --ssh2-unix

The remote host is running Unix and its Secure Shell server is Tectia. The public key is uploaded to the user's $HOME/.ssh2 directory and the $HOME/.ssh2/authorization file is updated.

-t, --key-type dsa|rsa

Selects the algorithm used in key generation. dsa (Digital Signature Algorithm) and rsa are supported. The default is dsa.

-u, --remote-user USER

Specify remote user name. The default is the local user name.

-U, --user-key-log FILE

Specifies a log file listing the generated and distributed user keys. The default is ssh_user_keys.log in the user home directory.

-v, --verbose

Enables verbose mode. Information on the progress of the program is displayed in standard output.

-W, --ssh2-windows

The remote host is running Windows and its Secure Shell server is Tectia. The public key is uploaded to the user's %USERPROFILE%\.ssh2 directory and the %USERPROFILE%\.ssh2\authorization file is updated.

-Z, --ssh2-zos

The remote host is running z/OS and its Secure Shell server is Tectia. The public key is uploaded to the user's USS $HOME/.ssh2 directory and the $HOME/.ssh2/authorization file is updated.

Caution

	Caution
When ssh-keydist-g3 is run with the `-N` option, it accepts the received host keys automatically without prompting the user. You should verify the validity of keys by verifying the key fingerprints after receiving them or you risk being subject to a man-in-the-middle attack. To validate the host key, obtain the host key fingerprint from a trusted source (for example by calling the server administrator) and verify it against the output from command: ssh-keygen-g3 --fingerprint <hostname>

When ssh-keydist-g3 is run with the -N option, it accepts the received host keys automatically without prompting the user. You should verify the validity of keys by verifying the key fingerprints after receiving them or you risk being subject to a man-in-the-middle attack.

To validate the host key, obtain the host key fingerprint from a trusted source (for example by calling the server administrator) and verify it against the output from command:

ssh-keygen-g3 --fingerprint <hostname>

Examples

Example 1: Connect to multiple hosts, fetch their host keys in hashed (default) format, and save them under the user's $HOME/.ssh2/hostkeys directory. Save the host key hash values with both the specified hostname and the IP address of the host. Store a log of the accepted new host keys under /tmp.

$ ssh-keydist-g3 -N -i -A /tmp/newhosts.log host1 host2 host3

Example 2: Connect to multiple hosts defined in the hostlist.txt file, fetch their host keys in plain format, and save them under the system-wide /opt/tectia/etc/hostkeys directory. Running the command requires administrator privileges.

# ssh-keydist-g3 -N -F plain -g -H /home/userid/hostlist.txt

The keys are stored with the names specified in the host list file. For example, the following list would specify storing the keys with FQDN and also connecting to port 222 on host1.example.com:

host1.example.com
host1.example.com#222
host2.example.com
host3.example.com

Example 3: Create a 1024-bit DSA key with an empty passphrase, and upload it to a Unix server running OpenSSH, including the necessary conversions. Public-key upload uses password-from-file for authentication.

$ ssh-keydist-g3 -t dsa -b 1024 -P -d -p /home/userid/passwd_file \
   -u user1 -O open_server.example.com

Example 4: Create a 1536-bit RSA key with an empty passphrase, and upload it to multiple servers, including the necessary conversions. Public-key upload uses password-from-file for authentication. passwd_file1 is used for the Unix, Windows, and z/OS hosts running Tectia and passwd_file2 is used for the host running OpenSSH.

$ ssh-keydist-g3 -t rsa -b 1536 -P -d \ 
   -p /home/userid/passwd_file1 \
   -S -u user1 tectia_unix.example.com \ 
   -W -u user2 tectia_win.example.com \
   -Z -u user3 tectia_zos.example.com \
   -p /home/userid/passwd_file2 \
   -O -u user1 open_server.example.com \

Example 5: Distribute an existing RSA public key to several hosts using host lists. Store the log of distributed keys under /tmp.

The host lists need to be grouped so that all Tectia Unix, Tectia Windows, Tectia z/OS, and OpenSSH hosts are in different host files, for example tectiaunix_hostlist.txt, tectiazos_hostlist.txt, openssh_hostlist.txt, each host list defined in the following way:

userid1/host1.example.com
userid2/host2.example.com
userid3/host3.example.com

The command is as follows:

$ ssh-keydist-g3 -f /home/userid/.ssh2/id_rsa_1024_a.pub \
   -p /home/userid/common_passwd_file -F plain -U /tmp/userkeys.log \
   -S -H tectiaunix_hostlist.txt \
   -Z -H tectiazos_hostlist.txt \
   -O -H openssh_hostlist.txt