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.

Note

The machine where you are creating a certificate must have the capability to generate random numbers. The BMC Server Automation installation program for the Application Server tests whether a machine has the capability to generate random numbers. The installation program also allows you to install a daemon or create a random number seed that BMC Server Automation uses for generating random numbers.

 Click here for more information on PRNGD.

BMC Server Automation uses random numbers to encrypt communication securely. On HP-UX, AIX, and Linux 7 systems without a suitable Random Number Generator, the BMC Server Automation Application Server installation program gives you the option to install the BMC Server Automation Pseudo Random Number Generator Daemon (PRNGD). PRNGD is an entropy gathering daemon (EGD) that performs a variety of actions to generate random data in a secure manner. 

If a server includes a hardware device for generating random numbers, it usually resides in /dev/random or /dev/urandom. If that device is not functioning properly or is not FIPS compliant, the installation program advises you to install a patch to correct the problem. BMC recommends this approach for setting up random number support on a server. 

Most computers have a random number generator, so you can choose not to install the PRNGD. However, if you choose not to install, the installation program aborts installation because it found no suitable random number generator and you chose to install a working device of your own. You can restart the installation when that has been done.

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 (IPv4 or IPv6) 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:

  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.

Tip

If you are already running Network Shell and you create a certificate, Network Shell prompts you for a password every time you issue a command during that session. To avoid this, create the certificate, exit Network Shell, and then start Network Shell again. Network Shell only prompts for the password when you start the new session.

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>.
Was this page helpful? Yes No Submitting... Thank you

Comments