diff --git a/specs/untargeted/byok-for-cinder.rst b/specs/2024.2/byok-for-cinder.rst similarity index 67% rename from specs/untargeted/byok-for-cinder.rst rename to specs/2024.2/byok-for-cinder.rst index 138808cb..b8db53b9 100644 --- a/specs/untargeted/byok-for-cinder.rst +++ b/specs/2024.2/byok-for-cinder.rst @@ -17,6 +17,8 @@ Problem description Encryption keys are currently generated completely transparent for end-users. Most features are already implemented and tested therefore. What's missing is the possibility to use a user defined key, known as "bring your own keys", for encryption. This may be useful for certain legal requirements or specifications to be fulfilled. +One example use of BYOK the European Union's "General Data Protection Regulation". This way the deployer has to ensure that the KeyManager and VM instances run within the regulated region or a legal agreement must be closed with the deployer but data at rest including any backups may be stored even outside the legitime region as data is encrypted at this stage already. + Use Cases ========= @@ -28,7 +30,7 @@ Use Cases Proposed change =============== -Most peaces are already in place and do not to be changed for that feature to be implemented. The KeyManager implementation holds the key provided by the end user. +Most pieces are already in place and do not to be changed for that feature to be implemented. The KeyManager implementation holds the key provided by the end user. With the current implementation the secret is copied and the passphrase is derived from the end user expected secret. - The most visible change is to be able to provide an encryption key ID to create volume. - ``cinder.volume.volume_utils.clone_encryption_key()`` must be used to ensure keys can be deleted when the volume is deleted @@ -46,17 +48,27 @@ None REST API impact --------------- -- ``/v3/{project_id}/volumes`` +- POST ``/v3/{project_id}/volumes`` - * Create a volume: POST + * Create a volume * Normal http response code(s): 202 * New optional ``parameter encryption_key_id`` indicates which encryption key ID from the KeyManager implementation should be used + :: + + { + "volume": { + "encryption_key_id": "", + ... + } + } + * 400 may be used to indicate if the volume type chosen does not support encryption at all as well * Maybe a new use of response code 409 may be needed if e.g. a encrypted snapshot volume should be copied with a different key + * 503 with a message similar to "KeyManager Service is Unavailable" should be returned if the KeyManager API neither does not return at all or provides no useful error message Security impact --------------- -No direct security impact changes are connected with the proposed change. For the alternative solution sensitive encryption keys are handled by ``.Create()``. +No direct security impact changes are connected with the proposed change. Security requirements and regulations are expected to be at the end users responsibility. Active/Active HA impact ----------------------- @@ -71,7 +83,7 @@ None Other end user impact --------------------- -For ``python-cinderclient`` a new optional attribute may be added. +For ``python-cinderclient`` and ``OpenStackClient`` the new optional attribute should be added. Documentation need to be updated to ensure that end users understand the internal handling of the provided secret with the default implementation. Performance Impact ------------------ @@ -99,8 +111,10 @@ nteo Work Items ---------- -- Update ``/cinder/volume/api.py`` to accept an encryption key ID. The encryption key ID should be stored in the configured KeyManager (usually Barbican). Based on feedback of the OpenStack community an alternative would be to provide and store the key right away on create. +- Update ``/cinder/volume/api.py`` to accept an encryption key ID. The encryption key ID should be stored in the configured KeyManager (usually Barbican). +- Request encryption details from the KeyManager implementation to ensure it matches the requirements for use with volume encryption - ``clone_encryption_key()`` of ``/cinder/volume/volume_utils.py`` must be used to ensure keys can be deleted when the volume is deleted +- Update / write documentation about secrets being copied upon use with volumes Dependencies ============ @@ -115,7 +129,7 @@ Similar to encrypted snapshot handling. Documentation Impact ==================== -The optional new parameter should be listed. +The optional new parameter should be listed. The workflow about secrets being copied upon use with volumes should be described. References ==========