TLS with client-side certs - Securing a Network Shell client

Use this procedure to generate a self-signed, client-side certificate for a Windows Network Shell client, provision all targeted agents with an SHA1 fingerprint of the self-signed certificate, and configure those agents to authenticate incoming requests using client-side certificates.

This procedure creates a file on the client called id.pem. That file contains the client's digital certificate and the corresponding private key, which is encrypted using a password supplied when the self-signed certificate is created. Then this procedure calculates the SHA1 fingerprint of the client certificate and pushes it to targeted agents using the putcert utility. The SHA1 fingerprint is written into fingerprint files on the agents. During the TLS handshake, the client uses the contents of the id.pem file (certificate and corresponding private key) and the agents uses the SHA1 fingerprint.

On UNIX machines running Network Shell clients, BMC Server Automation does not load the certificate if group or world permissions are set for the id.pem file or the .bladelogic directory, where the id.pem file is generated.

If you want to stop using self-signed, client-side certificates, see Discontinuing use of client-side certificates.

To secure a Network Shell client

1. Ensure that the secure file is configured correctly on all agents where you want to set up secure access. Ensure the rscd entry in the secure file is set to tls_mode=encryption_only. If necessary, generate this setting by running the following secadmin command on each agent:
   secadmin -m rscd -p 5 -T encryption_only -e tls
   This is the default setting after a fresh installation of an agent, so in many situations there is no need to perform this step. Later in this procedure, you will change the tls_mode setting.
2. Set up root or Administrator privileges on each managed server hosting an agent.
   To provision an agent with the SHA1 fingerprint of a client's certificate, you must have root or Administrator privileges on the server hosting the agent. To grant this privilege, update the exports file on the server by creating the following entry:
   (Windows):
   <host> rw,user=Administrator
   (UNIX):
   <host> rw,user=root
   where <host> is the IP address or host name of the Network Shell client.
3. Using a command line on the Network Shell client, generate a self-signed certificate by entering the following:
   bl_gen_ssl
4. Enter a passphrase. Then confirm the passphrase by entering it again.
   BMC Server Automation generates a self-signed certificate in a file named id.pem. The passphrase is used to encrypt the private key in the id.pem file.
   • (Windows) The id.pem file is stored in /<userProfileDirectory>/Application Data /BladeLogic, where <userProfileDirectory> specifies a path such as /Documents and Settings/<userName>.
   • (UNIX) The id.pem file is stored in /<userHomeDirectory>/.bladelogic, where <userHomeDirectory> is the user's home directory, such as /home/<userName>.
5. Cd to the directory where id.pem is stored.

6. For UNIX machines running Network Shell clients, ensure that access is restricted to the id.pem file and the .bladelogicdirectory by running the following commands:

   chmod 700 /home/<userName>/.bladelogic
   chmod 600 /home/<userName>/.bladelogic/id.pem
   

7. Push the SHA1 fingerprint of the self-signed certificate to managed servers by entering the following command:
   putcert <userName> id.pem <agent1 ... agentN>
   where <userName> is the name of the user who created the certificate and <agent1 ... agentN> is a space-delimited list of the names or IP addresses of the servers to which you want to push the certificate.
   This command creates or updates a fingerprint file on each targeted agent.
   • On a Windows agent, C:\Program Files\BMC Software\BladeLogic\RSCD\certs\<userName> is the fingerprint file.
   • On a UNIX agent, /opt/bmc/bladelogic/NSH/certs/<userName> is the fingerprint file.

8. Modify the rscd entry in the secure file on each targeted agent by entering the following secadmin command:
   secadmin -m rscd -p 5 -T encryption_and_auth -e tls

   Note

   Performing this step could have implications for Application Servers or Network Shell proxy servers when they communicate with the same targeted agents. This step sets tls_mode=encryption_and_auth on the targeted agents, which means these agents require Application Servers or Network Shell proxy servers to also use client-side certificates. For information about setting up client-side certificates on these entities, see:

   • TLS with client-side certs - Securing a Windows Application Server
   • TLS with client-side certs - Securing a UNIX Application Server.
     You can also use these procedures to set up client-side certificates on Network Shell proxy servers. The procedure is the same as the procedure for Application Servers.
