How to Add a Root Certificate to the Java Truststore on Mac OS 10.15 Catalina

When developing a java web app on Mac OS Catalina, you may have a service that makes an API request to a secure URL.

If you don’t have that secure (https) URL’s root certificate in your Java truststore, the call will fail with this error:

:    : :           

The solution is to put that secure URL’s host’s root certificate into your Java truststore. Easier said than done, but here’s how to do it on Mac OS Catalina.

1. Download the Certificate

1. Go to the secure URL in the Chrome browser.
2. Hit F12 to open the Chrome Inspector Tools.
3. Open the “Security” tab in the Inspector Tools. It’s going to be on the right side of the top nav.

1. Click the “View Certificate” button.
2. Open a new Finder window somewhere else on your screen.
3. In the certificate box, click on the certificate at the top of the tree. Then drag the big image of the Root Certificate into your Finder window. You should now have a file called something like: “DST Root CA X3.cer” in your finder window.
   1. Pro Tip:
      1. Clicking and dragging with no keys held down gives you a *.cer certificate
      2. Clicking and dragging with the Command key held down gives you a *.txt version of the certificate
      3. Clicking and dragging with the Option (or Alt) key held down gives you a *.pem version of the certificate
      4. The truststore will accept a *.pem or *.cer file
4. Rename the file so that it has no spaces in it: “DSTRootCAX3.cer”.

2. Put the Certificate in your Java truststore

1. Open a Terminal window.
2. Run this command to put the cert in your Java truststore:

sudo keytool - -alias dstrootcax3 -keystore /Library/Java/JavaVirtualMachines/jdk1_77.jdk/Contents/Home/jre/lib/security/cacerts -file DSTRootCAX3.cer  

Here is the command broken down so you can see where to replace strings with your values:

sudo keytool -import -alias  -keystore  -file   

You’ll next be asked for the password to the truststore. If you have never changed the password, the password is “changeit”.

The uniqueAliasName should be a unique name within the truststore cert list that will let you recognize this particular cert, say, in case you want to remove it.

The pathToYourJavaInstallations_cacerts_file is the path to cacerts file you are using as a truststore. If your server is not using a custom cacerts file, this will be at the default location for your Java installation. If you are using the default Java installation that came with your Mac, like I am, it could be this path: /Library/Java/JavaVirtualMachines/jdk1.8.0_77.jdk/Contents/Home/jre/lib/security/cacerts

The pathToCertYouJustDownloaded is the path to the cert you just put in your Finder folder.

If you’ve run the command successfully, you should see this message in your terminal: Certificate was added to keystore

You can now restart your Java web server, and your API call should work.

Срок действия корневого сертификата DST Root CA X3 истёк 30 сентября 2021 года. Соответственно, операционные системы и браузеры, которые давно не получали обновлений перестали доверять сайтам, сертификат безопасности которых был выдан центром сертификации Let’s Encrypt. Подробнее об этом я писал здесь: http://www.bolshoyv­opros.ru/questions/3­873202-oshibka-brauzera-google-chrome-chasy-speshat-kak-ispravit.html

Для начала, чтобы удостовериться что проблема связанна именно с отсутствием сертификата на вашем компьютере, проверим его наличие, или отсутствие. Для этого откройте Пуск => Панель управления => (Сеть и интернет) => Свойства браузера => Содержание => Сертификаты => Доверенные корневые центры сертификации. Пункт «Сеть и интернет» взят в скобки, потому что на разных ОС переход в «Свойства браузера» может быть сразу из «Панели управления».

Если выделенная на скриншоте строка у вас отсутствует, то вам необходимо установить сертификат ISRG Root X1.

Для этого переходим на официальный сайт Let’s Encrypt и скачиваем корневой сертификат ISRG Root X1 в формате der. К сожалению, разбираться нужно с английской версией, так как русская версия этой страницы устарела.

Ни в коем случае не скачивайте сертификаты с неизвестных и подозрительных сайтов!

Кликните по скачанному файлу сертификата, который будет иметь вот такой вид:

и разрешите его открытие, нажав Открыть.

Далее, разрешите Установить сертификат

и следуйте указаниям Мастера импорта сертификатов.

При установке, выберите хранилище Доверенные корневые центры сертификации

Нажмите кнопку Готово и завершите установку сертификата.

