Mister PKI

SSL Certificates * SSL Tools * Certificate Decoder

by Leave a Comment

OpenSSL rehash: Create a Hashed CA Certificate Directory

Overview

Copying a trusted CA certificate into a directory does not always make that directory usable as an OpenSSL trust store.

Many OpenSSL-based applications do not scan every certificate file in a directory whenever they need to build a certificate chain. Instead, they calculate a hash from the issuer name they are looking for and search for a file or symbolic link with that hash in its filename.

The openssl rehash command prepares a certificate directory for that type of lookup.

It scans supported certificate and CRL files, calculates their subject or issuer-name hashes, and creates links with names such as:

8f2a7b3c.0
8f2a7b3c.1
6d41c539.r0

This guide uses a practical system-administration scenario:

A monitoring agent successfully verifies an internal server certificate when given a CA certificate with -CAfile, but fails with unable to get local issuer certificate when configured to use a custom certificate directory.

You will use openssl rehash to:

  1. create a dedicated CA trust directory;
  2. validate the CA certificates before installation;
  3. generate the required hash links;
  4. understand the generated filenames;
  5. verify a certificate with -CApath;
  6. add multiple issuers with the same subject hash;
  7. add a certificate revocation list;
  8. troubleshoot common rehash and trust-store errors.

What does openssl rehash do?

The basic command is:

openssl rehash /path/to/certificates

According to the official OpenSSL rehash documentation, the command scans a directory for files ending in:

.pem
.crt
.cer
.crl

For each valid certificate, it calculates a hash from the certificate subject name and creates a symbolic link in this form:

HHHHHHHH.D

The eight H characters are the hexadecimal subject hash. D is a decimal number beginning with 0.

For example:

3f2c9b7a.0 -> example-root-ca.crt

CRL links use a similar format with an r before the number:

3f2c9b7a.r0 -> example-root-ca.crl

On systems that do not support symbolic links, OpenSSL may create copies instead.

Why does OpenSSL use hashed certificate filenames?

Assume OpenSSL is validating a server certificate issued by:

CN=Example Issuing CA
O=Example Organization

OpenSSL needs to locate the issuer certificate in the trusted certificate directory.

Rather than opening every file and comparing every subject, it can:

  1. calculate the hash of the issuer name;
  2. search for files named with that hash;
  3. inspect the matching certificate candidates;
  4. continue building the certificate chain.

This makes certificate lookup more efficient and gives OpenSSL a predictable directory structure.

The OpenSSL verification options documentation describes -CApath as a directory containing trusted certificates whose filenames are based on their subject-name hashes.

OpenSSL version compatibility

This guide covers:

  • OpenSSL 3.0;
  • OpenSSL 3.1;
  • OpenSSL 3.2;
  • OpenSSL 3.3;
  • OpenSSL 3.4;
  • OpenSSL 3.5 LTS;
  • OpenSSL 4.0.

The main workflow is consistent:

openssl rehash /path/to/certificates

The common options are also available across OpenSSL 3.0, 3.5, and 4.0:

-help
-old
-compat
-n
-v
-provider
-provider-path
-propquery

OpenSSL 3.5 and OpenSSL 4.0 additionally document:

-provparam

The most important operational difference is:

The separate c_rehash script was removed in OpenSSL 4.0. Use openssl rehash for new scripts and procedures.

Older instructions may still use:

c_rehash /path/to/certificates

On OpenSSL 3.x, that may continue to work when the script is installed. For procedures intended to work across OpenSSL 3 and OpenSSL 4, use:

openssl rehash /path/to/certificates

Check your version:

openssl version

Display detailed installation information:

openssl version -a

Real-world troubleshooting scenario

Assume an organization operates an internal monitoring service using a certificate issued by a private certificate authority.

The relevant files are:

monitoring-server.crt
example-issuing-ca.crt
example-root-ca.crt

The server certificate verifies successfully when the root certificate is supplied directly:

