tacker-specs/specs/2023.2/support-external-keymanager.rst

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)¹.

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.

{
    "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:

1. Add utility functions to integrate with an external key manager.
2. Add sample implementations with v2API and OpenStack Key Manager.
3. 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² 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 {

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 {

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.

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³ 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⁴.

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 <kenta.fukaya@ntt.com>

Yuta Kazato <yuta.kazato@ntt.com>

Other contributors:

Yusuke Niimi <niimi.yusuke@fujitsu.com>

Yoshiyuki Katada <katada.yoshiyuk@fujitsu.com>

Ayumu Ueha <ueha.ayumu@fujitsu.com>

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⁵.

• Decryption methods for authentication credentials

  Depends on Secret Get by UUID API in barbican⁶.

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

---

1. https://docs.openstack.org/barbican/latest/↩︎

2. https://docs.openstack.org/barbican/latest/↩︎

3. https://docs.openstack.org/barbican/latest/↩︎

4. 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↩︎

5. https://docs.openstack.org/barbican/latest/api/reference/store_backends.html↩︎

6. https://docs.openstack.org/barbican/latest/api/reference/secrets.html↩︎