Secure Transmission of Certificates

With newer security issues coming up every single day, organizations understand the importance of products having robust security mechanism. UIM 20.3.3 has further enhanced its security by enabling the seamless transfer of the certificates
from a hub to a robot
over a secure channel. Now, you no longer need to manually drag-and-drop the certificates from a hub to a robot when using the secure bus. The complete process is automatically done without any manual intervention, which ensures that the communication is secure and the data is not tampered with.
Review the Secure Hub and Robot article that contains the complete flow of securing the environment. Secure transmission of certificates is one of the steps involved in the overall process.
The following illustration outlines the certificate transfer process:
The following topics provide the detailed information:
2
At a high level, you create a whitelist file that contains the target robots pointing to a specific hub. You then configure the hub.cfg file. Based on the whitelist file and hub configuration, certificates are transferred to the target robots over a secure channel. The hub reads the whitelist file after every 1 minute.
Considerations
Review the following considerations:
  • Tunnels must be configured in your environment.
  • The latest version of the distsrv or ADE probe (available with UIM 20.3.3) must be deployed.
  • This functionality is applicable for the robot and hub packages that are released with UIM 20.3.3.
  • If a specific robot is not online, the certificate transfer does not happen on that robot.
  • The certificate transfer does not work in the case of passive robots.
  • Tunnel server acts as a certificate authority (CA).
  • You can create a whitelist file manually or can use a callback.
Create the Whitelist Configuration File
Create the whitelist configuration file, robots_certs_details.cfg, in the ..\Nimsoft\hub\changes location. In this file, you add the list of robots to which you want to transfer the certificates. The robots must point to the hub from where you want to transfer the certificates. The corresponding hub reads this file to determine the robots where it will transfer the certificates. You must add this file to all the required hubs. The hub reads the file after every 1 minute.
You can also use a callback to create the whitelist file. The callback creates the file, adds the robot information to it, and places it in the "changes" folder. The callback performs these tasks automatically. However, you can add only one robot entry at a time if you are using the callback. For more information, see Use a Callback to Create Whitelist File.
Follow these steps:
  1. Navigate to the ..\Nimsoft\hub\ location. This is the hub from where you want to transfer the certificates to the target robots that are pointing to it.
  2. Create a new folder named "changes" under the ..\Nimsoft\hub\ folder.
  3. Navigate to the "changes" folder.
  4. Create the robots_certs_details.cfg file with the following information under the "changes" folder:
    <certs> <robotname> name=robot_name_ABC commonName=10.xx.xxx.xx expiry_in_days=6 location=<keep_blank> deployed=no </robotname> </certs>
    Add the information for all the target robots.
  5. Review the parameters:
    • name: Specifies the name of the robot where you want to transfer the certificates. This robot points to the same hub.
    • commonName: Specifies the IP of the target robot.
    • expiry_in_days: Specifies the certificate expiry. If you leave it blank, the default expiry (one year) is considered.
    • location: Specifies the location where the generated certificate file (<robot_name>.pem) is stored. At this stage, this parameter is empty because the certificate transfer process has not started yet.
    • deployed: Specifies the status of the certificate deployment on the target robot. The default value is
      no
      , which implies that the deployment has not been done. Once the certificate is deployed successfully, the value is automatically changed to
      yes
      .
  6. Save the changes.
You have successfully created the whitelist file. Follow the same process to create the files for other hubs.
Use a Callback to Create the Whitelist File
If you do not want to manually create the whitelist file, you can use a callback to create it. However, you can add only one robot at a time using the callback.
Follow these steps:
  1. Open the probe utility (pu) for the hub (tunnel client or tunnel server). Ensure that the robots to which you want to transfer the certificates are pointing to this hub.
  2. Select the secure_transmission_add_robot_to_certs_whitelist callback from the drop-down list.
  3. Enter the following information:
    1. robotName: Specify the name of the target robot to which you want to transfer the certificate. This robot must point to the hub where you are running this callback.
    2. commonName: Specify the IP address of the target robot.
    3. expiry_in_days: Specify the number of days after which you want the certificate to expire. If you do not provide any value, the default expiry (1 year) is used.
  4. Run the command request.
The whitelist file robots_certs_details.cfg is created in the ..\Nimsoft\hub\changes folder. The following snippet shows an example of the generated file:
<certs> <robotname> name=robotname_ANC commonName=10.xx.xxx.xx expiry_in_days=10 location= deployed=no </robotname> </certs>
You have successfully created the whitelist file. Follow the same process to create the whitelist files for the other hubs. Note that the deployed value is still no because the transfer has not been completed. Similarly, note that the location field is blank because the certificate has not been transferred yet.
Configure the hub.cfg file
After you create the whitelist file, you configure the hub.cfg file to enable the secure transmission of the certificates. You must perform this configuration for all the hubs in the domain that you want to use for transferring the certificates. Only after this configuration is done, the process to securely transfer the certificates starts.
Follow these steps:
  1. Navigate to the ..\Nimsoft\hub\hub.cfg file.
  2. Open the file and add the following parameters:
    • enable_secure_cert_transmission: Specifies whether you want to enable the process of transferring the certificates from a hub to its robot over a secure channel. To do so, add the value as
      yes
      .
    • get_all_robots_certs: Specifies whether you want to transfer the certificates to all the robots that are pointing to the hub or only to those that are already listed in the whitelist file. The default value is
      no
      , which implies that the whitelist file is used for identifying the target robots. If you change the value to
      yes
      , then the certificate is transferred to all the robots pointing to that hub, overriding the whitelist file.
  3. Save your changes.