openssl verify \
  -CAfile example-root-ca.crt \
  -untrusted example-issuing-ca.crt \
  monitoring-server.crt

Expected result:

monitoring-server.crt: OK

The administrator then creates a custom trust directory:

mkdir -p /opt/example-agent/trust
cp example-root-ca.crt /opt/example-agent/trust/

However, this command fails:

openssl verify \
  -CApath /opt/example-agent/trust \
  -untrusted example-issuing-ca.crt \
  monitoring-server.crt

Example error:

CN = monitoring.example.internal
error 20 at 0 depth lookup: unable to get local issuer certificate
error monitoring-server.crt: verification failed

The root certificate is present, but OpenSSL cannot locate it through its hashed directory lookup.

The solution is to rehash the directory.

Step 1: Create a dedicated trust directory

Create a directory for the application’s trusted CA certificates:

sudo mkdir -p /opt/example-agent/trust

Set appropriate ownership:

sudo chown root:root /opt/example-agent/trust

Set directory permissions:

sudo chmod 755 /opt/example-agent/trust

The certificates in this directory are public information, so they generally do not require private-key-style permissions. The directory should still be writable only by authorized administrators.

Do not place private keys in a CA trust directory.

A trust directory should normally contain only:

  • trusted root CA certificates;
  • trusted intermediate certificates when the application requires them;
  • CRLs when certificate revocation checking is configured.

Step 2: Inspect the CA certificate before trusting it

Before installing a CA certificate, confirm that it is the certificate you expect.

Display its subject, issuer, serial number, dates, and fingerprint:

openssl x509 \
  -in example-root-ca.crt \
  -noout \
  -subject \
  -issuer \
  -serial \
  -dates \
  -fingerprint \
  -sha256

A self-signed root CA normally has matching subject and issuer names.

Confirm that it is permitted to act as a CA:

openssl x509 \
  -in example-root-ca.crt \
  -noout \
  -ext basicConstraints \
  -ext keyUsage

Expected values normally include:

X509v3 Basic Constraints: critical
    CA:TRUE

And key usage similar to:

Certificate Sign, CRL Sign

Do not trust a certificate based only on its filename.

Verify the SHA-256 fingerprint through an independent approved source whenever possible.

For more certificate-inspection examples, see Understanding X.509 Certificates.

Step 3: Copy the trusted CA certificate

Copy the verified root CA certificate into the trust directory:

sudo cp example-root-ca.crt \
  /opt/example-agent/trust/

Confirm the file:

ls -l /opt/example-agent/trust/

At this stage, the directory may contain:

example-root-ca.crt

But it does not yet contain the subject-hash link OpenSSL expects.

Step 4: Calculate the certificate subject hash manually

Before running rehash, inspect the hash OpenSSL will use:

openssl x509 \
  -in example-root-ca.crt \
  -noout \
  -subject_hash

Example output:

3f2c9b7a

That means OpenSSL expects a link beginning with:

3f2c9b7a

The first certificate with that hash receives the suffix:

.0

The expected link will therefore be:

3f2c9b7a.0

You can also display the older pre-OpenSSL-1.0 hash:

openssl x509 \
  -in example-root-ca.crt \
  -noout \
  -subject_hash_old

The old hash is relevant only when maintaining compatibility with very old OpenSSL software.

Step 5: Run openssl rehash

Run:

sudo openssl rehash /opt/example-agent/trust

OpenSSL will scan the directory and create the required symbolic links.

List the result:

ls -la /opt/example-agent/trust/

Example:

3f2c9b7a.0 -> example-root-ca.crt
example-root-ca.crt

The link name does not represent a hash of the entire certificate file. It is derived from the certificate’s subject name.

This distinction matters because two different certificates can have the same subject hash.

Step 6: Run rehash in verbose mode

Use -v to see what OpenSSL removes and creates:

sudo openssl rehash \
  -v \
  /opt/example-agent/trust

Example output may resemble:

Doing /opt/example-agent/trust
link example-root-ca.crt -> 3f2c9b7a.0

