Secure Connections for Java-based ybtools ​

Connections to the following Java-based client tools support and require Secure Sockets Layer (SSL) and Transport Layer Security (TLS) encryption:

• ybload
• ybunload
• ybbackup, ybrestore
• ybrelay: for details, see Setting Up the ybrelay Service

Note: ybsql also supports and requires SSL/TLS but uses some different command-line options. See ybsql Connections.

Java-based clients provide the following security options:

• --secured: require SSL, which has the default SSLMODE of require root CA verification. When --secured is set, SSL/TLS encryption is used to secure all communication. If this option is not set, secure connections are attempted anyway.
• --cacert: supply a custom root CA bundle for trusting the cert installed under Yellowbrick. Note that this is not a server cert to be used in two-way trust.
• --disable-trust: do not require root cert verification. --disable-trust is significant because it turns off the SSL/TLS root CA certification, not SSL/TLS. The bulk data tools require root CA certification by default. However, ybsql and many client tools do not require root CA certification.

See Opening Network Ports for Clients for a list of the port numbers that the client tools use for data control and data transfer.

When you are making a secure connection with Java-based ybtools:

• Keep in mind that all connections to data warehouse instances must be secure SSL connections.
• By default, secure connections require trust verification. To disable trust verification, use the --disable-trust option within each Java-based tool.
• Because the Java-based tools use the Java certificate keystore, you will typically need to have a root cert bundle file only for intermediary certificates issued by your organization.
• If you do need certificates included in a custom root cert file, the order of precedence for the file to use is the option --cacert, the environment variable YBCACERT (recognized only by the Java tools), then the environment variables YBSSLROOTCERT and PGSSLROOTCERT.
• The --cacert option has an alternative syntax for the Java keystore format file that is not found in the drivers or ybsql. For Java keystore files for certificates, use --cacert yellowbrick.jks:mypassword, where the : character separates the file name from the password of the keystore.
• If you are using a Java application/JDBC driver, you can update the Java SSL trust keystore to avoid providing a root cert bundle, but this approach is not generally recommended.

Summary of Options for Java-based ybtools ​

To connect securely to an instance with ybload or other Java-based client tools, you use the --secured connection option. By default, loads are "promoted" to secure SSL connections even if --secured is not specified, and an SSL connection is always attempted. You will see this message:

14:25:12.107 [ INFO] Connection to **************.yellowbrickcloud.com cannot be made without SSL/TLS; attempting upgrade to secured mode

Explicit SSL connections take one of the following options (or combinations of options) in the command:

• --secured for encryption without explicit trust verification
• --secured and --disable-trust (or -k) for encryption without trust verification
• --secured and --cacert for encryption and explicit trust verification

For example, the syntax in all of the following commands is valid:

ybload -t premdb.match --format --secured csv /mydata/premdb/match.csv
ybload -t premdb.match --format --secured --disable-trust csv /mydata/premdb/match.csv
ybload -t premdb.match --format --secured --cacert /mydata/ybcloud.pem csv /mydata/premdb/match.csv

Note that the --cacert option requires the path to a local .pem file that contains the trusted certificate. If necessary, you can use an openssl command to import the certificate and save it to a file.