diff --git a/doc/blockstore/storage/encryption-at-rest.md b/doc/blockstore/storage/encryption-at-rest.md new file mode 100644 index 0000000000..6f11c594da --- /dev/null +++ b/doc/blockstore/storage/encryption-at-rest.md @@ -0,0 +1,30 @@ +# Encryption at rest (NRD/Mirrored) + +## General information +The data encryption key (DEK) is stored in encrypted form in the volume metadata ([EncryptionDesc](../../../contrib/ydb/core/protos/blockstore_config.proto#L117)). For DEKs generating and encrypting the root key management service (RootKMS) is used. A master key that uses for encryption and decryption of DEKs is stored in RootKMS and is not transmitted in open form - requests to RootKMS use only the identificator of the master key. If the master key is compromised, a new one is generated and then all DEKs must be re-encrypted (and updated in the volume metadata) using the new master key. + +## Creating a volume +NBS requests a new DEK from RootKMS, sending the master key identificator. The received encrypted DEK is stored in the volume metadata. + +```mermaid +sequenceDiagram + participant NBS + participant RootKMS + + NBS->>+RootKMS: generate DEK (master key id) + RootKMS-->>-NBS: encrypted DEK + NBS->>NBS: store DEK in VolumeConfig +``` + +## Mounting a volume +NBS requests a decrypted DEK from RootKMS, sending the encrypted DEK and the master key. The received DEK is used for the encryption/decryption of IO requests data. To handle IO requests the [TEncryptionClient](../../../cloud/blockstore/libs/encryption/encryption_client.cpp#L138) is used. + +```mermaid +sequenceDiagram + participant NBS + participant RootKMS + + NBS->>+RootKMS: decrypt DEK (master key id, encrypted DEK) + RootKMS-->>-NBS: DEK + NBS->>NBS: create TEncryptionClient (DEK) +```