Where is the confluence_ca_cert located on Windows 10 machine?

[AndreasLuckert]

I get the following error message when pushing local docs to the remote Confluence wiki:

$ sphinx-build -E -a docs/source docs/build/confluence -b confluence

Running Sphinx v4.4.0
sphinxcontrib.confluencebuilder error:
---
SSL connection issue has been detected
An SSL issue has been detected when trying to communicate with the
configured Confluence instance. Ensure the instance is running and
inspect that the configured Confluence URL is valid:
   https://wiki.domainname.com/confluence/
This can be common for internal/self-hosted Confluence instances which
may have been signed with an internal/corporate root authority. If the
environment is not setup in a way to verify self-signed certificates,
users may be interested in manually configure the `confluence_ca_cert`
option.
(details: HTTPSConnectionPool(host='wiki.domainname.com', port=443): Max retries exceeded with url: /confluence/rest/api/space?spaceKey=BA&limit=1 (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1056)'))))
---

The support told me I should update the contents of "confluence_ca_cert", but cannot find it on my system. I also would not know for sure where to place it.

[jdknight]

@AndreasLuckert, before we get into acquiring an internal certificate authority's public key, a Sphinx configuration can be setup using the following:

1. Placing your public key certificate file (.crt or .pem) alongside a project's conf.py file.
2. Adding the following to configure to use the local key:

import os
conf_dir = os.path.dirname(os.path.abspath(__file__))
confluence_ca_cert = os.path.join(conf_dir, 'mycert.cer') # (or, use mycert.pem)

There are a couple of ways to acquire the public key to validate against in a Windows environment. The following shows some example steps for grabbing a public key using either Firefox or Chrome/Edge:

Firefox

Select the lock icon beside the Confluence instance URL:

Select the Connection secure option:

Followed by selecting More information:

A dialog should appear presenting an option to view specifics about the certificate; select it:

The opened up page should show public key information. Select the root certificate associated with this server and download the PEM (chain) file (which can be saved with a pem file extension):

(EDIT: select "chain")

Place the .pem file alongside the conf.py file.

Chrome/Edge

Select the lock icon beside the Confluence instance URL:

Select the Connection is secure option:

Followed by selecting Certificate is valid:

A Windows certificate dialog will appear; press the View certificate button:

Under the Details tab, press the Copy to File... button:

A wizard should appear to help provide a way to export the public key:

When presented the type of file to export, select Base-64 encoded X.590 (CER):

Place the .crt file alongside the conf.py file.

---

Please let me know if this does not work for you.

[AndreasLuckert]

Thanks for your thorough instructions, I've just tried everything out, but still get this error:

$ sphinx-build -E -a docs/source docs/build/confluence -b confluence

Running Sphinx v4.4.0

sphinxcontrib.confluencebuilder error:

---
SSL connection issue has been detected

An SSL issue has been detected when trying to communicate with the
configured Confluence instance. Ensure the instance is running and
inspect that the configured Confluence URL is valid:

   https://wiki.project.com/confluence/

This can be common for internal/self-hosted Confluence instances which
may have been signed with an internal/corporate root authority. If the
environment is not setup in a way to verify self-signed certificates,
users may be interested in manually configure the `confluence_ca_cert`
option.

(details: HTTPSConnectionPool(host='wiki.project.com', port=443): Max retries exceeded with url: /confluence/rest/api/space?spaceKey=BA&limit=1 (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1091)'))))
---

I was then notified that most likely it has to do with the Projects VPN Proxy certificate: -> the certificate directly from the Confluence Wiki is signed via GlobalSign anyway, so there should be no SSL-error produced by that. Much rather one might need to obtain the wiki proxy server certificate via e.g. "openssl s_client", but I'm not sure how to accomplish that exactly and if I'm on the right track anyway.

Do you have any thoughts on that?

[jdknight]

Ah, it may be the certificate of your proxy.

The confluence_ca_cert option is just a passthrough for Request's verify argument. If you were able to acquire your VPN's proxy certificate, referencing it in this command may work. I'm not sure if you would need to register multiple CA's for it to work in this use case, but if that were the case, I believe you'd need to stack multiple certificates into one PEM file and use it in this configuration -- although, I cannot say I have personally done that before.

Since you are on Windows, you may be able to use the python-certifi-win32 package, which from what I have read, can be used to allow Requests to use the Windows certificate store. From what I can tell, just installing the package may be enough, but I do not have an environment to confirm this at this time.

[AndreasLuckert]

I succeeded so far only by employing a workaround with the confluence-disable-ssl-validation.

Based on a conversation with the IT support of my client, I was able to gather the following information about these Confluence SSL certificates:

The confluence SSL certificate is not self-signed. It was issued by Entrust. All browsers with trusted global SSL provider certificates trust certificates signed by Entrust.

All SSL certificates begin with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE----- The key is always between these 2 lines.

There is a difference between in SSL certificates when accessed from external then from access internal. This is due to the web application firewall (WAF) provider we use.

A typical certificate consists of root, intermediate, and primary SSL certificates. You may have to chain these depending on how your application validates SSL certificates. The standard way is to chain the root, intermediate, and primary. In that order.

Although the key length may be different for each certficate.

Finally, the support even has a good guess regarding how to distribute the different certificate parts across the interface:

The root and intermediate certificates can go in confluence_ca_cert, the primary goes into confluence_client_cert. A password is not needed so confluence_client_cert_pass can be left blank.

--> What do you think about this, does this make sense to you?

[jdknight]

Interesting.

If the certificates were not self-signed, I would assume requests would work without additional configuration. The Requests library should be using the certifi package by default, which should be pulling from Mozilla's CA list. You can try to sanity check that you are using the most recent "common" CAs, by ensuring this package is up-to-date:

pip install -U certifi

Although, personally, I have never needed to do this before.

The support information provided seems valid. The end goal would be to form a single PEM file with all the certificates you would need for a secure channel. The usage of confluence_client_* options may be applicable to you; however, I have never been in an environment where I had to use such a capability (it was a community provided feature).

---

Note that if you can view/navigate on your Confluence instance with your local Chrome/Edge/etc. browser, using python-certifi-win32 may help. If you haven't been able to try this yet, it can be installed via:

pip install -U python-certifi-win32

And by adding the following in your Sphinx's configuration file, you can generate an update PEM file based on your Windows certificate store and load the PEM into this extension:

import sys
if sys.platform == 'win32':
    import certifi_win32
    certifi_win32.generate_pem()
    confluence_ca_cert = certifi_win32.wincerts.where()

[jdknight]

@AndreasLuckert, introduced some changes (#667) to better handle automatic loading of certification authorities registered in Windows's and ROOT system stores. If interested, feel free to try out the development version of this extension and check if it resolves your issue.

If it does not resolve your issue, would you mind telling me if your runs are being invoked from either a Command Prompt, Powershell, or some other environment like MinGW/Cygwin?

[jdknight]

In preparation for a v1.9 release, additional test was performed in some unique environments with custom certificates on a Confluence instance. One issue noticed in Windows environments is that even with some certificates with a trusted store, publishing would still report certificate issues.

While explicitly setting confluence_ca_cert should always resolve these issues, the biggest issue I have seen from this is ensuring the certificates used include a complete chain is made available. This is important for instances using an intermediate CA. This extension does not have a graceful way to help users validate a certificate chain at this time (maybe in the future, there looks to be some Python libraries which can help check this). In theory, downloading the CHAIN pem from a Firefox instance should provide the best chance at having a valid PEM file (I have updated an above comment to better reflect to acquire a CHAIN instead of a CERT).

Lastly, another change was introduced in #701. Requests library (used by this extension) will default to use its own CA bundle. By disabling verification, requests would work, and adding explicit CAs via configurations would (in theory) also work. However, the "default" case would automatically register Requests CA bundle, which would not use the Windows store (even if our adapter loaded from the local environment). This extension now attempts to avoid using Requests embedded CA bundle. This should let request calls to automatically use the local available CAs (depending on the environment). I suspect that this may have been the main cause of this issue.

Since there has been several CA-related fixes in this recent v1.9 request, I will be going ahead and closing this issue. Ideally, the most recent release should give users the best chance at authenticating with secured Confluence instances (no matter which host environment triggers the request). If still experiencing issues with authentication, we could re-open this issue (if desired); although it may be better to spawn a new/fresh issue since a lot have been covered in this existing one.