VDC API: How to use SSH key pairs

Introduction
Import (register) a public key to VDC (API command: registerSSHKeyPair)
Create a key pair in VDC (API command: createSSHKeyPair)
List the public keys stored in a VDC account (API command: listSSHKeyPairs)
Delete a stored public key (API command: deleteSSHKeyPair)
Deploy a virtual machine with the keypair option
Replace a public key stored in a virtual machine (API command: resetSSHKeyForVirtualMachine)

 

Introduction

This document describes how to setup SSH 'public key authentication' for Linux machines in VDC. SSH public keys can be stored in your VDC account, and passed to newly-deployed Linux virtual machines so that they contain the public key necessary for you to connect to the VM using the corresponding private key.

Important

The SSH key pair functions are not available in the VDC GUI.

The key pair functions only have an effect on a deployed virtual machine if a compliant boot script is installed in the VM template. The standard Linux templates provided by Interoute contain a boot script for SSH. .

 

Note that the API command names are a bit misleading because VDC does not store the key pair but only the public key half of the pair.

The code examples in this document use the Cloudmonkey API tool. For installation and setup, see Introduction to the API.

Import (register) a public key to VDC (API command: registerSSHKeyPair)

When you have a key pair already created (using the Linux command 'ssh-keygen', for example), then use the API command registerSSHKeyPair to import the public key part to VDC:

> registerSSHKeyPair name=MyKey01 publickey="ssh-rsa AAAAB3NzaC1y...........fyskMb4oBw== demo.user@interoute.com"
keypair:
name = MyKey01
fingerprint = 55:33:b4:d3:b6:52:fb:79:97:fc:e8:16:58:6e:42:02

The public key has been abbreviated here; it must be entered as a single long string without linebreaks, be careful when copying the public key that you don't introduce any linebreaks.

The keypair 'name' parameter is arbitrary and is only used to identify this public key.

For security reasons you can't see the value of the public key in VDC, only its 'fingerprint' value which you can compare against the fingerprint generated from the key pair in your own computer.

Create a key pair in VDC (API command: createSSHKeyPair)

You can create a new key pair in VDC, where the public key is stored in VDC and the private key is sent in the API response:

(local) > createSSHKeyPair name=MyKey02
keypair:
name = MyKey02
fingerprint = 53:35:10:16:14:27:d4:2a:59:48:1d:07:ca:14:41:87
privatekey = -----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQCD5ImluDq/Zi3GOs9aTJFPmt+kUVA2CZS9vxfr6wWYOnXAwIFu
8RRrai6N3RM0A9Tmy9PHiW84qiutS6kkmZ9Kz1fD7CFoHbqJYkXFk58HX1FZKQzN
wjG/AVB7f6N9RlbGzb67CCdQ/ReOYAfMvZvhaPVYOjwkF0eNO01Z7wuYJwIDAQAB
AoGAQKCOdh6k4r59tYGBsxyLo3cfGNQjOqdNNADcBuTdk+8pXe62PZdxywR3lVn7
m+Q4wXKk7kRAtIJl7n+BfQatj3WPyn9fKFsBd2HTPh0QRntIXx/2ZANmmrCjE5QU
bjSLw30+WLbTpNjuNQR3N+ZWAQMqKheAMXr2XzK5l3s/ZkECQQC8q3+it3+vNgbH
rclbisbvqVFRVOfkxDVtU7w3s9NM/bHQ4DejEtY/yLigd3d3Gmm9nQ6zR8ROY/Zm
484AwGmHAkEAsvX9bHf6/SbACmTWnQgQ/cF5OT3psW8ty9cFzoRSG8VKpW9tBkKN
Jl5XMqK0jvqEaDBITVsPSKObGAoGuPaEYQJBAKZ9zMdhmNqcGYWR9ZPDtmP9jZXx
ECYPg3ozn2+kT72sToMdqdtNHyXwUgTBB/pho5hBBZztouzuR51qP/rn0PcCQBID
qwfxJ+W1sd0Z+3SBLFyuzgoSDmUbAOwk7+Oy9CTxfisbBUl9B4JWOsbRFAXUd+GZ
Ap4uzWINff40fCrAPeECQQCwTH5KG76cz+AL3LjIHHj0nxn5yH3NpGxy3eXpZ6u+
UDFpZ2mfthuBjht74iUf/bP8EBT0uaIGNOVPiM7JEKg+
-----END RSA PRIVATE KEY-----

