Update documentation of artifact repositories using untrusted TLS certificates

[l0rd]

Is your enhancement related to a problem? Please describe.

The documentation "Using artifact repositories in a restricted environment" describes how to use artifact repositories that use TLS certificates signed by untrusted certificate authorities. The procedure is:

• Obtain the untrusted certificate
• Upload the certificate in a folder under /projects/ of the workspace pod
• Patch a devfile with the instructions to make the certificates trusted

This procedure can be simplified if the untrusted certificates are provided to Che operator using a ConfigMap referenced in CheCluster server.serverTrustStoreConfigMapName or, on OpenShift, included in the system trusted CA bundle. In those cases the certificates are automatically mounted in the workspace containers under /public-certs.

Describe the solution you'd like

We should reference the documentation that explains how to import untrusted SSL certificates (currently being reworked here) and describe the extra steps required so that the TLS certificates under /public-certs are trusted by the dependency managers (maven, gradle etc...).

Steps "Obtain the untrusted certificate", "Upload the certificate in a folder under /projects of the workspace pod" should be removed.

Describe alternatives you've considered

The extra steps required so that the TLS certificates under /public-certs are trusted by the dependency managers (maven, gradle etc...) can be automated too. We will create a separate issue for that.

[ericwill]

This doc task is dependent on eclipse-che/che-docs#1598, right?

[l0rd]

This doc task is dependent on eclipse/che-docs#1598, right?

yes

[tsmaeder]

The proposed solution does not work for maven and gradle, at least, because the procedure described in eclipse-che/che-docs#1598 does not work for binary files like Java truststores.

[l0rd]

@tsmaeder eclipse-che/che-docs#1598 was not supposed to address this issue but it makes current docs outdated. At least if we assume that the persona that deploys Che is also responsible to add the artifact repositories CA certificates into Che trusted CA bundle. In that scenario, the artifacts repositories certs will be automatically mounted on every workspace containers but the developer still needs to (manually) add those certs in the Java keystore.

[tsmaeder]

@l0rd we have a solution that takes some values (certificates in base64) and pushes them at a well known path into all workspaces. Wouldn't it be much simpler if that way of pushing secrets (which the certs are, in the end) would work for binary data as well? It just seems like an unnecessary limitation.
Also, if the developer needs to do manual process anyway, there is not much advantage to getting the certificate from /public-certs over other channels of distribution.

[tsmaeder]

Also, the current setup in the docs still works, it just does not specify a particular way of obtaining the certificates.

[l0rd]

OpenShift convention is to add external services trusted TLS certificates in the OpenShift CA bundle ConfigMap. If an admin follows that convention OpenShift provides a simple mechanism (a sort of dependency injection) to mount all those certificates in a Pod. That's a useful convention: you add the trusted certificate once and any service that requires it in the OpenShift cluster will have access to it.

This convention expects the certificates to be base64. And this convention expects the persona that collects and approves external TLS certificates to be distinct from the persona that runs the a workload in the cluster.

So, for a Nexus server that uses an enterprise TLS certificate for example, an OpenShift admin familiar with that convention will include that certificate in the OpenShift CA bundle ConfigMap and every Che container gets the certificate mounted. The last little step now is to include those trusted certificate in the Java trust store, something we already do automatically for the Che server.

[tsmaeder]

@l0rd so I would propose something like this:

Using self-signed certificates in Maven projects

Internal artifact repositories often do not have a certificate signed by an authority that is trusted by default in Java. They are usually signed by an internal company authority or are self-signed. Configure your tools to accept these certificates by adding them to the Java truststore.
Procedure

    Obtain a server certificate file from the repository server. It is customary for administrators to provide certificates of internal artifact servers as Kubernetes secrets (see Importing untrusted TLS certificates to Che). The relevant server certificates will be mounted in /public-certs in every container in the workspace.

        Copy the original Java truststore file:

        $ mkdir /projects/maven
        $ cp $JAVA_HOME/lib/security/cacerts /projects/maven/truststore.jks
        $ chmod +w /projects/maven/truststore.jks

        Import the certificate into the Java truststore file

        $ keytool -import -noprompt -file /public-certs/nexus.crt -alias nexus -keystore /projects/maven/truststore.jks -storepass changeit
        Certificate was added to keystore

    Add the truststore file.

        In the Maven container:

            Add the javax.net.ssl system property to the MAVEN_OPTS environment variable:

              - mountSources: true
                alias: maven
                type: dockerimage
                ...
                env:
                   -name: MAVEN_OPTS
                    value: >-
                      -Duser.home=/projects/maven -Djavax.net.ssl.trustStore=/projects/truststore.jks

    Restart the workspace.

In the Java plug-in container:

In the devfile, add the javax.net.ssl system property for the Java language server:

components:
  - id: redhat/java11/latest
    type: chePlugin
    preferences:
      java.jdt.ls.vmargs: >-
        -noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication
        -Duser.home=/projects/maven
        -Djavax.net.ssl.trustStore=/projects/truststore.jks
[...]

[RickJWagner]

Hi @tsmaeder,
Thank you for working to better our docs.
It looks like the proposal suggested above takes steps to set up /projects/maven/truststore.jks, but then uses -D flags for /projects/truststore.jks.

keytool -import -noprompt -file /public-certs/nexus.crt -alias nexus -keystore /projects/maven/truststore.jks

-Djavax.net.ssl.trustStore=/projects/truststore.jks
(and again in the devfile).

Don't feel bad, our docs do the same thing. (RHDEVDOCS-2502 is open for this.)

[RickJWagner]

A user is reporting issues that seem related. In that case, maven wanted a password (-Djavax.net.ssl.trustStorePassword=....)

In our keytool line we are specifying the well-known 'changeit'. Please consider adding the same to the two places where we use -D flags). Thanks!

[tsmaeder]

@RickJWagner good catch.

[l0rd]

@tsmaeder that good. Thanks

[tsmaeder]

@RickJWagner the PR has been merged. Would be cool if you could verify.