9. Revert the setting in the exports file on managed servers back to a more restrictive user mapping. Otherwise, all users accessing those agents are mapped to root or Administrator.
10. If you plan to use Network Shell to run non-interactive tools such as the BLCLI, you should cache your private key for your client-side certificate. For more information, see Caching private keys.

Caching private keys

A client certificate and its associated private key (that is, the contents of the id.pem file) constitute a user credential that the holder of the credential can use to assume the identity of the user named within the credential. If the private key in the id.pem file is not password-protected, anyone gaining access to the file can assume the identity of the user named in the certificate. To keep private keys safe, BMC Server Automation provides a password mechanism.

When an id.pem file is generated, the private key is encrypted using the password you provide when you run the bl_gen_ssl utility. When you start Network Shell, the system prompts you for your private key password. After you provide the password, Network Shell decrypts and caches your private key, making it available to any command running under the shell.

Because each Network Shell session requires knowledge of the private key password, BMC Server Automation provides a private key cache so users do not have to retype their passwords every time they start a new Network Shell session. The procedure for activating the private key cache varies for Windows and UNIX systems.

Activating the private key cache in Windows

1. From a Windows command line, enter the following command:
   bltray -blkey
   A dialog box prompts for your private key password.
2. Enter the password and click OK.
   The BMC Server Automation icon appears in the system tray on the task bar, indicating the private key password is shared.
3. To stop sharing the password, right-click the BMC Server Automation icon in the system tray and select Exit from the pop-up menu.

Activating the private key cache in UNIX

1. On the Network Shell client, enter the following command:
   bl_ssl_agent --background
   The system prompts for your private key password.

   Note

   This command must be run in the foreground because it prompts for a password. The command spawns a new process that remains in the background to cache the password in a shared memory segment.

2. Enter the password.
   The system generates a message similar to the following:
   set BL_X509_KEY to <xy> to reuse this private key
   where <xy> is the hexadecimal value of the location of the shared memory segment.
   After entering your password, bl_ssl_agent runs in the background with the password cached in a shared memory segment. This shared memory segment is only usable by the person who ran bl_ssl_agent.
3. To reuse this shared memory segment with Network Shell, set the BL_X509_KEY environment variable by entering the following command:
   BL_X509_KEY= <xy>
4. Export the BL_X509_KEY environment variable by issuing the following command:
   export BL_X509_KEY
   The bl_ssl_agent program remains in the background holding the private key password cached in a shared memory segment until you kill it.

Discontinuing use of client-side certificates

Use this procedure to stop using client-side certificates that secure access between Network Shell clients and agents.

1. Set up root or Administrator privileges on each managed server hosting an agent.
   To perform this procedure, you must have root or Administrator privileges on any servers hosting agents where you want to discontinue use of client-side certificates. To grant this privilege, update the exports file on a server by creating the following entry:
   (Windows):
   <host> rw,user=Administrator
   (UNIX):
   <host> rw,user=root
   where <host> is the IP address or host name of the Network Shell client.
2. Remove the SHA1 fingerprint of a client-side, self-signed certificate from managed servers by entering the following command:
   nukecert <userName> <agent1...agentN>
   where <userName> is the name of the user who created the certificate and <agent1...agentN> is a space-delimited list of the names or IP addresses of the servers where you want to stop using certificates.

3. Configure the secure file on all agents where you want to stop using certificates by using Network Shell to run the following secadmin command:
   secadmin -m rscd -p 5 -T encryption_only -e tls
   Running this command generates an rscd entry in the securefile like the following:

   rscd:port=4750:protocol=5:tls_mode=encryption_only:encryption=tls
   

   Note

   Performing this step could have implications for Application Servers or Network Shell proxy servers when they communicate with the same targeted agents. This step sets tls_mode=encryption_only on the targeted agents, which means these agents do not require Application Servers or Network Shell proxy servers to also use client-side certificates.

4. Revert the setting in the exports file on managed servers back to a more restrictive user mapping. Otherwise, all users accessing those agents are mapped to root or Administrator.
5. Remove certificates from clients by deleting the id.pem file.
   • (Windows) The id.pem file is stored in /<userProfileDirectory>/Application Data/BladeLogic, where <userProfileDirectory> specifies a path such as /Documents and Settings/<userName>.
   • (UNIX) The id.pem file is stored in /<userHomeDirectory>/.bladelogic, where <userHomeDirectory> is the user's home directory, such as /home/<userName>.