# Key Pairs

Key pairs refer to security credentials used for ensuring the identity of a
user connecting to a VM instance.

<a id="kp-newkey-ref"></a>

## Create a new key pair

1. Navigate to the **Main menu > Compute > Key Pairs** view.
2. Click **Create** in the top toolbar.
3. In the **Generate Key Pair > Details** tab, select **Generate a key pair
   and download the private key**.

   ![generate-key-pair-1](media/generate-key-pair-1.png)
4. Enter a unique name consisting of letters, numbers, spaces, underscores,
   periods and dashes. It must begin and end with a letter, number or an underscore.
5. Click **Next**.
6. In the **Generate Key Pair > Result** tab, the following is displayed:
   * **Name** of key pair.
   * **Fingerprint** of public key.

   ![generate-key-pair-2](media/generate-key-pair-2.png)
7. Click **Save** to download the private key to your browser’s default download
   location. The private key file is named:  `<name>.pem` where `<name>` is
   that specified for the key pair in the **Details** tab.
8. Click **Finish**.

## Upload an externally generated key pair

1. Use a tool of your choice to generate a key pair (public and private key),
   and change the file permissions on the private key to 400 or 600 to
   secure the key.

   Examples of `ssh-keygen` commands:
   * To generate keys in RSA and EDCSA formats:

     Usage: `ssh-keygen -t <type> -b <bits> -f <output file>`
     ```console
     ssh-keygen -t rsa -b 4096 -f id_rsa_4096
     ssh-keygen -t rsa -b 3072 -f id_rsa_3072
     ssh-keygen -t rsa -b 2048 -f id_rsa_2048
     ssh-keygen -t rsa -b 1024 -f id_rsa_1024
     ssh-keygen -t ecdsa -f id_ecdsa
     ssh-keygen -t ed25519 -f id_ed25519
     ```
   * To convert a key to RSA format, run the following command.
     This will update the key in place:
     ```console
     ssh-keygen -p -N "" -m pem -f <path_to_private_key_file>
     ```
   * To generate and secure (read-only) a 3KB RSA key:
     ```console
     ssh-keygen -t rsa -b 3072 -f id_rsa_3072
     chmod 400 id_rsa_3072
     ```
2. Navigate to the **Main menu > Compute > Key Pairs** view.
3. Click **Create** in the top toolbar.
4. In the **Generate Key Pair > Details** tab, select **Upload a public key
   for a key pair you have generated using another tool**.

   ![generate-public](media/generate-public.png)
5. Drag and drop the public key file into the window, or click **Browse** and
   navigate to it.
6. Click **Next**. The system displays the **Result** tab.
7. Click **Finish**.

<a id="kp-get-windows-instance-password"></a>

## Get a Windows instance password

1. Go to **Compute > Instances**.
2. Locate the Windows instance.

   ![vm-get-win-password](media/vm-get-win-password.png)
3. Right-click on the Windows instance row and click **Get Password** on the
   context menu, or go to **… More > Get Password**.
   The **Get Windows Password** dialog opens.
4. Locate the private key file (`<name>.pem`) of the key pair associated
   with the Windows instance. Either upload the private key file,
   or copy and paste its contents in the place provided.

   Click **Next**. The **Retrieve Password** tab displays the Windows
   instance’s admin password.
5. Copy the admin password string.
6. Either:
   - In your RDP client admin user session configuration, paste and save
     the copied password.
   - In your RDP session, on signing on as the admin user in the Windows VM
     instance, paste the copied admin password at the password prompt.

## Convert a private PEM key to PPK (PuTTY) format

To connect to a Linux VM instance using the PuTTY terminal emulator, your
private key must be converted to PuTTY’s PPK format.
The PuTTY download package includes the PuTTYgen utility for this purpose.

1. In PuTTYgen, under **Actions > Load an existing private key file**
   click **Load**.
2. In the File Explorer that opens:
   1. Change the file type selection filter from
      **PuTTY Private Key Files (\*.ppk)** to **All Files (\*.\*)**,
      so that `*.pem` files are displayed.
   2. Select the PEM file to convert to PPK format, and click **Open** to
      return to the PuTTYgen screen.

      A message displays that the PEM file was loaded successfully.
3. In PuTTYgen, for **Parameters > Type of key to generate** select **RSA**.
   If your version of PuTTYgen does not include this option, select
   **SSH-2 RSA**.
4. Click **Save private key**.
   1. In the dialog that opens, warning about saving the key without a
      protective passphrase, click **Yes**.
   2. In the **Save private key** dialog:
      1. **File name**: Enter the same name that was used for the key
         pair.
      2. **Save as type**: Select **PuTTY Private Key Files (\*.ppk)**
         (default).
      3. Click **Save**.

Using PuTTY, you can connect to your Linux VM instance with the PPK key.

## Generate a public key from a private key

A public key can be derived from a private key, using the `ssh-keygen`
utility.
This can be useful when there is a requirement to move the public key of a
key pair between zCompute clusters.
By default, `ssh-keygen` generates the public key output to standard
output, which can be redirected to a file.

Usage:

```console
ssh-keygen -y -f <private_key_file> > <public_key_file>
```

For example:

```console
ssh-keygen -y -f $HOME/.ssh/mykeyfile > $HOME/.ssh/mykeyfile.pub
```

### Generate a public key in PEM format

To generate a public key in PEM format from a private key, use the
`ssh-keygen` utility with the `-e -m pem` options.

Usage:

```console
ssh-keygen -y -f <private_key_file> -e -m pem > <public_key_file.pem>
```

For example:

```console
ssh-keygen -y -f $HOME/.ssh/mykeyfile > $HOME/.ssh/mykeyfile.pem
```