openvox 8x: document custom CA for HTTPS-inspecting proxies

[miharp]

Summary

• Adds a new doc page covering how to add a custom CA to OpenVox's vendored cert bundle for environments using HTTPS-inspecting proxies (Squid SSL Bump, etc.)
• Explains why OpenVox ignores the OS trust store (it uses its own DEFAULT_CERT_FILE at /opt/puppetlabs/puppet/ssl/cert.pem and DEFAULT_CERT_DIR at /opt/puppetlabs/puppet/ssl/certs/)
• Covers three persistent approaches: ssl_trust_store (module downloads only), SSL_CERT_FILE with a merged bundle (universal), and certs/ + openssl rehash (recommended — survives upgrades, no env var management)
• Puppet management examples: file + exec rehash for the certs/ approach; puppetlabs/concat for the SSL_CERT_FILE approach
• Adds nav entry under "SSL and certificates"

Motivation

Reported by a community member: gem installs and puppet module install fail behind Squid SSL Bump even when the proxy CA is in the system trust store.

Source verification

Claims verified against the OpenVox source:

• OpenSSL::X509::DEFAULT_CERT_FILE = /opt/puppetlabs/puppet/ssl/cert.pem and DEFAULT_CERT_DIR = /opt/puppetlabs/puppet/ssl/certs/ confirmed on a live openvox-agent-8.27.0 install
• puppet module install uses Puppet::SSL::SSLProvider#create_system_context → create_x509_store(include_system_store: true) → store.set_default_paths, which respects both DEFAULT_CERT_FILE and DEFAULT_CERT_DIR (ssl_provider.rb:258)
• ssl_trust_store scope confirmed via defaults.rb:1020 — applies to forge/https only, not gem subprocesses
• puppet_gem provider runs gem as a subprocess (puppet_gem.rb), so only inherits SSL_CERT_FILE from the service environment

Test results

Tested on openvox-agent-8.27.0 (CentOS Stream 9, aarch64) via Vagrant. Generated a self-signed test CA, started a Python HTTPS server using that CA, and verified each approach:

=== TEST 1: Default cert.pem (should FAIL) ===
ERROR: OpenSSL::SSL::SSLError: certificate verify failed (unable to get local issuer certificate)

=== TEST 2: certs/ + openssl rehash ===
OK

=== TEST 3: SSL_CERT_FILE merged bundle ===
OK

=== TEST 4: Docs verification command ===
OK

Puppet file + exec rehash approach also verified — idempotent, hash symlink created, Ruby connects without SSL_CERT_FILE:

Notice: /File[...proxy-ca.pem]/ensure: defined content as '{sha256}cda6...'
Notice: /Exec[rehash-puppet-ssl-certs]: Triggered 'refresh' from 1 event
# second run:
Notice: Applied catalog in 0.02 seconds  ← no changes

Test plan

• Review doc prose for accuracy
• Confirm nav link resolves correctly on built site

[Sharpie]

This works, but will not survive upgrades that update the public CA bundle. When that happens, integrations will break and someone has to remember to repeat the append.

A better solution should be:

cp /path/to/proxy-ca.pem /opt/puppetlabs/puppet/ssl/certs/

# This step "activates" the new file by writing out symlinks that allow the certs
# to be looked up by fingerprint.
/opt/puppetlabs/puppet/bin/openssl rehash

The contents of the certs/ directory should be left alone by an upgrade. There may be some workflows that see changes to cert.pem but miss files added to certs/ after rehash --- these should be reported as bugs so that we can fix them up.

Last I looked, Windows is in a bit of a bind as openssl rehash was wrapped in one giant #ifndef WINDOWS in the C source, but maybe things are better in OpenSSL 3.5.

[maxadamo]

If the package resource had an option to set an environment variable it would solve the problem. It is enough to set: SSL_CERT_FILE=/path/to/cert.pem