You have successfully configured the hub.cfg file.
After the hub.cfg file is configured, the transfer process starts and performs the following tasks:
  • The following files are added to the ..\Nimsoft\hub\robots_certs folder on the hub:
    • <robot_name>.pem
    • robots_certs_details.cfg
      This file is created based on the whitelist file that is placed in the ..\Nimsoft\hub\changes\ folder. After the creation of this file, the whitelist file is removed from the ..\Nimsoft\hub\changes\ folder. Any modifications that are made to the ..\Nimsoft\hub\changes\robots_certs_details.cfg file are appended to the already created ..\Nimsoft\hub\robots_certs\robots_certs_details.cfg file.
    • robots_certs_details.cfx
  • The following parameters are added/updated in the ..\Nimsoft\hub\robots_certs\robots_certs_details.cfg file:
    • password: Specifies a randomly generated and encrypted password.
    • location: Specifies the location where the generated certificate file (<robot_name>.pem) is stored. For example,
      location = robots_certs/<robot_name>.pem
      .
    • deployed: Updates the value to yes.
  • The certificates are transferred to the listed robots. The certificates .pem file is copied to the target ..\Nimsoft\robot\certs folder:
    • <robot_name>.pem
  • The robot.cfg file is updated with the location of the certificates:
    • proxy_private_key=robot/certs/<robot_name>.pem
    • proxy_ca_location= robot/certs/<robot_name>.pem
    • proxy_cert=robot/certs/<robot_name>.pem
    • proxy_private_key_password=/123456ZO7/0134QVSRf4
  • The hub.cfg file adds a parameter robot_certs_issuing_hub. This parameter shows the hub that is issuing the certificates to the target robots. For example,
    robot_certs_issuing_hub=/<domain_name>/<hub_name>/<robot_name>
Verify the Secure Transmission of Certificates
When the hub.cfg file is configured appropriately, it starts the transfer process and places the certificates in the required locations. You can verify whether the transfer happened successfully.
Follow these steps:
  1. Open the ..\Nimsoft\hub\robots_certs_details.cfg file.
  2. Locate the value of the
    deployed
    parameter.
    • If the value is
      yes
      , it means that the certificates have been successfully transferred to the target robots.
    • If the value is
      no
      , it means that the certificates have not been deployed successfully.
You have successfully verified the status.
Retrieve Information from Whitelist File
You can retrieve the information from the whitelist file. For example, you can get all the robots that are part of the whitelist file.
Follow these steps:
  1. Open the probe utility (pu) for the hub (tunnel client or tunnel server).
  2. Select the secure_transmission_get_robot_certs_whitelist callback from the drop-down list.
  3. Run the command.
    If you want to get the information for a specific robot, you can enter the robot name in the field.
    All the information that is included in the whitelist file is retrieved.
  4. Review the information.
Use the uimapi APIs
You can also use the latest uimapi package that is released with UIM 20.3.3 to perform these tasks:
  • Retrieve robot certificate information from the whitelist file.
  • Add robot certificate information to the whitelist file.
Retrieve Robot Certificate Information from the Whitelist File
You can use this procedure to get the robot certificate information from the whitelist file of a specific hub.
Follow these steps:
  1. Access the uimapi.
  2. Expand the hubs section.
  3. Locate and expand the following endpoint:
    GET /hubs/{domain}/{hub}/{robot}/robotcertswhitelist
  4. Enter the following information:
    1. domain: Specifies the domain name.
    2. hub: Specifies the hub that is related to the whitelist file.
    3. robot: Specifies the name of the hub robot.
    4. (Optional) robotname: Specifies the name of the specific robot for which you want to get the certificate information from the whitelist file.
  5. Execute the API.
    The response is generated and includes the information about the robot certificates.
Add Robot Certificate Information to the Whitelist File
You can use this procedure to add the robot certificate information to the whitelist file of a specific hub.
Follow these steps:
  1. Access the uimapi.
  2. Expand the hubs section.
  3. Locate and expand the following endpoint:
    POST /hubs/{domain}/{hub}/{robot}/robotcertswhitelist
  4. Enter the following information:
    1. domain: Specifies the domain name.
    2. hub: Specifies the hub that is related to the whitelist file.
    3. robot: Specifies the name of the hub robot.
    4. robotCert: Specifies the payload that contains the robotname, commonName, and expiry of certificate in days.
      <RobotCert> <commonName>10.xx.xxx.xxx</commonName> <expiry_in_days>3</expiry_in_days> <robotName>ANC</robotName> </RobotCert>
  5. Execute the API.
    The response is generated and the robot certificate is added to the whitelist file. All the other remaining steps in the process are followed in the same way.