Install or Renew a Custom Certificate - Administrator Guide - 6.10 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Administrator Guide
Product
Cortex XSOAR
Version
6.10
Creation date
2022-10-13
Last date published
2024-04-15
End_of_Life
EoL
Category
Administrator Guide
Abstract

Create a private key and certificate signing request in Cortex XSOAR. Troubleshoot key and certificate issues.

For security reasons, the default certificate for a production environment must be replaced with your private key and a certificate from a CA (Certificate Authority). For development environments, you have the option of using a self-signed certificate or a certificate from a CA (Certificate Authority).

Note

While the example below is generic, you might need to create your certificates and keys with different parameters, according to your internal company policies or compliance with regulations.

Create a Private Key and CSR

The following example is one way to create a private key and certificate signing request (CSR) on a Linux based system. The procedure may be slightly different between Linux releases, operating system versions, and OpenSSL versions. Our example uses Centos 7.

  1. In an SSH session to the Cortex XSOAR server, install OpenSSL by running the following command:

    • For Ubuntu: sudo apt install openssl

    • For Centos and Fedora: sudo yum install openssl

  2. Generate the certificate signing request and the private key. The certificate signing request is for the URL that will be publicly available for everyone and also includes all public facing aliases.

    Flag

    Description

    -newkey rsa:4096

    Creates a new certificate request and a 4096 bit RSA key. The default RSA key is 2048 bits.

    -sha256

    Uses 265-bit SHA (Secure Hash Algorithm).

    -out example.csr

    Specifies the file name for the newly created certificate signing request. You can specify any file name.

    -keyout example.key

    Specifies the file name for the newly created private key. You can specify any file name.

    -addext

    Adds desired DNS aliases to the certificate.

    Note

    If you prefer to create a key without a passphrase, add the -nodes flag.

  3. Save the cert.key file.

  4. Follow the on-screen instructions.

    The CSR is sent to the certificate signing authority. The CA (certificate authority) sends the certificate by email in different formats. For example, example.crt.

    Caution

    Cortex XSOAR server does not support PKCS#8 encrypted PEM files. To validate that the file is in a format that is supported, view the encrypted .key file (you can use one of the following commands - vi / less / cat) and check that the "DEK-Info" header exists.

    A certificate with the DEK-Info header begins with the following:

    -----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTEDVcNSY7T...
DEK-Info: AES-256-CBC,B94C43E0E49D267EB3AA84DC19EB41ED
VcNSY7T...

    If the DEK-Info header is not similar to the example above, the file is likely in the wrong format (PKCS#8).

    You can convert the .key file to the proper format by running the following command:

    openssl rsa -in oldcert.key -out cert.key -aes256

    You don't have to use aes256, you can use des3 or whichever encryption method you prefer.

    After you run this command, view the .key file and verify that the DEK-Info header is similar to the example above. This should allow the .key file to be read.

  5. For the certificate PEM file, you must concatenate the certificate chain one after the other in the file.

    If you are using an intermediate certificate, the order is:

    1. SSL certificate

    2. Intermediate certificate

    3. CA certificate

    If you are not using an intermediate certificate, the order is:

    1. SSL Certificate

    2. CA Certificate

    Note

    Only the certificate itself is needed, i.e., the text between and including "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----".

Apply the Certificate to Cortex XSOAR

To replace the default internal certificate with a private key and a certificate from a CA (Certificate Authority):

  1. Stop the Cortex XSOAR server.

    sudo service demisto stop

    Note

    In a live backup setup environment, you need to stop both servers and update the certificates on both servers before bringing them back up.

  2. Replace the existing default internal certificate in /usr/local/demisto/cert.pem and key in /usr/local/demisto/cert.key with the newly generated private certificate and key.

    For example:

    Copy the certificate (example.crt) to /usr/local/demisto: cp example.crt /usr/local/demisto/cert.pem

    Copy the key (example.key) to /usr/local/demisto: cp example.key /usr/local/demisto/cert.key

  3. If you store the certificate and key in a folder other than /usr/local/demisto, you must edit the /etc/demisto.conf file and add the locations below:

    {  
  "Security":{  
    "CertFile":"",       
      "KeyFile":""   
  }
}

    Check both files have the correct ownership: demisto:demisto.

  4. If your private key is encrypted, you need to add the key password to the one-time-configuration (OTC) file located in /var/lib/demisto/otc.conf.json. After the file is saved and the Cortex XSOAR server is restarted, the OTC file is automatically deleted. Add the following content to the OTC file: {"keypass":"certpassword"}. The otc.conf.json must have permissions for demisto:demisto.

  5. Restart the Cortex XSOAR server.

    sudo service demisto start

Troubleshoot Creating a Private Key and CSR

After the newly generated certificate key pair is copied to /usr/local/demisto, if the browser does not show the new certificate, do one or more of the following:

  • Check whether the FQDN of the Cortex XSOAR server is the same as the CN field of the certificate, or any of the DNS fields in the Certificate Subject Alternative NAME (SAN) .

  • Check whether there are any other certificates or keys in /usr/local/demisto, other than the ones generated recently for the Cortex XSOAR server. If so, remove or move them to another folder on the server.

  • On your browser on which you are trying to load Cortex XSOAR, clear cookies and other data. For example, in Chrome, go to Settings → Advanced → Clear Browsing data → Clear data.

  • If the Cortex XSOAR server is behind a load balancer, re-upload the certificate on the load balancer. For example, if the Cortex XSOAR server is behind the ELB (Elastic Load Balancing), re-import the certificate on ELB (Elastic Load Balancing) on the Amazon Certificate Manager AWS console.

  • Confirm the demisto.conf file contains the following keys:

    {  
  "Security":{  
    "CertFile":"",       
      "KeyFile":""   
  }
}