Keys (KMS)

Customer managed keys, bring your own key, key custody, SSH key pairs.

What it is

The keys that protect your secrets and encrypted disks, and the SSH key pairs you attach to compute instances. Find them under KMS in the console. Secrets themselves have their own guide: Secrets.

Concepts

Term Meaning
CMK A customer managed key: a symmetric AES-256-GCM key whose material the platform wraps and never shows.
Ciphertext blob What an encrypt call returns — ciphertext, initialisation vector and authentication tag. All three go back in to decrypt.
SSH key pair An ED25519 pair. The platform keeps the public key and its SHA256:… fingerprint; a generated private key is shown once and never stored.

How to

Create a key and encrypt with it

KMS → Keys → Create key, or POST /kms/api/keys. Then:

POST /kms/api/keys/{id}/encrypt
{ "plaintext": "hello" }

The response is the ciphertext blob. Pass its three parts back to POST /kms/api/keys/{id}/decrypt.

Disable or delete a key

Disable stops the key encrypting and decrypting, and every secret under it becomes unreadable until you enable it again:

PATCH /kms/api/keys/{id}
{ "status": "disabled" }

Deletion takes a waiting period. POST /kms/api/keys/{id}/schedule-deletion with { "pendingWindowInDays": 30 } starts it. While secrets are still encrypted with the key it is refused (409, code: "key_in_use", with the secrets' names): recreate them under another key or delete them first. POST /kms/api/keys/{id}/cancel-deletion calls it off while the window runs (the key returns to the status it had when the deletion was scheduled, enabled or disabled). When the window ends, the key is deleted within the hour, recorded in your audit log as kms:ScheduleKeyDeletion by system/kms-key-sweep; anything else still encrypted with it (a volume's key) can never be opened again. DELETE /kms/api/keys/{id} deletes it at once only once the window has elapsed, or earlier when nothing at all uses the key. A key scheduled before 18 November 2026 that still has secrets is held, with a warning on the key, until they are gone or the deletion is cancelled.

Bring your own key

A key can hold material you generate and keep yourself. Deutsche Cloud uses it like any key, and you can take it away again: delete the material, or let it expire, and nothing encrypted under the key opens until you import the same material again.

  1. KMS → Keys → Create key → Bring your own key, or POST /kms/api/keys with { "origin": "external" }. The key starts pending_import.

  2. Key material → Get wrapping key and token, or POST /kms/api/keys/{id}/import-parameters with { "wrappingAlgorithm": "RSAES_OAEP_SHA_256" }. You get an RSA-3072 public key (SubjectPublicKeyInfo DER, base64) and an import token. Both are valid for 24 hours and the token works once.

  3. Wrap your 32-byte key on your own machine:

    openssl rand -out key.bin 32          # your key; keep a copy, it is never shown back
    base64 -d wrapping-key.b64 > wrapping-key.der
    openssl pkeyutl -encrypt -pubin -inkey wrapping-key.der -keyform DER \
      -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256 \
      -in key.bin -out wrapped.bin
    base64 -w0 wrapped.bin

    With RSA_AES_KEY_WRAP_SHA_256, wrap a fresh AES-256 key with RSA-OAEP as above, wrap your key with it using AES key wrap with padding (RFC 5649, openssl enc -id-aes256-wrap-pad -iv A65959A6), and send the two concatenated in that order. The console shows both recipes.

  4. Import, or POST /kms/api/keys/{id}/import with { "importToken": "…", "encryptedKeyMaterial": "<base64>", "expiresAt": "2027-01-01T00:00:00Z" }. expiresAt is optional. The key becomes enabled.

What you can do with the material:

  • Disable the key: nothing opens. Enable it: everything opens again.
  • Delete key material (DELETE /kms/api/keys/{id}/material): the key becomes pending_import and nothing opens. Secrets cannot be read or deployed. A database, cache or compute volume under the key does not unlock the next time its machine starts. Running machines keep the volumes they have open until they restart.
  • Import again: only the same material is accepted. Deutsche Cloud compares the key check value, because different material would leave everything under the key unreadable. Importing again also replaces the expiry.
  • Expiry: within five minutes of expiresAt, Deutsche Cloud deletes the material as if you had.

