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.
KMS → Keys → Create key → Bring your own key, or
POST /kms/api/keyswith{ "origin": "external" }. The key startspending_import.Key material → Get wrapping key and token, or
POST /kms/api/keys/{id}/import-parameterswith{ "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.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.binWith
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.Import, or
POST /kms/api/keys/{id}/importwith{ "importToken": "…", "encryptedKeyMaterial": "<base64>", "expiresAt": "2027-01-01T00:00:00Z" }.expiresAtis optional. The key becomesenabled.
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 becomespending_importand 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 |