Certificate Trust Settings

There are a number of situations where you need to provide Document Engine with TLS certificates.

The Document Engine Helm chart provides convenient wrapping for custom certificates, allowing you to consolidate them from different ConfigMap(opens in a new tab) or Secret(opens in a new tab) resources.

This guide will cover those scenarios.

Digital Signatures

Document Engine will search for certificate stores used for digital signature validation at the /certificate-stores path inside its container.

Note that, for performance reasons, Document Engine defers loading certificate files until a signature needs to be validated, so you’ll need to open a signed document to test that the files are loaded as expected.

Helm Values

Assume that certificates are stored in PEM format in the following resources:

• A ConfigMap called digital-signature-trust with signing-ca and second-signing-ca keys
• A Secret called secret-ca-store with an another-signing-ca.pem key

Here are the Helm values for mounting these bundles to /certificate-stores to be used for signature validation:

certificateTrust:
  digitalSignatures:
    - name: my-signature-trust
      path: my-signing-ca.pem
      configMap:
        name: trust-store
        key: signing-ca
    - name: my-signature-trust-2
      path: my-signing-ca-2.pem
      configMap:
        name: trust-store
        key: second-signing-ca
    - name: another-one
      path: my-other-signing-ca.pem
      secret:
        name: secret-ca-store
        key: another-signing-ca.pem

PostgreSQL Database

Encrypting the connection with the PostgreSQL database requires trusting its certificate. This can be disabled, but we don’t recommend using TLS encryption without thorough certificate validation.

All database options are configurable as values for convenient deployment.

Helm Values

Assume your PostgreSQL database CA certificate bundle is stored in the ConfigMap postgresql-trust-bundle by the ca key.

This is how to configure Document Engine to use it:

certificateTrust:
  customCertificates:
    - name: postgresql-trust-bundle
      path: postgresql-ca.pem
      configMap:
        name: postgresql-trust-bundle
        key: ca
assetStorage:
  postgres:
    enabled: true
    tls:
      enabled: true
      verify: true
      hostVerify: true
      trustFileName: "postgresql-ca.pem"

This will mount your bundle as /certificate-stores-custom/postgresql-ca.pem and set Document Engine to use this file to verify database connections.

Remote File Downloader

The Document Engine API enables adding documents from a URL. By default, Mozilla-included CAs(opens in a new tab) are used for verifying a remote URL HTTPS server. It’s possible to provide an alternative certificate chain for verification using the DOWNLOADER_CERT_FILE_PATH configuration option.

Helm Values

Consider a ConfigMap named my-certificates with the certificate bundle saved by the key downloader. Here’s how it can be configured for use for remote asset certificate validation:

certificateTrust:
  customCertificates:
    - name: my-downloader-certificates
      path: my-downloader-certificates.pem
      configMap:
        name: my-certificates
        key: downloader
  downloaderTrustFileName: my-downloader-certificates.pem

This will mount the downloader value at /certificate-stores-custom/ and set DOWNLOADER_CERT_FILE_PATH to /certificate-stores-custom/downloader-certificates.pem.

Custom Certificates with Docker Compose

Digital Signatures

If you’re using Docker Compose, you can mount the certificate file from your host system by adding volumes to your docker-compose.yml file.

Consider the host machine directory /custom-signature-cas holding certificates for digital signatures in PEM format. The following will make Document Engine use them:

document-engine:
  ...
  volumes:
    - "./custom-signature-cas:/certificate-stores"

Remote File Downloader

If your custom trust bundle for remote files is stored as /path/to/my/custom-ca.pem, use the following in your docker-compose.yml file:

document-engine:
  environment:
    DOWNLOADER_CERT_FILE_PATH: /custom-certificates/ca.pem
  volumes:
    - /path/to/my/custom-ca.pem:/custom-certificates/ca.pem:ro