Verbose mode is especially helpful in:

  • deployment scripts;
  • configuration-management runs;
  • container image builds;
  • troubleshooting sessions;
  • directories containing several CA certificates;
  • directories with stale links.

Step 7: Verify the certificate with -CApath

Retry the certificate verification:

openssl verify \
  -CApath /opt/example-agent/trust \
  -untrusted example-issuing-ca.crt \
  monitoring-server.crt

Expected output:

monitoring-server.crt: OK

The difference is that OpenSSL can now locate the trusted root certificate using the hash generated from the issuer name.

For a complete guide to certificate-chain validation, see OpenSSL Verify: Certificate, Chain, CRL, and Key Examples.

CAfile versus CApath

OpenSSL supports two common ways of supplying trusted certificates.

CAfile

A CA file contains one or more trusted certificates in a single PEM file:

openssl verify \
  -CAfile trusted-roots.pem \
  monitoring-server.crt

Use -CAfile when:

  • you have a small bundle;
  • an application expects one trust file;
  • you generate a combined CA bundle;
  • maintaining one file is simpler.

CApath

A CA path is a directory containing separate certificate files with hash-based links:

openssl verify \
  -CApath /opt/example-agent/trust \
  monitoring-server.crt

Use -CApath when:

  • certificates are maintained individually;
  • the application performs hashed-directory lookups;
  • CA certificates are added or removed independently;
  • the trust directory is managed through automation;
  • CRLs are stored alongside certificates.

The directory must be prepared with:

openssl rehash /opt/example-agent/trust

Simply placing certificates in the directory may not be sufficient.

Step 8: Add an intermediate certificate when required

A trust store normally contains trust anchors—usually root CA certificates.

Intermediate CA certificates are commonly supplied by the server or through an -untrusted chain file rather than automatically trusted as roots.

However, some application-specific trust directories may include intermediate certificates.

Copy the intermediate:

sudo cp example-issuing-ca.crt \
  /opt/example-agent/trust/

Rehash again:

sudo openssl rehash \
  -v \
  /opt/example-agent/trust

List the links:

find /opt/example-agent/trust \
  -maxdepth 1 \
  -type l \
  -printf '%f -> %l\n'

Be deliberate about which certificates are treated as trust anchors. Trusting an intermediate directly can alter how certificate paths are built and may expand trust beyond the intended design.

What happens when two certificates have the same subject hash?

Two CA certificates may contain the same subject distinguished name.

For example, a CA may renew its certificate while keeping the same name:

CN=Example Root CA
O=Example Organization

The certificates may differ in:

  • serial number;
  • validity dates;
  • public key;
  • signature;
  • extensions.

Because their subjects are the same, they may produce the same subject hash.

OpenSSL handles this by incrementing the numeric suffix:

3f2c9b7a.0
3f2c9b7a.1
3f2c9b7a.2

Example:

3f2c9b7a.0 -> example-root-ca-2022.crt
3f2c9b7a.1 -> example-root-ca-2026.crt

The suffix does not indicate trust priority or certificate quality. It only distinguishes multiple objects that share the same hash.

The official documentation notes that exact duplicates are detected by comparing full SHA-1 fingerprints and generate a warning.

That fingerprint is used for duplicate detection within the rehash process. It is separate from the subject-name hash used in the link filename.

Step 9: Detect duplicate certificates

Assume the same certificate was copied twice:

example-root-ca.crt
example-root-ca-copy.pem

Run:

sudo openssl rehash \
  -v \
  /opt/example-agent/trust

OpenSSL may report a duplicate warning and avoid creating another useful entry for the identical certificate.

Compare SHA-256 fingerprints manually:

openssl x509 \
  -in /opt/example-agent/trust/example-root-ca.crt \
  -noout \
  -fingerprint \
  -sha256

openssl x509 \
  -in /opt/example-agent/trust/example-root-ca-copy.pem \
  -noout \
  -fingerprint \
  -sha256

Remove unneeded duplicates:

sudo rm \
  /opt/example-agent/trust/example-root-ca-copy.pem

