Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This guide will assist you with importing a custom SSL certificate for enterprise and production Datameer X environments.

Table of Contents

Prerequisites

Before you attempt to create a custom certificate, check the following to ensure your environment is ready:

  • Install Datameer X and Enable SSL.

  • Install the Java Cryptography Extension (JCE) for your version of Java.

  • Work within the current Datameer X installation directory.

  • Familiarize yourself with obfuscating passwords. The following is an example where the password "changeit" is obfuscated:

    Obfuscate password

    Code Block
    languagenone
    [datameer@<host> current]$ java -cp ./lib/jetty-util-<version>.jar org.eclipse.jetty.util.security.Password
    <timestamp>:INFO::main: Logging initialized @75ms
    Usage - java org.eclipse.jetty.security.Password [<user>] <password>
    If the password is ?, the user will be prompted for the password
    # According 
    # Usage - java org.eclipse.jetty.security.Password [<user>] <password> 
    # the user value is optional 
    [datameer@<host> current]$ java -cp lib/jetty-util-<version>.jar org.eclipse.jetty.util.security.Password changeit
    <timestamp>:INFO::main: Logging initialized @75ms
    changeit
    OBF:1vn21ugu1saj1v9i1v941sar1ugw1vo0
    MD5:b91cd1a54781790beaa2baf741fa6789

Providing a Custom Certificate for Embedded Jetty

Get a certificate

  1. Generate a private key and a certificate signing request (CSR) file before requesting CA authorized certificates:

    Create CSR file

    Code Block
    languagebash
    openssl req -new -newkey rsa:2048 -nodes -keyout <yourdomain>.key -out <yourdomain>.csr
  2. Download the certificates from the certificate authority (CA).

  3. Check your X.509 certificates:

    Check certificate

    Code Block
    languagebash
    openssl x509 -in <yourdomain>.crt -text -noout
  4. Generate a PKCS12 file:

    Generate PKCS12 file

    Code Block
    languagebash
    openssl pkcs12 -inkey <yourdomain>.key -in <yourdomanin>.crt -export -out datameer.p12 -name datameer

    This file bundles the private  key together with the public X.509 certificate and is a public key cryptographic standard. The private key needs to be protected by a password. For the key password, you can use keypwd

  5. Obfuscate the password.

    Obfuscate password

    Code Block
    languagebash
    [datameer@<host> current]$ java -cp lib/jetty-util-<version>.jar org.eclipse.jetty.util.security.Password datameer keypwd
    <timestamp>:INFO::main: Logging initialized @75ms
    keypwd
    OBF:1u2u1wml1z7s1z7a1wnl1u2g
    MD5:4a27e9a4bd7a907bd04606dd05be4d25
    CRYPT:da3b2s9U.Q7Nw

    The obfuscated key password, in this example OBF:1u2u1wml1z7s1z7a1wnl1u2g , will need to be added to Datameer’s start.d/ssl.ini file under the parameter jetty.sslContext.keyManagerPassword.

Generate a keystore 

Generate a repository of security certificates for Datameer's embedded Jetty. For this process, use keytool

  1. Check the default keystore located in your Datameer X installation path within etc/:

    Check keystore

    Code Block
    languagebash
    [datameer@<host> current]$ keytool -list -v -keystore etc/keystore | grep -i 'jetty'
    Enter keystore password:  storepwd
    Alias name: jetty
    Owner: CN=jetty.mortbay.org, OU=Jetty, O=Mort Bay Consulting Pty Ltd, L=Unknown, ST=Unknown, C=Unknown
    Issuer: CN=jetty.mortbay.org, OU=Jetty, O=Mort Bay Consulting Pty Ltd, L=Unknown, ST=Unknown, C=Unknown
  2. Backup the default keystore file:

    Backup keystore

    Code Block
    languagebash
    mv etc/keystore etc/keystore.original
  3. Ensure you no longer have a file named keystore within the etc/ path.

  4. Create a new Java KeyStore (JKS) file using the datameer.p12 file that was generated previously. The keystore must be protected by a password. 

    Create keystore

    Code Block
    languagebash
    keytool -importkeystore -srckeystore datameer.p12 -srcstoretype PKCS12 -destkeystore etc/keystore 

    For the keystore password you can use storepwd

  5. Obfuscate the password:

    Obfuscate password

    Code Block
    languagebash
    [datameer@<host> current]$ java -cp lib/jetty-util-<version>.jar org.eclipse.jetty.util.security.Password datameer storepwd
    <timestamp>:INFO::main: Logging initialized @75ms
    storepwd
    OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
    MD5:7bfa04a176c6d48e5283e1c037e4668e
    CRYPT:dake2.vBb3e52

    The obfuscated keystore password, in this example OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4 , will need to be added to Datameer’s start.d/ssl.ini file under the parameter jetty.sslContext.keyStorePassword.

  6. Check the generated keystore repository:

    Check keystore

    Code Block
    languagebash
    [datameer@<host> current]$ keytool -list -v -keystore etc/keystore | grep -i 'datameer'
    Enter keystore password:  storepwd
    Alias name: datameer
    Owner: <...>
    Issuer: <...>

