Skip to content

keypairs.rst

Latest commit

 

History

History
154 lines (100 loc) · 5 KB

keypairs.rst

File metadata and controls

154 lines (100 loc) · 5 KB

Keypairs (SSH keys)

The keypairs resource can be used to store ssh keys, for use with your servers. You have the choice whether to store only the public key or the full public-private key keypair. Keys attached to a server appear in the :doc:`server context <server_context>`, and for OS images, which support cloudinit, they can also be automatically added to authorized_keys on a reboot. If you omit the public and private keys when creating a keypair, a new rsa keypair will be automatically generated for you. Having the private key in your profile will allow for using a web-based ssh client. It is also useful if your OS does not have key generation tools installed.

If the user has turned on two-factor authentication, the keypairs resource is protected with one time password. In order to make key management for servers easier (and not requiring OTP), there is pubkeys resource, which is a read-only version of the keypairs resource. The pubkeys objects are identical to keypairs except for the fact that they do not contain the private key, and have a has_private_key attribute instead of private_key, which indicates whether the private key was set.

We currently support two types of SSH Keys: RSA and ed25519. The maximum size for the RSA keys is 4096 bits.

Creating a keypair

.. http:post:: /keypairs/

You have three choices when creating a keypair:

  • Provide both private and public key
  • Provide only a public key, in which case the private key will remain empty
  • Provide no public, neither private key, in which case a new pair will be generated for you

For the 3rd choice, you need to also define the "algorithm_type" for generating the key.

Here is an example of providing both pairs:

.. literalinclude:: dumps/request_self_gen_keypair_create
    :language: http


.. literalinclude:: dumps/response_self_gen_keypair_create
    :language: javascript

Here is an example of providing only a public key:

.. literalinclude:: dumps/request_pub_key_only_keypair_create
    :language: http


.. literalinclude:: dumps/response_pub_key_only_keypair_create
    :language: javascript

Here is an example of creating an autogenerated pair, for which you need to also specify the algorithm type. The choices for the algorithm_type can be one of the "rsa" or "ed25519" types. The maximum size for the RSA keys is 4096 bits.

.. literalinclude:: dumps/request_autogen_keypair_create
    :language: http


.. literalinclude:: dumps/response_autogen_keypair_create
    :language: javascript

Listing, Getting, Updating, Deleting

List keypairs:

.. http:get:: /keypairs/


.. literalinclude:: dumps/request_keypair_list
    :language: http


.. literalinclude:: dumps/response_keypair_list
    :language: javascript

Get a single keypair:

.. http:get:: /keypairs/{uuid}/


.. literalinclude:: dumps/request_keypair_get
    :language: http


.. literalinclude:: dumps/response_keypair_get
    :language: javascript

Update a kypair:

.. http:put:: /keypairs/{uuid}/


.. literalinclude:: dumps/request_keypair_update
    :language: http


.. literalinclude:: dumps/response_keypair_update
    :language: javascript

Delete a keypair:

.. http:delete:: /keypairs/{uuid}/


.. literalinclude:: dumps/request_keypair_delete
    :language: http


.. literalinclude:: dumps/response_keypair_delete
    :language: javascript

Pubkeys resource

In order to access just the public keys without the need for OTP, you can use the pubkeys resource. Instead of a private key it contains an attribute has_private_key which indicates whether the private key was set.

For example creating an autogenerated keypair:

.. literalinclude:: dumps/request_autogen_keypair_create
    :language: http


.. literalinclude:: dumps/response_autogen_keypair_create
    :language: javascript

Results in a corresponding pubkeys object with has_private_key, which is true:

.. literalinclude:: dumps/request_pubkeys_full_keypair
    :language: http


.. literalinclude:: dumps/response_pubkeys_full_keypair
    :language: javascript

Creating a keypair with only a public key:

.. literalinclude:: dumps/request_pub_key_only_keypair_create
    :language: http


.. literalinclude:: dumps/response_pub_key_only_keypair_create
    :language: javascript

Results in a corresponding pubkeys object with has_private_key, which is false:

.. literalinclude:: dumps/request_pubkeys_pub_only_keypair
    :language: http


.. literalinclude:: dumps/response_pubkeys_pub_only_keypair
    :language: javascript

Attaching pubkeys to a server

You can attach the keys to a server definition on the pubkeys attribute. They are made available to the VM OS via the :doc:`server context <server_context>`.

Here is an example of doing that using the keys created in the above section:

.. literalinclude:: dumps/request_pubkeys_server
    :language: http


.. literalinclude:: dumps/response_pubkeys_server
    :language: javascript