ssh-keygen-g3

Synopsis

ssh-keygen-g3 [ options ...]
[ key1 key2 ...]

Description

ssh-keygen-g3 (ssh-keygen-g3.exe on Windows) is a tool that generates and manages authentication keys for Secure Shell. Each user wishing to use a Secure Shell client with public-key authentication can run this tool to create authentication keys. Additionally, the system administrator can use this to generate host keys for the Secure Shell server. This tool can also convert openSSH public or private keys to the Tectia key format, or, from Tectia key format to openSSH format. Tectia public keys use The Secure Shell (SSH) Public Key File Format (RFC 4716).

By default, if no path for the key files is specified, the key pair is generated under the user's home directory ($HOME/.ssh2 on Unix, "%APPDATA%\SSH\UserKeys" on Windows). If no file name is specified, the key pair is likewise stored under the user's home directory with such file names as id_type_bits_a and id_type_bits_a.pub.

When specifying file paths or other strings that contain spaces, enclose them in quotation marks ("").

Options

The following options are available:

-1 file

Converts a key file from the SSH1 format to the SSH2 format. Note: "1" is number one (not letter L).

-7 file

Extracts certificates from a PKCS #7 file.

-b bits

Specifies the length of the generated key in bits. The allowed and default lengths for different key types are:

RSA or DSA: allowed 512 to 65536 bits, default 3072 bits
ECDSA: allowed 256, 384 and 521 bits, default 384 bits
Ed25519: allowed/default 256 bits

-B num

Specifies the number base for displaying key information (default: 10).

-c comment

Specifies a comment string for the generated key.

-D file

Derives the public key from the private key file.

-e file

Edits the specified key. Makes ssh-keygen-g3 interactive. You can change the key's passphrase or comment.

-F, --fingerprint file

Dumps the fingerprint and type (RSA, DSA, ECDSA or Ed25519) of the given public key. By default, the fingerprint is given in the SSH Babble format, which makes the fingerprint look like a string of "real" words (making it easier to pronounce). The output format can be changed with the --fingerprint-type option.

The following options can be also used to modify the behavior of this option: --fingerprint-type --hash, --hostkeys-directory, --known-hosts, --rfc4716.

-F, --fingerprint host_ID

Dumps the location, fingerprint and type (RSA, DSA, ECDSA or Ed25519) of the locally stored host key(s) identified with the given host_ID. The host_ID is a host name or string "host#port".

The following options can be used to modify the behavior of this option: --fingerprint-type, --hash, --hostkeys-directory, --known-hosts, --rfc4716.

-H, --hostkey

Stores the generated key pair in the default host key directory (/etc/ssh2 on Unix, "<INSTALLDIR>\SSH Tectia Server" on Windows). By default stores the private key with an empty passphrase or if in FIPS mode with random passphrase in <privatekey>.pass. Use --prompt-pass option to prompt for the passphrase in --hostkey mode.

-i file

Loads and displays information on the key file.

--pass-file file

Read passphrase from a file for displaying -i information on a passphrase protected private key. If <privatekey>.pass exists, it is used by default.

-p passphrase

Specifies the passphrase for the generated key.

-P

Specifies that the generated key will be saved with an empty passphrase.

	Note
	In FIPS mode, due to a FIPS regulation which forbids exporting unencrypted private keys out of the FIPS module, it is not possible to generate user keys without a passphrase.

--random-pass

Create random passphrase for the generated private key and save it to <privatekey>.pass. By default the passprase is Base64 encoded.

-k file

Converts a PKCS #12 file to an SSH2-format certificate and private key.

-m, --generate-moduli-file

Generates moduli file secsh_dh_gex_moduli for Diffie-Hellman group exchange.

-q, --quiet

Hides the progress indicator during key generation.

-r file

Adds entropy from file to the random pool. If file contains 'relatively random' data (i.e. data unpredictable by a potential attacker), the randomness of the pool is increased. Good randomness is essential for the security of the generated keys.

-t dsa | rsa | ecdsa | ed25519

Selects the type of the key. Valid values are rsa (default), dsa, ecdsa, and ed25519.

-x file

Converts a private key from the X.509 format to the SSH2 format.

--append [ =yes | no ]

Appends the keys. Optional values are yes and no. The default is yes to append.

--copy-host-id host_ID destination

Copies the host identity to the specified destination directory.

The following options can be used to modify the behavior of this option: --append, --hostkeys-directory, --known-hosts, --overwrite.

If --hostkey-file is given, the file is treated as a normal host identity file used by the Connection Broker, and its contents will be copied to the destination directory.

--delete-host-id host_ID

Deletes the host key of the specified host ID. The host_ID is a host name or string "host#port".

