Working with MasterKeys

Author : Arnaud Fauvel (Obiane – Orange Group – France)


Introduction :

As explained in “SOL9420: Installing a UCS file containing an encrypted passphrase”:
Passphrases used for configuration items, such as monitors, profiles, and Secure Sockets Layer (SSL) keys, are stored in the configuration file in encrypted format. The BIG-IP system uses a hardware-key encrypted master key to encrypt and decrypt passphrases contained in the configuration file. These hardware-key encrypted passwords can be identified with a prefix of $M$.
Prior to BIG-IP 11.5.0, only the passphrases used for SSL private keys are stored in encrypted format. In BIG-IP 11.5.0 and later, passphrases used for other configuration objects, such as monitors and profiles, are also stored in encrypted format.


To complete the description, the master key unit is:
- Different on each standalone device but shared within a cluster.
- Different on each vCMP guest and is dissociated from vCMP host.

How to modify MasterKey
As explained in the SOL it’s possible to modify the master key of the device with the following command:
f5mku -r
There are two bad behaviors of this command:
- If there are already configuration items with encrypted parameter, the bigip is unable to load the configuration. We have to remove SSL key passphrase encryption as explained in the SOL14302: Replacing a VIPRION chassis that has one or more blades installed.
- On a vCMP Host or Guest after executing the command the device become unstable.
F5 support provides me the following commands explained in the following “SOL13508: ConfigSync operations fail to complete and generate a validation message”:
modify /sys crypto master-key prompt-for-password
This command is magic:
- A new masterkey is defined based on a provided password
- Saving the configuration automatically re-encrypts any encrypted-SSL-key passphrases, using the new master key, prior to saving them in the configuration file.
- It works on BIGIP or vCMP guest.
Considering the masterkey of the vCMP Host it’s not so simple. The precedent command can be used but all vCMP Guest will be unable to retrieve their master key:
notice mcpd[6230]: 01071029:5: Cannot open unit key store
notice mcpd[6230]: 01070406:5: Removed publication with publisher id ha_table_publish
warning mcpd[6230]: 012a0004:4: halStorageRead: unable to read storage on this platform

The masterkey of the vCMP host seems to be used for a unit key store shared with all vCMP Guest. You will find bellow a scheme which tries to represent the master key architecture:


How to restore archive configuration without removing SSL key passphrase encryption
The “SOL9420: Installing a UCS file containing an encrypted passphrase” is not really satisfactory because as explained before the f5mku -r commands doesn’t work with vCMP guest. But by using the magic commands it’s works very well J.
1. After installing a BIGIP or vCMP Guest, log in on to de device and force the master key with a password by typing the following command:
# tmsh
# modify /sys crypto master-key prompt-for-password
enter password:
password again:
# save /sys config
Saving running configuration...

2. Save regulary the configuration (using iApp or remote expect script):
save /sys ucs passphrase
3. Log in to the RMA BIG-IP system command line.
4. Install the master key with the password you enter in step 1 to the RMA BIG-IP system using the following command syntax:
# tmsh
# modify /sys crypto master-key prompt-for-password
enter password:
password again:
# save /sys config
Saving running configuration...

5.Restore the UCS file to the RMA BIG-IP system using the following command syntax:
tmsh load sys ucs .ucs no-license

Published Jul 27, 2015
Version 1.0

Was this article helpful?


  • Hello,


    I find a recent SOL and it explain this command and masterkey with vCMP :


    In HA configuration, it's only necessary to used this command on one member of cluster and to sync in all member of cluster.


    We just have one interrogation about unit key and storage of unit key for vCMP guest ?


    It explain in this article that :


    "If no EEPROM is available, for example in the case of a BIG-IP Virtual Edition (VE) system, the system stores the unit key as a hidden file named .unit.key in the /config/bigip/kstore file. The system generates and stores Virtual Clustered Multiprocessing (vCMP) guest unit keys on the vCMP host, and the host unit key, stored in hardware, protects the host master key."


    So it doesn't very clear for me if used specific path and file in vCMP host to store the unit key of guest or if it used EEPROM of vCMP host to store unit key of guest vCMP.