IBM Support

QRoC: How to set up a TLS connection between a Disconnected Log Collector and a QRadar on Cloud 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® on Cloud host such as the console or an EPFP. This process is not applicable for Data Gateways.

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. 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 a QRadar on Cloud (QRoC) instance, excluding Data Gateways.

Environment

QRadar On Cloud console and EPFPs hosted by IBM

Steps

This article is split into sections based on the subobjectives:
  • Creating the server certificate
  • Creating the client CSR
  • Creating your CA certificate for signing your client CSR
  • Signing the manually created CSR with your CA certificate
  • Creating the Log Source for the DLC
  • Troubleshooting
Glossary:
  • CA = Certificate Authority
  • CSR = Certificate Signing Request
  • EPFP = Event and Flow Combo Processor
  • Key = Private Key (Public Keys are not used in this process)
 

Creating the server certificate

The creation of the server certificate is a task for IBM only when the DLC is connecting directly to server within the QRoC environment (if you are using a Data Gateway, see QRadar: How to set up a TLS connection between a Disconnected Log Collector and a QRadar host). Open a support case and indicate which QRadar host you want to connect the DLC to. IBM provides the Keystore File Name, Keystore File Password, Truststore File Path and Truststore Password for the log source configuration.
As you follow this process, you must supply additional information in the support case. The information is as follows, but it is be pointed out again in the specific step where you must provide it:
  • The CA cert, which was used to sign the client certificate.
  • The client cert.

Creating the client CSR

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 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. Submit the CSR to your internal certificate authority for signing according to their instructions. The procedure might involve opening the CSR file and copying a block of encoded text that is contained between the BEGIN and END markers.

    Result
    The client CSR is created and signed.
     
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, Go Daddy and so on. 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 the DLC as the root user.
  2. Create a config file. 
    touch dlc-client.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 might add:
    SAN = DNS:aaa.mydomain.com,DNS:bbb.mydomain.com,DNS:ccc.mydomain.com,DNS:servers.mydomain.com
    commonName = aaa.mydomain.com
    ############ Start of file ##########################################
[ default ]
# Change the following line to include the FQDN and IP address of the QRoC host
SAN = DNS:<Console or EPFP FQDN>,IP:<Console or EPFP IP>

[ 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 dlc-client.conf -out dlc-client.csr -keyout dlc-client.key
    Result
    Example of successful output: 
    Generating a 2048 bit RSA private key
....................+++
.............................................................+++
writing new private key to 'dlc-client.key'
-----
    You now have two files: dlc-client.csr and dlc-client.key in the working directory.

Creating your CA certificate for signing your client CSR

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.
  1. Use SSH to log in the 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      = 1000   # 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
default_md          = sha256       # Use public key default MD

####################################################################
[ req ]
default_bits        = 2048
distinguished_name  = ca_distinguished_name
string_mask         = utf8only
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 DLC to /etc/pki/ca-trust/source/anchors/.
    You must share this CA cert with IBM in your support case so they can place the cert on the Console or EPFP.
  6. Update the trusted CAs. Run this command on your DLC then notify IBM in your support case. IBM performs this task on the QRoC console or EPFP. 
    update-ca-trust
    Result
    There is no output after a successful execution of update-ca-trust.

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 sections: 
    ####################################################################
[ 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. These files are for housekeeping and tracking and this method allows the same CN to be used multiple times if needed. 
    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-client.crt -infiles dlc-client.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. Move the dlc-client.crt file to the DLC to the /tmp directory, or your preferred location.

    Result
    The dlc-client.crt is signed. 
On the DLC:
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. Update the config.json to set the destination.ip to the public IP of the QRoC host (console or EPFP).
  4. Restart the DLC service: 
    systemctl restart dlc
    Result:
    Notify IBM in your support case that the certificates are created and configured.

 

Creating the Log Source for the DLC

Create a 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. Set the Target Event Collector to the console or EPFP, which you indicated to IBM, as the server cert resides on that host.
  8. Select Authentication by Common Name (enabled).
    Enter the UUID of the DLC, or if you followed the alternative client cert method, enter the Common Name of the client cert.
  9. Set Keystore Filename and Keystore Password to the values that IBM shared with you.
  10. Set Check Revocation to No if your client cert was created with the alternative method.
  11. Set Truststore File Path and Truststore Password to the values that IBM shared with you.
  12. 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 for the changes to take effect.

Troubleshooting

If there is an issue with any of the certificates or private keys, you might see an SSL Handshake-related error in the Log Source Management app when you run the test. This usually means that there is a problem with the server cert or private key. In this case, open a QRadar Support case and describe the issue and refer to any old case where you requested the certs to be created as a reference.
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.
 

Document Location

Worldwide

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

Document Information

Modified date:
06 April 2023

UID

ibm16620591

Page Feedback