Удалите устаревший корневой сертификат DST Root CA X3, чтобы он не мешал нормальной работе с сервисами, которые используют сертификаты Let’s Encrypt.

Проверьте работу тех сервисов, с доступом к которым у вас до этого возникали проблемы.

Для MacOS пока что только одна рекомендация — обновить систему.

Don’t Let Replacing the Expired DST Root CA x3 Bring You Down

If you are using an older Mac OS X version to browse the web, it’s likely that you recently started seeing «NET::ERR_CERT_DATE_INVALID», «Your connection is not private», «Clock expired privacy issue», «Safari can’t verify the identity of the website», or a similar error in your browser, when trying to visit sites that should be safe.

The error is probably occurring on your older computer because the popular certificate DST root ca x3 from the certificate authority Let’s encrypt expired on September 30, 2021. You need its replacement isrg root x1 to resolve the NET::ERR_CERT_DATE_INVALID error.

Your computer has a list of certificates that allow it to verify the authenticity of the websites you visit. OS updates usually include the latest batch of certificates required to verify most websites you might visit. However, you can also manually add certificates to your computer’s certificate store.

Manually Adding Certificates on Mac OS El Capitan

Here is how to add the isrg root x1 certificate on Mac OS El Capitan. The process is very similar on other Mac OS versions as well.

Step 1: Get the legit isrg root x1 certificate from Let’s encrypt by visiting https://letsencrypt.org/certs/isrgrootx1.pem.txt. If the Lets Encrypt site itself is marked as insecure for you, you can download it from here: https://intellitect.com/wp-content/uploads/2022/03/isrgrootx1.pem_.txt (don’t make downloading certs from websites a habit though).

Don’t let the encoding of the file intimidate you.

Step 2: Save it by right-clicking on the page and clicking save as (or if in Safari, click File > Save as ).

Step 3: Save it as a .pem file (remove the .txt extension).

You now have a file that looks like this:

Step 4: Open the file. The file opens with Mac OS’s certificate store called Keychain Access.

If it doesn’t open with KeyChain Access, then open the KeyChain Access app manually by either searching for it via Spotlight ? or finding it in the Utilities App Folder. Then drag and drop the .pem file into KeyChain Access.

Step 6: Now, we need to mark it as trusted.

Find it in the certificates, and open it. Under the Trust drop-down ? (double click to open), set the SSL field as always trusted.

Step 7: Close and save.

Wrapping Up!

You should be able to use SSL (HTTPS) with it now! Wikipedia.org is a site that you wouldn’t be able to visit without SSL backed by isrg root x1, so give it a try.

Want More?

Need more information on fixing errors like «NET::ERR_CERT_DATE_INVALID»? Check out Mark Michaelis’ quick fix for the NETSDK1004 compile error. Curious about the software development work IntelliTect does? Check out our innovative products to see what software solutions we offer that solve your real-world issues.

Does Your Organization Need a Custom Solution?

Let’s chat about how we can help you achieve excellence on your next project!

pepemou opened this issue

May 19, 2021

· 17 comments

Comments

 "Acme": {
    "PreferredIssuer": "ISRG Root X1", 
    ... 
    }

30 сентября 2021 14:01:15 GMT оканчивается срок действия корневого сертификата IdenTrust DST Root CA X3.

Это событие достойно вашего внимания по той причине, что после наступления этого момента ряд устаревших систем перестанут доверять сертификатам, выпущенным центром сертификации Let’s Encrypt. С учётом того, что на текущий момент Let’s Encrypt предоставляет бесплатные криптографические сертификаты примерно для 250 миллионов доменных имен, а «устаревшие системы» — это порой системы возрастом всего 5-6 лет, вряд ли окончание срока действия сертификата DST Root CA X3 пройдёт для всех гладко и незаметно. В чём причина, кого конкретно это затронет, и что можно сделать?

Немного теории и истории

Не углубляясь в детали, пару слов для неспециалистов, почему окончание срока действия сертификата DST Root CA X3 повлияет на сертификаты, выпущенные Let’s Encrypt. У каждой системы, проверяющей сертификат на валидность, есть своё хранилище доверенных корневых сертификатов. Система при проверке будет доверять сертификатам, которые подписаны с использованием закрытого ключа одного из этих корневых сертификатов. Сами корневые сертификаты как правило имеют длительные сроки действия, меняются редко и не используются при формировании сертификатов конечного субъекта (в данном случае, сертификатов для доменных имен), вместо этого инфраструктура открытых ключей, предполагает использование цепочек доверия  — корневые сертификаты применяются для подписания промежуточных сертификатов, а уже с использованием них подписываются сертификаты конечного субъекта (сертификаты для доменов). При этом, для того, чтобы система доверяла конечному сертификату, она должна быть способна проследить всю цепочку от этого сертификата до одного из корневых сертификатов, которым она доверяет. 

