My SSH Key Operations

On the My SSHClosed The SSH (secure shell) protocol provides for secure connections between computers. It provides several options for authentication, including public key, and protects the communications with strong encryption. Key page, any user with the SSH User Keyfactor Command role permission (see SSH Permissions) can generate an SSH key pairClosed In asymmetric cryptography, public keys are used together in a key pair with a private key. The private key is retained by the key's creator while the public key is widely distributed to any user or target needing to interact with the holder of the private key. for himself or herself. If the user has previously generated a key pair through Keyfactor Command, it will be displayed here. In this interface a user can view only his or her own key pair; keys for any other Keyfactor Command users are not accessible.

Example:  An administrator wants to provision new user Zed Adams and grant him access to login via secured SSH using PuTTY to three Linux servers controlled by the Keyfactor Bash OrchestratorClosed The Bash Orchestrator, one of Keyfactor's suite of orchestrators, is used to discover and manage SSH keys across an enterprise.. The servers are set to both inventory and publish policy. To accomplish this, the administrator:
  1. Adds Zed's AD account to the AD group that grants him the SSH User role permission in Keyfactor Command and allows him to login to the Management Portal.

  2. Directs Zed to login to the Management Portal, go to the My SSH Key page and generate a new key pair (see Generate a New SSH Key). She instructs him to enter the following information in the form:

  3. Instructs Zed to download the SSH private key and use the PuTTY Key Generator tool to open the key and convert it to the PuTTY format:

    1. Click Load and browse to locate the downloaded private key. This key is named something like SSH-Key-KEYEXAMPLE-zadams.identity.

    2. In the Parameters section of the page, select Ed25519 as the type of key to generate.

    3. Click Save private key and save the private key in the PuTTY format (*.ppk) in a safe location on the local machine.

    Figure 325: Use PuTTY Key Generator to Convert Zed's Private Key

  4. Uses the Keyfactor Command Management Portal to create Linux logons for Zed on each of the three servers that Zed should have access to and map Zed's new public keyClosed In asymmetric cryptography, public keys are used together in a key pair with a private key. The private key is retained by the key's creator while the public key is widely distributed to any user or target needing to interact with the holder of the private key. to these three logons (see Edit Access to a Server Group).

    Figure 326: Create Logons and Mappings for Zed

    Note:  The three servers that Zed needs access to are in a server group so the administrator can create Zed's logons and map his key using the Access Management option on the Server Group page. If the servers were in different server groups or the server group contained servers to which Zed should not have access, the administrator would need to create the logons and mappings separately for each server using the Access Management option on the Servers page (see Edit Access to an SSH Server).
  5. Waits for the logons to be created on the three servers and the public key to be published to them. The time that this takes depends on the frequency of the server group synchronization schedule (see Add or Edit a Server Group).

  6. Instructs Zed to configure PuTTY to use the private key for authentication, providing also connection information for the three Linux servers to which he will be connecting.

    Figure 327: Configure PuTTY to Use Zed's Private Key

  7. Confirms that Zed is able to successfully connect using secured SSH to each of the three servers.

This information is included for a key:

Creation Date

The date on which the SSH key pair was generated.

Stale Date

The date on which the SSH key pair is considered to have reached the end of its lifetime. By default, the lifetime of an SSH key pair is 365 days (see Application Settings: SSH Tab).

Key Type

A number of cryptographic algorithms can be used to generate SSH keys. Keyfactor Command supports RSA, Ed25519, and ECDSA. RSA keys are more universally supported, and this is the default key typeClosed The key type identifies the type of key to create when creating a symmetric or asymmetric key. It references the signing algorithm and often key size (e.g. AES-256, RSA-2048, Ed25519). when generating a new key.

Key Length

The key lengthClosed The key size or key length is the number of bits in a key used by a cryptographic algorithm. available when generating a new key depends on the key type selected. Keyfactor Command supports 256 bits for Ed25519 and ECDSA and 2048 or 4096 bits for RSA. The default key length is 2048.

Email

The email address of the user requesting the key. This email address is used to alert the user when the key pair is approaching the end of its lifetime (see Key Rotation Alerts).

Comment

The user-defined descriptive comment, if any, on the key. Although entry of an email address in the comment field of an SSH key is traditional, this is not a required format. The comment may can contain any characters supported for string fields, including spaces and most punctuation marks.

SHA256 Fingerprint

The fingerprint of the public key. Each SSH public key has a single cryptographic fingerprint that can be used to uniquely identify the key.

Public Key

The public key of the key pair.

Figure 328: Key Information for an SSH User Key

Important:  A given user can only have one SSH key pair in Keyfactor Command. Generating a new key pair removes the existing key pair from Keyfactor Command, if one exists. This means any mappings between the Keyfactor user and Linux logon accounts will be updated with the public key from the new key pair. This essentially invalidates the user's previous private key for servers managed with the Keyfactor Bash OrchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores.. Although the Generate button is not active for users who already have a key pair, the Rotate button will also remove the existing key pair.

To generate a new SSH key pair:

  1. In the Management Portal, browse to SSH > My SSH Key.

  2. On the My SSH Key page, click Generate.

    Figure 329: Generate an SSH Key Pair

  3. In the Key Information section of the Generate dialog, select a Key Type in the dropdown (seeKey Type).
  4. In the Key Information section, select a Key Length in the dropdown (see Key Length). The available key lengths will vary depending upon the option selected in the Key Type dropdown.
  5. In the User Information section, confirm that the displayed Username matches the Active Directory user name you wish to associate with your key. This field defaults to your logged in username and cannot be edited.
  6. In the User Information section, enter an Email address. This address is used for key rotation alerts (see Key Rotation Alerts). This field is required.

  7. In the User Information section, enter a Passphrase to encrypt the downloaded copy of the private key of the key pair. You will need to provide this passphrase again when you use the private key to connect via SSH. By default, the minimum password length is 12 characters (see the SSH Key Password setting in Application Settings: SSH Tab). This field is required.

    Tip:  Your private key downloads immediately at the conclusion of the generation process, encrypted with this passphrase. You may later download the private key again from this same page and encrypt it with a different passphrase, if desired.

  8. In the Key Comment section, enter a Comment to include with the key. This field is optional.

    Tip:  Although entry of an email address in the comment field of an SSH key is traditional, this is not a required format. The comment may contain any characters supported for string fields, including spaces and most punctuation marks.
  9. Click Save to create the key pair.
