Overview #
Namazu Elements connects to MongoDB over TLS using mutual certificate authentication. The application side converts raw PEM certificates into PKCS12 (.p12) format for use by the Java client, while MongoDB itself consumes PEM files natively via OpenSSL. Ten environment variables drive the configuration, covering the connection URI, TLS certificate paths and passphrases, and the cryptographic algorithm selections.
Prerequisites #
The following tools must be available on the host running the Elements initialization script:
You will also need the following PEM files available at boot time, typically mounted as file secrets:
- ca.pem – the certificate authority certificate
- certificate.pem – the client private key concatenated with the client certificate (private key first)
MongoDB Node Configuration #
MongoDB natively understands PEM files via its built-in OpenSSL support. No special Java-side handling is needed on the database node. The relevant mongod.conf settings are:
net:
tls:
mode: requireTLS
CAFile: /etc/mongod.conf.d/ca.pem
certificateKeyFile: /etc/mongod.conf.d/certificate.pem
ipv6: true
bindIpAll: true
replication:
replSetName: <your-replica-set-name>Replica Set is Mandatory
Namazu Elements uses MongoDB transactions which require a replica set, even if the set only has a single member. Without that some APIs will not work and we provide no guarantees which will and will not work with transactions disabled.
The certificateKeyFile must be a single PEM file containing the private key followed by the certificate, concatenated together:
-----BEGIN CERTIFICATE-----
<public key material>
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
<private key material>
-----END PRIVATE KEY-----
On a Kubernetes-based deployment, these can be mounted as file secrets in the pod. On an AMI-based deployment, they should be placed at the equivalent paths on disk before mongod starts.
Application Node Configuration #
The Elements application node cannot consume PEM files directly from Java. The initialization script converts them to PKCS12 format using keytool and openssl before the application starts.
Certificate Conversion Script Snippet #
# Convert CA certificate to PKCS12 keystore
echo "yes" | keytool \
-importcert \
-alias "MongoDB Certificate Authority" \
-file "${ELEMENTS_CONF}/mongo/ca.pem" \
-keystore "${dev_getelements_elements_mongo_tls_ca}" \
-storepass "${dev_getelements_elements_mongo_tls_ca_passphrase}"
# Convert client certificate + key to PKCS12
openssl pkcs12 \
-export \
-name "MongoDB Client Certificate" \
-in "${ELEMENTS_CONF}/mongo/certificate.pem" \
-out "${dev_getelements_elements_mongo_tls_client_certificate}" \
-passout "pass:${dev_getelements_elements_mongo_tls_client_certificate_passphrase}"The output .p12 files are then chowned to the elements user before the application process starts. The input PEM files at ${ELEMENTS_CONF}/mongo/ should be the same CA and concatenated client certificate/key described in the MongoDB node section above.
Default output paths (overridable via environment variables).
| Variable | Default |
dev_getelements_elements_mongo_tls_ca | ${ELEMENTS_CONF}/mongo_ca.p12 |
dev_getelements_elements_mongo_tls_client_certificate | ${ELEMENTS_CONF}/mongo_certificate.p12 |
Note
These variables are recommended as part of an initialization script as they overlap the variables understood by the Namazu Elements application code. The intent is that these are written to the container “just in time” as part of the server startup, but practically they need only be run at some time before application boot.
Environment Variables #
The following variables configure the Elements MongoDB connection. All are read by MongoConfigurationService at startup.
| Variable | Default | Sensitive | Description |
dev_getelements_elements_mongo_uri | mongodb://localhost | No | MongoDB connection URI. Set tls=true in the query string to enable TLS. |
dev_getelements_elements_mongo_database_name | elements | No | Name of the MongoDB database used for Elements data storage. |
dev_getelements_elements_mongo_tls_format | PKCS12 | No | KeyStore format for the CA and client certificate files. |
dev_getelements_elements_mongo_tls_ca | (blank) | No | Absolute path to the CA KeyStore file (.p12). May be blank if TLS is disabled. |
dev_getelements_elements_mongo_tls_ca_passphrase | (blank) | Yes | Passphrase for the CA KeyStore. If blank, null is passed to KeyStore.load(). |
dev_getelements_elements_mongo_tls_client_certificate | (blank) | Yes | Absolute path to the client certificate KeyStore file (.p12). |
dev_getelements_elements_mongo_tls_client_certificate_passphrase | (blank) | Yes | Passphrase for the client certificate KeyStore. Used both to load the KeyStore and to initialize the KeyManagerFactory. An empty string and a null are not equivalent here. |
dev_getelements_elements_mongo_tls_protocol | TLS | No | TLS/SSL protocol string passed to the SSL context. |
dev_getelements_elements_mongo_tls_trust_algorithm | System Default | No | TrustManagerFactory algorithm. Defaults to TrustManagerFactory.getDefaultAlgorithm(). |
dev_getelements_elements_mongo_tls_key_algorithm | System Default | No | KeyManagerFactory algorithm. Defaults to KeyManagerFactory.getDefaultAlgorithm(). |
Connection URI Format #
When used in Kubernetes or with SRV records, this is the example format of the connection URI. The actual DNS record may vary depending on your specific setup (for example Route53).
mongodb+srv://<host>.<namespace>.svc.cluster.local/?replicaSet=<replica-set-name>&tls=trueUsage Notes
The tls=true parameter in the URI is what activates TLS in Elements. The Java code checks ConnectionString.getSslEnabled() and skips all certificate loading if it is not set. The host should resolve to all replica set members. When not using SRV for replica set resolution, use a standard mongodb:// URI with the appropriate hostnames.
Additionally, MongoDB has some idiosyncratic expectations with the format of the connection string and hostname. Specifically, the host is expected to be _mongodb._tcp. Pay careful attention to the hostname format and refer to the MongoDB Driver Documentation if you get stuck.
Source References #
For deeper implementation detail:
- Certificate loading logic:
sdk-mongo/src/main/java/dev/getelements/elements/sdk/mongo/StandardMongoConfigurationService.java - Integration tests:
sdk-mongo-test/src/test/java/dev/getelements/elements/sdk/mongo/test/. These tests stand up a live replica set, configure it with test certificates, and exercise the full connection path. They serve as a working reference implementation.
Other References #
- Java KeyStores – the gory details. Shoutout to Neil Maden for a great article on understanding the technical nuances of the Java KeyStore.
- Reddit if you just need to vent. We get it.