IBM Support

QRadar: How to set up a TLS connection between a Disconnected Log Collector and a QRadar host

How To


Summary

This article describes a process for setting up a connection over TLS between a Disconnected Log Collector (DLC) and a QRadar® host.

Objective

Notice: This method is not currently officially supported, as it is not fully tested by IBM's Product Engineering teams. This article shows a template process for how a TLS connection might work and administrators must contact their network or system administrator to discuss their specific situation. Creation and management of certificates and private keys are the user's responsibility. See the Custom certificate creation and support policies for details on what is out-of-scope for QRadar support.
To send encrypted events from a Disconnected Log Collector (DLC) to any QRadar host that has an ecs-ec-ingress component such as event collectors, event processors, Data Gateway, or the Console.
IMPORTANT: This article refers to a QRadar host. For a standard configuration, this is your QRadar Console. For nonstandard configurations, it can be a Data Gateway, event collector, or event processor.

Environment

On-premise QRadar deployments or Data Gateways.

Steps

This article is split into sections based on the subobjectives:
  • Creating your CA certificate
  • Creating the CSRs
  • Signing the CSRs with your CA certificate
  • Creating the Log Source for the DLC
  • Troubleshooting
Glossary:
  • CA = Certificate Authority
  • CSR = Certificate Signing Request
  • Key = Private Key (Public Keys are not used in this process)

Creating your CA certificate

These steps must be performed on a Linux host with a recent version of openssl installed. You can create the CSRs, keys, and certificates all on one host, either on the DLC host or a QRadar host, or a third host. The only requirement is that you must be able to copy files between hosts. In this example, we create them on the DLC.

Before you begin
You need only to do these steps if:
  • You are not going to use a public CA to sign certificates with.
  • You do not already have an internal corporate Certificate Authority.
  1. Use SSH to log in the DLC as the root user.
  2. Create a config file for your CA certificate and key. 
    touch openssl-ca.cnf
  3. Edit the following sample config to meet your requirements and insert it into the openssl-ca.cnf file. In the [ ca_distinguished_name ] section, if you do not need certain fields you can remove them. Fields come in pairs so for example, to remove the email section you must remove both emailAddress and emailAddress_default.

    Note: IBM does not endorse the default values in this sample configuration. Users must confirm the appropriate values with their network or system administrator. You can read more about OpenSSL configs values here. 
    ######## Start of file #############################################
[ ca ]
default_ca = CA_default # The default ca section

####################################################################
[ CA_default ]
HOME.             = .
RANDFILE          = $ENV::HOME/.rnd
default_cel_days  = 30      # How long before next CRL
preserve          = no          # Keep passed DN ordering
policy            = policy
default_days      = 3650   # How long to certify for -days
email_in_dn       = no       # Don't concat the email in the DN
copy_extensions   = copy       # Required to copy SANs from CSR to cert

####################################################################
[ req ]
default_bits        = 2048
distinguished_name  = ca_distinguished_name
string_mask         = utf8only
default_md          = sha256       # Use public key default MD
x509_extensions     = ca_extensions
default_keyfile     = cakey.pem

####################################################################
[ ca_distinguished_name ]
countryName                     = Country Name (2 letter code)
countryName_default             = US

stateOrProvinceName             = State or Province Name (full name)
stateOrProvinceName_default     = NY

localityName                    = Locality Name (eg, city)
localityName_default            = Armonk

organizationName                = Organization Name (eg, company)
organizationName_default        = Company, Limited

organizationalUnitName          = Organizational Unit (eg, division)
organizationalUnitName_default  = Server Research Department

commonName                      = Common Name (e.g. server FQDN or YOUR name)
commonName_default              = Test CA

emailAddress                    = Email Address
emailAddress_default            = myemail@example.com

