Skip to main content

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

optiondescription
-eDirectly enter into the edit section of the configurator.
-cbconfirm backup, you will not need to verify the location of the backup file before continuing
-dExecute the configurator in detailed mode which will offer more details on all commands and questions that may need to answered.
-aExecute 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.

nodeadmin@Constellation-Node:~$ sudo nodectl configure
[sudo] password for nodeadmin:

alternatively, add the options.

nodeadmin@Constellation-Node:~$ sudo nodectl configure -e -cb -d
[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
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.

Do you want to enable encryption? [y]: y

Validate your current passphrase

nodectl will request the p12 you want to encrypt and validate that passphrase before allowing you to encrypt.

------------ * GLOBAL P12 * ------------

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

seed phrase [deriving] ........................ complete

Remove and destroy the seed phrase because it is a one-time use element of the encryption process.

seed phrase [redacting] ........................ complete

Remove all elements that helped to prepare the encryption hash

seed phrase [forgetting] ........................ complete

Encryption is complete

seed phrase [finished] ........................ complete

Update the configuration

Building encryption elements [global] ......... completed
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
Configuration manipulation quit by Operator
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.

  1. Start Configurator
  2. Advanced Mode
  3. Main Menu
  4. Backup

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.

Do you want to remove encryption? [n]: y

Automated Decryption

nodectl will begin the process of removing decryption.

First it will warn it is permanent.

This is permanent...

The decryption process will start.

Removing encryption elements .................. running
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.

----- * GLOBAL PROFILE P12 ENTRY * -----

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 the admin username for this Node [nodeadmin]:
This is the location on your Debian Operating system where the p12 private key file is located.

Enter in p12 file path [/home/nodeadmin/tessellation/]:
This is the name of your p12 private key file. It should have a '.p12' extension.

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.

Would you like to hide the global passphrase [n]:

Add Plain Text Passprhase

Enter your current p12 passphrase

Enter in a passphrase. The passphrase [also called 'keyphrase' or simply 'password'] will not be seen as it is entered. This configurator does NOT create new p12 private key files. The Node Operator should enter in their EXISTING p12 passphrase. This configurator also does NOT change or alter the p12 file in ANY way. A p12 file should have been created during the original installation of nodectl on this Node. If the Node Operator wants to modify the p12 passphrase, the 'sudo nodectl passwd12' command can be used. To remove the passphrase from the configuration, enter in "None" as the passphrase, and confirm with "None". MAKE SURE TO SAVE YOUR PASSPHRASE IN A SAFE LOCATION! Losing your passphrase is not recoverable!

Enter in p12 passphrase:

Confirm the passphrase

Confirm this passphrase:

Configuration will be applied

Confirm this passphrase:
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.