Adding docs on how to add certificates (asciidoctor#1153)

ahus1 · Mar 16, 2023 · 70cdb99 · 70cdb99
1 parent ebafef0
commit 70cdb99
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 0 deletions.
diff --git a/doc/users-guide/modules/ROOT/nav.adoc b/doc/users-guide/modules/ROOT/nav.adoc
@@ -61,3 +61,4 @@
 ** xref:faq/troubleshooting-mps.adoc[]
 ** xref:faq/diagrams-in-pdf-without-text.adoc[]
 ** xref:faq/could-not-find-dot-executable.adoc[]
+** xref:faq/custom-tls-certificates.adoc[]
diff --git a/doc/users-guide/modules/ROOT/pages/faq.adoc b/doc/users-guide/modules/ROOT/pages/faq.adoc
@@ -129,3 +129,10 @@ Please consider adding a rating for the plugin in the https://plugins.jetbrains.
 
 This plugin is based on Asciidoctor and a lot of ideas from its community.
 To support Asciidoctor, please consider contributing funds via https://opencollective.com/asciidoctor[Open Collective].
+
+=== I'm getting an error "`SSLError / certificate verify failed`"
+
+This happens if the remote server presents a certificate which is not trusted.
+Usually this happens if it uses a self-signed certificate or an unknown/private root certificate authority.
+
+See the page about xref:faq/custom-tls-certificates.adoc[] on how to fix this.
diff --git a/doc/users-guide/modules/ROOT/pages/faq/custom-tls-certificates.adoc b/doc/users-guide/modules/ROOT/pages/faq/custom-tls-certificates.adoc
@@ -0,0 +1,28 @@
+= Custom TLS certificates
+:navtitle: Custom TLS certificates
+:description: When connecting to TLS with custom TLS certificates, users need to add them to the truststore of the IDE.
+
+{description}
+
+== Symptom
+
+When rendering an AsciiDoc document which for example connects to a Kroki diagram server that presents a self-signed certificate, the output contains an error similar to the following:
+
+====
+org.jruby.exceptions.StandardError: (SSLError) asciidoctor: FAILED: ...: Failed to load AsciiDoc document - certificate verify failed
+====
+
+== Cause: Untrusted certificate authority
+
+This happens if the remote server presents a certificate which is not trusted.
+Usually this happens if it uses a self-signed certificate or an unknown/private root certificate authority.
+
+== How do I fix this?
+
+Add the self-signed certificate or the matching root certificate authority to the IntelliJ's `cacerts` file.
+
+Users can also add certificates via the menu menu:File[Settings... > Tools > Server Certificates]. See https://www.jetbrains.com/help/idea/settings-tools-server-certificates.html[the IDE's help] for details.
+
+== Help, it still doesn't work!
+
+To have the maintainers investigate the issue, open a https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues[GitHub issue].