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

.. _attach_pubkeys_to_server:

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