После появления проекта Let’s Encrypt, его корневой сертификат ISRG Root X1 (как и любой новый корневой сертификат) не мог быстро попасть в хранилища доверенных сертификатов заметного количества систем. При этом для успешного функционирования проекта выданным сертификатам с самого начала должно было доверять максимальное количество систем «из коробки» (без дополнительных действий со стороны пользователей этих систем). В связи с этим, для сертификатов Let’s Encrypt стала использоваться цепочка доверия, ведущая к корневому сертификату DST Root CA X3, который признается большинством систем:

К настоящему моменту корневой сертификат ISRG Root X1 существует уже более 5 лет и за это время попал в доверенные в большинстве современных систем, ему доверяют:

• Windows >= XP SP3 (при условии, что производилось автоматическое обновление корневых сертификатов)

• macOS >= 10.12.1

• iOS >= 10 

• Android >= 7.1.1 

• Mozilla Firefox >= 50.0

• Ubuntu >= xenial / 16.04 (с установленными обновлениями)

• Debian >= jessie / 8 (с установленными обновлениями)

• Java 8 >= 8u141

• Java 7 >= 7u151

• NSS >= 3.26

Для сертификатов Let’s Encrypt по умолчанию в данный момент предлагается такая цепочка доверия: 

IdenTrust’s DST Root CA X3 -> ISRG Root X1 -> Let’s Encrypt R3 -> Конечный сертификат пользователя

Что произойдет 30 сентября?

Срок действия DST Root CA X3 подходит к концу 30 сентября 2021 14:01:15 GMT, что произойдет после этого?

Те системы, которые не доверяют ISRG Root X1, перестанут доверять сертификатам, выпущенным Let’s encrypt (системы будут выдавать предупреждения при посещении сайтов, использующих сертификаты Let’s Encrypt). За исключением Android >= v2.3.6, т.к. Android не учитывает срок действия своих доверенных корневых сертификатов. 

Проблема с доверием возникнет также у систем, использующих OpenSSL версии меньше 1.1.0. Даже если у таких систем ISRG Root X1 входит в список доверенных сертификатов, особенность проверки сертификата в OpenSSL 1.0.x приведёт к тому, что наличие в цепочке истекшего DST Root CA X3, несмотря на наличие доверия к ISRG Root X1, будет приводить к отрицательному результату проверки на доверие. Аналогичная проблема у OpenSSL 1.0.x возникла 20 мая 2020 года с истекшим сертификатом AddTrust External CA Root.

Что со всем этим делать?

На стороне клиента

Linux

Для того, чтобы проверить, как поведёт себя ваша система при обращении к сайтам, использующим сертификаты Let’s Encrypt, после 30 сентября, можно воспользоваться утилитой faketime. В Debian и Ubuntu она доступна в пакете faketime.

Если всё в порядке, curl вернёт содержимое страницы, если же нет — выдаст сообщение об ошибке:

curl: (60) server certificate verification failed.

В этом случае нужно убедиться, что:

1. Ваша система доверяет ISRG Root X1 

2. Вы не пользуетесь устаревшей версией OpenSSL

Проверка доверия к ISRG Root X1

Например, Ubuntu 16.04 xenial и Debian 8 jessie доверяют ISRG Root X1, но при этом поставляются с OpenSSL 1.0.x, поэтому проблема их может коснуться.

Чтобы проверить наличие сертификата ISRG Root X1 в числе доверенных: 

В выводе команды в обоих случаях должно присутствовать:

subject= /C=US/O=Internet Security Research Group/CN=ISRG Root X1

Если такой строчки нет, то нужно добавить ISRG Root X1 в доверенные. В Debian/Ubuntu:

добавить в файл /etc/ca-certificates.conf строчку:

и выполнить комнаду

Проверка версии OpenSSL

Если система доверяет ISRG Root X1, нужно проверить версию OpenSSL

В выводе должна быть версия 1.1.0 или новее.