Deutsche Cloud never generates or rotates an imported key's material. What this key protects on the key's overview, or GET /kms/api/keys/{id}/usage, counts the secrets, volumes, databases and caches under it, and names what a customer key does not cover yet: object storage, function code and logs, and Kubernetes etcd (encrypted with a key of its own).

The imported material is held the way generated material is: wrapped by the platform key, in software (see Key custody). Bringing your own key controls where the key comes from and when it stops working. It does not keep the key out of the platform while it is imported.

Add an SSH key pair

KMS → SSH key pairs → Generate, or POST /kms/api/ssh-key-pairs/generate. Copy the private key out of the response and save it — that is the only time it appears. To use a key you already have:

POST /kms/api/ssh-key-pairs/import
{ "name": "laptop", "publicKey": "ssh-ed25519 AAAA…" }

The launch wizard offers the same list when you start an instance, and installs the public key on the machine. Keys for pushing to Git live in a separate list under Account → SSH keys.

From a password manager

Keep the key in 1Password (or Vault) and let Deutsche Cloud follow its public key. KMS → SSH key pairs → From a password manager, or:

POST /kms/api/ssh-key-pairs/from-source
{ "name": "alice-laptop", "reference": "op://Private/Server key/public key" }

The reference names the public key: in 1Password, the public key field of an SSH Key item; in Vault, a KV field such as vault://secret/ssh/alice#public_key. A reference to a private key is refused, and the value is not kept. The private key stays in the password manager; connect with 1Password's SSH agent. Deutsche Cloud never holds a copy, so there is only one place to revoke it.

The source's sync keeps the key in step. If the public key changes upstream, Deutsche Cloud stores the new one, uploads it for new instances and deletes the old upload. Running instances keep the key they booted with, and an instance's page names that key when it is no longer the current one. A pair whose reference stops resolving, or now names a private key, shows the error and keeps its last key. Sync now (POST /kms/api/ssh-key-pairs/{id}/sync) re-reads it at once. A source cannot be disconnected while a key pair syncs from it.

Reference

Key fields and states

Field / state Values Default
description text up to 256 characters none
usage encrypt_decrypt encrypt_decrypt
status enabled, disabled — a disabled key neither encrypts nor decrypts enabled
pending deletion set by schedule-deletion; the key neither encrypts nor decrypts while the window runs —
pendingWindowInDays 7–30 30
origin dcloud (generated here) or external (you import the material) dcloud
pending_import an external key with no material; it neither encrypts nor decrypts —
keyCheckValue external keys: HMAC-SHA256 of ews-kms-key-check-v1 under your key, hex —
materialExpiresAt external keys: when Deutsche Cloud deletes the imported material never

Key custody

What protects your keys, plainly:

  • Software, not a hardware security module. Keys are AES-256-GCM and every cryptographic operation runs in the platform's own processes. There is no HSM and no FIPS-validated module anywhere in the chain.
  • One platform key at the root. Every CMK's material is stored in the platform database wrapped by a single 256-bit platform key, held in the environment of the platform's own servers. The same key wraps the platform's own secrets: database backup passphrases, the database certificate authority, the keys of encrypted disks, mail signing keys and object storage keys.
  • Who can unwrap. Anyone with root on the platform's own servers, or with both the platform key and a copy of the platform database, can unwrap every key. There is no split knowledge or dual control on the platform key. It can be rotated without downtime; no schedule rotates it automatically.
  • Disk keys. Each encrypted volume, database disk and cache disk has its own random key, wrapped by the platform key, or by a CMK you choose when you create the volume, database or cache. A machine receives its disk's key at boot only, only while the provider has the volume attached to it, and only from its own address. A disk's key can be rotated at any time (the disk's passphrase is replaced on the machine; the data is not re-encrypted).

A CMK you disable stops encrypting and decrypting at once; one you delete after its waiting period destroys everything under it, including a compute volume whose key it wraps.

SSH key pair fields

Field Values Default
name 1–64 characters required
publicKey an OpenSSH public key (import only) required
comment up to 128 characters, written into a generated key (generate only) none
uploadToHetzner also register the key with the compute provider true
Did this page help you?