Controller Overview

The QKD device controller has a dual role in establishing QKD links between KMEs and also authorising SAEs onto which KME they can communicate to. In the initial implementation, only two nodes are present and thus the QKD device controller is only responsible for stopping and starting the devices which is described in QKDServer.

The QKD device controller may also be responsible for unsealing the vault depending on how strict the implementation of the QKD device is configured. In the current [1] Guardian implementation, there is an unsealer process that does this automatically.

Unsealing Vault

Whenever the Vault is started, it is in a sealed state. It will also be the QKD device controller’s duty together to unseal the vault (if implemented as such). He/she will need a minimum quorum of unseal keys in order to do this.

GUI

The unseal method using the Vault web UI is shown as an example below.

Vault in a sealed state

When Vault is in a sealed state, the Vault GUI interface will indicate with a red sealed under status. It will display the following prompt for the Unseal Key Portion to be entered.

One unseal key entered

If one unseal key is entered, it shows 1/3 keys provided.

Two unseal keys entered

Similarly for two unseal keys entered.

Vault unsealed

Once the vault is unsealed, the login screen is shown once again with the status now green indicating that Vault is unsealed.

API

Vault also has an API endpoint for the unsealing process. This is documented in Vault documentation. Briefly, it supplies a PUT request to /sys/unseal with a JSON payload of the unseal key.

{
   "key": "abcd1234..."
}

HVAC

If using Python, the hvac module has the submit_unseal_key(key=None, reset=False, migrate=False) function. This is the same function that Guardian’s unsealer uses.

In essence, this function makes use of the Vault API /v1/sys/unseal backend to input the unseal keys.

Changing Password

The qkd_controller can login to the Vault via the userpass auth method that is enabled. This is for convenience in demonstration and initial setup and should be switched off in a production environment. The default password should be changed for security and can be done through the web UI, hvac or vault-API

web UI

Log in the the vault web UI using the username and password

Vault username login :scale: 60% :figwidth: 60%

Once logged in, bring up the Vault browser CLI by clicking the shell icon at the top right hand corner. Enter vault write auth/userpass/users/qkd_controller/password password="new_password" where new_password is the updated new password.

Vault userpass change password :scale: 60% :figwidth: 60%

Once successful, the password is changed and the new password can be used to log in.

HVAC

 1import hvac
 2
 3url = "https://kme_address:8200/"
 4client_key = 'path/to/key"
 5client_cert = 'path/to/cert"
 6server_cert = 'path/to/server/cert'
 7username = 'qkd_controller'
 8password = 'qkd_controleer_password'
 9
10vclient = hvac.Client(url,  cert = (client_cert, client_key), verify = server_cert)
11vclient.auth.userpass.login(username=username, password=password)
12new_password = 'new_qkd_controller_password'
13vclient.auth.userpass.update_password_on_user(username=username, password=new_password)

Vault will return a 204 empty respose if call is successful.

Vault API

In this example of changing the password with the Vault API. Similar to CSR signing, to use this method, a Token is required. First we obtain the token using the controller username and password and the /auth/userpass/users/login backend.

{
   "password": "old_password"
}

With this token, the user password can be changed using the auth/userpass/users/{name}/password backend

{
   "password": "new_password"
}