Keypair support for X509 public key certificates

Keypair support for X509 public key certificates

Introduction of X509 public key certificates keypair support in the Nova API.

Problem description

Nova keypairs are mostly used by Linux guests to handle user authentication via SSH public key authentication without incurring in the management and security overhead that passwords require.

Public keys are provided to the guests as part of the metadata and included in the guest configuration by tools like cloud-init.

Windows operating systems don’t support natively SSH and thus authentication requires the usage of passwords unless the image deployer chooses to include a 3rd party unsupported SSH service port, which implies incurring in potential security and support issues.

Windows supports natively password-less authentication for WinRM by using X509 certificates, including PowerShell remoting.

X509 certificates are used by WinRM in a way which can be considered consistent with the usage of SSH keys on Linux, as both are based on public / private keypairs. This is limited by the lack of native availability of SSH on Windows.

Certificates can be generated by the user or by Nova (like for the SSH keypair case). Self-signed certificates are accepted.

Use Cases

End User will be able to connect to a Windows instance without requiring a password.

Like for the SSH keypair case, the use has the choice to generate the X509 certificate and pass the public X509 to Nova (recommended) or let Nova generate and return the certificate including the private key.

Project Priority


Proposed change

While Nova currently supports SSH keypairs only, the API can be extended to support x509 certificates, while maintaining full backwards compatibility.

The areas that require changes are:

  • Nova API, to accept the certificate type as an option (defaulting to SSH if not provided)

  • The nova.compute.api.KeypairAPI class to be able to generate and manage X509 certificates beside the existing SSH case

  • nova.objects.Keypair class to add a type property

  • Related database migration

  • Nova metadata API to support an additional x509 content in nova.api.metadata.base.InstanceMetadata()

  • python-novaclient to add the optional keypair type option

Usage examples

Generating an x509 keypair via CLI and saving the private certificate locally (in PKCS#12 format):

nova keypair-add keypair1 –keypair-type x509

Importing an x509 public key certificate:

nova keypair-add keypair1 –keypair-type x509 –pub-key /path/to/PEM_encoded_public_certificate

The certificate type could be discovered by examining the content without requiring the user to provide it explicitly.

For backwards compatibility, omitting the certificate type results in a SSH certificate:

nova keypair-add keypair2 –pub-key /path/to/SSH_pub_key

equivalent to:

nova keypair-add keypair2 –keypair-type SSH –pub-key /path/to/SSH_pub_key

On the metadata side ssh keys and x509 keys are provided separately for backwards compatibility:

“public_keys”: {“keypair2”: “ssh-rsa AAAAB3…cyJvOQ== Generated by Novan”}, “x509”: {“keypair1”: “MIIDaTC…ysk8w==n”},

Server metadata schema does not need changes:


We are not worrying about the WinRM service certificate, as tools like cloudbase-init can generate a self signed certificate that works in a similar way to ssh host keys. Ideally the client would be told what certificate it needs to trust, but this will be left until we do the same for ssh host keys.

Data model impact

nova.objects.Keypair requires an additional string (VARCHAR(20)) type property, named “Type”. Initial possible values will be:

“ssh” “x509”

Default value during database migration will be “ssh”.

REST API impact

An optional extension named “os-extended-keypairs” will be added to “/v2/{tenant_id}/os-keypairs” providing the following:

GET /v2/{tenant_id}/os-keypairs

Will include in the response dictionary the key type “key_type”.

If the “os-extended-keypairs” extension is not present, only SSH keypairs will be returned.

POST /v2/{tenant_id}/os-keypairs

Will include an optional parameter “key_type” (xsd:string), with possible values “SSH” and “X509”, default value “SSH”.

The keypair schema definition will include “key_type” as well:

create = {
    'type': 'object',
    'properties': {
        'keypair': {
            'type': 'object',
            'properties': {
                'public_key': {'type': 'string'},
                'key_type': {'type': 'string'},
            'required': ['name'],
            'additionalProperties': False,
    'required': ['keypair'],
    'additionalProperties': False,

server_create = {

Security impact


Notifications impact


Other end user impact


Performance Impact


Other deployer impact


Developer impact




Primary assignee:


Other contributors:


Work Items

  • Nova feature implementation

  • python-novaclient support


  • The guest will need to employ an agent able to retrieve the certificates from the metadata and import them. Cloudbase-Init >= 0.9.6 is already supporting x509 certificates.


  • CI testing will be performed by the Hyper-V CI.

  • Tempest tests will be developed for this feature.

Documentation Impact

The Nova driver documentation for nova keypair API and CLI commands usage need to be updated.


Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.