Then rebuild the links:

sudo openssl rehash \
  /opt/example-agent/trust

Step 10: Add a CRL to the hashed directory

openssl rehash can process certificate revocation lists as well as certificates.

Assume you have a PEM-formatted CRL:

example-issuing-ca.crl

Inspect it:

openssl crl \
  -in example-issuing-ca.crl \
  -noout \
  -issuer \
  -lastupdate \
  -nextupdate

Copy it into the trust directory:

sudo cp example-issuing-ca.crl \
  /opt/example-agent/trust/

Rehash the directory:

sudo openssl rehash \
  -v \
  /opt/example-agent/trust

A CRL link uses the issuer-name hash and an r suffix:

6d41c539.r0 -> example-issuing-ca.crl

The naming convention is:

HHHHHHHH.rD

The r distinguishes CRLs from certificate links.

Step 11: Verify a certificate using a hashed CRL directory

To require CRL checking, use:

openssl verify \
  -CApath /opt/example-agent/trust \
  -untrusted example-issuing-ca.crt \
  -crl_check \
  monitoring-server.crt

To check the entire constructed chain:

openssl verify \
  -CApath /opt/example-agent/trust \
  -untrusted example-issuing-ca.crt \
  -crl_check_all \
  monitoring-server.crt

CRL validation can fail when:

  • the required CRL is missing;
  • the CRL has expired;
  • the CRL was issued by a different CA;
  • the CRL is DER rather than PEM;
  • the CRL directory was not rehashed;
  • the certificate is listed as revoked.

Inspect CRL details with the official openssl crl command.

Convert a DER CRL before rehashing

A downloaded CRL may use binary DER encoding.

Convert it:

openssl crl \
  -inform DER \
  -in example-issuing-ca.der.crl \
  -outform PEM \
  -out example-issuing-ca.crl

Inspect it:

openssl crl \
  -in example-issuing-ca.crl \
  -noout \
  -issuer \
  -lastupdate \
  -nextupdate

Then copy and rehash:

sudo cp example-issuing-ca.crl \
  /opt/example-agent/trust/
sudo openssl rehash \
  /opt/example-agent/trust

What files does openssl rehash process?

The command scans files with these extensions:

.pem
.crt
.cer
.crl

A valid certificate named with another extension may be ignored.

For example:

example-root-ca.cert
example-root-ca.txt
example-root-ca.backup

Rename the certificate to a supported extension:

mv example-root-ca.cert example-root-ca.crt

Then run:

openssl rehash /path/to/trust

The extension is not enough by itself. The file must also parse as a certificate or CRL.

One certificate or CRL per file

Each scanned file should contain one certificate or one CRL.

Do not use a multi-certificate bundle such as:

-----BEGIN CERTIFICATE-----
Root certificate
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Intermediate certificate
-----END CERTIFICATE-----

The official documentation warns when more than one certificate or CRL object is found in a scanned file.

Split a bundle into individual files before rehashing.

For example:

root-ca.crt
issuing-ca.crt

A CAfile bundle may contain multiple certificates, but a hashed CApath directory should use individual files.

How openssl rehash handles existing links

By default, openssl rehash removes existing links whose names match the hash-link pattern before creating new ones.

That pattern looks like:

HHHHHHHH.D
HHHHHHHH.rD

This means you should not use hash-shaped filenames in the trust directory for unrelated purposes.

Run:

openssl rehash /path/to/trust

only against a directory intended for CA certificates and CRLs.

Do not point it at:

  • an arbitrary application directory;
  • a home directory;
  • a general backup directory;
  • a directory containing unrelated hash-named files;
  • a source-code repository.

Preserve existing links with -n

Use -n to prevent removal of existing hash links:

openssl rehash \
  -n \
  /opt/example-agent/trust

This is primarily useful when maintaining both new-style and old-style hashes.

However, -n can preserve stale links. For routine modern trust-store maintenance, rebuilding the generated links is usually clearer:

