Securing External Communication with the RE Certificate

At the center of the Platform is a Kubernetes cluster where communication occurs between pods within the cluster and with non-containerized ArcSight components outside of the cluster. In order to ensure secure trusted communication between pods within the cluster and components outside of the cluster, encrypted communication with client certificate authentication is configured by default.

Understanding the ArcSight Platform Certificate Authorities
Using an RE External Communication Certificate Signed by Your Trusted Certificate Authority

Understanding the ArcSight Platform Certificate Authorities

During installation, three self-signed Certificate Authorities (CA) are created automatically, two for signing certificates used exclusively for pod to pod communication within the cluster (RIC and RID CA), and the other for signing certificates for each pod that performs communication external to the cluster (RE CA). Only pods that perform external communication have a certificate that is signed by the external CA.

External cluster communication occurs not only with ArcSight components, but also with user web browsers and, in some cases, user clients of ArcSight APIs (such as the REST API). By default, when the user connects to the cluster, they will be presented with a certificate that has been signed by the self-signed external CA. Since the external CA is self-signed, the user's connection will not automatically trust the certificate because it will not be verifiable using a certificate chain that is already in the user's trust store.

To give users confidence they are connecting to the trusted cluster, we recommend signing the certificates that are presented to the user with a CA that is trusted by the user's trust store. There are two approaches to doing this that are described in the documentation below. These approaches are:

Method 1 - Signing the RE External Communication Certificate with Your Trusted Certificate Authority: This is the recommended approach, because it is theoretically more secure than the other approach, in that, it only involves transferring a CSR and public certificate between systems, which does not put any private secrets at risk.
Method 2 - Importing an Externally Created Intermediate CA: This approach involves creating an Intermediate CA (key and certificate pair) in a system outside of the ArcSight Platform, and then importing it into the ArcSight Platform. While this approach does work, it is theoretically less secure than the other approach, because it involves transferring a CA private key between systems, which potentially exposes it to unintended parties.

Use only one of the two approaches above.

Using an RE External Communication Certificate Signed by Your Trusted Certificate Authority

Use only one of the two approaches below. The first one, "Signing the RE External Communication Certificate with Your Trusted Certificate Authority" approach is recommended for the reasons described in Understanding the ArcSight Platform Certificate Authorities.

Method 1 - Signing the RE External Communication Certificate with Your Trusted Certificate Authority

Signing the RE External Communication Certificate with Your Trusted Certificate Authority approach is recommended for the reasons described in Understanding the ArcSight Platform Certificate Authorities.

In order to sign the RE external communication certificate with your trusted CA, you need to (1) create a certificate signing request (CSR) from vault, (2) take it to your organization, (3) sign it, and (4) return the signed CSR and all the public chain-of-certificates used to sign it.

Export the following access token dependencies (you can remove these later if not needed):

export CDF_APISERVER=$(kubectl get pods -n core -o custom-columns=":metadata.name"| grep cdf-apiserver)
export PASSPHRASE=$(kubectl get secret vault-passphrase -n core -o json 2>/dev/null | jq -r '.data.passphrase')
export ENCRYPTED_ROOT_TOKEN=$(kubectl get secret vault-credential -n core -o json 2>/dev/null | jq -r '.data."root.token"')
export VAULT_TOKEN=$(echo ${ENCRYPTED_ROOT_TOKEN} | openssl aes-256-cbc -md sha256 -a -d -pass pass:"${PASSPHRASE}")

Ask vault to generate the CSR by running the following command:

Important: When you execute this command, proceed expeditiously through steps 3 and 4, as your cluster will not be able to issue external certificates while it waits for the CSR to be signed.
```
kubectl exec -it -n core ${CDF_APISERVER} -c cdf-apiserver -- bash -c "VAULT_TOKEN=$VAULT_TOKEN vault write -tls-skip-verify -format=json RE/intermediate/generate/internal common_name=\"none-MF CDF RE CA on <FQDN of ArcSight Platform Virtual IP for HA or single master node>\" country=<Country> locality=<Locality> province=<Province> organization=<Organization> ou=<Organizational Unit>" | jq -r '.data.csr' > /tmp/pki_intermediate.csr
```
Note: The common_name in the command above is an example common name. Substitue your own values for the common name to fit your environment. Additionally, your trusted certificate authority might require additional parameters in the CSR besides common_name. Ask your PKI team for what the required CSR parameters are and add the appropriate parameters to the command (similar to how the parameter common_name is specified). The parameter names for the vault command used above are documented at https://www.vaultproject.io/api-docs/secret/pki#generate-intermediate
Sign the CSR file with your trusted certificate authority, and save the result into the intermediate.cert.pem file.

