TLS with server-side, CA-signed certificates - Securing a Windows Application Server

Important

In this topic, a server refers to an RSCD Agent and a client refers to an Application Server that is attempting to establish contact with the RSCD Agent. Generally, in TrueSight Server Automation documentation a client refers to a host running the TrueSight Server Automation Console or Network Shell.

Securing the communication from a Windows Application Server to an RSCD Agent with the server-side, CA-signed certificates involves the following steps:

  1. Configure the Application Server for the CA bundle, which contains root and intermediate CA certificates
  2. Generate a CA-signed for the RSCD Agent
  3. Provision the agent with the CA-signed certificate and enable certificate verification

To stop using the server-side certificate verification for an RSCD Agent, see Discontinue the use of CA-signed, server certificates.

Step 1: Configure an Application Server for CA bundle

An Application Server uses the configured CA bundle to verify the RSCD Agent's server certificate.

  1. Configure the RSCD CA bundle (rscd.cabundle.pem) on the Application Server by using the following sample commands. This CA bundle is the collection of different CA bundles, located in the <installDirectory>\NSH\br\deployments directory.

    • To create a new RSCD CA bundle and add the CA bundle (for example, ca1.pem) that you received from your CA, run the following command:

      type ca1.pem > rscd.cabundle.pem

    • To add new CA bundle (for example, ca2.pem) that you received from your CA to an existing RSCD CA bundle, run the following command:

      type ca2.pem >> rscd.cabundle.pem

    • To list all the CA certificates present in the RSCD CA bundle, run the following command:

      openssl crl2pkcs7 -nocrl -certfile rscd.cabundle.pem | openssl pkcs7 -print_certs -noout
  2. If you have multiple Application Servers in your environment, sync the CA bundle across all Application Servers. For more information, see Ensuring all bladelogic.keystore and rscd.cabundle.pem files are consistent.
  3. Restart the Application Servers.

Step 2: Generate a server-side, CA-signed certificate for an RSCD Agent

  1. Generate the private key (certificate.key) and Certificate Signing Request (certificate.csr) for the server certificate by running the following command on a computer where the OpenSSL utility is installed:

    openssl req -new -nodes -newkey rsa:2048 -keyout certificate.key -out certificate.csr -subj '/C=US/ST=TX/L=Houston/O=BMC Software/OU=server/CN=rhelprod.abc.com'

    In the command, replace the subject (-subj) details as per your organization's needs.

  2. Get the CSR signed by the same trusted CA from which you received the CA bundle in step 1 (either a commercial CA or an internally-trusted CA for your organization) and obtain the signed certificate (certificate.crt).

  3.  Generate the certificate.pem file that contains the private key and the signed certificate, and then delete certificate.key and certificate.crt by running the following commands:

    type certificate.key certificate.crt > certificate.pem
    Del "certificate.key" "certificate.crt"

Step 3: Provision an RSCD agent with the server-side, CA-signed certificate and enable a target server for certificate verification

  1. Copy the certificate.pem file that you generated in Step 2 to a temporary location on the target server.
  2. Navigate to the /etc/rsc directory (UNIX target server) or %WINDIR%\rsc directory, where %WINDIR% is typically C:\Windows (Windows target server), and do the following:
    1. (Applicable if you want to verify the older RSCD log files on the target server) If secure logging is configured for the RSCD agent, certificate.pem file is used for securing the log files. Back up the existing certificate.pem, RSCD log files, and the corresponding signature files.
    2. Replace the existing certificate.pem file with the certificate.pem file that you copied in Step 1. 
  3. To enable the target server for the RSCD server certificate verification, set the TLS_VERIFY_AGENT_CERTIFICATE server property for the target server to True. The default value of this property is False. For instructions, see Changing property values for one or more system objects.
  4. Perform operations such as running a Update Server Properties Job and running the agentinfo command against the agent to verify that agent communication is working correctly with the certificate verification.
  1. (Optional) Remove certificate.pem from all other intermediate locations, such as temporary location on the target server or the computer where this file as generated.

If you want to provision multiple agents simultaneously, see Provisioning multiple agents with server-side, CA-signed certificates.