openssl rehash /opt/example-agent/trust

Treat the original certificate and CRL files as the source of truth. Treat hash links as generated data.

Old-style hashes with -old

Very old OpenSSL releases used an MD5-based subject-name hash.

Generate old-style links with:

openssl rehash \
  -old \
  /opt/example-agent/trust

Current OpenSSL releases do not use the old-style hash for normal lookups.

This option exists for compatibility with software based on OpenSSL versions before 1.0.0.

Because this MisterPKI series covers OpenSSL 3.0 and later, most readers should not need -old.

Do not enable legacy compatibility without a documented requirement.

Generate both hash styles with -compat

Generate both modern and old-style links:

openssl rehash \
  -compat \
  /opt/example-agent/trust

This can produce two sets of links for the same certificate.

Use it only when the same certificate directory must serve:

  • a modern OpenSSL application; and
  • a legacy application requiring pre-1.0.0 hashes.

A better long-term solution is usually to upgrade or isolate the legacy application.

openssl rehash versus c_rehash

Older documentation frequently shows:

c_rehash /etc/ssl/certs

Modern documentation should use:

openssl rehash /etc/ssl/certs

OpenSSL 3.x

OpenSSL 3.x may provide both:

openssl rehash
c_rehash

The c_rehash command is an external script that invokes OpenSSL to calculate certificate and CRL hashes.

OpenSSL 4.0

The separate c_rehash script was removed in OpenSSL 4.0.

Use:

openssl rehash

This is the preferred form for scripts intended to work across OpenSSL 3.0, OpenSSL 3.5 LTS, and OpenSSL 4.0.

Provider options

OpenSSL 3 uses the provider architecture.

The rehash command supports provider-related options such as:

-provider
-provider-path
-propquery

OpenSSL 3.5 and OpenSSL 4.0 also document:

-provparam

A typical custom-provider invocation might resemble:

openssl rehash \
  -provider-path /opt/openssl/providers \
  -provider default \
  /opt/example-agent/trust

Most administrators using standard X.509 certificates do not need to specify provider options.

Use provider arguments only when:

  • OpenSSL is installed in a nonstandard location;
  • a custom provider supplies required algorithms;
  • a restricted property query is configured;
  • the normal provider configuration does not load correctly.

For ordinary RSA and elliptic-curve CA certificates, the default provider is generally sufficient.

Process multiple directories

You can pass multiple directories:

openssl rehash \
  /opt/application-one/trust \
  /opt/application-two/trust

Each directory is processed in turn.

This can be useful in deployment scripts where several applications maintain separate trust stores.

Example shell loop:

for trust_dir in \
  /opt/application-one/trust \
  /opt/application-two/trust
do
  openssl rehash -v "$trust_dir"
done

Quote directory variables to handle spaces safely.

Use SSL_CERT_DIR

When no directory is supplied, OpenSSL checks the SSL_CERT_DIR environment variable.

On Unix-like systems, separate multiple directories with colons:

export SSL_CERT_DIR="/opt/application-one/trust:/opt/application-two/trust"

Then run:

openssl rehash

On Windows, directory entries are separated with semicolons.

A directory supplied directly on the command line takes precedence over SSL_CERT_DIR.

For predictable automation, explicitly specifying the target directory is often clearer:

openssl rehash /opt/example-agent/trust

Find OpenSSL’s default certificate directory

Display OpenSSL’s compiled certificate directory:

openssl version -d

For additional built-in paths, use:

openssl info -configdir

You can also inspect environment variables:

env | grep -E '^SSL_CERT_(DIR|FILE)='

The default location varies by:

  • operating system;
  • Linux distribution;
  • OpenSSL build;
  • package maintainer;
  • application configuration.

Do not assume every system uses:

/etc/ssl/certs

or:

/usr/local/ssl/certs

Verify the application’s actual trust-store configuration.

Linux distribution trust-store tools

openssl rehash is useful for custom application directories, test environments, and manually managed trust stores.

