primary-key

docs/initial_setup_of_velos_system_controllers.rst

@@ -272,6 +272,129 @@ Finally, add the aggregate that you created by name to each of the management in
   config type ethernetCsmacd
   ethernet config aggregate-id mgmt-aggr
 
+-------------
+Primary Key
+-------------
+
+The VELOS system uses a primary key to encrypt highly sensitive passwords/passphrases in the configuration database, such as:
+
+•	Tenant unit keys used for TMOS Secure Vault
+•	The F5OS API Service Gateway TLS key
+•	Stored iHealth credentials
+•	Stored AAA server credentials
+
+The primary key is randomly generated by F5OS during initial installation. You should set the primary key to a known value prior to performing a configuration backup. If you restore a configuration backup on a different VELOS device, e.g. during an RMA replacement, you must first set the primary key passphrase and salt on the destination device to the same value as the source device. If this is not done correctly, the F5OS configuration restoration may appear to succeed but produce failures later when the system attempts to decrypt and use the secured parameters.
+
+You should periodically change the primary key for additional security. If doing so, please note that a configuration backup is tied to the primary key at the time it was generated. If you change the primary key, you cannot restore older configuration backups without first setting the primary key to the previous value, if it is known. More details are provided in the solution article below.
+
+**IMPORTANT: Be sure to make note and save the salt and passphrase in a safe location, as these will be needed to restore the configuration on a replacement system.** 
+
+
+Setting the Primary Key via CLI
+-------------------------------
+
+Below is an example of configuring the passphrase and salt for the primary-key.
+
+.. code-block:: bash
+
+    syscon-1-active(config)# system aaa primary-key set passphrase               
+    Value for 'passphrase' (<string, min: 6 chars, max: 255 chars>): **************
+    Value for 'confirm-passphrase' (<string, min: 6 chars, max: 255 chars>): **************
+    Value for 'salt' (<string, min: 6 chars, max: 255 chars>): **************
+    Value for 'confirm-salt' (<string, min: 6 chars, max: 255 chars>): **************
+    response Info: Key migration is initiated. Use 'show system aaa primary-key state status' to get status
+
+    syscon-1-active(config)#
+
+You can view the status of the primary-key being set with the **show system aaa primary-key state status** CLI command.
+
+.. code-block:: bash
+
+    syscon-1-active# show system aaa primary-key state status
+    system aaa primary-key state status "IN_PROGRESS        Initiated: Tue Apr  9 19:46:14 2024"
+    
+    syscon-1-active# show system aaa primary-key state status
+    system aaa primary-key state status "COMPLETE        Initiated: Tue Apr  9 19:46:14 2024"
+    syscon-1-active# 
+
+Note that the hash key can be used to check and compare the status of the primary-key on both the source and the replacement devices if restoring to a different device. To view the current primary-key hash, issue the following CLI command.
+
+.. code-block:: bash
+
+    syscon-1-active# show system aaa primary-key state
+    system aaa primary-key state hash aNSWX6Xl8+dFx94JMRbySD/d/AJ8RarqJ+fedD#57bDxRF0cTgGFcZvMY415eDeAJjZlXp1qGuKI7CDmxNrnhw==
+    system aaa primary-key state status "COMPLETE        Initiated: Tue Apr  9 19:46:14 2024"
+    syscon-1-active#
+
+
+Setting the Primary Key via API
+-------------------------------
+
+Below is an example of viewing and configuring the passphrase and salt for the primary-key via the API:
+
+
+To view the key use the following API call:
+
+.. code-block:: bash
+
+  GET https://{{velos_chassis1_system_controller_ip}}:8888/restconf/data/openconfig-system:system/aaa/f5-primary-key:primary-key
+
+
+The response will look similar to the output below.
+
+.. code-block:: json
+
+  {
+      "f5-primary-key:primary-key": {
+          "state": {
+              "hash": "sj2GslitH9XYbmW/cpY0TJhMWkU+CpvAU9vqoiL4aZcfE6qnSUDU3PWx+lCZO5KrqVzlWu/3mRugCNniNyQhSA==",
+              "status": "NONE"
+          }
+      }
+  }
+ 
+Below is the API call to set the primary-key:
+
+.. code-block:: bash
+
+  POST https://{{velos_chassis1_system_controller_ip}}:8888/restconf/data/openconfig-system:system/aaa/f5-primary-key:primary-key/f5-primary-key:set
+
+In the body of the API call provide the passphrase and salt. Be sure to save the passphrase and sale in a secure location so that a configuration can be restored if something needs to be replaced. 
+
+.. code-block:: json
+
+  {
+  "f5-primary-key:passphrase": "Pa$$w0rd!",
+  "f5-primary-key:confirm-passphrase": " Pa$$w0rd!",",
+  "f5-primary-key:salt": " Pa$$w0rd!",",
+  "f5-primary-key:confirm-salt": " Pa$$w0rd!","
+  }
+ 
+After setting the passphrase and salt for the primary-key, you'll see a response similar to the one below.
+
+.. code-block:: json
+
+  {
+      "f5-primary-key:output": {
+          "response": "Info: Key migration is initiated. Use 'show system aaa primary-key state status' to get status\n"
+      }
+  }
+ 
+ 
+You can then run the API GET command again to see status:
+
+.. code-block:: json
+
+{
+    "f5-primary-key:primary-key": {
+        "state": {
+            "hash": "sUwBWJYT/VCne4xBVIdSfmjylG7QjMUskI1gtAKIfHifeahm/3/Ywq8zSdV2wn+RsiHdG+3EM/Ilih9GXQoyMA==",
+            "status": "COMPLETE        Initiated: Thu May 30 19:22:13 2024"
+        }
+    }
+}
+
+
 ---------------
 System Settings
 ---------------

docs/velos_api_workflows.rst

@@ -22,6 +22,10 @@ Workflows
 Initial Setup of System Controllers
 -----------------------------------
 
+`Configure Internal Network Ranges via API <https://clouddocs.f5.com/training/community/velos-training/html/initial_setup_of_velos_system_controllers.html#internal-chassis-ip-ranges-via-api>`_
+
+`Configure Primary-Key via API <>`_
+
 `Configure System Settings From the API <https://clouddocs.f5.com/training/community/velos-training/html/initial_setup_of_velos_system_controllers.html#configure-system-settings-from-the-api>`_
 
 `Manual Licensing via API <https://clouddocs.f5.com/training/community/velos-training/html/initial_setup_of_velos_system_controllers.html#manual-licensing-via-api>`_