####################################################################
[ ca_extensions ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = keyCertSign, cRLSign 

############ End of file ###########################################
  4. Run this command to create the certificate (cacert.pem) and the private key for the CA certificate (cakey.pem). 
    openssl req -x509 -config openssl-ca.cnf -newkey rsa:2048 -sha256 -nodes -out cacert.pem -outform PEM
    Example of successful output: 
    Generating a 2048 bit RSA private key
.................................................................++
................................................................................................................................++
writing new private key to 'cakey.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [US]:
[OTHER ca_distinguished_name FIELDS]
  5. Copy the CA certificate (cacert.pem) to your QRadar host and your DLC.
    Example that uses scp: 
    scp cacert.pem root@QRADAR-HOST-IP:/etc/pki/ca-trust/source/anchors/
scp cacert.pem root@DLC-IP:/etc/pki/ca-trust/source/anchors/
  6. Update the trusted CAs. Run this command on both your QRadar host and on your DLC. 
    update-ca-trust
    Result
    There is no output after a successful execution of update-ca-trust.

Creating the CSRs

Creating a CSR Using generateCertificate.sh
Create a CSR for the DLC for the standard use-case. If you require public CA signing, follow the Alternative steps for a creating a CSR that requires public CA signing instead.
Note: You can find the IBM Documentation this article uses for Setting up certificate-based authentication on Disconnected Log Collector here.
  1. Use SSH to log in the DLC as the root user.
  2. Run the following script. It prompts you for the certificate information. 
    /opt/ibm/si/services/dlc/current/script/generateCertificate.sh -csr -2k
    Note: The -2k option represents a 2048-bit key. You can use -4k for a 4096-bit key. Choose the key size value for the certificate according to the requirements of your organization. In this example, we use -2k.

    You now have two files: dlc-client.csr and dlc-client.key. Both files reside in: /opt/ibm/si/services/dlc/keystore/<UUID>. The UUID is the actual Common Name in the final DLC client certificate. Record it for use in the Creating the Log Source for the DLC section.
  3. Run the following script on the DLC to create a CSR for your QRadar host. This CSR when signed, becomes the server certificate. 
    /opt/ibm/si/services/dlc/current/script/generateCertificate.sh -servercsr -2k
    Enter the following information when prompted:
    Parameter Definition
    SAN IP The IP address of the QRadar host that Disconnected Log Collector connects to.
    SAN DNS The fully qualified domain name of the QRadar host.
    Organization Name The name of your organization.
    Organization Unit Name The name of your organization unit.
    Common Name This value is typically the FQDN of the QRadar host.

    Result
    After you enter the parameter information, the script creates a dlc-server.csr and a dlc-server.key file in the /opt/ibm/si/services/dlc/keystore/<UUID> directory on your DLC.
Alternative steps for a creating a CSR that requires public CA signing.
This manual creation method is for use cases where the client certificate needs to be signed by a public CA such as DigiCert, Let's Encrypt, or Go Daddy. The generateCertificate script in the standard process creates a client cert with the UUID of the DLC as the Common Name (CN), which might not be suitable because a public CA does not accept a UUID as the CN.
  1. Use SSH to log in the DLC as the root user.
  2. Create another config file. 
    touch tls-server.conf
  3. Add the following snippet to the config file. Note the line beginning with "SAN =" you must add the hostname, or the FQDN of the host, where the certificate is used. You can have multiple hostnames, for example if your host has aliases, or if your intention is to have the same certificate on several event collectors. Set the commonName value to match one of the values in the SAN string.
    For example, if you have 3 hostnames, you can add
    SAN = DNS:aaa.mydomain.com,DNS:bbb.mydomain.com,DNS:ccc.mydomain.com,DNS:servers.mydomain.com
    commonName = servers.mydomain.com
     
    ############ Start of file ##########################################
[ default ]
# Change the following line to include the FQDN and IP address of the QRadar Console or host
SAN = DNS:<QRadar hostname or FQDN>,IP:<QRadarIP>

[ req ]
default_bits = 2048                 # RSA key size; change to 4096 if required by your organization
encrypt_key = no                          # Protect private key
default_md = sha256                     # MD to use
utf8 = yes                               # Input is UTF-8
string_mask = utf8only                   # Emit UTF-8 strings
prompt = no                                # Prompt for DN
distinguished_name = server_dn          # DN template
req_extensions = server_reqext           # Desired extensions
 
[ server_dn ]
countryName = US                   # ISO 3166 - enter a two-letter country code
organizationName = Company
organizationalUnitName = Security
commonName = <commonName>           # Must match one of the listed SANs, see above
 
[ server_reqext ]
keyUsage = critical,digitalSignature,keyEncipherment
extendedKeyUsage = serverAuth,clientAuth
subjectKeyIdentifier = hash
subjectAltName = $ENV::SAN
############ End of file ###########################################
  4. Create the server Private Key and the server CSR with your config file.
    openssl req -new -config tls-server.conf -out dlc-server.csr -keyout dlc-server.key
    Result
    Example of successful output: 
    Generating a 2048 bit RSA private key
....................+++
.............................................................+++
writing new private key to 'dlc-server.key'
-----
    You now have two files: dlc-server.csr and dlc-server.key in the working directory.

Signing the CSRs with your CA certificate

  1. Take note of where your dlc-client.csr, cacert.pem, and cakey.pem are located. We recommend keeping the files in the same folder while you are following these steps. In this example, they are on the DLC.
  2. The CA's openssl-ca.cnf file needs two more sections before you issue the signing command. Open openssl-ca.cnf and add the following: 
    ####################################################################
[ signing_policy ]
countryName            = optional
stateOrProvinceName    = optional
localityName           = optional
organizationName       = optional
organizationalUnitName = optional
commonName             = supplied
emailAddress           = optional

####################################################################
[ signing_req ]
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid,issuer
basicConstraints       = CA:FALSE
keyUsage               = digitalSignature, keyEncipherment
  3. Add the following to the [ CA_default ] section of openssl-ca.cnf: 
    base_dir      = .
certificate   = $base_dir/cacert.pem   # The CA certifcate
private_key   = $base_dir/cakey.pem    # The CA private key
new_certs_dir = $base_dir              # Location for new certs after signing
database      = $base_dir/index.txt    # Database index file
serial        = $base_dir/serial.txt   # The current serial number

unique_subject = no  # Set to 'no' to allow creation of
                     # several certificates with same subject.
  4. Create two files: index.txt and serial.txt. If needed, these are for housekeeping and tracking because they allow the same CN to be used multiple times. 
    touch index.txt
echo '01' > serial.txt
  5. Run the commands to sign the CSRs: 
    openssl ca -config openssl-ca.cnf -policy signing_policy -extensions signing_req -out dlc-server.crt -infiles dlc-server.csr
    Example of successful output: 
    Using configuration from openssl-ca.cnf
Check that the request matches the signature
Signature ok
The Subject's Distinguished Name is as follows
countryName           :PRINTABLE:'US'
stateOrProvinceName   :ASN.1 12:'NY'
localityName          :ASN.1 12:'Armonk'
commonName            :ASN.1 12:'Test CA'
emailAddress          :IA5STRING:'test@example.com'
Certificate is to be certified until Oct 20 16:12:39 2016 GMT (1000 days)
Sign the certificate? [y/n]:Y

1 out of 1 certificate requests certified, commit? [y/n]Y
Write out database with 1 new entries
Data Base Updated
  6. Repeat the command for the second CSR. The "successful" output is similar for both commands.
    openssl ca -config openssl-ca.cnf -policy signing_policy -extensions signing_req -out dlc-client.crt -infiles dlc-client.csr
  7. Move the dlc-client.crt file to the DLC to the /tmp directory, or your preferred location. Move the dlc-server.crt file to the QRadar host. You can put it in the /root directory.

    Result
    The dlc-client.crt and dlc-server.crt are signed. 
Convert the client certificate:
Perform these steps on the DLC and ensure the dlc-client.crt is in the /tmp directory.
  1. Convert the client certificate to PKCS#12 format by using the following command. Choose a secure password when prompted. 
    /opt/ibm/si/services/dlc/current/script/generateCertificate.sh -p12 /tmp/dlc-client.crt
  2. A generated personal exchange format (PFX) file is saved as /opt/ibm/si/services/dlc/keystore/dlc-client.pfx and the required PFX information is stored in the /opt/ibm/si/services/dlc/conf/config.json file. The dlc-client.crt file is moved to /opt/ibm/si/services/dlc/keystore/<UUID>
    You can also see that your client certificate has the UUID as the Common Name, you need this later in the Log Source configuration.
    openssl x509 -in /opt/ibm/si/services/dlc/keystore/<UUID>/dlc-client.crt -text -noout | grep "Subject:"
  3. Restart the DLC service: 
    systemctl restart dlc
Convert the server certificate:
  1. Perform this step in the directory where the dlc-server.crt and dlc-server.key are saved. In this example, it is on the DLC. Convert the dlc-server.crt  to a P12/PFX file. You are prompted for an export password. Remember this password. You need it in the Creating the Log Source for the DLC section. 
    openssl pkcs12 -export -out dlc-server.pfx -inkey dlc-server.key -in dlc-server.crt
    You now have a dlc-server.pfx file.
  2. Copy the dlc-server.pfx file to the /opt/qradar/conf/key_stores directory of the QRadar host. If the /key_stores directory doesn't exist, create it. 
    mkdir -pv /opt/qradar/conf/key_stores
cp -pv dlc-server.pfx /opt/qradar/conf/key_stores
    Result
    The server certificate is now converted to a PKCS12 truststore.

Creating the Log Source for the DLC

Create a new Log Source in QRadar.
  1. Log in to QRadar.
  2. Click the Admin tab.
  3. To open the app, click the QRadar Log Source Management app icon.
  4. Click New Log Source > Single Log Source.
  5. Select Universal DSM and IBM QRadar DLC Protocol.
  6. Name and Log Source Identifier. The names can be arbitrary as they are not critical.
  7. Select the Target Event Collector that is the same as the QRadar host where you placed the dlc-server.pfx.
  8. Select Authentication by Common Name (enabled).
    If you followed the Additional steps for when the Common Name differs from the UUID, in the CN/Alias Allowlist field, enter the UUID.
  9. Set the Keystore Filename to dlc-server.pfx. Do not enter a path.
  10. Set the Keystore Password to the export password.
  11. Set Check Revocation to No. We are using internally signed certs.
  12. Set Truststore File Path to /etc/pki/ca-trust/extracted/java/cacerts
  13. Set Truststore Password to changeit.
  14. Save the log source and deploy it.

    Result
    If you made corrections to the log source configuration, you might need to toggle the log source, and restart ecs-ec-ingress service for the changes to take effect. 
    systemctl restart ecs-ec-ingress
    IMPORTANT: Restarting ECS-EC might temporarily stop event collection while the service restarts. Administrators with strict outage policies are advised to complete the next step during a scheduled maintenance window for their organization.

Troubleshooting

If there is an issue with any of the certificates or private keys, you might see an SSL Handshake-related error in the dlc.error log. You can try re-creating the certificates and keys from start, as there might be a simple spelling mistake in one of the configuration files or an invalid character. You can also refer to the Extra troubleshooting section in QRadar: Troubleshooting your DLC - health metrics or other events not received in QRadar
Before contacting support on issues related to this process, review our custom certificate creation and support policies.
 

[{"Type":"MASTER","Line of Business":{"code":"LOB24","label":"Security Software"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSBQAC","label":"IBM Security QRadar SIEM"},"ARM Category":[{"code":"a8m0z000000cwt9AAA","label":"DLC"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

Modified date:
03 November 2022

UID

ibm16461943

Page Feedback