Certificate Management

Fabric uses TLS certificates both to identify itself to clients and to establish trust when connecting to external services. Understanding the connection direction matters because Fabric's certificate requirements and the certificate store it uses differ in each case.

This article introduces Fabric certificate management, explains the difference between the keystore and truststore, and directs you to the appropriate procedure for each certificate use case.

Table of Contents

• Certificate Usage in Fabric
• Inbound TLS - Fabric Identity
• Outbound TLS - Trusting External Services
• Keystore and Truststore
• Fabric Certificate Management Scripts
  • certificates.sh
  • get-certificate.sh
  • get_interface_certs.sh
• Choosing the Appropriate Procedure
• Deployment Considerations

Certificate Usage in Fabric

TLS certificates are used differently depending on whether Fabric receives a secure connection or initiates one.

A useful way to distinguish the two is:

• Keystore - "Who am I?" - Contains Fabric's certificate and private key used to establish Fabric's identity.
• Truststore - "Who do I trust?" - Contains certificates or Certificate Authority (CA) certificates that Fabric trusts when establishing TLS connections to external systems.

Inbound TLS - Fabric Identity

When a browser, application, JDBC client, or other client establishes a secure connection to Fabric, Fabric acts as the TLS server.

Fabric presents a TLS certificate to the connecting client. Fabric maintains the corresponding certificate and private key in the Fabric keystore.

A Fabric TLS identity can be configured using:

• an existing certificate and private key issued by your organization's Certificate Authority (CA) or another trusted CA; or
• a self-signed certificate, typically for development, testing, or isolated environments.

Fabric provides the certificates.sh utility for common keystore operations, including importing certificate material and generating a self-signed keypair.

For instructions on configuring Fabric's TLS identity, see Fabric TLS Identity.

For development, testing, or isolated environments where a self-signed certificate is appropriate, see Generating a Self-Signed Certificate in Fabric.

After you configure Fabric's TLS identity, you can configure services such as the Fabric API and Web UI to use it. See Fabric API, UI, and JDBC Hardening.

Outbound TLS - Trusting External Services

Fabric can also act as a TLS client when connecting to an external service.

Examples include connections to:

• external Key Management Systems (KMS);
• databases;
• APIs and web services;
• identity and authentication services;
• messaging services; and
• other TLS-enabled external endpoints.

During the TLS handshake, the external service presents its certificate. Fabric's Java runtime must be able to establish a trusted certification path for that certificate.

Certificates issued by a CA already trusted by the Java runtime normally require no additional configuration.

If the external service uses a private CA, a self-signed certificate, or another certificate that is not already trusted, you must add the required certificate or CA certificate to the Fabric truststore.

A missing trust relationship can result in TLS handshake errors such as:

javax.net.ssl.SSLHandshakeException:
PKIX path building failed

Fabric provides several utilities for establishing trust with external services:

• certificates.sh addtrust - imports an existing certificate into the Fabric truststore.
• get-certificate.sh - connects to a TLS endpoint, retrieves its certificate, and adds it to the Fabric truststore.
• get_interface_certs.sh - performs certificate retrieval and trust configuration for multiple external endpoints.

For instructions, see Trusting External TLS Services.

Keystore and Truststore

Although both stores contain certificate-related information, they serve different purposes.

Importing a certificate into the Fabric keystore does not make that certificate trusted for outbound TLS connections. Likewise, adding an external certificate to the truststore does not configure Fabric to use that certificate as its own TLS identity.

Fabric Certificate Management Scripts

Fabric includes three scripts for common certificate-management operations.

certificates.sh

Location:

${FABRIC_HOME}/fabric/scripts/certificates.sh

certificates.sh is the core Fabric certificate-management utility. It supports operations against both the Fabric keystore and truststore.

Supported commands are:

certificates.sh addkey <ALIAS> <PATH> [PASSWORD]
certificates.sh addtrust <ALIAS> <PATH> [PASSWORD]
certificates.sh genkey <ALIAS> [CNAME] [PASSWORD]

Fabric TLS Identity, Trusting External TLS Services, and Generating a Self-Signed Certificate in Fabric cover the detailed use of these commands.

get-certificate.sh

Location:

${FABRIC_HOME}/fabric/scripts/get-certificate.sh

Use get-certificate.sh when Fabric must trust a certificate presented by an external TLS endpoint.

The script:

1. connects to the specified endpoint;
2. retrieves the certificate presented by the endpoint;
3. saves the retrieved certificate temporarily, unless a certificate output path is specified;
4. invokes certificates.sh addtrust to add the certificate to the Fabric truststore; and
5. removes the temporary certificate after the import completes.

The syntax is:

get-certificate.sh <IP:PORT> <ALIAS> [PASSWORD] [CERT_PATH]

This script is useful when the certificate is available directly from the target TLS service and needs to be added to Fabric's truststore.

See Trusting External TLS Services for the complete procedure.

get_interface_certs.sh

Location:

${FABRIC_HOME}/scripts/get_interface_certs.sh

get_interface_certs.sh is a convenience utility for retrieving and trusting certificates from multiple external endpoints.

The script accepts either:

• a file containing endpoints, one endpoint per line; or
• a comma-separated list of endpoints.

It invokes get-certificate.sh for each endpoint and imports the retrieved certificates into the Fabric truststore.

The syntax is:

get_interface_certs.sh <interfaces> [truststore_path]

This utility is useful when Fabric connects to multiple TLS-enabled external interfaces whose certificates must be trusted.

See Trusting External TLS Services for detailed usage.

Choosing the Appropriate Procedure

Use the TLS connection's direction and purpose to determine which certificate procedure applies.

Deployment Considerations

Apply certificate and truststore configuration consistently to the Fabric instances that require it.

For traditional Linux installations, the keystore or truststore is maintained on the filesystem used by the Fabric installation. In multi-node deployments, ensure that the required certificate configuration is available to all applicable Fabric nodes.

For containerized deployments, including Kubernetes deployments, certificate changes made interactively inside a running container might not persist when the container or pod is replaced or recreated. Therefore, incorporate certificate, keystore, and truststore configuration into the deployment's persistent configuration when you need persistence across container recreation.

For the configuration appropriate to each certificate use case, see:

• Fabric TLS Identity
• Trusting External TLS Services
• Generating a Self-Signed Certificate in Fabric
• Fabric API, UI, and JDBC Hardening