Use your own keystore

To use the custom certificate stored in the created Java Keystore (JKS) file, configure the start up configuration file. 

  1. Check the current configuration:

    Check current config

    Code Block
    languagebash
    # The path to the keystore file 
    [datameer@<host> current]$ java -jar start.jar --list-config | grep -i 'StorePath ='
     jetty.sslContext.keyStorePath = etc/keystore
     jetty.sslContext.trustStorePath = etc/keystore
    # The necessary passwords 
    [datameer@<host> current]$ java -jar start.jar --list-config | grep -i 'Password ='
     jetty.sslContext.keyManagerPassword = OBF:1u2u1wml1z7s1z7a1wnl1u2g
     jetty.sslContext.keyStorePassword = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
     jetty.sslContext.trustStorePassword = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
  2. Back up the default configuration:

    Backup config

    Code Block
    languagebash
    cp start.d/ssl.ini start.d/ssl.ini.backup 
  3. Configure start.d/ssl.ini by locating and altering the following parameters:

    Info
    iconfalse
    Since this example uses default values, no changes are necessary.

    Configure start.d/ssl.ini

    Code Block
    languagebash
    jetty.ssl.port=<desired_port>						(default=8443)
    jetty.sslContext.keyStorePath=<path/to/keystore> 	(default=etc/keystore)
    jetty.sslContext.trustStorePath=<path/to/keystore> 	(default=etc/keystore)
    jetty.sslContext.keyStorePassword=<password>		(default=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
    jetty.sslContext.keyManagerPassword=<password>		(default=OBF:1u2u1wml1z7s1z7a1wnl1u2g)
    jetty.sslContext.trustStorePassword=<password>		(default=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4)
  4. Create a configuration change log:

    Create changelog

    Code Block
    languagebash
    diff -e start.d/ssl.ini.backup start.d/ssl.ini > changes.start.ini
  5. Restart the Datameer X service to enable the above changes and monitor the boot process:

    Restart and monitor

    Code Block
    languagebash
    [datameer@<host> current]$ ./bin/conductor.sh restart
    [datameer@<host> current]$ tail -f logs/conductor.log

Renew certificate

Certificates typically have an expiration date as such it is necessary to renew them to prevent Datameer X from loading out of date certificates. To do so, complete the following steps:

  • Get own certificate

  • Generate own keystore

  • Use own keystore

Anchor
trustcertificates
trustcertificates
Trusting Custom Certificates from Other Services

The Java Virtual Machine (JVM) enforces security and validates the certification path to the requested target. If the certificate isn't provided from a generally trusted root certificate, you must trust the certificate by adding it to the truststore of the Java Virtual Machine (JVM) that runs Datameer. 

  • Gather the certificate:

    Gather certificate

    Code Block
    languagebash
    openssl s_client -connect <host>.<domain>.<tld>:<port> -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > <yourservice>.pem
  • Validate the certificate:

    Validate certificate

    Code Block
    languagebash
    openssl x509 -in <yourservice>.pem -inform pem -noout -text
  • Trust the certificate by importing it:

    Import certificate

    Code Block
    languagebash
    sudo keytool -keystore ${JAVA_HOME}/jre/lib/security/cacerts -storepass changeit -import -trustcacerts -v -alias <yourservice> -file <yourservice>.pem
  • Restart the Datameer X service to enable the above changes and monitor the boot process:

    Restart and monitor

    Code Block
    languagebash
    [datameer@<host> current]$ ./bin/conductor.sh restart
    [datameer@<host> current]$ tail -f logs/conductor.log

Further Information 

For more information, refer to the Secure Socket Extension (JSSE) Reference Guide.  

...