Configuring TLS Between eMake and Agents

You can set up authentication and encryption based on Transport Layer Security (TLS) for communication between eMake and agents on Linux platforms. Authentication is bidirectional and mandatory if configured by either side—in other words, both eMake and the agent must provide credentials to the other party in the connection. If either party fails to provide credentials, if the credentials are invalid, or if the credentials are not acceptable for any reason, the connection between eMake and the agent is ended.

Both the eMake and the agent’s side of the connection configures the following attributes:

  • A certificate that identifies the principal—eMake or agent

  • A private key for the principal

  • A certificate authority chain that is used to verify the peer’s certificate

  • The list of common names and organizational units permitted to connect to the principal

The principal’s certificate and private key are from a single combined user-supplied PEM file; the certificate authority chain is taken from a single CA bundle file in PEM format. You provide the list of accepted common names (CNs) and organizational units (OUs) via a command-line argument.

Configuring eMake for TLS

Following are the eMake command line options for enabling TLS. If you use TLS for eMake, you must configure all agent machines as well. For details about configuring agent machines, see Configuring Agents for TLS.

Command-Line Option Description

--emake-ssl-cacert=< path_to_PEM_file >

Path to the certificate authority bundle file. For example, --emake-ssl-cacert=cacert.pem. This file contains root and intermediate certificates that are needed to complete the end-entity certificate chain. This file must be in PEM format.

--emake-ssl-keystore=< path_to_PEM_file >

Path to the combined certificate and keystore file used to identify eMake to agents. For example, --emake-ssl-keystore=client-combined.pem. This file must be in PEM format.

-emake-ssl-allow=< acl >

List of common names or organizational units (or both) that eMake will accept in agent certificates and thus permitted to connect to the agents, where <acl> is a comma-separated list of elements of the forms cn=common_name and ou=organizational_unit. For example, to indicate that the common names eric and cindy are permitted, specify cn=eric,cn=cindy. To indicate that the common name eric and organizational unit accelerator are permitted, specify cn=eric,ou=accelerator.

Configuring Agents for TLS

Following are the settings that specify the TLS command-line arguments to runagent. If you use TLS for agents, you must configure eMake as well. For details about configuring eMake, see Configuring eMake for TLS.

On each agent machine, add the following settings to both lines that start with $AGENT $RUNAGENT in the /etc/init.d/ecagent file. You can add these options in any order, but both lines must use the identical set of options.

Option Description

-emakesecurity ssl

(Required) Indicates that the agents on this machine will use SSL.

-sslcacert < path_to_PEM_file >

Path to your certificate authority bundle file. This file contains root and intermediate certificates that are needed to complete the end-entity certificate chain. This file must be in PEM format.

-sslkeystore < path_to_PEM_file >

Path to your agent-side combined certificate and keystore file to be used to identify eMake to agents. This file must be in PEM format.

-sslallow < acl >

List of common names or organizational units (or both) that eMake will accept in agent certificates and thus permitted to connect to the agents, where <acl> is a comma-separated list of elements of the forms cn=common_name and ou=organizational_unit. For example, to indicate that the common names eric and cindy are permitted, specify cn=eric,cn=cindy. To indicate that the common name eric and organizational unit accelerator are permitted, specify cn=eric,ou=accelerator.

ecconfig does not provide functionality to configure these options.

The following excerpt from an /etc/init.d/ecagent file provides examples (shown in bold ) of how to add these options:

#!/bin/sh
#
# ecagent
#
# Copyright (c) 2002-2019 Electric Cloud, Inc.
# All rights reserved
#
# chkconfig: 3 77 20
# description: Electric Cloud Agent

…

    i=0
    while [ $i -lt $AGENT_NUMBER ] ; do
        if [ -n "$SHARED_AGENT_NUMBER" ] && [ $i -ge $SHARED_AGENT_NUMBER ] ; then
            $AGENT $RUNAGENT -daemon yes -cm $CMHOST:$CMPORT -efsid $i -numagents $AGENT_NUMBER -secureconsole $SECURE_CONSOLE -diskcacheportfile $DISKCACHE_PORTFILE -tempdir "$TEMPDIR" -local 1 -emakesecurity "$EMAKESECURITY" -trace "$TRACE" -emakesecurity ssl -sslcacert cacert.pem -sslkeystore server-combined.pem -sslallow cn=eric,ou=accelerator
        else
            $AGENT $RUNAGENT -daemon yes -cm $CMHOST:$CMPORT -efsid $i -numagents $AGENT_NUMBER -secureconsole $SECURE_CONSOLE -diskcacheportfile $DISKCACHE_PORTFILE -tempdir "$TEMPDIR" -local "$LOCALAGENT" -emakesecurity "$EMAKESECURITY" -trace "$TRACE" -emakesecurity ssl -sslcacert cacert.pem -sslkeystore server-combined.pem -sslallow cn=eric,ou=accelerator

…