Introduction
Fredhopper uses certificates from the Certificate Authority Let's Encrypt for all its secure API endpoints.
LE certificates are valid for 90 days. Fredhopper requests new certificates when they are valid for 30 days or fewer, and applies them on API endpoints immediately. This means that during normal operations, certificates are refreshed around every 60 days.
This mechanism is entirely automatic and transparent to Fredhopper's infrastructure/operations engineers.
Under normal circumstances, this also does not require any action from Fredhopper customers.
Certificate validation
The certificate validation is commonly executed as follows:
During the SSL handshake, our secured API endpoint offers the site certificate and intermediary certificate. The client verifies the site certificate and intermediary certificate against its root certificates.
The client's root certificates are bundled with the OS, middleware, or application.
Recommendations to customers/integrators
Some applications use the central OS's certificate store, others have their own.
Import the Let's Encrypt root certificates "ISRG Root X1" (RSA) and "ISRG Root X2" (ECDSA) in your OS or middleware certificate store, if they are not already present there. Ensure the import is persisted across your server/middleware restarts.
Let's Encrypt's newer roots "ISRG Root YR" (RSA) and "ISRG Root YE" (ECDSA), introduced with the 2026 "Generation Y" hierarchy, are cross-signed by ISRG Root X1/X2 - so trusting X1 and X2 keeps current and future chains valid. Adding YR/YE as well future-proofs once they are widely distributed in trust stores.
This will ensure current and future certificate chains are valid. See the current Let's Encrypt hierarchy:
Specific trust validation
When not trusting the mentioned root certificates, but instead trusting a specific intermediary certificate or even site certificate, the SSL integration can break at any time.
In the case of trusting only a specific site certificate:
- When Fredhopper refreshes the site certificate every 60 days under normal circumstance, this requires a new import of the site certificate on the client's side.
- When Fredhopper refreshes the site certificate for technical reasons or emergencies, and this could theoretically occur at any time, this requires a new import of the qtsite certificate on the client's side.
In the case of trusting only a specific intermediary certificate:
When Let's Encrypt changes to a different intermediary certificate, this requires importing the new intermediary certificate on the client's side.
Note: For Let's Encrypt to change to a different intermediary certificate is not uncommon and has happened repeatedly. Most recently from R3 to YR1 during the 2026 "Generation Y" roll out.
Fredhopper serves the chain leaf → YR1 → ISRG Root YR (cross-signed) → ISRG Root X1, which terminates at ISRG Root X1. If this chain changes because Let's Encrypt rotates intermediates/roots, or we migrate explicitly, clients pinning a specific intermediary must import the new one. Trusting the ISRG roots above avoids this.
Warning: It is not always possible for Fredhopper to notify customers of any changes in the certificate chain. We know when certificates will expire, but they may be retired before that date, or at any time due to emergencies.
Real-world example under normal circumstances
When connecting to <customer>-query-live1.fas.global.fredhopperservices.com, we see the site certificate "CN = global.fredhopperservices.com", the intermediary "YR1", and the cross-signed "ISRG Root YR" — terminating at the trusted root "ISRG Root X1":
$ openssl s_client -connect <customer>-query-live1.fas.global.fredhopperservices.com:443 \
-servername <customer>-query-live1.fas.global.fredhopperservices.com
...
Certificate chain
0 s:CN = global.fredhopperservices.com
i:C = US, O = Let's Encrypt, CN = YR1
1 s:C = US, O = Let's Encrypt, CN = YR1
i:C = US, O = ISRG, CN = Root YR
2 s:C = US, O = ISRG, CN = Root YR
i:C = US, O = Internet Security Research Group, CN = ISRG Root X1
...
SSL certificate verify ok.
Verify return code: 0 (ok)
A client that trusts ISRG Root X1 validates this chain successfully. ISRG Root YR is included in the served chain in cross-signed form (issued by ISRG Root X1), so clients that do not yet have ISRG Root YR in their trust store still validate via X1.
Comments
0 comments
Please sign in to leave a comment.