Tip:  Once the key pair is generated, the user needs to download the private key as an encrypted file and store it locally and an administrator needs to use Keyfactor Command to associate the user's Keyfactor user account with his or her Linux logon account on the target server that the user wishes to access via SSH. After this is complete and the orchestrator has published the user's public key to the target server, the user may connect via SSH to the target server using the new private key for authentication. For more information, see SSH.

The rotate key option is used to replace an existing key that is approaching the end of its life or has been compromised. If key rotation alerts have been configured in the environment (see Key Rotation Alerts), the user will receive an email when the key is approaching the end if its lifetime to instruct the user to rotate his or her keys.

Important:  A given user can only have one SSH key pair in Keyfactor Command. Generating a new key pair with the rotate option removes the existing key pair from Keyfactor Command. This means any mappings between the Keyfactor user and Linux logon accounts will be updated with the public key from the new key pair. This essentially invalidates the user's previous private key for servers managed with the Keyfactor Bash Orchestrator.

The rotate dialog defaults to all the existing settings of the user's current key. At its simplest, users may choose to accept all the defaults, enter a passphrase to encrypt the downloaded private key and click save to generate the new key pair.

To rotate an SSH key pair:

  1. In the Management Portal, browse to SSH > My SSH Key.

  2. On the My SSH Key page, click Rotate.

    Figure 330: Rotate an SSH Key Pair

  3. In the Key Information section of the Rotate dialog, modify the existing Key Type in the dropdown, if desired (see Key Type).
  4. In the Key Information section, modify the existing Key Length in the dropdown, if desired (see Key Length). The available key lengths will vary depending upon the option select in the Key Type dropdown.
  5. In the User Information section, confirm that the displayed Username matches the Active Directory user name you wish to associate with your key. This field defaults to your logged in username and cannot be edited.
  6. In the User Information section, modify the existing Email address, if desired. This address is used for key rotation alerts (see Key Rotation Alerts). This field is required.
  7. In the User Information section, enter a Passphrase to encrypt the downloaded copy of the private key of the key pair. You will need to provide this passphrase again when you use the private key to connect via SSH. By default, the minimum password length is 12 characters (see the SSH Key Password setting in Application Settings: SSH Tab). This field is required.
  8. In the Key Comment section, modify the existing Comment to include with the key, if desired. This field is optional.
    Tip:  Although entry of an email address in the comment field of an SSH key is traditional, this is not a required format. The comment may can contain any characters supported for string fields, including spaces and most punctuation marks.
  9. Click Save to create the new key pair.
Tip:  Once the key pair is generated, the user needs to download the private key as an encrypted file and store it locally and an administrator needs to use Keyfactor Command to associate the user's Keyfactor user account with his or her Linux logon account on the target server that the user wishes to access via SSH. After this is complete and the orchestrator has published the user's public key to the target server, the user may connect via SSH to the target server using the new private key for authentication. For more information, see SSH.

After generating a key pair, you need to download the private key on the machine from which you will be making SSH connections. Although the private key is encrypted, for best security practice it should not be moved around from machine to machine.

The key downloads in the proprietary OpenSSH private key format, encrypted by a user-defined password.

Only the private key can be downloaded with the download option, though the public key is displayed on the screen and may be copied and pasted to a file, if desired.

To download the private key:

  1. In the Management Portal, browse to SSH > My SSH Key.
  2. On the My SSH Key page, confirm that you have been issued a key pair and click Download.

  3. In the Download dialog, enter a passphrase that will be used to encrypt the private key. By default, the minimum password length is 12 characters (see the SSH Key Password setting in Application Settings: SSH Tab). This field is required.

    Figure 331: Add a Password to Encrypt the Downloaded Private Key

  4. Click Download to save the file to your local machine.

By default, the file has the following name, where DOMAIN is your Active Directory domain name and username is the Active Directory user name of the user logged into the Keyfactor Command Management Portal:

SSH-Key-DOMAIN-username.identity

Once you have generated an SSH key pair, most things about the key pair are fixed and cannot be changed. However, two pieces of key information can be changed for an existing key pair—the email address to which alerts about the key should be directed and the comment associated with the public key.

To modify the email address or key comment:

  1. In the Management Portal, browse to SSH > My SSH Key.

  2. On the My SSH Key page, update the fields in the Edit Key Information section as needed and click Save.

    Figure 332: Edit SSH User Key Information

Changes made to the key comment will be published to any associated servers during the next synchronization cycle.

Tip:  Click the help icon () next to the My SSH Key Operations page title to open the Keyfactor Software & Documentation Portal to this section. You will receive a prompt indicating:

You are being redirected to an external website. Would you like to proceed?

You can also find the help icon () at the top of the page next to the Log Out button. From here you can choose to open either the Keyfactor Software & Documentation Portal at the home page or the Keyfactor API Endpoint Utility.

Keyfactor provides two sets of documentation: the On-Premises Documentation Suite and the Managed Services Documentation Suite. Which documentation set is accessed is determined by the Application Settings: On-Prem Documentation setting (see Application Settings: Console Tab).