Provisioning multiple agents with server-side, CA-signed certificates

You can provision multiple agents with different CA-signed certificates simultaneously using an NSH Script Job.

Before you begin

Before you start provisioning agents with CA-signed certificates, ensure that the following prerequisites are met:

  1. Ensure that all CA-signed certificates (created in Step 2) are in PEM format and have the following details in the specified order, as shown in the sample file:

    1. Private key
    2. Certificate
    Sample certificate file
    -----BEGIN PRIVATE KEY-----
    89tvCuKOcL0L5WR0OKA+Oj9F2sv3mHQuH8SgSff07AnDehntK2W6L1Vu7xGtWR
    cErKyCFXtmibR18Da99AoGBAI1EJXQ1htzzjzmin+Jc/X83o82tgcbdPA6hGWs4F
    4BA7xGgxRF7NAI1csNT8Z9ahMzCX83o82tgcbdPA6hGWs4FP9thzZa8zw/GBALDL
    O0csWQZ4F1x5ky3SNGIg6sgcAw0n0Vu9KjS7MnFLghdqZ4jSCBZXiAXlAvOdUblzyq
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    ywK4o5wDCCAiigAwIBAgIBADANBgkqhkiG9w0BAQsFADAPMQ0wCwYDVQQDDARyc2
    MB4789IxMDcxNDA4MzQzMloXDTMxMDUyMzA4MzQzMlowDzENMAsGA1UEAwwEcnNj
    cQvpYv879jDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKMK7OY+WVRkO5NhFF
    kO5NhFFF7nv57fFbY59P1+SC6WSLe+Czc/r7/7aLdNGGkW4dGjQQ5/h+cQvpYvz+
    -----END CERTIFICATE-----
  2. Ensure that the certificates are stored in a single NSH location that is accessible by the Application Server. The certificates should have the following naming convention: <enrolledServerName>.pem.

  3. Copy the following script to your Application Server and save it as a .nsh file, for example, provisionRSCDCertificates.nsh.

    provisionRSCDCertificates.nsh
    #!/bin/nsh
    #set -x
    #<name> provisionRSCDCertificate
    #<desc> Script for provisioning certificate.pem on RSCD
    #<owner> Copyright (C) 2021 BMC Software, Inc.
    #######################################################################

    #######################################################################
    #<doc> NAME
    #<doc>        provisionRSCDCertificate
    #<doc>
    #<doc> SYNTAX
    #<doc>        provisionRSCDCertificate -d //host/absolute/path/to/certs/dir [-v 0|1]
    #<doc>        Ex. provisionRSCDCertificate -d //localhost/root/rscd_certs
    #<doc>
    #<doc> DESCRIPTION
    #<doc>        -d: NSH path to a directory containing rscd server certificates for different servers.
    #<doc>            Directory should contain certificate files with name as "SERVER_NAME.pem", where
    #<doc>            SERVER_NAME is the name with which server is enrolled in Application Server.
    #<doc>
    #<doc>        -v: Specify whether Agent Certificate verificataion should be enabled(1) or disabled(0) after provisioning
    #<doc>            the RSCD certificate on Target Server. Possible values: 0 or 1
    #<doc>            If enabled, script will set server property TLS_VERIFY_AGENT_CERTIFICATE to value "True"
    #<doc>            If disabled, script will set server property TLS_VERIFY_AGENT_CERTIFICATE to value "False"
    #<doc>            Note: If you want to enable/disable RSCD server certificate at some later point, you can do that as well.
    #<doc>
    #<doc> NOTE:
    #<doc>     1. Each certificate file consists of PRIVATE_KAY and CERTIFICATE entries in PEM format.
    #<doc>        Refer existing certificate.pem file for the format.
    #<doc>     2. As this script will be replacing the existing certificate.pem file on Target servers, make sure the NSH script
    #<doc>        job is executed with a Role:User which is mapped to administrative user on those Target servers.
    #<doc>     3. The previously cached TLS sessions on Target server are also purged, so that new TLS connections
    #<doc>        uses the newly deployed certificates.
    #<doc>     4. (Applicable if you want to verify the older RSCD log files on the target server) If secure logging is configured
    #<doc>        for the RSCD agent, certificate.pem file is used for securing the log files. Back up the existing certificate.pem,
    #<doc>        RSCD log files, and the corresponding signature files.
    #<doc>        This script will overwrite the existing certificate.pem file
    #######################################################################

    usage()
    {
        echo "Script for provisioning RSCD certificate (certificate.pem) on hosts" >&2
        echo "Usage: provisionRSCDCertificate.nsh -d <NSH_PATH_TO_CERTS_DIR> [-v 0|1]" >&2
    }

    argc=$#
    ret=0
    if [ $argc -eq 0 ]; then
        usage
        exit 1
    fi

    cnt=1
    TLS_VERIFY_AGENT_CERTIFICATE=
    while [ $cnt -lt $argc ]
    do
        if [ "$1" = "-d" ]; then
            shift
            CERTS_DIR="$1"
            shift
            cnt=`expr $cnt + 2`
            continue
        elif [ "$1" = "-v" ]; then
            shift
            case "$1" in
              0)
                TLS_VERIFY_AGENT_CERTIFICATE="False"
                ;;
              1)
                TLS_VERIFY_AGENT_CERTIFICATE="True"
                ;;
              *)
                echo "ERROR: Invalid Input provided for -v option" >&2
                usage
                exit 1;
            esac       
            shift
            cnt=`expr $cnt + 2`
        else
            echo "ERROR: Invalid Input !!!" >&2
            usage
            exit 1
        fi
    done

    if [ -z "$CERTS_DIR" ]; then
        echo "ERROR: Invalid Input. Required argument -d is not provided" >&2
        usage
        exit 1;
    fi
    if [ ! -d "$CERTS_DIR" ]; then
        echo "ERROR: Invalid Input. Error accessing certificate directory: $CERTS_DIR" >&2
        usage
        exit 1;
    fi

    echo "Certificates Location: $CERTS_DIR"

    if [ -z "$TLS_VERIFY_AGENT_CERTIFICATE" ]; then
        echo "-v parameter is not provided. Server's TLS_VERIFY_AGENT_CERTIFICATE property will not be updated"
    fi

    blcli_connect

    # Extract target server names from certificate file names
    servers=`find $CERTS_DIR -maxdepth 1 -type f -iname "*.pem" | sed "s/.*\///; s/\.pem//"`

    for SERVER_NAME in $servers
    do
        UPDATE_PERMISSION=false
        cd //$SERVER_NAME
        if [ $? -ne 0 ]; then
            echo "ERROR: cd //$SERVER_NAME failed, provisioning certificate file to server $SERVER_NAME will be skipped." >&2
            ret=1
            continue
        fi
        OS=`uname -s`
        cd -

        if [ -z "$OS" ]; then
            echo "ERROR: Unable to determine OS for server $SERVER_NAME, provisioning certificate file to server $SERVER_NAME will be skipped." >&2
            ret=1
            continue
        fi

        RSC_DIR=
        if [ "$OS" = "WindowsNT" ]; then
            blcli_execute Server getFullyResolvedPropertyValue $SERVER_NAME "WINDIR" > /dev/null
            blcli_storeenv WIN_DIR
            if [ -z "$WIN_DIR" ]; then
                echo "ERROR: Unable to determine 'WINDIR' value for server $SERVER_NAME, provisioning certificate file to server $SERVER_NAME will be skipped." >&2
                ret=1
                continue
            fi
            RSC_DIR=${WIN_DIR}"/rsc"
        else
            RSC_DIR="/etc/rsc"
            UPDATE_PERMISSION=true
        fi

        if [ -z "$RSC_DIR" ]; then
            echo "ERROR: Unable to determine Agent configuration directory for server $SERVER_NAME, provisioning certificate file to server $SERVER_NAME will be skipped." >&2
            ret=1
            continue
        fi

        SRC="$CERTS_DIR/$SERVER_NAME.pem"
        DEST="//${SERVER_NAME}${RSC_DIR}/certificate.pem"

        cp $SRC $DEST
        if [ $? -ne 0 ]; then
            echo "ERROR: Failed to copy certificate file to server $SERVER_NAME" >&2
            ret=1
            continue
        fi
        echo "Successfully copied certificate file to server $SERVER_NAME"

        if [ ! -z "$TLS_VERIFY_AGENT_CERTIFICATE" ]; then
            blcli_execute Server setPropertyValueByName $SERVER_NAME TLS_VERIFY_AGENT_CERTIFICATE "$TLS_VERIFY_AGENT_CERTIFICATE" >/dev/null
        fi

        # Set permission for Unix targets
        if [ "$UPDATE_PERMISSION" = true ]; then
            chmod 600 "$DEST"
            chown root:root "$DEST"
        fi

        blcli_execute Server getFullyResolvedPropertyValue $SERVER_NAME "RSCD_DIR" >/dev/null
        blcli_storeenv RSCD_INSTALL_DIR

        # Purge previous cached TLS sessions from RSCD
        if [ ! -z "$RSCD_INSTALL_DIR" ]; then
            RSCD_SESSIONS_DIR="//${SERVER_NAME}${RSCD_INSTALL_DIR}/sessions/"
            rm -f "${RSCD_SESSIONS_DIR}/*"
            echo "Purged previous cached TLS sessions from ${RSCD_SESSIONS_DIR}"
        else
            echo "ERROR: Unable to fetch RSCD_DIR server property value for server '$SERVER_NAME'. You can try removing all the files from <Agent installation dir>/sessions/ or can restart the RSCD Agent" >&2
            ret=1
        fi
    done

    exit $ret