The public key is retained by VDC; it is not possible to see it with the API. You can use the fingerprint to test that a private key and public key make a matching key pair.

To use the new key pair you need to copy the private key into a file (which in Linux is usually stored in the folder '~/.ssh') and you must set the file permissions to 'owner read-only'. For example, create the private key file '~/.ssh/id_rsa_MyKey02' and then use the command:

$ chmod 600 ~/.ssh/id_rsa_MyKey02

Note: you can inspect the public key by using it to deploy a VM and then looking at the content of the SSH '~/.ssh/authorized_keys' file for the administrator user (usually 'root', but it depends on the operating system: CoreOS Linux uses 'core', and Ubuntu Certified virtual machines use 'ubuntu').

List the public keys stored in a VDC account (API command: listSSHKeyPairs)

To get a list of the public keys currently stored in your account:

(local) > listSSHKeyPairs
count = 2
sshkeypair:
+------------------+--------------------------------------+----------------+--------------------+-------------------------------------------------+
|     account      |               domainid               |      name      |       domain       |                   fingerprint                   |
+------------------+--------------------------------------+----------------+--------------------+-------------------------------------------------+
|  Interoute Demo  | 5b195d44-b1af-4540-a976-a6e162857e8f |    MyKey01     |   Interoute Demo   | 55:33:b4:d3:b6:52:fb:79:97:fc:e8:16:58:6e:42:02 |
|  Interoute Demo  | 5b195d44-b1af-4540-a976-a6e162857e8f |    MyKey02     |   Interoute Demo   | 53:35:10:16:14:27:d4:2a:59:48:1d:07:ca:14:41:87 |
+------------------+--------------------------------------+----------------+--------------------+-------------------------------------------------+

For security reasons you can't see the values of the public keys, only the 'fingerprint' values which you can compare against the fingerprint generated from the private key in your own computer.

Delete a stored public key (API command: deleteSSHKeyPair)

Use the 'name' to refer to the public key that you want to delete:

(local) > deleteSSHKeyPair name=MyKey01
success = true

Deploy a virtual machine with the keypair option

To use a public key in a virtual machine deployment add the 'keypair' option to the deployVirtualMachine API command. For example:

(local) > deployVirtualMachine networkids=b52c8831-c997-4a68-b06d-3bbbbf9dfd6a displayname=ubuntu1604server name=ubuntu1604server zoneid=e564f8cf-efda-4119-b404-b6d00cf434b3 templateid=fe22df7f-dbdf-40ae-b1f7-0c04cbdf1dbd serviceofferingid=4cb92069-e001-4637-8848-76d74f406bb8 keypair=MyKey02
virtualmachine:
id = 64c109dc-e542-4d90-9616-f5afd5c4dce5
name = ubuntu1604server
......
keypair = MyKey02
......

When you connect to this VM using SSH, you can include the private key which matches the public key stored in the VM, and this will bypass the usual login/password request. For example:

$ ssh -i ~/.ssh/id_rsa_MyKey02 ubuntu@213.XXX.XXX.XXX

For the first connection to the virtual machine you will be asked to check authenticity:

The authenticity of host '213.XXX.XXX.XXX (213.XXX.XXX.XXX)' can't be established.
ED25519 key fingerprint is e8:6a:a9:02:09:93:4a:2c:20:97:e4:56:da:c1:b7:a0.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '213.XXX.XXX.XXX' (ED25519) to the list of known hosts.
ubuntu@ubuntu1604server:~$

If the public and private keys do not match, then you will see a 'password:' prompt in response to the 'ssh' command. This often happens because you forget to use the correct administrator name, so you type for example 'root@...' rather than 'ubuntu@...'.

Replace a public key stored in a virtual machine (API command: resetSSHKeyForVirtualMachine)

You can use this command to replace a public key already stored in a virtual machine with a different public key. One use of this could be to reset access to a virtual machine to lock out any person whose right of access has been withdrawn.

(local) > resetSSHKeyForVirtualMachine id=64c109dc-e542-4d90-9616-f5afd5c4dce5 keypair=MyKey03

'id' here is the UUID of the virtual machine. The virtual machine needs to be in 'stopped' state to apply this command. When the VM is re-started the new public key value will be installed. This result does depend on having a compliant boot script in the VM to perform the re-installation.