Passphrase Encryption
Introduction
Prior to version v2.13.0 of nodectl, the passphrase responsible for unlocking your p12 keystore that contains the private and public keys necessary to access your hot wallet and to digitally sign your validated data, was unencrypted.
Optionally, nodectl has added the ability to encrypt the p12 passphrase, within the persistent configuration file that nodectl requires to perform its functionality.
Encrypt during upgrade
During a nodectl upgrade, if nodectl identifies that the configuration file contains an unencrypted passphrase, it will offer you the ability to encrypt during the upgrade.
Encrypt via the Configurator
Start Configurator
Start the configurator module.
sudo nodectl configure
Alternatively, you can add optional switches that will allow you to enter the configurator in edit mode, confirming the backup automatically, and entering detailed mode (verses advanced mode).
| option | description |
|---|---|
| -e | Directly enter into the edit section of the configurator. |
| -cb | confirm backup, you will not need to verify the location of the backup file before continuing |
| -d | Execute the configurator in detailed mode which will offer more details on all commands and questions that may need to answered. |
| -a | Execute the configurator in advanced mode which will not offer any details or detailed understanding of any questions that may need to be answered. |
Since we are using sudo, we will be challenged for our nodeadmin user password.
[sudo] password for nodeadmin:
alternatively, add the options.
[sudo] password for nodeadmin:
Advanced Mode
Note
If you choose to add the options mentioned above 👆 you can skip directly to the encryption step.
Until we are more comfortable with the configurator and all the particular settings of the configurator, we should not use advanced mode. We will choose no here 👇 by pressing enter to accept the default value or n+enter.
= CONSTELLATION NETWORK HYPERGRAPH =
= NODECTL =
= CONFIGURATION TOOL =
========================================
Code Name: Princess Warrior
Welcome to the nodectl configuration tool.
This feature of nodectl will help you initialize a new configuration or update/edit an existing configuration file.
nodectl will attempt to migrate/integrate your configurations changes in order to ensure a smooth transition and operations of your Node via nodectl.
Detailed Mode: will walk you through all steps/questions; with detailed explanations of each element of the configuration.
Advanced Mode: will be non-verbose, with no walk through explanations, only necessary questions.
The configuration tool does only a limited amount of data type or value verification. After the configuration tool creates a new configuration or edits an existing configuration, it will attempt to verify the end resulting configuration.
You can also choose the -a option at the command line to enter advanced mode directly.
Continue in advanced mode? [n]: n
Main Menu
Note
If you choose to add the options mentioned above 👆 you can skip directly to the encryption step.
Our goal in this procedure (documentation) is to encrypt existing passphrases, so we want to edit our configuration and will choose e.
= MAIN MENU =
========================================
N)ew Configuration
E)dit Existing Configuration
Q)uit
KEY PRESS an option
Backup
Note
If you choose to add the options mentioned above 👆 you can skip directly to the encryption step.
Before continuing, nodectl will backup your existing configuration file cn-config.yaml and offer you information on where it is located.
By default your configuration will use the /var/tessellation/backups directory. This is where you will find copy of your configuration file with the current system date and time (UTC) appended to the file name. nodectl can now make changes with the confidence that a backup of what was there previous is available if needed.
You can review the information on the screen and press any key to continue.
We can utilize the restore_config command to restore your configuration.
Enable Encryption
From the main edit menu of the configurator, we will choose P to enter into the encryption section.
= OPTIONS MENU =
========================================
E) Edit Individual Profile Sections
G) Global P12 Configuration
I) Global Cluster Token Identifier
T) Global Cluster Token Coin Id
R) Auto Restart Configuration
L) Set Log Level
P) Passphrase Encryption
M) Main Menu
Q) Quit
KEY PRESS an option
Confirm Encryption
You will be presented with a couple of important warning messages explaining the following key points:
- If you need to disable the configuration for any reason, it is simple to re-encrypt the passphrase at a later date. The old hash will be permanently removed and unusable. The passphrase will not be decrypted; rather, you will need to reconfigure the p12 elements via both the p12 global section and the individual p12 sections per profile manually. If you only have a single global p12 that is used for all profiles on the Node, you will still need to configure those sections to reference the global p12 section. This is done for security purposes..
- If you reenable encryption after a previous disablement, the old hashes will be overwritten permanently.
= PASSPHRASE ENCRYPTION =
= ENABLE ENCRYPTION =
========================================
IMPORTANT
Enabling encryption will encrypt your passphrase in the configuration file linked to nodectl functionality.
In the unlikely event the encrypted hash stops working [for whatever reason], you can simply disable this functionality, update/change your passphrase, and, upon completion, re-enable the encryption feature.
Encryption will be turned on globally for all profiles. Each unique profile passphrase may be encrypted with a different key.
For security purposes, nodectl will not decrypt the passphrase upon disabling the encryption feature.
WARNING
If the configuration file was manually updated, any updated encryption elements [or other] will be overwritten causing old encryption data that may be allowing nodectl to handle previously encrypted elements to stop working, to be overwritten, and removed!
You can confirm by pressing the enter key to accept the default value of y or hit the y+enter.
Validate your current passphrase
nodectl will request the p12 you want to encrypt and validate that passphrase before allowing you to encrypt.
Press enter your p12 passphrase for encryption.
p12 passphrase:
p12 file keyphrase (passphrase) [global] ...... validated!
Single Attempt
If you do not enter the correct passphrase, you will receive an error message from nodectl, and will need to restart the process.
Please take care to enter the correct passphrase on the first attempt.
Automated Encryption
nodectl will begin the encryption and return you to the main menu when the encryption is completed.
Derive a seed phrase to use with the encryption
Remove and destroy the seed phrase because it is a one-time use element of the encryption process.
Remove all elements that helped to prepare the encryption hash
Encryption is complete
Update the configuration
Building encryption elements [dag-l0] ......... completed
Configuration changes applied ................. successfully
Building encryption element ................... completed
Exit configurator
Finally, we will be returned to the main edit menu.
We will choose q to exit nodectl.
= OPTIONS MENU =
========================================
E) Edit Individual Profile Sections
G) Global P12 Configuration
I) Global Cluster Token Identifier
T) Global Cluster Token Coin Id
R) Auto Restart Configuration
L) Set Log Level
P) Passphrase Encryption
M) Main Menu
Q) Quit
KEY PRESS an option
nodeadmin@Constellation-Node:~$
Decrypt via the Configurator
Initial Steps
We first start by starting up the configurator and following the same steps as if we were going to encrypt our passphrase.
Disable Encryption
nodectl will detect that our passphrase is set to encrypted, via the configuration file.
= PASSPHRASE ENCRYPTION =
= DISABLE ENCRYPTION =
========================================
WARNING Disabling encryption is permanent.
Profile specific non-global passphrases will NOT be restored in your Node's configuration file. Each specific p12 configurations will be reset to None
Please reset specific dedicated profile passphrases via the configurator to resume nodectl's ability to automate processes that require the p12 keystore elements to function.
Alternatively, you can resume using --pass <passphrase> at the command prompt.
You will be redirected automatically to reset your global p12 passphrase.
We can confirm by entering y+Enter.
Permanent
This will not be reversible. The keys associated with the current encrypted passphrase will be destroyed permanently.
However, you can encrypt again at any time by going through the process to create brand new encryption keys.
Automated Decryption
nodectl will begin the process of removing decryption.
First it will warn it is permanent.
The decryption process will start.
Configuration changes applied ................. successfully
Removing encryption elements .................. completed
Resetting [global] configuration...............
Existing global p12 details identified ........ success
Establish plain text passphrase
nodectl will now automatically direct you to the GLOBAL PROFILE P12 ENTRY section of the configurator. This is important because nodectl removed the hash associated with your passphrase; as well as, the appropriate keys that would decrypt the passphrase for us. We do not allow nodectl to decrypt the passphrase for us for extra security.
This is the Debian Operating system username used to administer your Node. It was created during Node installation. Avoid the 'root', 'admin', or 'ubuntu' user.
You should be able to verify default values between the brackets [] and then hit the Enter key to accept these values. They should not have changed, so you should be able to use the default for all 3 questions.
Confirm or Change p12 details
Default Values
Your default values may be different from the example output below
Enter in p12 file path [/home/nodeadmin/tessellation/]:
Enter in your p12 file name: [nodeadmin.p12]:
Confirm Values
We can press the Enter key to accept and confirm our p12 values.
= CONFIRM VALUES =
========================================
If you reached this confirmation unexpectedly ,from the input [above] you may have hit <enter> along with your option; therefore, choosing the default. You can choose n here and reenter the correct value.
nodeadmin: nodeadmin
key location: /home/nodeadmin/tessellation/
key name: nodeadmin.p12
Please confirm values are as requested: [y]: y
Hide Passphrase?
nodectl will ask you if you want to "hide" your passphrase, if you choose y here your configuration will not contain a passphrase and you will be required to enter every time it is needed.
Encryption's purpose
Removing the passphrase creates extra work for the Node Operator when encryption may be a better solution.
We will press Enter to accept the default n.
Add Plain Text Passprhase
Enter your current p12 passphrase
Enter in p12 passphrase:
Confirm the passphrase
Configuration will be applied
Global p12 entries ............................ complete
Configuration changes applied ................. successfully
Individual Profile Passphrase Updates
In the event you had non-global p12 details entered for your profiles. The configurator will take you to each profile and request you update the p12 details for each profile, as was completed in the above global update section.
If you already had these profiles set to global ( only using the global p12 for all profiles ), you will not be redirected and returned to the main menu.
Conclusion
Your Node is now updated with an encrypted or decrypted passphrase. From the main menu, you can choose q to return to your Node's command line interface.