.github/scripts/ReencodeAdminSecretKey.java
New file @@ -0,0 +1,66 @@ /* * The contents of this file are subject to the terms of the Common Development and * Distribution License (the License). You may not use this file except in compliance with the * License. * * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the * specific language governing permission and limitations under the License. * * When distributing Covered Software, include this CDDL Header Notice in each file and include * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL * Header, with the fields enclosed by brackets [] replaced by your own identifying * information: "Portions copyright [year] [name of copyright owner]". * * Copyright 2026 3A Systems, LLC. */ import java.io.InputStream; import java.io.OutputStream; import java.nio.file.Files; import java.nio.file.Path; import java.security.KeyFactory; import java.security.KeyStore; import java.security.PrivateKey; import java.security.interfaces.RSAPrivateCrtKey; import java.security.spec.MGF1ParameterSpec; import java.security.spec.PSSParameterSpec; import java.security.spec.RSAPrivateCrtKeySpec; /** Re-encodes the fixture's RSA private key as RSA-PSS while retaining its certificate. */ public final class ReencodeAdminSecretKey { public static void main(String[] args) throws Exception { final String alias = "admin-cert"; final Path storePath = Path.of(args[0]); final char[] pin = Files.readString(Path.of(args[1])).stripTrailing().toCharArray(); final KeyStore store = KeyStore.getInstance("JKS"); try (InputStream input = Files.newInputStream(storePath)) { store.load(input, pin); } final PSSParameterSpec params; if (args.length > 2) { final String digest = args[2]; params = new PSSParameterSpec(digest, "MGF1", new MGF1ParameterSpec(digest), Integer.parseInt(args[3]), PSSParameterSpec.TRAILER_FIELD_BC); } else { params = null; } final RSAPrivateCrtKey rsa = (RSAPrivateCrtKey) store.getKey(alias, pin); final RSAPrivateCrtKeySpec spec = new RSAPrivateCrtKeySpec(rsa.getModulus(), rsa.getPublicExponent(), rsa.getPrivateExponent(), rsa.getPrimeP(), rsa.getPrimeQ(), rsa.getPrimeExponentP(), rsa.getPrimeExponentQ(), rsa.getCrtCoefficient(), params); final PrivateKey pss = KeyFactory.getInstance("RSASSA-PSS").generatePrivate(spec); store.setKeyEntry(alias, pss, pin, store.getCertificateChain(alias)); try (OutputStream output = Files.newOutputStream(storePath)) { store.store(output, pin); } } } .github/scripts/docker-test-admin-certificate.sh
New file @@ -0,0 +1,354 @@ #!/usr/bin/env bash # The contents of this file are subject to the terms of the Common Development and # Distribution License (the License). You may not use this file except in compliance with the # License. # # You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the # specific language governing permission and limitations under the License. # # When distributing Covered Software, include this CDDL Header Notice in each file and include # the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL # Header, with the fields enclosed by brackets [] replaced by your own identifying # information: "Portions copyright [year] [name of copyright owner]". # # Copyright 2026 3A Systems, LLC. set -eo pipefail image=${1:?usage: $0 <image>} work=$(mktemp -d) container="test-admin-certificate-${work##*.}" volume="$container-data" secret_mount=(-v "$work/secret":/var/secrets/opendj:ro) cleanup() { local status=$? if [ "$status" -ne 0 ]; then docker logs "$container" >&2 || true fi docker rm -f "$container" >/dev/null 2>&1 || true docker volume rm "$volume" >/dev/null 2>&1 || true rm -rf "$work" } trap cleanup EXIT mkdir "$work/secret" "$work/client" openssl req -x509 -newkey rsa:2048 -nodes -days 2 -subj '/CN=OpenDJ test CA' \ -addext 'basicConstraints=critical,CA:TRUE' -addext 'keyUsage=critical,keyCertSign' \ -keyout "$work/ca.key" -out "$work/client/ca.pem" 2>/dev/null printf '%s\n' changeit > "$work/client/ca.pin" docker run --rm --user "$(id -u):$(id -g)" --entrypoint keytool -v "$work/client":/certs "$image" \ -importcert -noprompt -alias test-ca -file /certs/ca.pem -keystore /certs/ca.jks \ -storetype JKS -storepass:file /certs/ca.pin make_secret() { local serial=$1 password=$2 format=$3 generation="$work/secret/..$1" local usage=${4:-extendedKeyUsage=serverAuth} local key_options=(-newkey rsa:2048) if [ "$#" -gt 4 ]; then key_options=("${@:5}") fi mkdir "$generation" printf '%s\n' "$password" > "$generation/admin-keystore.pin" openssl req -new "${key_options[@]}" -nodes -subj '/CN=OpenDJ admin' \ -keyout "$work/leaf.key" -out "$work/leaf.csr" 2>/dev/null openssl x509 -req -days 2 -set_serial "$serial" -in "$work/leaf.csr" -out "$work/leaf-$serial.pem" \ -CA "$work/client/ca.pem" -CAkey "$work/ca.key" \ -extfile /dev/stdin <<< $'subjectAltName=DNS:localhost\n'"$usage" openssl pkcs12 -export -name admin-cert -inkey "$work/leaf.key" -in "$work/leaf-$serial.pem" \ -certfile "$work/client/ca.pem" -out "$generation/admin-keystore" \ -passout "file:$generation/admin-keystore.pin" if [ "$format" != PKCS12 ]; then docker run --rm --user "$(id -u):$(id -g)" --entrypoint keytool -v "$generation":/keys "$image" \ -importkeystore -noprompt -srcalias admin-cert -srcstoretype PKCS12 -srckeystore /keys/admin-keystore \ -srcstorepass:file /keys/admin-keystore.pin -deststoretype "$format" -destkeystore /keys/converted-keystore \ -deststorepass:file /keys/admin-keystore.pin -destkeypass:file /keys/admin-keystore.pin mv -f "$generation/converted-keystore" "$generation/admin-keystore" fi chmod 644 "$generation/admin-keystore" } make_pss_secret() { local serial=$1 digest=$2 salt_length=$3 make_secret "$serial" shared-password JKS extendedKeyUsage=serverAuth -newkey rsa-pss:2048 "-$digest" \ -pkeyopt "rsa_pss_keygen_md:$digest" -pkeyopt "rsa_pss_keygen_mgf1_md:$digest" \ -pkeyopt "rsa_pss_keygen_saltlen:$salt_length" -sigopt "rsa_pss_saltlen:$salt_length" } project_secret() { # Kubernetes switches both filenames by replacing the shared ..data symlink. ln -s "..$1" "$work/secret/..data-new" python3 -c 'import os, sys; os.replace(sys.argv[1], sys.argv[2])' \ "$work/secret/..data-new" "$work/secret/..data" } start_container() { local refresh=$1 shift docker run -d --memory=512m -e "SECRET_VOLUME_REFRESH=$refresh" -p 127.0.0.1::4444 --name "$container" \ -v "$work/client":/certs:ro -v "$volume":/opt/opendj/data "$@" "$image" address=$(docker port "$container" 4444/tcp) timeout 3m bash -ec ' until [ "$(docker inspect -f "{{.State.Health.Status}}" "$1")" = healthy ]; do [ "$(docker inspect -f "{{.State.Running}}" "$1")" = true ] sleep 2 done ' _ "$container" } stop_container() { docker stop "$container" docker rm "$container" } edit_stopped_volume() { docker run --rm --entrypoint bash -v "$volume":/opt/opendj/data \ -v "$work/secret":/fixtures:ro "$image" -ec "$1" } dsconfig() { docker exec "$container" /opt/opendj/bin/dsconfig get-administration-connector-prop \ --hostname "$1" --port 4444 --bindDN 'cn=Directory Manager' --bindPassword password \ --trustStorePath /certs/ca.jks --trustStorePasswordFile /certs/ca.pin --no-prompt "${@:2}" } verify_admin_certificate() { local expected served expected=$(openssl x509 -in "$work/leaf-$1.pem" -noout -serial) shift served=$(timeout 10 openssl s_client -connect "$address" -servername localhost -verify_hostname localhost \ -verify_return_error -CAfile "$work/client/ca.pem" "$@" </dev/null | openssl x509 -noout -serial) if [ "$served" != "$expected" ]; then echo "Expected $expected on port 4444, got $served" >&2 return 1 fi dsconfig localhost } ln -s ..data/admin-keystore "$work/secret/admin-keystore" ln -s ..data/admin-keystore.pin "$work/secret/admin-keystore.pin" echo 'Check a fresh instance with the mounted administration certificate' make_secret 130701 initial-password JKS project_secret 130701 start_container 5 "${secret_mount[@]}" verify_admin_certificate 130701 test "$(docker exec "$container" stat -c %a /opt/opendj/data/config/admin-keystore)" = 600 test "$(docker exec "$container" stat -c %a /opt/opendj/data/config/admin-keystore.pin)" = 600 echo 'Check that the instance restarts with the previous certificate when the PIN arrives first' make_secret 130702 renewed-password PKCS12 stop_container mkdir "$work/secret/..pin-first" cp "$work/secret/..130701/admin-keystore" "$work/secret/..pin-first/" cp "$work/secret/..130702/admin-keystore.pin" "$work/secret/..pin-first/" project_secret pin-first start_container 5 "${secret_mount[@]}" verify_admin_certificate 130701 echo 'Check that the running instance serves a renewed certificate with a new password' project_secret 130702 timeout 1m bash -c 'until docker exec "$1" sh -c " cd /opt/opendj/data/config && cmp -s /var/secrets/opendj/admin-keystore admin-keystore && cmp -s /var/secrets/opendj/admin-keystore.pin admin-keystore.pin"; do sleep 2; done' _ "$container" verify_admin_certificate 130702 if dsconfig 127.0.0.1 --quiet; then echo 'dsconfig accepted a certificate without a SAN for 127.0.0.1' >&2 exit 1 fi echo 'Check a replacement container with a JKS keystore, the existing data volume and the watcher disabled' stop_container make_secret 130703 replacement-password JKS project_secret 130703 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130703 echo 'Check that an incompatible JCEKS preserves the installed pair on a reused volume' stop_container make_secret 130704 incompatible-password JCEKS project_secret 130704 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130703 echo 'Check that a second private key with a different PIN preserves the installed pair' stop_container make_secret 130706 shared-password JKS docker run --rm --user "$(id -u):$(id -g)" --entrypoint keytool \ -v "$work/secret/..130706":/keys "$image" \ -genkeypair -alias auxiliary -keyalg RSA -dname CN=auxiliary -storetype JKS \ -keystore /keys/admin-keystore -storepass:file /keys/admin-keystore.pin -keypass different-password project_secret 130706 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130703 echo 'Check that a zero-byte PIN preserves the installed pair' stop_container make_secret 130707 '' PKCS12 mkdir "$work/secret/..empty-pin" cp "$work/secret/..130707/admin-keystore" "$work/secret/..empty-pin/" : > "$work/secret/..empty-pin/admin-keystore.pin" project_secret empty-pin start_container 0 "${secret_mount[@]}" verify_admin_certificate 130703 echo 'Check that an empty first PIN line still works' stop_container project_secret 130707 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130707 echo 'Check that an auxiliary key without signature support permits installation' stop_container make_secret 130708 shared-password JKS openssl genpkey -algorithm X25519 -out "$work/auxiliary.key" openssl pkey -in "$work/auxiliary.key" -pubout -out "$work/auxiliary.pub" openssl x509 -req -days 2 -set_serial 130709 -in "$work/leaf.csr" \ -force_pubkey "$work/auxiliary.pub" -CA "$work/client/ca.pem" -CAkey "$work/ca.key" \ -out "$work/auxiliary.pem" openssl pkcs12 -export -name auxiliary -inkey "$work/auxiliary.key" -in "$work/auxiliary.pem" \ -out "$work/secret/..130708/auxiliary.p12" -passout "file:$work/secret/..130708/admin-keystore.pin" docker run --rm --user "$(id -u):$(id -g)" --entrypoint keytool \ -v "$work/secret/..130708":/keys "$image" \ -importkeystore -noprompt -srcalias auxiliary -srcstoretype PKCS12 -srckeystore /keys/auxiliary.p12 \ -srcstorepass:file /keys/admin-keystore.pin -deststoretype JKS -destkeystore /keys/admin-keystore \ -deststorepass:file /keys/admin-keystore.pin -destkeypass:file /keys/admin-keystore.pin rm "$work/secret/..130708/auxiliary.p12" project_secret 130708 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130708 echo 'Check that an administration key without signature support preserves the installed pair' stop_container cp -R "$work/secret/..130708" "$work/secret/..non-signing-admin" docker run --rm --user "$(id -u):$(id -g)" --entrypoint sh \ -v "$work/secret/..non-signing-admin":/keys "$image" -ec ' cd /keys keytool -changealias -alias admin-cert -destalias rsa-backup -storetype JKS \ -keystore admin-keystore -storepass:file admin-keystore.pin -keypass:file admin-keystore.pin keytool -changealias -alias auxiliary -destalias admin-cert -storetype JKS \ -keystore admin-keystore -storepass:file admin-keystore.pin -keypass:file admin-keystore.pin ' project_secret non-signing-admin start_container 0 "${secret_mount[@]}" verify_admin_certificate 130708 echo 'Check that an intact pending pair is validated before recovery' stop_container edit_stopped_volume ' cd /opt/opendj/data/config mkdir -m 700 .admin-secret-pending install -m 600 /fixtures/..non-signing-admin/admin-keystore /fixtures/..non-signing-admin/admin-keystore.pin .admin-secret-pending/ ' start_container 0 verify_admin_certificate 130708 docker exec "$container" test ! -e /opt/opendj/data/config/.admin-secret-pending echo 'Check that a certificate without digital signature usage preserves the installed pair' stop_container make_secret 130710 shared-password PKCS12 $'keyUsage=keyAgreement\nextendedKeyUsage=serverAuth' project_secret 130710 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130708 echo 'Check that a client certificate preserves the installed pair' stop_container make_secret 130711 shared-password PKCS12 'extendedKeyUsage=clientAuth' project_secret 130711 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130708 echo 'Check that different private key and certificate algorithms preserve the installed pair' stop_container make_secret 130712 shared-password JKS java "$(dirname -- "${BASH_SOURCE[0]}")/ReencodeAdminSecretKey.java" \ "$work/secret/..130712/admin-keystore" "$work/secret/..130712/admin-keystore.pin" project_secret 130712 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130708 echo 'Check that an RSA-PSS pair with a compatible TLS signature scheme can be installed' stop_container make_pss_secret 130713 sha384 48 # The TLS scheme uses 48 bytes even though the private key permits a shorter salt. java "$(dirname -- "${BASH_SOURCE[0]}")/ReencodeAdminSecretKey.java" \ "$work/secret/..130713/admin-keystore" "$work/secret/..130713/admin-keystore.pin" SHA-384 32 project_secret 130713 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130713 -tls1_2 verify_admin_certificate 130713 -tls1_3 echo 'Check that an RSA-PSS pair without a compatible TLS signature scheme preserves the installed pair' stop_container make_pss_secret 130714 sha256 48 project_secret 130714 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130713 echo 'Check that pending recovery also rejects an RSA-PSS pair without a compatible TLS signature scheme' stop_container edit_stopped_volume ' cd /opt/opendj/data/config mkdir -m 700 .admin-secret-pending install -m 600 /fixtures/..130714/admin-keystore /fixtures/..130714/admin-keystore.pin .admin-secret-pending/ ' start_container 0 verify_admin_certificate 130713 docker exec "$container" test ! -e /opt/opendj/data/config/.admin-secret-pending echo 'Check interrupted installation with a queued change and without a Secret mount' stop_container make_secret 130705 recovered-password JKS edit_stopped_volume ' cd /opt/opendj/data/config mkdir -m 700 .admin-secret-pending .admin-secret.stale1 install -m 600 /fixtures/..130705/admin-keystore admin-keystore install -m 600 /fixtures/..130705/admin-keystore.pin .admin-secret-pending/admin-keystore.pin install -m 600 /fixtures/..130704/admin-keystore /fixtures/..130704/admin-keystore.pin .admin-secret.stale1/ cat > config-changes.ldif <<EOF dn: cn=Administration Connector,cn=config changetype: modify replace: ds-cfg-ssl-cert-nickname ds-cfg-ssl-cert-nickname: admin-cert - EOF ' start_container 0 verify_admin_certificate 130705 docker exec "$container" sh -ec ' cd /opt/opendj/data/config test ! -e .admin-secret-pending test ! -e .admin-secret.stale1 test ! -e config-changes.ldif ' echo 'Check that a queued administration certificate nickname change preserves the installed pair' stop_container edit_stopped_volume ' cd /opt/opendj/data/config keytool -changealias -alias admin-cert -destalias custom-admin -storetype JKS \ -keystore admin-keystore -storepass:file admin-keystore.pin -keypass:file admin-keystore.pin mkdir -m 700 .admin-secret-pending install -m 600 /fixtures/..130703/admin-keystore /fixtures/..130703/admin-keystore.pin .admin-secret-pending/ cat > config-changes.ldif <<EOF dn: cn=Administration Connector,cn=config changetype: modify replace: ds-cfg-ssl-cert-nickname ds-cfg-ssl-cert-nickname: custom-admin - EOF ' project_secret 130703 start_container 0 "${secret_mount[@]}" verify_admin_certificate 130705 docker exec "$container" sh -ec ' cd /opt/opendj/data/config test ! -e config-changes.ldif test ! -e .admin-secret-pending ' echo 'Check that a reused volume keeps its configured administration certificate nickname' stop_container start_container 0 "${secret_mount[@]}" verify_admin_certificate 130705 .github/workflows/build.yml
@@ -858,6 +858,11 @@ docker exec test_secret sh -c '! cmp -s /var/secrets/opendj/keystore /opt/opendj/data/config/keystore' docker rm -f test_secret docker volume rm test_secret_data - name: Docker test administration certificate shell: bash env: IMAGE: localhost:5000/${{ env.image_repository }}:${{ env.release_version }}${{ matrix.suffix }} run: .github/scripts/docker-test-admin-certificate.sh "$IMAGE" - name: Docker test bootstrap LDIFs shell: bash run: | opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-change-certs.adoc
@@ -12,7 +12,7 @@ information: "Portions copyright [year] [name of copyright owner]". Copyright 2017 ForgeRock AS. Portions Copyright 2024-2026 3A Systems LLC. Portions Copyright 2024-2026 3A Systems, LLC. //// :figure-caption!: @@ -41,7 +41,7 @@ [NOTE] ====== When a volume is mounted at `SECRET_VOLUME` (`/var/secrets/opendj` by default), a container started from the Docker image copies the `key*` and `trust*` files of that volume, such as `keystore`, `keystore.pin`, `truststore` and `truststore.pin`, into its instance on every start, and by default also while the server runs, when they change. Replace the key pair that secures connections with client applications on that volume rather than in the instance, where the next copy would overwrite it. Only these files are copied: the `admin-keystore`, `admin-truststore` and `ads-truststore` of the administration connector and of replication stay in the instance, and are replaced there as described in this chapter. A renewed keystore is served without a restart only if it holds the key under an alias that the previous one used as well. See the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md#certificates[Certificates section of the README of the image, window=\_blank]. When a volume is mounted at `SECRET_VOLUME` (`/var/secrets/opendj` by default), the Docker image copies its `key*` and `trust*` files into the instance on every start. It installs the mounted `admin-keystore` and `admin-keystore.pin` only after verifying that the PIN opens the `admin-cert` private key. Update these files on the mounted volume. By default, the image checks the volume for changes while the server runs. Keep the existing key alias for a renewal to take effect on new TLS connections without a restart. The procedures in this chapter cover updating `admin-truststore` and `ads-truststore` directly in the instance. For the Secret layout and verification commands, see the link:https://github.com/OpenIdentityPlatform/OpenDJ/blob/master/opendj-packages/opendj-docker/README.md#certificates[Docker image certificate documentation, window=\_blank]. ====== OpenDJ uses keystores (for private keys) and truststores (for public, signed certificates). Up to three sets of keystores are used, as shown in the following illustration. @@ -60,10 +60,10 @@ Each keystore has a specific purpose: `admin-keystore`:: This Java Keystore holds the private key and administrative certificate for the server, `admin-cert`. This key pair is used to protect communications on the administration port. The password, stored in `admin-keystore.pin`, is also the key password for `admin-cert`. This keystore holds the private key and certificate chain for the administration port under the default alias `admin-cert`. It can be JKS or PKCS12. Use the password in `admin-keystore.pin` for the keystore and all its private key entries. `admin-truststore`:: This Java Keystore holds a copy of the administrative certificate, `admin-cert`. The password is the same as for the `admin-keystore`, in other words the string in `admin-keystore.pin`. Setup initializes this Java Keystore with a copy of the initial `admin-cert` and gives it the same password as the initial `admin-keystore`. For an existing `admin-truststore`, use its own password, set at creation or by its last password change. With a mounted Secret, `admin-keystore.pin` contains the password for the key pair supplied by the Secret. `ads-truststore`:: This Java Keystore holds public key certificates of all servers replicating with the current server. It also includes the `ads-certificate` key pair of the current server. The password is stored in `ads-truststore.pin`. @@ -91,6 +91,8 @@ ==== This procedure shows how to replace a server key pair in the `admin-keystore` and copy of the administrative certificate in `admin-truststore`. For an administration key pair managed by `SECRET_VOLUME`, replace the pair in the mounted Secret and configure administrative clients to trust the issuing CA in a client truststore. To continue maintaining the existing `admin-truststore`, retain its password before mounting a replacement PIN. The commands below prompt for the password of `admin-truststore`. The examples also apply when replacing a key pair in the `keystore` and copy of the server certificate in `truststore`. Just adapt the commands to use the correct keystore, truststore, and PIN file names. This procedure does not apply for replication key pairs. Instead, see xref:#replace-ads-cert["To Replace the Key Pair Used for Replication"]. @@ -110,7 +112,8 @@ admin-cert, May 20, 2015, PrivateKeyEntry, Certificate fingerprint (SHA1): 21:9F:F0:E8:A3:22:A3:62:1D:C7:04:BD:12:44:A6:FA:0C:3F:3A:35 $ keytool -list -keystore admin-truststore -storepass `cat admin-keystore.pin` $ keytool -list -keystore admin-truststore Enter keystore password: Keystore type: JKS Keystore provider: SUN @@ -137,8 +140,7 @@ $ keytool \ -delete \ -alias admin-cert \ -keystore admin-truststore \ -storepass `cat admin-keystore.pin` -keystore admin-truststore ---- . Generate a new key pair in the keystore: @@ -184,8 +186,8 @@ -import \ -alias admin-cert \ -keystore admin-truststore \ -storepass `cat admin-keystore.pin` \ -file admin-cert.crt Enter keystore password: Owner: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate Issuer: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate Serial number: 4cdd42a opendj-doc-generated-ref/src/main/asciidoc/admin-guide/chap-troubleshooting.adoc
@@ -12,7 +12,7 @@ information: "Portions copyright [year] [name of copyright owner]". Copyright 2017 ForgeRock AS. Portions Copyright 2024-2026 3A Systems LLC. Portions Copyright 2024-2026 3A Systems, LLC. //// :figure-caption!: @@ -434,14 +434,14 @@ $ grep ds-cfg-replication-server: config/config.ldif | sort | uniq ---- . Make sure that the host names in OpenDJ certificates also contain fully qualified host names, and correspond to the host names found in the previous step: . Make sure that the host names in the OpenDJ certificates are fully qualified and match the host names found in the previous step. For the administration connector, check the DNS subject alternative names (SANs) in the endpoint certificate. If the certificate has no DNS SANs, check the common name in its subject. Use the configured certificate alias in the command below. + [source, console] ---- # Examine the certificates used for the administration connector. $ keytool -list -v -keystore config/admin-truststore \ -storepass `cat config/admin-keystore.pin` |grep "^Owner:" # Examine the end-entity certificate configured for the administration connector. $ keytool -exportcert -rfc -alias admin-cert -keystore config/admin-keystore \ -storepass:file config/admin-keystore.pin | keytool -printcert -v # Examine the certificates used for replication. $ keytool -list -v -keystore config/ads-truststore \ @@ -456,9 +456,13 @@ ds-cfg-replication-server: opendj.example.com:8989 ds-cfg-replication-server: opendj.example.com:9989 $ keytool -list -v -keystore config/admin-truststore -storepass `cat config/admin-keystore.pin` | grep "^Owner:" Owner: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate $ keytool -exportcert -rfc -alias admin-cert -keystore config/admin-keystore \ -storepass:file config/admin-keystore.pin | keytool -printcert -v Owner: CN=OpenDJ Administration ... SubjectAlternativeName [ DNSName: opendj.example.com ] $ keytool -list -v -keystore config/ads-truststore \ -storepass `cat config/ads-truststore.pin`| grep "^Owner:" @@ -536,13 +540,13 @@ --no-prompt ---- . Check that the host names are correct in the configuration and in the keystores by following the steps you used to check for host name problems. The only broken host name remaining should be in the key and truststores for the administration connector: . Follow the earlier steps to check host names in the configuration and keystores, including the DNS SANs in the administration connector's certificate. + [source, console] ---- $ keytool -list -v -keystore config/admin-truststore \ -storepass `cat config/admin-keystore.pin` |grep "^Owner:" $ keytool -exportcert -rfc -alias admin-cert -keystore config/admin-keystore \ -storepass:file config/admin-keystore.pin | keytool -printcert -v ---- . Stop each server, and then fix the remaining admin connector certificate as described in xref:chap-change-certs.adoc#replace-key-pair["To Replace a Server Key Pair"]. opendj-packages/opendj-docker/AdminSecretValidator.java
New file @@ -0,0 +1,178 @@ /* * The contents of this file are subject to the terms of the Common Development and * Distribution License (the License). You may not use this file except in compliance with the * License. * * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the * specific language governing permission and limitations under the License. * * When distributing Covered Software, include this CDDL Header Notice in each file and include * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL * Header, with the fields enclosed by brackets [] replaced by your own identifying * information: "Portions copyright [year] [name of copyright owner]". * * Copyright 2026 3A Systems, LLC. */ import java.io.BufferedReader; import java.io.FileReader; import java.io.InputStream; import java.nio.file.Files; import java.nio.file.Path; import java.security.GeneralSecurityException; import java.security.InvalidKeyException; import java.security.KeyStore; import java.security.PrivateKey; import java.security.PublicKey; import java.security.Signature; import java.security.cert.CertificateException; import java.security.cert.X509Certificate; import java.security.spec.MGF1ParameterSpec; import java.security.spec.PSSParameterSpec; import java.util.Arrays; import java.util.Collections; import java.util.List; import java.util.Set; import javax.net.ssl.KeyManagerFactory; /** Checks whether a staged keystore can supply the default administration TLS key. */ public final class AdminSecretValidator { private static final String ADMIN_ALIAS = "admin-cert"; private static final Set<String> TLS_SERVER_USAGES = Set.of( "1.3.6.1.5.5.7.3.1", "2.5.29.37.0", // serverAuth and anyExtendedKeyUsage "1.3.6.1.4.1.311.10.3.3", "2.16.840.1.113730.4.1"); // Legacy server-gated cryptography, accepted by JSSE. // JSSE's TLS 1.2 and 1.3 RSA-PSS schemes use a salt exactly as long as the digest. private static final List<PSSParameterSpec> TLS_PSS_PARAMETERS = List.of( new PSSParameterSpec("SHA-256", "MGF1", MGF1ParameterSpec.SHA256, 32, PSSParameterSpec.TRAILER_FIELD_BC), new PSSParameterSpec("SHA-384", "MGF1", MGF1ParameterSpec.SHA384, 48, PSSParameterSpec.TRAILER_FIELD_BC), new PSSParameterSpec("SHA-512", "MGF1", MGF1ParameterSpec.SHA512, 64, PSSParameterSpec.TRAILER_FIELD_BC)); public static void main(String[] args) throws Exception { final char[] pin; try (BufferedReader reader = new BufferedReader(new FileReader(args[1]))) { final String firstLine = reader.readLine(); if (firstLine == null) { throw new IllegalArgumentException("The administration PIN file has no first line"); } pin = firstLine.toCharArray(); } try { final KeyStore store = KeyStore.getInstance("JKS"); try (InputStream input = Files.newInputStream(Path.of(args[0]))) { store.load(input, pin); } if (!store.entryInstanceOf(ADMIN_ALIAS, KeyStore.PrivateKeyEntry.class)) { throw new IllegalArgumentException("The administration keystore has no admin-cert private key"); } final KeyManagerFactory factory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()); factory.init(store, pin); factory.getKeyManagers(); // The key manager loads every key with the same PIN. Only the configured alias // needs to sign, since it is the one selected for administration TLS. final PrivateKey key = (PrivateKey) store.getKey(ADMIN_ALIAS, pin); verifyAdminCertificate(key, (X509Certificate) store.getCertificate(ADMIN_ALIAS)); } finally { Arrays.fill(pin, '\0'); } } private static void verifyAdminCertificate(PrivateKey key, X509Certificate certificate) throws GeneralSecurityException { final PublicKey certificateKey = certificate.getPublicKey(); // JSSE requires both keys to match the negotiated authentication type. if (!key.getAlgorithm().equals(certificateKey.getAlgorithm())) { throw new GeneralSecurityException("The admin-cert private key and certificate use different algorithms"); } final boolean[] keyUsage = certificate.getKeyUsage(); if (keyUsage != null && (keyUsage.length == 0 || !keyUsage[0])) // digitalSignature is the first bit. { throw new CertificateException("The admin-cert certificate does not allow digital signatures"); } final List<String> extendedKeyUsage = certificate.getExtendedKeyUsage(); if (extendedKeyUsage != null && Collections.disjoint(extendedKeyUsage, TLS_SERVER_USAGES)) { throw new CertificateException("The admin-cert certificate does not allow TLS server authentication"); } if ("RSASSA-PSS".equals(key.getAlgorithm())) { if (!matchesTlsPssSignature(key, certificateKey)) { throw new GeneralSecurityException("The admin-cert key and certificate do not match a TLS RSA-PSS scheme"); } } else if (!matchesSignature(signatureFor(key), key, certificateKey)) { throw new GeneralSecurityException("The admin-cert private key does not match its certificate"); } } private static boolean matchesTlsPssSignature(PrivateKey key, PublicKey certificateKey) throws GeneralSecurityException { for (PSSParameterSpec parameters : TLS_PSS_PARAMETERS) { final Signature signature = Signature.getInstance("RSASSA-PSS"); signature.setParameter(parameters); try { if (matchesSignature(signature, key, certificateKey)) { return true; } } catch (InvalidKeyException e) { // Either key can restrict the digest or the minimum salt length. Try the next TLS scheme. } } return false; } private static boolean matchesSignature(Signature signature, PrivateKey key, PublicKey certificateKey) throws GeneralSecurityException { signature.initSign(key); signature.update((byte) 0); final byte[] signed = signature.sign(); signature.initVerify(certificateKey); signature.update((byte) 0); return signature.verify(signed); } private static Signature signatureFor(PrivateKey key) throws GeneralSecurityException { switch (key.getAlgorithm()) { case "RSA": return Signature.getInstance("SHA256withRSA"); case "EC": return Signature.getInstance("SHA256withECDSA"); case "DSA": return Signature.getInstance("SHA256withDSA"); case "EdDSA": case "Ed25519": case "Ed448": return Signature.getInstance(key.getAlgorithm()); default: throw new GeneralSecurityException("The admin-cert key does not support signing: " + key.getAlgorithm()); } } } opendj-packages/opendj-docker/Dockerfile
@@ -12,6 +12,11 @@ # # Copyright 2018-2026 3A Systems, LLC. FROM --platform=$BUILDPLATFORM eclipse-temurin:25-jdk-noble AS admin-secret-validator WORKDIR /build COPY AdminSecretValidator.java . RUN javac --release 11 AdminSecretValidator.java FROM eclipse-temurin:25-jre-noble LABEL org.opencontainers.image.authors="Open Identity Platform Community" @@ -82,6 +87,7 @@ # that is only in group 0, and that uid still has to write instance.loc and the instance # root. The scripts copied below are only read and run, so they just keep the same group. COPY --chown=$OPENDJ_USER:0 bootstrap/ /opt/opendj/bootstrap/ COPY --from=admin-secret-validator /build/AdminSecretValidator.class /opt/opendj/bootstrap/ COPY --chown=$OPENDJ_USER:0 run.sh /opt/opendj/run.sh COPY --chown=$OPENDJ_USER:0 healthcheck.sh /opt/opendj/healthcheck.sh opendj-packages/opendj-docker/Dockerfile-alpine
@@ -12,6 +12,11 @@ # # Copyright 2018-2026 3A Systems, LLC. FROM --platform=$BUILDPLATFORM eclipse-temurin:25-jdk-noble AS admin-secret-validator WORKDIR /build COPY AdminSecretValidator.java . RUN javac --release 11 AdminSecretValidator.java FROM alpine:latest LABEL org.opencontainers.image.authors="Open Identity Platform Community" @@ -82,6 +87,7 @@ # that is only in group 0, and that uid still has to write instance.loc and the instance # root. The scripts copied below are only read and run, so they just keep the same group. COPY --chown=$OPENDJ_USER:0 bootstrap/ /opt/opendj/bootstrap/ COPY --from=admin-secret-validator /build/AdminSecretValidator.class /opt/opendj/bootstrap/ COPY --chown=$OPENDJ_USER:0 run.sh /opt/opendj/run.sh COPY --chown=$OPENDJ_USER:0 healthcheck.sh /opt/opendj/healthcheck.sh opendj-packages/opendj-docker/README.md
@@ -1,6 +1,6 @@ # How-to: Build docker image: Build the Docker image with BuildKit enabled so the keystore validator can be compiled on the build host. ```bash docker build -t openidentityplatform/opendj . @@ -330,8 +330,7 @@ one renewal to the next. A keystore with only new aliases is served from the next restart, and until then the server logs that it could not load it. So does a keystore caught by a handshake between its copy and that of its `.pin` file, until the second file is copied as well. The administration connector and replication keep keys of their own and are not affected. well. The administration connector uses a separate keystore described below. On Kubernetes, the PEM files of a `kubernetes.io/tls` Secret cannot be used as they are: OpenDJ reads keystores, not PEM. cert-manager can add a PKCS12 keystore to the Secret it @@ -366,6 +365,92 @@ Mount the volume as a whole, not with `subPath`: Kubernetes does not update files mounted with `subPath` when the Secret changes. ### Administration connector certificate For the default administration connector configuration (port 4444), mount both of these files at `SECRET_VOLUME`. The image leaves the persisted files in place when the instance uses a custom administration key manager, keystore configuration, or certificate nickname. If startup configuration changes are queued in `config-changes.ldif`, the image defers installation. A later refresh or restart checks the resulting configuration. - `admin-keystore` is a JKS or PKCS12 keystore containing the private key and its certificate chain. Use the default alias `admin-cert` and include the DNS names that administrative clients use in the certificate's subject alternative names. - `admin-keystore.pin` contains the keystore password on its first line. Use that password for every private key entry in the keystore. Before the server starts, the image verifies that the PIN opens the keystore and its private keys, and that `admin-cert` has a signing key and a matching certificate whose usage permits TLS server authentication. It installs the validated pair in `/opt/opendj/data/config` with mode 0600 on both fresh and reused volumes. If the mounted pair fails validation, the image logs a warning and keeps the current files. On a fresh volume those files contain the self-signed certificate created by setup. Clients trust the issuing CA through their own truststore. Replication uses its own `ads-truststore`. For a [cert-manager Certificate](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.JKSKeystore), request a JKS keystore with the required alias. This example requires cert-manager 1.15 or later and its matching CRDs. For this JKS example, use a single-line ASCII password with no carriage return or line feed in the Secret. The pod template projects the generated keystore and the password into the same directory. If the pod already has a projected `SECRET_VOLUME`, add these sources to it. ```yaml # Certificate spec spec: secretName: opendj-admin-tls dnsNames: [opendj.example.com] keystores: jks: create: true alias: admin-cert passwordSecretRef: { name: opendj-admin-password, key: password } --- # StatefulSet pod template spec volumes: - name: secrets projected: sources: - secret: name: opendj-admin-tls items: [{ key: keystore.jks, path: admin-keystore }] - secret: name: opendj-admin-password items: [{ key: password, path: admin-keystore.pin }] containers: - name: opendj volumeMounts: - { name: secrets, mountPath: /var/secrets/opendj, readOnly: true } ``` Keep the `admin-cert` alias and the same keystore password for routine certificate renewals. After Kubernetes projects the renewed Secret, the next `SECRET_VOLUME_REFRESH` check validates and installs the pair. New TLS connections use the renewed certificate without a rollout. To rotate the password in this two-Secret setup, update the password Secret and trigger reissuance with [`cmctl renew`](https://cert-manager.io/docs/reference/cmctl/#renew). The pod can see the new password before cert-manager publishes the matching JKS. OpenDJ keeps the installed pair during that interval. Wait for cert-manager to publish the new JKS and Kubernetes to project both files, then verify the renewed certificate. With `SECRET_VOLUME_REFRESH=0`, roll the pods after both files are ready, then verify the certificate. To verify the renewal, compare the served serial number with the renewed certificate and run a read-only administrative command. The example uses the issuing CA certificate (`ca.pem`), a client JKS truststore (`admin-ca.jks`) containing that CA, and local password files for the bind account and client truststore. ```bash openssl s_client -connect opendj.example.com:4444 -servername opendj.example.com \ -verify_hostname opendj.example.com -verify_return_error -CAfile ca.pem </dev/null | openssl x509 -noout -serial -dates dsconfig get-administration-connector-prop --hostname opendj.example.com --port 4444 \ --bindDN 'cn=Directory Manager' --bindPasswordFile root-password \ --trustStorePath admin-ca.jks --trustStorePasswordFile truststore.pin --no-prompt ``` ## Environment Variables | Variable | Default Value | Description | @@ -377,7 +462,7 @@ | BASE_DN | dc=example,dc=com | OpenDJ Base DN | | ROOT_USER_DN | cn=Directory Manager | Initial root user DN | | ROOT_PASSWORD | password | Initial root user password; the bootstrap fails if it contains a line break (CR or LF) | | SECRET_VOLUME | /var/secrets/opendj | Mounted keystore volume, if present its `key*` and `trust*` files are copied into the instance on every start, see [Certificates](#certificates) | | SECRET_VOLUME | /var/secrets/opendj | Mounted volume for LDAP and administration keystores, see [Certificates](#certificates) | | SECRET_VOLUME_REFRESH | 60 | While the server runs, `SECRET_VOLUME` is checked again every that many seconds and changed files are copied again; `0` copies them on start only | | MASTER_SERVER | - | Replication master server; with `simple` it works as a one-element `REPLICATION_PEERS` | | REPLICATION_PEERS | value of MASTER_SERVER | every server of the replication topology by DNS name, comma separated; the first entry may seed a new topology, and servers no longer listed are removed from it, see [Replication](#replication) | @@ -396,4 +481,4 @@ | BACKEND_DB_DIRECTORY | db | OpenDJ `db-directory` attribute for backend | | SETUP_ARGS | - | extra setup args | | HEALTHCHECK_BIND_DN | - | DN the health check binds as, for an instance that rejects unauthenticated requests; unset, the health check searches the root DSE anonymously | | HEALTHCHECK_BIND_PASSWORD_FILE | - | file in the container holding the password of `HEALTHCHECK_BIND_DN` | | HEALTHCHECK_BIND_PASSWORD_FILE | - | file in the container holding the password of `HEALTHCHECK_BIND_DN` | opendj-packages/opendj-docker/pom.xml
@@ -81,6 +81,7 @@ <include name="Dockerfile*" /> <include name="../opendj-openshift-template/*.yaml" /> <include name="bootstrap/**" /> <include name="AdminSecretValidator.java" /> <include name="run.sh" /> <include name="healthcheck.sh" /> </fileset> opendj-packages/opendj-docker/run.sh
@@ -11,7 +11,7 @@ # Header, with the fields enclosed by brackets [] replaced by your own identifying # information: "Portions copyright [year] [name of copyright owner]". # # Portions copyright 2026 3A Systems, LLC. # Portions Copyright 2026 3A Systems, LLC. # Run the OpenDJ server # The idea is to consolidate all of the writable DJ directories to @@ -113,10 +113,9 @@ # checked again every that many seconds; 0 checks it on start only SECRET_VOLUME_REFRESH=${SECRET_VOLUME_REFRESH:-60} # Copies the key* and trust* files of the secret volume that differ from those in # ./data/config. Each one is written next to its target and renamed over it, so the server # never reads a file half copied, and it is readable by the server's user only: a keystore # holds the private key, a .pin file its password. Succeeds when it copied a file. # Copies the LDAP keystores, truststores and PIN files that differ from those in ./data/config. # Each file is written next to its target and renamed over it, with mode 0600. # Succeeds when it copied a file. copy_secrets() { local src dst tmp copied=1 [ -d "$SECRET_VOLUME" ] || return 1 @@ -135,12 +134,125 @@ return $copied } # A pending directory contains a staged pair. Validate it before either file moves. # Moving each file out of the directory records progress on the same volume, so a # restart between the two renames can finish the installation. ADMIN_SECRET_PENDING=./data/config/.admin-secret-pending clean_admin_secret_staging() { local staged for staged in ./data/config/.admin-secret.??????; do [ -d "$staged" ] && [ ! -L "$staged" ] || continue if ! rm -f -- "$staged/admin-keystore" "$staged/admin-keystore.pin" || ! rmdir -- "$staged"; then echo "Could not remove abandoned administration Secret staging directory $staged" >&2 fi done } install_pending_admin_secret() { local name discarded rejection= [ -d "$ADMIN_SECRET_PENDING" ] || return 0 # Both files still staged means the live pair is intact. Once the keystore # has moved, finish installing its PIN even if the configuration has changed. if [ -f "$ADMIN_SECRET_PENDING/admin-keystore" ] && [ -f "$ADMIN_SECRET_PENDING/admin-keystore.pin" ]; then if ! java -cp ./bootstrap AdminSecretValidator \ "$ADMIN_SECRET_PENDING/admin-keystore" "$ADMIN_SECRET_PENDING/admin-keystore.pin" \ </dev/null >/dev/null 2>&1; then rejection="the store must open as JKS or PKCS12, use that PIN for every private key," rejection+=" and contain a signing key and matching TLS server certificate for admin-cert" elif [ -e ./data/config/config-changes.ldif ] || ! uses_default_admin_keystore; then rejection="it no longer matches the instance configuration" fi if [ -n "$rejection" ]; then echo "Discarding the staged administration Secret: $rejection" >&2 # Remove the transaction marker before deleting either staged file. if ! discarded=$(mktemp -d ./data/config/.admin-secret.XXXXXX) || ! mv -fT -- "$ADMIN_SECRET_PENDING" "$discarded"; then echo "Could not move the rejected administration Secret out of the pending directory" >&2 return 1 fi clean_admin_secret_staging return 0 fi fi for name in admin-keystore admin-keystore.pin; do if [ -f "$ADMIN_SECRET_PENDING/$name" ] && ! mv -fT -- "$ADMIN_SECRET_PENDING/$name" "./data/config/$name"; then echo "Could not install $name from the staged administration Secret" >&2 return 1 fi done rmdir -- "$ADMIN_SECRET_PENDING" || return 1 echo "Installed the administration keystore and PIN from the staged Secret" } # Only manage the files used by the default administration key manager and nickname. uses_default_admin_keystore() { local config connector provider connector='(&(objectClass=ds-cfg-administration-connector)(ds-cfg-key-manager-provider=cn=Administration,cn=Key Manager Providers,cn=config))' provider='(&(objectClass=ds-cfg-file-based-key-manager-provider)(ds-cfg-enabled=true)(ds-cfg-key-store-type=JKS)' provider+='(ds-cfg-java-class=org.opends.server.extensions.FileBasedKeyManagerProvider)' provider+='(!(ds-cfg-key-store-pin-property=*))(!(ds-cfg-key-store-pin-environment-variable=*)))' # Read both entries from the same snapshot of the instance configuration. config=$(./bin/ldifsearch -b cn=config ./data/config/config.ldif "(|$connector$provider)" \ ds-cfg-ssl-cert-nickname ds-cfg-key-store-file ds-cfg-key-store-pin-file 2>/dev/null) || return 1 awk ' BEGIN { connector = "dn: cn=administration connector,cn=config" provider = "dn: cn=administration,cn=key manager providers,cn=config" } /^dn: / { dn = tolower($0) } dn == connector && /^ds-cfg-ssl-cert-nickname:/ { nicknames++ nickname = $0 } dn == provider && /^ds-cfg-key-store-file:/ { store = $0 } dn == provider && /^ds-cfg-key-store-pin-file:/ { pin = $0 } END { exit !(nicknames == 1 && nickname == "ds-cfg-ssl-cert-nickname: admin-cert" && store == "ds-cfg-key-store-file: config/admin-keystore" && pin == "ds-cfg-key-store-pin-file: config/admin-keystore.pin") } ' <<< "$config" } sync_admin_secret() { local store="$SECRET_VOLUME/admin-keystore" pin="$SECRET_VOLUME/admin-keystore.pin" staged install_pending_admin_secret || return 1 [ -f "$store" ] && [ -f "$pin" ] || return 0 if cmp -s "$store" ./data/config/admin-keystore && cmp -s "$pin" ./data/config/admin-keystore.pin; then return 0 fi if ! staged=$(mktemp -d ./data/config/.admin-secret.XXXXXX); then echo "Could not stage the administration Secret" >&2 return 0 fi # The mounted files can change independently. Stage the exact bytes to be validated and installed. if ! install -m 600 -- "$store" "$staged/admin-keystore" || ! install -m 600 -- "$pin" "$staged/admin-keystore.pin"; then echo "Could not stage the administration keystore and PIN" >&2 elif mv -T -- "$staged" "$ADMIN_SECRET_PENDING"; then install_pending_admin_secret return $? fi rm -f -- "$staged/admin-keystore" "$staged/admin-keystore.pin" rmdir -- "$staged" return 0 } # The files are compared one at a time, so a Secret updated in the middle of a pass can leave # a keystore of one version next to the .pin of the other. Passes are repeated until one finds # nothing left to copy, which puts the files of a single version back together. # nothing left to copy, which puts the LDAP files of a single version back together. sync_secrets() { local passes=0 while copy_secrets && [ $((passes += 1)) -lt 5 ]; do :; done sync_admin_secret } # The server loads a keystore or truststore again, together with its .pin file, on the first @@ -160,7 +272,7 @@ start_server() { if [ -d "$SECRET_VOLUME" ]; then echo "Secret volume is present. Will copy any keystores and truststore" sync_secrets sync_secrets || exit 1 if [[ $SECRET_VOLUME_REFRESH =~ ^[0-9]+$ ]] && [ "$SECRET_VOLUME_REFRESH" -gt 0 ]; then watch_secrets & elif ! [[ $SECRET_VOLUME_REFRESH =~ ^0+$ ]]; then @@ -179,6 +291,8 @@ # Instance dir does exist? We start opendj without detach if [ -d ./data/config ]; then clean_admin_secret_staging install_pending_admin_secret || exit 1 # nothing is bootstrapped here, the instance is already there - but a half-migrated one # is not ready to serve either, so the marker follows the upgrade if [ -f "$BOOTSTRAP_PENDING" ]; then