To provision agents using the NSH Script Job

  1. Add the NSH Script to the Depot:
    1. On the Console, right-click a depot folder and select New > NSH Script from the pop-up menu.
      The Add NSH Script to Depot wizard opens.

    2. On the Script Options panel, enter the following information and click Next.

      Field

      Description

      Name

      Enter a name for the script, for example, provisionRSCDCertificates.

      Save in

      Browse to the folder where you want to store this job, for example, nshScripts.

      File location

      Enter full path to the script (including host name for remote locations).

      Script Type

      Select the Execute script once passing the host list as a parameter to the script option.

      Allow run with no targets

      Select this option.

    3. On the Parameters panel, add the following script parameters, and click Next.

      Field

      Value

      Certs_Directory

      Enter the NSH path to the directory where server certificates are stored. For example, //foo.certqa01/c/rscd_ca_cert.

      Enable_Verification

      Enter 1 to indicate that server-side validation is enabled.

      Hosts

      Enter %h (Required for type 2 NSH script) for this dummy parameter.

      nsh_script_parameters.PNG

    4. Accept default values in the Properties and Permissions panel and click Finish to exit the wizard.

      The NSH script appears in the Depot folder.

  2. Create the NSH Script Job that uses the NSH Script added in step 1:
    1. In the Depot folder, navigate to the nshScripts folder where you added the NSH script.
    2. Right-click the provisionRSCDCertificates script and select NSH Script Job.

    3. In the General panel, enter the following information, click Next.

      Field

      Description

      Name

      Enter a name for the job, for example, Identifying name.

      Save in

      Browse to the folder in which to store the job.

      NSH Script

      Click Browse and navigate to the script (nshScripts/provisionRSCDCertificates) that is the basis of this NSH Job.
      If you selected a script to begin this procedure, this field is already complete. An information line beneath the NSH Script text box identifies the type of script you have selected.

    4. On the Targets panel, don't select any target server. The targets will be selected based on the files present in the directory that is defined as the value of the Certs Directory parameter.
    5. Accept default values in all other panels and click Finish to exit the wizard.
  3. Right-click the job and select Execute to run the job.
  4. Check the job run log for results.
  5. (Optional) If job runs are successful, delete certificates from Certs_Directory.

Discontinue the use of server-side, CA-signed certificates

If you do not want to use the server-side certificate verification for an RSCD Agent, set the TLS_VERIFY_AGENT_CERTIFICATE server property to False for a target server. For instructions, see Changing property values for one or more system objects.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*