For the operating system’s main trust store, use the distribution-supported mechanism whenever possible.

Examples include tools such as:

update-ca-certificates
update-ca-trust

Those tools may:

  • copy certificates into managed locations;
  • update combined CA bundles;
  • rebuild hashed links;
  • apply distribution policies;
  • trigger related system updates.

Do not replace the distribution trust-management workflow with a manual openssl rehash command unless you understand how that distribution manages certificates.

A common pattern is:

  • use the OS tool for system-wide trust;
  • use openssl rehash for a private application-specific CApath.

Windows considerations

Native Windows does not normally use an OpenSSL-style hashed CA directory as its primary operating-system certificate store.

Windows applications may use:

  • the Windows Certificate Store;
  • an application-specific PEM bundle;
  • a Java keystore;
  • a custom OpenSSL CApath;
  • certificates bundled with the application;
  • a WSL Linux trust store.

When an OpenSSL-based Windows application expects a CApath, openssl rehash can prepare the directory.

Example PowerShell command:

openssl rehash C:\ExampleAgent\trust

On platforms without symbolic-link support or permissions, OpenSSL may create copies.

Confirm the result:

Get-ChildItem C:\ExampleAgent\trust

OpenSSL 3.x documentation specifies semicolon-separated paths for Windows when using SSL_CERT_DIR.

For native Windows applications that use the Windows Certificate Store, adding hashed PEM links will not affect system trust. Follow the application’s documentation to determine which trust mechanism it uses.

Automate rehash after certificate changes

Run openssl rehash whenever a certificate or CRL is:

  • added;
  • replaced;
  • renewed;
  • removed;
  • renamed;
  • converted;
  • updated.

Example deployment script:

#!/usr/bin/env bash
set -euo pipefail
trust_dir="/opt/example-agent/trust"
source_cert="/srv/pki/example-root-ca.crt"
target_cert="$trust_dir/example-root-ca.crt"
install \
  -o root \
  -g root \
  -m 0644 \
  "$source_cert" \
  "$target_cert"
openssl rehash -v "$trust_dir"
openssl verify \
  -CApath "$trust_dir" \
  "$target_cert"

In a real deployment, verify a representative leaf certificate rather than only verifying the root against itself.

Automation should fail when rehashing or validation fails. Do not ignore command exit codes.

For broader lifecycle automation guidance, see Automate Certificate Renewal.

Verify the generated links in automation

Check for broken symbolic links:

find /opt/example-agent/trust \
  -xtype l \
  -print

No output means no broken links were found.

List generated links:

find /opt/example-agent/trust \
  -maxdepth 1 \
  -type l \
  -printf '%f -> %l\n' \
  | sort

Count certificates:

find /opt/example-agent/trust \
  -maxdepth 1 \
  -type f \
  \( -name '*.pem' -o -name '*.crt' -o -name '*.cer' \) \
  | wc -l

Count certificate hash links:

find /opt/example-agent/trust \
  -maxdepth 1 \
  -type l \
  -regextype posix-extended \
  -regex '.*/[0-9a-fA-F]{8}\.[0-9]+' \
  | wc -l

Hash-link counts do not always equal certificate counts because:

  • duplicates may be skipped;
  • certificates may share a hash;
  • invalid files may be ignored;
  • one certificate may receive multiple compatibility links.

Common openssl rehash errors

Unable to write to the directory

Example symptoms include permission-denied errors or failure to create links.

Check permissions:

ls -ld /opt/example-agent/trust

Run with appropriate administrative privileges:

sudo openssl rehash /opt/example-agent/trust

Do not make the trust directory world-writable.

Skipping file because it cannot be parsed

Confirm the object type:

openssl x509 \
  -in suspect-file.crt \
  -noout \
  -subject

For a CRL:

openssl crl \
  -in suspect-file.crl \
  -noout \
  -issuer

Possible causes include:

  • DER data being treated as PEM;
  • a private key stored with a .pem extension;
  • a CSR stored with a .crt extension;
  • corrupted Base64;
  • multiple objects in one file;
  • unrelated text inside the file.