Если используется OpenSSL 1.0.x, то достаточным решением проблемы будет удалить из доверенных сертификат DST Root CA X3 (это решение может не сработать для openssl версий <1.0.1p и <1.0.2d). Это можно сделать, не дожидаясь 30 сентября.

В файле /etc/ca-certificates.conf нужно найти строчку:

и поставить в начало сроки символ «!»:

Далее, необходимо выполнить команду:

Локальное продление срока действия сертификата DST Root CA X3

Для тех случаев, когда используется совсем старый openssl (версии меньше 1.0.1p и 1.0.2d, но новее 0.9.8m), или по иной причине не срабатывает метод с изъятием из доверенных сертификата DST Root CA X3, можно воспользоваться еще одним методом, предложенным в статье Scott’а Helme. Метод основан на том, что OpenSSL, начиная с версии 0.9.8m, не проверяет сигнатуру сертификатов, хранящихся в локальном защищенном хранилище. Таким образом, можно изменить время действия сертификата в защищенном хранилище, при этом модифицированный сертификат будет по-прежнему восприниматься OpenSSL как валидный. Для того, чтобы продлить для OpenSSL на системе срок действия сертификата DST Root CA X3 еще на три года можно выполнить следующие команды:

sudo sed -i "s/xMDkzMDE0MDExNVow/0MDkzMDE4MTQwM1ow/g" /etc/ssl/certs/DST_Root_CA_X3.pem

sudo sed -i "s/xMDkzMDE0MDExNVow/0MDkzMDE4MTQwM1ow/g" /etc/ssl/certs/ca-bundle.crt

Не забудьте проверить так же все ваши контейнеры!!! У них свои хранилища корневых сертификатов и могут использоваться другие версии openssl

Windows

В мастере импорта сертификатов выбрать «Локальный компьютер»:

На последнем шаге мастера нажать кнопку «Готово».

После выполнения этой последовательности шагов, сертификат должен появиться в защищенном хранилище. Чтобы проверить это, нужно нажать комбинацию клавиш «Win+R», откроется диалог «Выполнить», в котором нужно ввести certmgr.msc

В открывшемся окне в подразделе «Сертификаты» раздела «Доверенные корневые центры сертификации» в списке должен появиться сертификат ISRG Root X1:

На стороне сервера 

На стороне сервера от вас мало что зависит. Если вы используете сертификаты от Let’s Encrypt на своем сервере, то должны понимать, что после 30 сентября 2021 14:01:15 GMT к вашему серверу смогут без проблем подключиться только клиенты, доверяющие ISRG Root X1 (см. список выше), а также использующие Android >= v2.3.6. При этом, если клиенты используют OpenSSL, то они должны пользоваться версией OpenSSL >= 1.1.0. 

При этом, у вас есть выбор — ценой отказа от поддержки старых Android (оставив поддержку Android >= 7.1.1), вы можете сохранить поддержку OpenSSL 1.0.x без манипуляций на стороне клиента.

Для этого нужно использовать предлагаемую Let’s Encrypt альтернативную цепочку доверия для своих сертификатов. В этой цепочке исключен DST Root CA X3 и выглядит она так: 

ISRG Root X1 -> Let’s Encrypt R3 -> Конечный сертификат пользователя

Для переключения на альтернативную цепочку нужно воспользоваться документацией вашего ACME-клиента. В частности, в certbot за возможность выбора альтернативной цепочки отвечает параметр  —preferred-chain.

Итоги

30 сентября после окончания срока действия сертификата DST Root CA X3 часть пользователей старых устройств столкнутся с тем, что не смогут корректно открывать сайты, использующие сертификаты Let’s Encrypt. Я бы выделил в первую очередь пользователей старых устройств Apple, для которых нет возможности обновиться хотя бы на iOS 10. Кроме того, под раздачу могут попасть различные устройства IoT, старые телевизоры и подобные им устройства, для которых не существует обновлений с новыми корневыми сертификатами.

В то же время, для администраторов серверов с не очень современным софтом, которые могут взаимодействовать с сервисами, использующими сертификаты Let’s Encrypt, еще есть несколько дней на то, чтобы всё проверить и подготовиться к часу X.

Update: Добавил важное дополнение про необходимость проверки всех используемых контейнеров

Update3: Еще один метод решения проблемы для старых OpenSSL, процедура по добавлению сертификата ISRG Root X1 в доверенные в Windows для тех, кто еще не разобрался