Examply only. A basic example is provided below. Your environment will likely be different.
```
openssl ca -keyfile your-rootca-sha256.key -cert your-rootca-sha256.crt -config your-openssl-configuration-file -extensions v3_ca -notext -md sha256 -in /tmp/pki_intermediate.csr -out intermediate.cert.pem
```
Make sure the v3_ca extension is enabled and a new certificate is useable as a certificate authority on its own. Otherwise, you will receive a warning in the next step that given certificates are not marked for CA use.
Create an intermediate.chain.pem file that includes the combination of the intermediate.cert.pem, the public certificate of your trusted certificate authority, and all intermediate public certificates in the chain between them so that intermediate.chain.pem includes the full trust chain.
```
cp intermediate.cert.pem intermediate.chain.pem
cat [parent-intermediate1.crt] [parent-intermediate2.crt] [...] your-rootca-sha256.crt >> intermediate.chain.pem
```
If you have intermediate certificates between your intermediate.cert.pem and your trusted certificate authority, you must add the certificates in the specific order of the sequence of the chain, with the last certificate being the certificate of the root trusted CA.

Import the intermediate.chain.pem file into the cluster vault:

chaincerts=$(cat intermediate.chain.pem) && kubectl exec -it -n core ${CDF_APISERVER} -c cdf-apiserver -- bash -c "VAULT_TOKEN=$VAULT_TOKEN vault write -tls-skip-verify -format=json RE/intermediate/set-signed certificate=\"${chaincerts}\""

Update ConfigMap RE_ca.crt by running these commands:

reCrtForJson=$(sed -E ':a;N;$!ba;s/\r{0,1}\n/\\n/g' intermediate.chain.pem) && kubectl patch configmap -n core public-ca-certificates -p "{\"op\": \"replace\", \"data\":{\"RE_ca.crt\":\"${reCrtForJson}\"}}"

ARCSIGHT_NS=$(kubectl get namespaces --no-headers -o custom-columns=":metadata.name" | grep arcsight-installer)

if [ -n "$ARCSIGHT_NS" ];then reCrtForJson=$(sed -E ':a;N;$!ba;s/\r{0,1}\n/\\n/g' intermediate.chain.pem); kubectl patch configmap -n $ARCSIGHT_NS public-ca-certificates -p "{\"op\": \"replace\", \"data\":{\"RE_ca.crt\":\"${reCrtForJson}\"}}";fi

(Conditional) If you already deployed ArcSight Capabilities onto the CDF, update the ArcSight Capabilities to use the updated RE external communication certificate, by following the instructions in Configuring ArcSight Kubernetes Pods to Use the Updated RE External Communication Certificate.

If you deployed CDF but have not yet deployed any ArcSight Capabilities, you can skip those instructions.

Method 2 - Importing an Externally Created Intermediate CA

This is an alternate approach for signing certificates to connect to the trusted cluster. Before choosing this approach, ensure that your understand the other approach recommended in Understanding the ArcSight Platform Certificate Authorities.

To import an externally created intermediate CA:

Obtain an intermediate CA (key and certificate pair) from your trusted certificate authority.
1. Name the certificate files as follows:
  - key file: intermediate.key.pem
  - certificate file: intermediate.cert.pem
2. Obtain the root CA certificate (including chain), and put it in a file named ca.cert.pem.
Replace the existing RE CA in the ArcSight Platform with the intermediate CA you obtained in the step above, based on your type of deployment, on-premises or cloud.
1. Change the directory:
  - For an on-premises deployment, run these commands:
```
cd /opt/arcsight/kubernetes/scripts/
```
  - For a cloud deployment, run these commands:
```
cd {path to cdf installer}/cdf-deployer/scripts/
```
2. Run the following command to replace the existing RE CA:
```
./cdf-updateRE.sh write --re-crt=/pathto/intermediate.cert.pem --re-key=/pathto/intermediate.key.pem [--re-ca=/pathto/ca.cert.pem]
```
  Note: --re-ca=/pathto/ca.cert.pem is the path to the file containing the certificate of CA used to sign re-crt. It is not required when re-crt is self-signed or CA is included in re-crt.
(Conditional) If you already deployed ArcSight Capabilities onto CDF, proceed to the next section to update the ArcSight Capabilities to use the updated RE external communication certificate, Configuring ArcSight Kubernetes Pods to Use the Updated RE External Communication Certificate.

However, if you have only deployed CDF, but have not deployed ArcSight Capabilities yet, you can skip that section.