The following options can be used to modify the behavior of this option: --host-key-file, --hostkeys-directory, --known-hosts.

--hash sha256 | sha1 | md5

Specifies the digest algorithm for fingerprint generation. Valid options are sha256, sha1 and md5. The default is sha1.

--fingerprint-type base64 | babble | babble-upper | pgp-2 | pgp-5 | hex | hex-upper

Specifies the output format of the fingerprint. If this option is given, the -F option and the key file name must precede it. The default format is babble.

See the section called “Examples” for examples of using this option.

--fips-mode

Generates the key using the FIPS mode for the cryptographic library.

The keys must have non-empty passphrases.

By default (if this option is not given or Tectia FIPSMODE switch file is not present), the key is generated using the standard mode for the cryptographic library.

--fips-crypto-dll-path PATH

Specifies the location of the FIPS cryptographic DLL.

--hostkey-file file

When copying, uses the given file as the source host key, instead of autodetecting the location. When deleting, only deletes from the given location. If the specified file does not contain identities for the specified host, does nothing.

--hostkeys-directory directory

Specifies the directory for known host keys to be used instead of the default location.

--import-public-key infile [ outfile ]

Attempts to import a public key from infile and store it to outfile in the format specified by --key-format parameter. If outfile is not given, it will be requested. The default output format is SSH2 native format.

--import-private-key infile [ outfile ]

Attempts to import a private key from infile and store it to outfile in the format specified by --key-format parameter. If outfile is not given, it will be requested. The default output format is SSH2 native private key format.

--import-ssh1-authorized-keys infile outfile

Imports an SSH1-style authorized_keys file infile and generates an SSH2-style authorization file outfile, and stores the keys from infile to generated files into the same directory with outfile.

--key-format format

Output key format: secsh2, pkcs1, pkcs8, pkcs12, openssh2, or openssh2-aes.

--key-hash hash

This option can be used for other than Tectia key formats. Specifies the hash algorithm to be used in passphrase-based private key derivation. The default value is sha1. Other supported algorithms are sha224, sha256, sha384, and sha512. Note that all key formats do not support all hash algorithms.

--known-hosts file

Uses the specified known hosts file. Enables fetching fingerprints for hosts defined in an OpenSSH-style known-hosts file. Using this option overrides the default locations of known_hosts files (/etc/ssh/ssh_known_hosts and $HOME/.ssh/known_hosts). Giving an empty string will disable known-hosts usage altogether.

--moduli-file-name file

Writes the moduli generated for Diffie-Hellman group exchange to file. (The default file name for option -m is secsh_dh_gex_moduli.)

--overwrite [ =yes | no ]

Overwrite files with the same file names. The default is to overwrite.

--rfc4716

Displays the fingerprint in the format specified in RFC4716. The digest algorithm (hash) is md5, and the output format is the 16-bytes output in lowercase HEX separated with colons (:).

--set-hostkey-owner-and-dacl file

On Windows, sets the correct owner and DACL (discretionary access control list) for the host key file. This option is used internally when a host key is generated during Tectia Server installation.

--sign-cert file

Make a certificate with the generated public key, and write to file. For a complete list of additional certificate options, view the option help with --sign-cert help.

-V

Displays version string and exits.

-h, --help, -?

Displays a short summary of command-line options and exits.

Examples

Create a 3072-bit RSA key pair using the cryptographic library in the FIPS mode and store the key pair in the default user key directory with file names newkey and newkey.pub:

$ ssh-keygen-g3 --fips-mode -b 3072 newkey

Display the fingerprint of a server host public key in SSH babble (default) format:

$ ssh-keygen-g3 -F hostkey.pub
Fingerprint for key:
xeneh-fyvam-sotaf-gutuv-rahih-kipod-poten-byfam-hufeh-tydym-syxex

Display the Base64-encoded SHA256 fingerprint of the public hostkey:

$ ssh-keygen-g3 --hash sha256 --fingerprint-type base64 -F hostkey.pub
Fingerprint for key `hostkey.pub':
9UmbXHpUodKPXS0pFIACGLjKoiHQBShPVZj6ShUNWgM (RSA)

Convert a private key into openSSH2-AES format:

$ ssh-keygen-g3 -p <password> --key-format openssh2-aes \
  --import-private-key <source_key_file> <destination_key_file>

Note: if the private key file that is being converted is encrypted with a passphrase, the passphrase must be provided with the '-p' option.

Convert a Tectia public key tectiakey.pub to an OpenSSH public key opensshkey.pub:

$ ssh-keygen-g3 --key-format openssh2 --import-public-key \ 
  tectiakey.pub opensshkey.pub

Generate moduli file dhgex-moduli for Diffie-Hellman group exchange:

$ ssh-keygen-g3 -m --moduli-file-name dhgex-moduli