|
| 1 | +--- |
| 2 | +id: kb-202601-letsencrypt |
| 3 | +title: Let's Encrypt YE/YR Roots on Windows |
| 4 | +--- |
| 5 | + |
| 6 | +# Summary |
| 7 | + |
| 8 | +**From January 7th 2026 let's Encrypt have started to issue from a new hierarchy with root certificates Root YE (ECDSA chains) and Root YR (RSA chains).** This may affect compatibility with some "clients" (browsers and other software connecting to your services) if their trust store does not have these new roots. |
| 9 | + |
| 10 | +Certificate trust mainly relies on the "root" issuing certificate (and intermediate certificates issued via that root) being trusted by your computer. |
| 11 | + |
| 12 | +This is called a "Chain" of trust. Your certificate (called a Leaf or end-entity certificate) will be validated by following this chain or using OS/app-specific chain building logic. |
| 13 | + |
| 14 | +The [new YE/YR hierarchy](https://letsencrypt.org/certificates/) also includes a "cross-sign" to the already trusted ISRG Root X1/X3 roots. For most windows clients (browsers, .Net, PowerShell etc) this means the client will determine a trusted chain on it's own, even if it doesn't yet trust Root YR/Root YE. |
| 15 | + |
| 16 | +## The Problem |
| 17 | + |
| 18 | +If your server trusts the new Root YR and Root YR certificates for Let's Encrypt it will start to use them in the served chain with schannel enabled services like IIS. **The only way to control this is to not trust those roots on your server yet.** |
| 19 | + |
| 20 | +If your server trusts the new roots YE/YR *before your connected clients do* your server may present a chain that your clients don't yet trust. This may affect clients such as browsers, mobile devices, apps, tools etc. |
| 21 | + |
| 22 | +On Windows, the default TLS implementation schannel determines the most trusted path for a given certificate chain, regardless of what the initially intended/preferred chain should be. It then use this chain in the TLS conversation when presenting a TLS-enabled service to a client such as a browser. |
| 23 | + |
| 24 | +### Example Errors for affected clients |
| 25 | +Curl: `curl: (60) SSL certificate problem: unable to get local issuer certificate` |
| 26 | + |
| 27 | +## Possible Solutions |
| 28 | + |
| 29 | +:::warning if you need to support old devices or those not updated to new roots |
| 30 | + If you require legacy support without workarounds, you may prefer to temporarily change the [Certificate Authority](../guides/certificate-authorities.md) for your certificates. |
| 31 | +::: |
| 32 | + |
| 33 | +### Update clients to trust the new roots |
| 34 | + |
| 35 | +#### Manually Trust New Roots on Windows |
| 36 | +Download the root from the CA and import into the *Local Machine* certificate store under *Trusted Root Certification Authorities*, then reboot. |
| 37 | + |
| 38 | +The quick way to do this is to open the file with the default windows certificate view, choose *Install Certificate..*, then choose *Local Machine* > *Place all certificates in the following store..* > *Trusted Root Certification Authorities*. |
| 39 | + |
| 40 | +#### Linux, macOS, iOS etc |
| 41 | + |
| 42 | +Update the OS with the latest updates, for some tools you may need to update the individual tools if they have their own trust store (sometimes called a "ca bundle"). |
| 43 | + |
| 44 | +Some operating systems hold onto the chain even if your server is no longer using it. Try a restart of the affected client device. |
| 45 | + |
| 46 | +For older macOS not updated by Apple: |
| 47 | + |
| 48 | +- Download the Root YE/Root YR certificate files |
| 49 | +- Open the Keychain Access app and drag that file into the System folder of that app. |
| 50 | +- Find the certificate in System and double click on it, open the Trust menu and change "Use System Defaults" to "Always Trust", then close that and enter your password to confirm the change (if prompted). |
| 51 | + |
| 52 | +## Java based systems etc |
| 53 | +Some applications maintain their own trust store. . Any system that can't be updated needs to see the cross-signed chain or you need to switch CA. |
| 54 | + |
| 55 | +e.g. for Java you might use: `keytool -import -alias isrgrootx1 -keystore $JAVA_HOME/jre/lib/security/cacerts -trustcacerts -file rootye.cer` |
| 56 | + |
| 57 | +## Azure (Application Gateway) |
| 58 | +Ensure that the HTTP settings for back-end hosts are updated with the latest Trusted Root Certificate. Upload the new roots via the Azure Portal or via PowerShell. See [Application Gateway Troubleshooting](https://docs.microsoft.com/en-us/azure/application-gateway/application-gateway-backend-health-troubleshooting) for further details. |
| 59 | + |
| 60 | +### Revert the served chain on your server |
| 61 | + |
| 62 | +You can force your server to communicate using the "cross-signed" chains which preserve compatibility by removing *Root YE* and *Root YR* from *Trusted Root Certification Authorities* collection under certlm (Computer Certificates). |
| 63 | + |
| 64 | +:::warning Caution - Workaround |
| 65 | +This may have unintended side effects because it also changes how your server trusts services it connects to. |
| 66 | +::: |
| 67 | + |
| 68 | +Your server will however continue to trust the new roots while windows update etc is allowed to update the CA roots. Another option is to temporarily move *Root YE* and *Root YR* into the *Untrusted Certificates* collection, then reboot. You should make a note to review this decision every month and remove this workaround as soon as possible. |
| 69 | + |
| 70 | +### Proxy your service |
| 71 | +Instead, if you require this chain for compatibility, either use a proxy (Caddy, nginx, Apache) in front of IIS and use the proxy to terminate TLS. This lets you control the served chain via that proxy. |
| 72 | + |
| 73 | +## Use a different CA |
| 74 | +If no other solution works or for any other reason you cannot update client trusts stores etc or require other broader compatibility, you may need to consider moving your certificate to a new Certificate Authority. |
| 75 | +::: |
| 76 | + |
| 77 | + |
| 78 | +## Other considerations |
| 79 | +### Certify Certificate Manager - Export Tasks |
| 80 | +If you use Certify The Web to export certificates to PEM files etc (for Apache or other servers), the chain you get in the export will correspond with the chain your server is currently building. The "Preferred Issuer" setting for the certificate authority will have *no effect*, because Windows is overriding the chain. We will release an update to control the strictness of export chains. |
| 81 | + |
| 82 | +## Further Troubleshooting |
| 83 | + |
| 84 | +:::tip Licensed Users can contact Certify The Web support |
| 85 | +While the problem itself relates to and is controlled by Windows and Let's Encrypt, licensed users can contact Certify The Web support via `support at certifytheweb.com` if they have further related questions and issues they need advice with. We are in the AEST (Australia) Time Zone. A higher than normal volume of support tickets are expected so please expect delays and perform as much of your own troubleshooting and research as you can. |
| 86 | +::: |
| 87 | + |
| 88 | +## Useful Information |
| 89 | +Visit the Let's Encrypt support community for more information about the chain changes: https://community.letsencrypt.org |
| 90 | + |
| 91 | +### Chain Checking |
| 92 | +Other ways to check and diagnose chain issues: |
| 93 | +- Chain Checker by Certify The Web: https://chainchecker.certifytheweb.com/ provides useful diagnostics for Let's Encrypt chains. |
| 94 | +- Qualsys SSL Server Test: https://www.ssllabs.com/ssltest/ is useful for full diagnostics of your certificate chain. |
| 95 | +- Namecheap SSL Checker: https://decoder.link/sslchecker/ |
| 96 | +- OpenSSL: `openssl s_client -connect your.domain.com:443 -servername your.domain.com` |
| 97 | + |
| 98 | +### Further Reading |
| 99 | +The Windows certificate chaining engine: https://social.technet.microsoft.com/wiki/contents/articles/3147.pki-certificate-chaining-engine-cce.aspx |
0 commit comments