No hash link is created

Check the filename extension:

ls -l /opt/example-agent/trust

Supported extensions include:

.pem
.crt
.cer
.crl

Then verify the file parses:

openssl x509 \
  -in /opt/example-agent/trust/example-root-ca.crt \
  -noout \
  -subject_hash

Run verbose mode:

openssl rehash \
  -v \
  /opt/example-agent/trust

More than one certificate found in the file

Split the bundle into individual certificate files.

A hashed directory expects one certificate or CRL per scanned file.

Use a combined bundle with -CAfile, not as a single file in -CApath.

Warning about a duplicate certificate

Compare fingerprints:

openssl x509 \
  -in first.crt \
  -noout \
  -fingerprint \
  -sha256

openssl x509 \
  -in second.crt \
  -noout \
  -fingerprint \
  -sha256

Delete the redundant copy if the certificates are identical.

unable to get local issuer certificate

This error may mean:

  • the CA certificate is missing;
  • the directory was not rehashed;
  • the required intermediate was not supplied;
  • the wrong CA directory was configured;
  • the certificate subject or issuer differs from what was expected;
  • the application is not using the configured CApath;
  • file permissions prevent access;
  • the certificate chain is incomplete.

Test directly:

openssl verify \
  -show_chain \
  -CApath /opt/example-agent/trust \
  -untrusted example-issuing-ca.crt \
  monitoring-server.crt

self-signed certificate in certificate chain

This usually indicates that OpenSSL encountered a self-signed certificate that is not trusted in the selected validation context.

Confirm that the intended root is in the directory:

openssl x509 \
  -in example-root-ca.crt \
  -noout \
  -subject \
  -issuer \
  -fingerprint \
  -sha256

Confirm its hash link:

hash_value="$(
  openssl x509 \
    -in example-root-ca.crt \
    -noout \
    -subject_hash
)"
ls -l "/opt/example-agent/trust/${hash_value}."*

The command works, but the application still fails

The application may:

  • use a different OpenSSL installation;
  • use a different certificate directory;
  • use a bundled CA file;
  • use Java or Windows trust instead of OpenSSL;
  • run in a container with another filesystem;
  • require a restart;
  • cache certificate data;
  • override SSL_CERT_DIR;
  • run under a user that cannot read the directory.

Inspect the process configuration and application logs. Confirm the exact OpenSSL library and trust-store path used by the application.

Security considerations

A hashed certificate directory is a trust store. Adding a CA certificate can cause applications to trust every certificate validly issued beneath that CA, subject to validation rules.

Before adding a CA:

  1. Confirm its SHA-256 fingerprint.
  2. Confirm the certificate source.
  3. Inspect basic constraints and key usage.
  4. Confirm its intended trust scope.
  5. Avoid trusting unnecessary intermediate certificates directly.
  6. Restrict write access to administrators.
  7. Remove obsolete and compromised CA certificates.
  8. Rehash after every change.
  9. Test chain building before restarting production services.
  10. Document why each private CA is trusted.

Do not add an unfamiliar root certificate merely to suppress a TLS error.

That may hide:

  • a server presenting the wrong chain;
  • a TLS interception device;
  • an unauthorized internal CA;
  • a misconfigured application;
  • a certificate issued from the wrong PKI;
  • a potential security incident.

Privacy considerations

Certificate files and command output may reveal:

  • internal domain names;
  • server hostnames;
  • organization names;
  • email addresses;
  • internal CA names;
  • certificate policy OIDs;
  • serial numbers;
  • private trust relationships;
  • filesystem layouts.

Use generic placeholders in screenshots, articles, support tickets, and public repositories.

Examples in this article use:

monitoring.example.internal
Example Root CA
Example Issuing CA
/opt/example-agent/trust

Never place private keys in the trust directory or include them in troubleshooting output.

Important openssl rehash options

