Preparing custom certificates for use with KV store

To use custom certificates in Splunk Enterprise 9.4 and higher, you must take extra steps to ensure your certificates comply with the KV store requirements. If you use the default Splunk certificates, no action is needed.

Complete the following steps to prepare your self-signed certificates, or custom certificates generated by a third party.

1. Enter one of the following commands in the command-line interface (CLI), replacing <certificateType> with sslConfig if you're using a server certificate, or with kvstore if you're using a certificate defined exclusively for KV store:
   • Unix:

     ./bin/splunk cmd btool server list <certificateType> | grep sslPassword
     

   • Windows:

     ./bin/splunk.exe cmd btool server list <certificateType> | grep sslPassword
     

2. To ensure your certificate is password protected, verify that the results include the following line:

   sslPassword = <yourCertificatePassword>
   

   If no password is specified, set one before proceeding.

3. Ensure your server certificate is in a PEM file, and that the certificate authority used to sign it is appended to that PEM file. For more information about how to make sure your certificate is in the correct format, see How to prepare TLS certificates for use with the Splunk platform in the Securing Splunk Enterprise manual.
4. Enter one of the following commands in the CLI, replacing <filePath> with the absolute file system path to your certificate:
   
   • Unix:

     ./bin/splunk cmd openssl x509 -text -in <filePath>
     

   • Windows:

     ./bin/splunk.exe cmd openssl x509 -text -in <filePath>
     

5. Verify that the results include the following lines, if applicable:
   • If your certificate is configured with extendedKeyUsage, then extendedKeyUsage must define both the clientAuth (TLS Web Client Authentication), and serverAuth (TLS Web Server Authentication). See the following example:

     extendedKeyUsage = clientAuth, serverAuth
     

   • If your certificate is defined in the [kvstore] stanza of server.conf and configured with Subject Alternative Name (SAN), ensure it contains 127.0.0.1, the IPv6 equivalent of the localhost address, or the IP address used to bind the Splunk Enterprise and KV store server process. If your certificate is not defined in the [kvstore] stanza, no action is needed for this step.
6. Enter one of the following commands in the CLI:
   
   • Unix:

     ./bin/splunk cmd btool server list sslConfig
     

   • Windows:

     ./bin/splunk.exe cmd btool server list sslConfig
     

7. From the command's output, make a note of the caCertFile and serverCert values. These are the file paths to these certificate files. Also, ensure that results include the sslPassword line, as in the following example output:

   caCertFile = $SPLUNK_HOME/etc/auth/cacert.pem
   serverCert = $SPLUNK_HOME/etc/auth/server.pem
   sslPassword = <yourCertificatePassword>
   

   If the sslRootCAPath value is defined in this output, it takes priority over the caCertFile value. In that case, note the serverCert value and the sslRootCAPath value instead.

8. Using the information you noted in the previous step, enter the following command into the CLI:
   
   • Unix:

     ./bin/splunk cmd openssl verify -verbose -x509_strict -CAfile <file path to sslRootCAPath or caCertFile> <file path to serverCert>
     

   • Windows:

     ./bin/splunk.exe cmd openssl verify -verbose -x509_strict -CAfile <file path to sslRootCAPath or caCertFile> <file path to serverCert>
     

   To verify that your certificate is properly signed, ensure this output matches the following example response, where instead of this example file path, it shows the file path to your server certificate:

   $SPLUNK_HOME/etc/auth/server.pem: OK
   

   If you see any other output, your certificate pair is not properly signed.

Troubleshooting your certificates

See the following documentation for more information about troubleshooting your certificates:

• How to prepare TLS certificates for use with the Splunk platform in the Security Splunk Enterprise manual.
• Configure TLS certificates for inter-Splunk communication in the Securing Splunk Enterprise manual.
• Securing the Splunk platform with TLS in the Splunk Lantern Customer Success Center.