From 42002be8aebfb9a37b82c8d61b6590a35c44b5c4 Mon Sep 17 00:00:00 2001 From: Yuta Kazato Date: Thu, 30 Mar 2023 09:31:47 +0900 Subject: [PATCH] Support External Keymanager for auth credential This specification describes the encryption and decryption methods for authentication credentials in Tacker by using an external key manager service such as OpenStack Key Manager (barbican). Implements: blueprint support-external-keymanager Change-Id: I384891eb1f967d7ab21639a18899a75e995e767b --- specs/2023.2/support-external-keymanager.rst | 399 +++++++++++++++++++ 1 file changed, 399 insertions(+) create mode 100644 specs/2023.2/support-external-keymanager.rst diff --git a/specs/2023.2/support-external-keymanager.rst b/specs/2023.2/support-external-keymanager.rst new file mode 100644 index 00000000..74f67ee4 --- /dev/null +++ b/specs/2023.2/support-external-keymanager.rst @@ -0,0 +1,399 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + + +============================================================== +Support an external key manager for authentication credentials +============================================================== + +This specification describes the encryption and decryption methods +for authentication credentials in Tacker by using an external key manager +service such as OpenStack Key Manager (barbican) [#OpenStack_Key_Manager]_. + + +Problem description +=================== + +Tacker stores some authentication credentials in Tacker DB. +However, in the case of the actual NFV operation of Tacker, +these information should be encrypted for secure NFV +management and security requirements to prevent +eavesdropping and data exploitation by attackers. + +The following is a sample of VnfInstanceV2.vimConnectionInfo (Kubernetes): +authentication credentials are password, bearer_token and client_secret. + +.. code-block:: + + { +     "vim1": { +         "vimType": "ETSINFV.KUBERNETES.V_1", +         "accessInfo": { +             "username": "nfv_user", +             "password": "password", +             "bearer_token": "bearer_token", +             "client_secret": "client_secret" +         }, +         "interfaceInfo": { +             "endpoint":"http://123.124.64.6:8443", +             "ssl_ca_cert": "ssl_ca_cert" +         } +     } + } + +This specification proposes an encryption and decryption implementations +using a common key scheme using "cryptography" library and an external +key management service to manage credentials and keys securely. + +Proposed change +=============== + +The following changes will be proposed: + +#. Add utility functions to integrate with an external key manager. +#. Add sample implementations with v2API and OpenStack Key Manager. +#. Add configuration options. + +Add utility functions to integrate with an external key manager +--------------------------------------------------------------- + +Since Tacker stores sensitive credentials in multiple DB tables, +this specification will implement common utility functions to +encrypt and decrypt the credentials in cooperation with +an external key manager are required for both v1 and v2 API. + +Examples of authentication credentials to be encrypted +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following is a list of examples of authentication credentials +to be encrypted in Tacker. + +* accessInfo in VimConnectionInfo: + password, bearer_token, and client_secret + +* paramsBasic and paramsOauth2ClientCredentials in authentication: + password and clientPassword + +* metadata.targetsInfo.authInfo in Prometheus Plugin: + ssh_password + +.. note:: + This function will use generically for other sensitive information too. + + We will analysis and add more detailed target data + if new targets are found during our implementation. + +common utility functions include three main roles: + +1. Manage encryption keys in cooperation with an external key manager. + It enables the registration and deletion of encryption keys. +2. Encrypt the authentication credentials using the encryption key + and store them to Tacker DB. +3. Decrypt the authentication credentials stored in Tacker DB + by the decryption key and use them for VNF operations. + +Users can perform VNF operations without awareness of this process. +On the other hand, the authentication credential is encrypted in tacker DB +and the possibility of eavesdropping or data data exploitation is reduced. + + +Two types of encryption keys are created: master key and table key. +The table key is used to encrypt authentication information, +and the master key is used to encrypt the table key. +The table key is created when authentication information +is saved in the DB, and the master key is created when Tacker is started. +The table key and master key are stored in +a new table created to store the encryption key. + + +Add sample implementations with v2API and Barbican +-------------------------------------------------- + +In this specification, it implements a sample usecase for +encryption and decryption of authentication credentials +to integrates with barbican [#OpenStack_Key_Manager]_ +in v2 API. + +Example of proposed sequences in VNF LCM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The following is an example of sequence for encryption and decryption +of authentication credentials in VNF LCM operations under consideration. + +The following is a flow of Instantiation of a VNF instance +with barbican under consideration. + +.. seqdiag:: + + seqdiag { + Client; NFVO; tacker-server; tacker-conductor; VnfLcmDriver; TackerDB; Barbican; + + Client -> "tacker-server" + [label = "POST /vnflcm/v2/vnf_instances/{vnfInstanceId}/instantiate"]; + Client <-- "tacker-server" [label = "202 Accepted"]; + "tacker-server" -> "tacker-conductor" + [label = "trigger asynchronous task"]; + NFVO <- "tacker-conductor" [label = "POST /grants"]; + NFVO --> "tacker-conductor" [label = "201 Created"]; + "tacker-conductor" -> "tacker-conductor" [label = "encrypt auth credentials"]; + "tacker-conductor" -> "Barbican" [label = "register the encryption key"]; + "tacker-conductor" <-- "Barbican" [label = "200 Successful Request"]; + "tacker-conductor" -> "VnfLcmDriver" [label = "execute VnfLcmDriver"]; + "tacker-conductor" <-- "VnfLcmDriver" [label = ""]; + "tacker-conductor" -> "TackerDB" [label = "store encrypted auth credentials"]; + "tacker-conductor" <-- "TackerDB" [label = ""]; + + } + + +The following is a flow of Termination of a VNF instance +with barbican. + +.. seqdiag:: + + seqdiag { + Client; NFVO; tacker-server; tacker-conductor; VnfLcmDriver; TackerDB; Barbican; + + Client -> "tacker-server" + [label = "POST /vnflcm/v2/vnf_instances/{vnfInstanceId}/terminate"]; + Client <-- "tacker-server" [label = "Response 202 Accepted"]; + "tacker-server" -> "tacker-conductor" + [label = "trigger asynchronous task"]; + NFVO <- "tacker-conductor" [label = "POST /grants"]; + NFVO --> "tacker-conductor" [label = "201 Created"]; + "tacker-conductor" -> "TackerDB" [label = "load encrypted auth credentials"]; + "tacker-conductor" <-- "TackerDB" [label = ""]; + "tacker-conductor" -> "Barbican" [label = "get the encryption key"]; + "tacker-conductor" <-- "Barbican" [label = "200 Successful Request"]; + "tacker-conductor" -> "tacker-conductor" [label = "decrypt the encrypted auth credentials"]; + "tacker-conductor" -> "VnfLcmDriver" [label = "execute VnfLcmDriver"]; + "tacker-conductor" <-- "VnfLcmDriver" [label = ""]; + "tacker-conductor" -> "Barbican" [label = "delete the encryption key"]; + "tacker-conductor" <-- "Barbican" [label = "204 No Content"]; + + } + + +Add configuration options +-------------------------- + +As the function defined in this specification changes the default sequences, +it is suggested to add a configuration option to the +``tacker.conf`` file. +Therefore, users can choose whether to enable this function or not. + ++ Boolean value of "use_credential_encryption" + This parameter determines whether using encryption. + + Default value: "false" + ++ String value of "keymanager_type" + This parameter determines the type of external key management service. + + Default value: "barbican" + ++ String value of "crypt_key_dir". + This parameter specifies the path where the encryption key is stored. + + Default value: "" + + .. note:: + barbican will be supported in Tacker Bobcat cycle. + If other external key management services will be supported in the future, + this parameter allows the target service to be changed. + +As a suggested implementation, when the ``use_credential_encryption`` is True, +the function of encryption and decryption of authentication credentials takes effect; +When ``use_credential_encryption`` is False, this function will not performed. + + +Alternatives +------------ + +None + +Data model impact +----------------- + +The key-related information (e.g., key type, key id) +of the external key manager needs to be added in the data model. + +.. list-table:: + :widths: 15 10 30 + :header-rows: 1 + + * - Attribute name + - Data type + - Parameter description + * - id + - String + - id of key information (primary key) + * - secret_uuid + - String + - uuid of master key registered in barbican + * - encrypted_key + - String + - table key for tacker + * - key_type + - String + - how to retain master key. local or barbican + * - in_use + - Boolean + - Flag of the latest key is used + +REST API impact +--------------- + +None + +Security impact +--------------- + +If this change will be applied, the authentication credentials in Tacker DB +will be encrypted with the encryption key, so encryption keys must +be secured by an external key manager. +The option to store encryption keys in the local is also allowed, +but is deprecated in the production environment. + +In addition, encryption keys need to be backup so that users can +decrypt the credentials in case of failure or disaster recovery. +The following is an example of key backup when using barbican [#OpenStack_Key_Manager]_ +as an external key manager. + +Key backup methods by Barbican +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The process for backup and restore of encryption keys will +vary depending on the type of backend. +Two separate components need to be backed up for simple +crypto back end: the Key Encryption Key (KEK) and the database. + +* Backup and restore KEK. + +For the simple crypto back end, to backup the ``barbican.conf`` file +that contains the master encryption key; KEK is written. +This file must be backed up to a security hardened location. +The actual data is stored in the Barbican database. + +To restore the key from a backup, it needs to copy the restored +``barbican.conf`` over the existing ``barbican.conf``. + +* Backup and restore the barbican database. + +Run the following steps while logged in to the ``controller-0`` node. + +1. Retrieve barbican user password +2. Backup the barbican database +3. Database backup is stored in ``/home/heat-admin`` +4. Restore the databases + +.. note:: + Only the user barbican has access to the barbican database. + So the barbican user password is required to backup or + restore the database. + + For more information, please refer to the + OpenStack Key Manager backup documentation [#OpenStack_Key_Manager_Backup]_. + +Notifications impact +-------------------- + +None + +Other end user impact +--------------------- + +None + +Performance Impact +------------------ + +Tacker needs to access an external key manager service for +both encryption and decryption of authentication credentials. +The performance impact might be ``LOW`` if there are few +cases to use the encrypted authentication credentials that +each time the Rest API is called. + +However, the impact might be ``HIGH`` if it needs access to +an external key manager for every single data in the DB table. + +Implementation policies need to be carefully decided. + +Other deployer impact +--------------------- + +None + +Developer impact +---------------- + +None + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + Kenta Fukaya + + Yuta Kazato + +Other contributors: + Yusuke Niimi + + Yoshiyuki Katada + + Ayumu Ueha + +Work Items +---------- + ++ Implement Tacker to support: + + + Add utility functions to integrate with an external key manager + + Add sample implementations with v2API and OpenStack Key Manager + + Add a configuration option. + ++ Add new unit and functional tests. ++ Write Tacker documentation to explain how to use + the function described in this specification. + +Dependencies +============ + ++ Encryption methods for authentication credentials + + Depends on Secret Stores API in barbican [#Barbican_Stores_API]_. + ++ Decryption methods for authentication credentials + + Depends on Secret Get by UUID API in barbican [#Barbican_Get_API]_. + + +Testing +======= + +Unit and functional tests will be added to cover cases required +in this specification. + +Documentation Impact +==================== + +Add how to use external key management services via this function +to Tacker User guide. + +References +========== + +.. [#OpenStack_Key_Manager] + https://docs.openstack.org/barbican/latest/ +.. [#OpenStack_Key_Manager_Backup] + https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/17.0/html/manage_secrets_with_openstack_key_manager/assembly-managing-secrets-and-keys_rhosp +.. [#Barbican_Stores_API] + https://docs.openstack.org/barbican/latest/api/reference/store_backends.html +.. [#Barbican_Get_API] + https://docs.openstack.org/barbican/latest/api/reference/secrets.html