SSL Certificate Handling for FME Transformers

Introduction

This document provides guidance on handling custom certificates for transformers in FME. It includes locations to place certificates, error messages to watch for, and detailed steps for managing certificates in both FME and FME Flow. 

FME Flow Components that rely on Certificates (SSL/TLS):

• FME Flow Core
  • FME Flow Database (JDBC)
  • Automations (Java)
  • Publishers and Subscribers (Java)
• FME Flow Application Server
  • HTTPS Configuration
• FME Flow Engines
  • Workspace Readers and Writers (JDBC, C++)
  • Workspace Transformers (Python, C++)
  • Startup/Shutdown Scripts and Scripted Published Parameters (Python)

Common Error Messages

When certificates are missing or improperly configured, you may encounter the following error messages in FME job log files:

For Java JDBC transformers:

java.sql.SQLException: No suitable driver found

    javax.net.ssl.SSLHandshakeException: unable to find valid certification path to requested target

For Python-based transformers or formats:

requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

For Kafka or non-HTTPS protocols:

SSL error: handshake failure

These errors indicate that FME cannot locate the appropriate certificate for secure communication.

Locations Where FME Looks for Certificates

1. Java Certificates and JDBC Transformers:

For Java-based JDBC transformers, certificates must be placed in the following directory:

Windows FME Flow Engines: (Readers, Writers, and Transformers)

C:\Program Files\FMEFlow\Server\fme\jre\lib\security\cacerts

Windows FME Flow Core (Automations, Notifications and FME Flow Database) 

C:\Program Files\FMEFlow\Utilities\jre\lib\security\cacerts

Linux Engines: Use the system Java Truststore, such as:

• PEM bundle:

  /etc/ssl/certs/ca-certificates.crt

• OpenSSL-compatible directory:

  /etc/ssl/certs

  Certificates can be installed using the update-ca-certificates command.

Linux Core: Certificates for the backend database should be added to:

/opt/fmeflow/Utilities/jre/lib/security/cacerts

2. Python Certificates and Certificate Stores:

Python-based transformers and formats in FME generally use the operating system's certificate store. However, there are exceptions:

• MacOS: Python relies on a custom certificate store.
• Non-HTTPS protocols (e.g., Kafka using a TCP variant): The certificate store depends on the protocol's implementation.
• Library-level HTTPS communication: The certificate store used is determined by the library's implementation.

C:\Program Files\FME\python\certifi\cacert.pem  

C:\Program Files\FMEFlow\Server\fme\python\certifi\cacert.pem

Custom Python code, such as PythonCaller and PythonCreator, typically uses certifi's cacert.pem. Certifi is a Python certificate module included with FME, which can be manually updated to address expired certificates or compatibility issues.

Most Python-based transformers default to the system trust store. However, specific transformers, such as WebSocketConnector, use certifi's cacert.pem. For TLS connections, certificates can also sometimes be provided directly within the Python code.

Steps to Upload and Configure Certificates

Importing Certificates into Certifi’s cacert.pem

If your environment is affected by the certifi regression or requires manual updates, follow these steps:

1. Back Up the cacert.pem File

• FME Form:

C:\Program Files\FME\python\certifi\cacert.pem

• FME Flow:

C:\Program Files\FMEFlow\Server\fme\python\certifi\cacert.pem

2. Examine the Certificate with KeyStoreExplorer

• Open the certificate (e.g., .crt file) in KeyStoreExplorer or a similar tool.
• Review the certificate chain, including Root, Intermediate, and Top-Level certificates.

3. Open the cacert.pem File

• Use a text editor with admin privileges (e.g., Notepad++).
• Locate the certificates in the file, structured as:

# Certificate Info

-----BEGIN CERTIFICATE-----

[Certificate Data]

-----END CERTIFICATE-----

• Copy an existing certificate block and replace its values with the details from KeyStoreExplorer.

4. Repeat for Additional Certificates

Repeat the process for each certificate in the chain that needs to be added.

Importing Certificates into a Windows Trust Store 

1. Obtain the Certificate

2. Launch MMC (mmc.exe).

• If you are using FME Flow with a service account, you will need to run MMC under that FME Flow service account. To do this, find mmc.exe in the File Explorer (default location: C:\Windows\System32\mmc.exe), then Shift + Right Click on the executable and select "Run as different user."
• If you are running FME Flow services under "Local System," right click on mmc.exe and select "Run as administrator."
• If prompted by User Account Control (UAC), select Yes to allow the MMC to make changes to your device.

3. Add the Certificates Snap-in

• Select File > Add/Remove Snap-ins.

4. Click Certificates, then click Add

5. Select My User Account.

• This step is unnecessary if you are running mmc.exe as administrator and FME Flow's services are run under "Local System"

6. Click Add again, and this time select Computer Account.

7. Move the new certificate from the Certificates-Current User > Trusted Root Certification Authorities into Certificates (Local Computer) > Trusted Root Certification Authorities.

Importing Certificates into Java Keystores for FME Flow

When using HTTPS in FME Flow, certificates must be imported into the appropriate Java keystore to ensure secure communication. Different components of FME Flow require certificate imports into different keystores. Below are the steps to import certificates correctly.

Importing Certificates for Automations, Database Connections, Publishers, Subscribers, and the FME Flow UI

1. Obtain the Certificate

Export the public certificate or obtain it from your IT team.

The certificate file is usually in .crt or .cer format.

2. Open the Command Prompt as Administrator

Press Win + R, type cmd, and press Ctrl + Shift + Enter to open as administrator.

3. Navigate to the Keytool Directory.

cd <FMEFlow>\Utilities\jre\bin

4. Run the Keytool Import Command

Update the command below with the correct certificate path and alias:

keytool -import -trustcacerts -keystore "<FMEFlow>\Utilities\jre\lib\security\cacerts" -storepass changeit -noprompt -alias mycert -file "<certpath>\mycert.crt"

Replace <certpath>\mycert.crt with the actual path to your certificate file.

Importing Certificates for Transformers and Readers/Writers in Workspaces

These components use the FME Engine's Java keystore, which is separate from the one used by the Flow UI and Automations.

1. Obtain the Certificate

As with the previous step, get the required .crt or .cer file from the source system or your IT team.

2. Open the Command Prompt as Administrator

Follow the same steps to open Command Prompt.

3. Navigate to the Keytool Directory

cd <FMEFlow>\Server\fme\jre\lib\

4. Run the Keytool Import Command

Modify and run the following command:

keytool -import -trustcacerts -keystore "<FMEFlow>\Server\fme\jre\lib\security" -storepass changeit -noprompt -alias mycert -file "<certpath>\mycert.crt"

To confirm that the certificate has been successfully imported, run:

keytool -list -keystore "<keystorepath>"

• Replace <keystore-path> with the relevant keystore location.
• If successful, the certificate alias should be listed.

Restart FME Flow services after importing certificates.

Additional Notes

• For Python-based transformers on Windows, certificates should ideally align with the Windows Trusted Root Certification Authorities store.
• If you encounter regressions or library-specific exceptions, ensure you’re using the correct version of FME and follow these steps to import certificates into the appropriate store.