OptionPurpose
-help, -hDisplays command help
-vDisplays links removed and created
-nPreserves existing hash links
-oldGenerates old MD5-style hashes
-compatGenerates old and modern hashes
-provider nameLoads a named provider
-provider-path pathSets the provider module path
-provparam key=valueSupplies a provider parameter in supported versions
-propquery queryApplies an algorithm property query

For normal OpenSSL 3 and 4 certificate directories, the most useful command is:

openssl rehash -v /path/to/trust

Frequently asked questions

What does openssl rehash do?

openssl rehash scans a certificate directory and creates hash-named symbolic links or copies for certificates and CRLs. OpenSSL-based applications can use those links to locate issuers efficiently.

When should I run openssl rehash?

Run it after adding, replacing, renewing, deleting, or renaming a certificate or CRL in an OpenSSL CApath directory.

What is the difference between openssl rehash and c_rehash?

openssl rehash is the OpenSSL command. c_rehash is an older external script with similar behavior. The separate c_rehash script was removed in OpenSSL 4.0, so new procedures should use openssl rehash.

Why does openssl rehash create a .0 file?

The .0 suffix identifies the first certificate with a particular subject hash. Additional certificates sharing the same hash receive .1, .2, and so on.

What does .r0 mean?

A filename ending in .r0 is the first CRL associated with a particular issuer-name hash.

Is the filename a hash of the certificate?

No. The link is based on the certificate subject name. OpenSSL uses that value to find potential issuer certificates.

Does openssl rehash copy certificates?

It normally creates symbolic links. On systems that do not support symbolic links, it may create copies.

Can I place a certificate bundle in a hashed directory?

You should use one certificate or CRL per file. A multi-certificate bundle may generate a warning. Use bundles with -CAfile.

Does openssl rehash install a certificate system-wide?

Not necessarily. It only prepares the directory you specify. Whether an application uses that directory depends on its configuration.

Does openssl rehash make an untrusted certificate trusted?

It makes a certificate discoverable in a CApath. Trust still depends on the application selecting that directory and treating its contents as trusted certificates.

Does openssl rehash work with OpenSSL 4.0?

Yes. Use openssl rehash. The separate c_rehash script was removed in OpenSSL 4.0.

Complete practical example

Create the trust directory:

sudo mkdir -p /opt/example-agent/trust
sudo chown root:root /opt/example-agent/trust
sudo chmod 755 /opt/example-agent/trust

Inspect the CA:

openssl x509 \
  -in example-root-ca.crt \
  -noout \
  -subject \
  -issuer \
  -dates \
  -fingerprint \
  -sha256

Install it:

sudo install \
  -o root \
  -g root \
  -m 0644 \
  example-root-ca.crt \
  /opt/example-agent/trust/example-root-ca.crt

Create the hash links:

sudo openssl rehash \
  -v \
  /opt/example-agent/trust

Review them:

find /opt/example-agent/trust \
  -maxdepth 1 \
  -type l \
  -printf '%f -> %l\n'

Verify the server certificate:

openssl verify \
  -show_chain \
  -CApath /opt/example-agent/trust \
  -untrusted example-issuing-ca.crt \
  monitoring-server.crt

Expected result:

monitoring-server.crt: OK

Related OpenSSL guides

External references

Conclusion

The openssl rehash command solves a specific but common certificate-trust problem: preparing a directory so OpenSSL can find CA certificates and CRLs by their hashed names.

The essential workflow is:

Inspect the CA certificate
Copy it into a controlled trust directory
Run openssl rehash
Confirm the generated links
Test the directory with openssl verify -CApath
Repeat after every certificate or CRL change

When -CAfile succeeds but -CApath fails, checking whether the certificate directory has been rehashed should be one of the first troubleshooting steps.

For modern environments, use:

openssl rehash /path/to/trust

rather than c_rehash. That command works across OpenSSL 3.0, OpenSSL 3.5 LTS, and OpenSSL 4.0 and avoids relying on the legacy script removed in OpenSSL 4.

Reader Interactions

Leave a Reply

Your email address will not be published. Required fields are marked *