This guide shows you how to import a custom SSL certificate for enterprise and production environments.

Prerequisites

Before you create a custom certificate, make sure your environment is ready:

Install Datameer X and enable TLS.
Install Java Cryptography Extension (JCE) for Java 8.
Work within the current Datameer X installation directory.

Familiarize yourself with obfuscating passwords, as in the following example, where the password "changeit" is obfuscated:

Obfuscate password

[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

Generate a private key and a certificate signing request (CSR) file before requesting CA authorized certificates:
Create CSR file
```
openssl req -new -newkey rsa:2048 -nodes -keyout <yourdomain>.key -out <yourdomain>.csr
```
Download the certificates from the certificate authority (CA).

Check your X.509 certificates:

Check certificate

openssl x509 -in <yourdomain>.crt -text -noout

Generate a PKCS12 file:
Generate PKCS12 file
```
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.

Obfuscate the password.

Obfuscate password

[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 for keypwd, needs to be provided later as jetty.keymanager.password in Jetty's start.ini file.

Generate a keystore

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

Check the default keystore:

Check keystore

[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

Back up the default keystore file:
Backup keystore
```
mv etc/keystore etc/keystore.original
```
Create a new Java KeyStore (JKS) file using the datameer.p12 file that was generated previously. The keystore needs to be protected by a password.
Create keystore
```
keytool -importkeystore -srckeystore datameer.p12 -srcstoretype PKCS12 -destkeystore etc/keystore 
```
For the keystore password you can use storepwd.

Obfuscate the password:

Obfuscate password

[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 for storepwd, needs to be provided later as jetty.keystore.password in Jetty's start.ini file.

Check the generated repository:

Check keystore

[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.

Check the current configuration:

Check current config

# The path to the keystore file 
[datameer@<host> current]$ java -jar start.jar --list-config | grep -i 'store ='
 jetty.keystore = etc/keystore
 jetty.truststore = etc/keystore
# The necessary passwords 
[datameer@<host> current]$ java -jar start.jar --list-config | grep -i 'password'
 jetty.keymanager.password = OBF:1u2u1wml1z7s1z7a1wnl1u2g
 jetty.keystore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
 jetty.truststore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4

Back up the default configuration:
Backup config
```
cp start.ini start.ini.original 
```

Configure start.ini:

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

Configure start.ini

## Set up a demonstration keystore and truststore
jetty.keystore=etc/keystore
jetty.truststore=etc/keystore

## Set the demonstration passwords
## Note that OBF passwords are not secure, just protected from casual observation
## See http://www.eclipse.org/jetty/documentation/current/configuring-security-secure-passwords.html
jetty.keystore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4   # storepwd
jetty.keymanager.password=OBF:1u2u1wml1z7s1z7a1wnl1u2g         # keypwd
jetty.truststore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4 # storepwd

Create a configuration change log:

Create changelog

diff -e start.ini.original start.ini > changes.start.ini

Restart Datameer X to make the change active and monitor the boot process:
Start and monitor
```
dmstart
dmlog
```

Renew certificate

Certificates typically have an expiration date, so it is necessary to renew them. To do, so just follow the following steps again:

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 need to trust the certificate by adding it into the truststore of the Java Virtual Machine (JVM) that runs Datameer.

Gather the certificate:

Gather certificate

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

openssl x509 -in <yourservice>.pem -inform pem -noout -text

Trust the certificate by importing it:

Import certificate

sudo keytool -keystore ${JAVA_HOME}/jre/lib/security/cacerts -storepass changeit -import -trustcacerts -v -alias <yourservice> -file <yourservice>.pem

Start and stop Datameer X service:

Start and stop

dmstop
# This will create a new instance of the JVM 
dmstart
dmlog

Further Information

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

The JDK ships with a limited number of trusted root certificates in the <java-home>/lib/security/cacerts file. As documented in keytool , it is your responsibility to maintain (that is, add/remove) the certificates contained in this file if you use this file as a truststore.

You can also review available documentation from Hadoop distributors, such as Creating Java Keystores and Truststores, Understanding the SSL Keystore Factory, and Demystify LDAP, SSL, CA Cert integration. If you want to connect to an specific service, see vendor documentation such as Configure External SSL for Tableau.

Browser not supported