Skip to content

Secure keystores with filesystem acl, use pkcs12 - #422

Open
mgaffigan wants to merge 14 commits into
OpenIntegrationEngine:mainfrom
mgaffigan:fix/keystore-privs
Open

mgaffigan wants to merge 14 commits into
OpenIntegrationEngine:mainfrom
mgaffigan:fix/keystore-privs

Conversation

@mgaffigan

Copy link
Copy Markdown
Contributor

Related to #307

Sets default access controls for key material created on first boot to only be accessible to the owner (600-equivalent):

Posix:

# ls -al server/setup/appdata/keystore.jks
-rw-------@ 1 user  staff  3973 Aug 26 17:23 server/setup/appdata/keystore.jks

Windows:

PS C:\drop\setup> icacls .\appdata\keystore.jks
.\appdata\keystore.jks COMPUTER\mirthuser:(F)

Successfully processed 1 files; Failed processing 0 files
PS C:\drop\setup>

Removes the 81uWxplDtB password in favor of a password-less PKCS12 (pfx) file instead of the deprecated jks format for new installs. Upgrades retain their prior password.

@github-actions

github-actions Bot commented Aug 26, 2026 •

Copy link
Copy Markdown

Test Results

  145 files  +1    145 suites  +1   4m 14s ⏱️ +38s
  979 tests +9    977 ✅ +7  2 💤 +2  0 ❌ ±0 
1 261 runs  +9  1 253 ✅ +7  8 💤 +2  0 ❌ ±0 

Results for commit 399776b. ± Comparison against base commit 11695df.

♻️ This comment has been updated with latest results.

@jonbartels jonbartels left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is making my brain itch. I feel like there could be some cyclic problem, maybe with containers? where the keystore is generated and a PW set, then the keystore is retained as a file (like if appdata is a persistent volume) but the generated keystore pass isn't retained because conf isnt in a persistent volume and the env var isn't set.

Instinctively - I'd document this, but theres a massive curse of knowledge problem because I am intimate with my keystores but a more casual, first-time user won't know how to process the big error

# no longer a password to pin here. Keystores created by earlier versions are JCEKS and were pinned
# to 'changeme', so keep those settings when one is already present in appdata.
KEYSTORE_FILE="$APP_DIR/appdata/keystore.jks"
if [ -f "$KEYSTORE_FILE" ] && [ "$(head -c 4 "$KEYSTORE_FILE" | od -An -tx1 | tr -d '[:space:]')" = "cececece" ]; then

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Explan what this is checking and how it knows its a jceks?

@mgaffigan mgaffigan Aug 27, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a dirty hack suggested to me by AI. It's checking if the first 4 bytes of the file are cececece - which is the magic signature for a JCEKS keystore (the legacy format that would require the "changeme" default password).

TL;DR: backcompat hack.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed it in favor of a filename check.

Comment thread server/conf/mirth.properties Resolved

keyStore.load(null, keyStorePassword);
logger.debug("keystore file not found, created new one");
FilePermissionUtil.createOwnerOnlyFile(keyStoreFile);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A failed first boot leaves an empty keystore that blocks every later boot.
Tthe new createOwnerOnlyFile call creates keystore.pfx before the encryption key and default certificate are generated and written. Before this PR, the file was only created just before writing.
If key or certificate setup throws (for example, a bad encryption setting), the error is only logged and a 0-byte keystore.pfx stays on disk. On the next start the file exists, loading it fails, and security setup fails on every boot until someone deletes the file by hand.
Fix: create the owner-only file right before writing, or delete it when setup fails.

@tonygermano tonygermano left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great foundation! I've got suggestions for several commits to layer on top of this at eef989c...cdfafce

This also addresses the issue that Nico raised.

I have not yet tested building and running on windows.

mgaffigan and others added 10 commits November 19, 2026 01:25
Signed-off-by: Mitch Gaffigan <mitch.gaffigan@comcast.net>
Signed-off-by: Mitch Gaffigan <mitch.gaffigan@comcast.net>
Add SPDX headers to the new FilePermissionUtil, WindowsFilePermissionUtil
and FilePermissionUtilTest files, and drop an unused import from
DefaultConfigurationController.

Reword the keystore comment in mirth.properties. It now says that the
keystore is protected by file permissions on every platform, not just
"chmod 600", and that keeping a JCEKS keystore means setting the path,
both passwords and the type, not the type alone.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
…sources

Updated `DefaultConfigurationController.initializeSecuritySettings` to
use `java.nio.file.Path` and `Files` in place of legacy `java.io.File`,
and changed `FilePermissionUtil.createOwnerOnlyFile` and its tests to
take a `Path` to match.

Key changes and benefits:
- Replaced `FileInputStream` and `FileOutputStream` with `Files.newInputStream`
  and `Files.newOutputStream`.
- Implemented try-with-resources, removing boilerplate `finally` blocks
  and `ResourceUtil.closeResourceQuietly` calls.
- Fixed a silent failure risk: exceptions thrown during the output stream's
  `close()` operation (e.g., when flushing to a full disk) are now properly
  caught and logged instead of being swallowed.
- Leveraged modern `Path.of()` for path instantiation.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
The Windows test matched account names in icacls output, which Windows
translates into the display language, so it was skipped on non-English
systems. Its user.language check also did not reliably match the
language icacls prints in.

Read the file's ACL through JNA instead and compare SIDs, which are the
same in every language. The test now requires exactly the expected
entries (the current user, LocalSystem and Administrators, each with
full control and none inherited) rather than ruling out a few names.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
The default keystore path changed from keystore.jks to keystore.pfx.
If an existing appdata directory is used with a fresh mirth.properties,
the server would not find keystore.pfx and would create a new keystore
with a new encryption key, leaving anything already encrypted in the
database unreadable. Before this change, the mismatched password made
that case fail loudly instead.

When the configured keystore is missing but appdata/keystore.jks
exists, fail security initialization with a message that says which
settings to fix, rather than creating a new keystore.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
…-env

The keystore is now protected by file permissions rather than a
password, but a keystore fetched with KEYSTORE_DOWNLOAD was written
using the default umask. Download it with umask 077, and chmod it
afterwards in case an existing file was overwritten. A failed chmod
only warns, so it cannot stop the container from starting.

Also drop the unused KEYSTORE_FILE variable, and log whether an
existing keystore or KEYSTORE_DOWNLOAD caused the switch to the JCEKS
settings.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
* Write the keystore to an owner-only temp file in the same directory and
  atomically move it into place, so a failure part way through can no
  longer leave an empty or truncated keystore that prevents startup.
  Because the file is replaced, a rewritten keystore always ends up with
  owner-only permissions, even if they were changed by hand.
* Only write the keystore when it is new or an entry was added, instead
  of rewriting an unchanged keystore on every startup.
* Replace the target of a symlinked keystore rather than the link itself.
* Document that FilePermissionUtil.createOwnerOnlyFile throws
  FileAlreadyExistsException if the file already exists.
* Add tests for creating missing parent directories and for
  FileAlreadyExistsException.
* Replace the license header of DefaultConfigurationController with SPDX
  identifiers.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
initializeSecuritySettings sets up the encryptor, and puts the key in
the encryption settings it sends to the Administrator, before the
keystore is written. If a new encryption key is generated and writing
the keystore then fails, the error was only logged and the server kept
encrypting data with a key that would be gone after a restart, leaving
that data unreadable. The Administrator would also encrypt exports with
that key.

When storing the keystore fails and the encryption key is new, clear the
encryptor and the key in the encryption settings, so the failure leaves
the server and its clients without encryption, the same as any other
failure to initialize security settings.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
WindowsFilePermissionUtil passes the path to CreateFile as is. The
Win32 file APIs reject paths longer than MAX_PATH (260 characters)
unless they use the \\?\ extended-length form, which java.nio adds for
its own calls but JNA does not, so creating a keystore under a deeply
nested appdata directory is expected to fail.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
CreateFile rejects paths longer than MAX_PATH (260 characters) unless
they are in the \\?\ extended-length form. java.nio adds that prefix
for its own calls, but the path passed to CreateFile through JNA did not
have it, so a keystore under a deeply nested appdata directory could
not be created.

Pass CreateFile the extended-length form of the path, using \\?\UNC\
for UNC paths. Because that form turns off the handling of "." and "..",
normalize the absolute path first.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
On main, keystore.path could be a symlink to a file that didn't exist
yet: FileOutputStream followed the link and created the target. Since
the keystore is written to a temp file and moved into place, the link
was resolved with Path.toRealPath, which fails with NoSuchFileException
when the target doesn't exist, so the first start failed.

Follow the link, and any links it leads to, with
Files.readSymbolicLink instead, so the target need not exist. The new
target is created with owner-only permissions, and a cycle of links
fails after 40 steps rather than looping forever.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
The keystore is written to a temp file and renamed over the old one,
but nothing made sure the contents were on disk first. After a crash
or power loss, some filesystems can then leave an empty file in place
of the keystore, and the first write is the one that carries a newly
generated encryption key.

Write the temp file through a FileChannel and force it to disk before
the move, then flush the directory so the rename itself is kept.
Flushing a directory isn't possible on every platform, such as
Windows, and the keystore is already in place by then, so a failure
there is only logged at debug level.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>
When KEYSTORE_DOWNLOAD replaces an existing keystore.jks, curl keeps
the file's mode, so a file that was readable by others held the
downloaded keystore until the chmod after the download. Restrict the
existing file before downloading instead. A new file is still created
with umask 077, so the chmod afterwards is no longer needed.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Tony Germano <tony@germano.name>

@tonygermano tonygermano left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mgaffigan I've pushed the follow-up commits I mentioned earlier straight to fix/keystore-privs, so they're now part of this PR. To resolve a conflict with the configuration map tests that landed on main, I rebased the whole branch, including your two commits, onto current main and force-pushed it. The contents of your commits are unchanged. Please reset your local branch to the pushed one before you push again, so these commits aren't lost.

They're 12 separate commits so each one can be reviewed on its own:

  1. Add SPDX headers and fix keystore comments and imports: SPDX headers on the new files, an unused import removed, and the mirth.properties comment reworded. Keeping a JCEKS keystore means setting the path, both passwords and the type, not just the type.
  2. Modernize keystore file handling with NIO.2 and try-with-resources: initializeSecuritySettings and FilePermissionUtil.createOwnerOnlyFile now use Path/Files. An exception from closing the output stream (for example, a full disk) is no longer swallowed.
  3. Make FilePermissionUtilTest independent of the Windows display language: the test reads the ACL through JNA and compares SIDs instead of matching account names in icacls output, so it also runs on non-English Windows. It now requires exactly the current user, SYSTEM and Administrators, each with full control and none inherited.
  4. Refuse to create a new keystore when a legacy keystore.jks exists: if an existing appdata is used with a fresh mirth.properties, the server used to create a new keystore.pfx with a new encryption key, which made data that was already encrypted unreadable. Now it fails security initialization and the message names the settings to fix.
  5. Restrict permissions on a downloaded keystore and tidy configure-from-env: KEYSTORE_DOWNLOAD downloads with umask 077 and then runs chmod 600. If the chmod fails, it only warns. The unused KEYSTORE_FILE is removed, and the log says why the JCEKS defaults were chosen.
  6. Write keystore atomically and only when it changes: the keystore is written to an owner-only temp file and atomically moved into place, so a failed write can't leave a truncated keystore. Because the file is replaced, it always ends up owner-only. It's only written when it's new or an entry was added, instead of on every startup. This supersedes #134, which can be closed once this PR is merged. A symlinked keystore has its target replaced, not the link.
  7. Don't run with an encryption key that couldn't be saved: if a new encryption key is generated but the keystore can't be written, the encryptor is cleared, along with the key in the encryption settings that the Administrator uses to encrypt exports. Otherwise the server would encrypt data with a key that's gone after a restart.
  8. Test creating an owner-only file with a long path on Windows: this failed on Windows with "The system cannot find the path specified".
  9. Support long paths when creating an owner-only file on Windows: the path is passed to CreateFile in the \\?\ (or \\?\UNC\) extended-length form, after it's normalized.
  10. Create the keystore behind a symlink whose target doesn't exist yet: this worked on main, but Files.createFile in your first commit and then toRealPath() in the atomic write (6) broke it. The link is now followed with Files.readSymbolicLink, so the target is created with owner-only permissions. A cycle of links fails after 40 steps.
  11. Flush the keystore to disk before moving it into place: the temp file is written through a FileChannel and forced to disk before the move, and then the directory is flushed. Otherwise a crash or power loss right after the move could leave an empty keystore on some filesystems. Windows can't flush a directory, so that step only logs a debug message there.
  12. Restrict an existing keystore before downloading over it: when KEYSTORE_DOWNLOAD replaces a keystore.jks that's readable by others, its permissions are restricted before the download instead of after, because curl keeps the existing file's mode.

Manual testing

Every check passed. The checklist says which checks I ran on Windows and which Claude ran on Linux and in Docker.

Checklist

Commits are named by their subjects, because the branch will likely be rebased again before it's merged. Most of my Windows checks ran on an earlier version of the branch that ended at "Support long paths when creating an owner-only file on Windows"; the last item below I rechecked on the full branch. Claude's Linux and Docker checks ran on the full branch, before its last rebase onto main, with the same keystore code. The full build passed again after that rebase.

I checked on Windows

  • FilePermissionUtilTest ran on Windows, and testWindowsPermissions passed (it ran and wasn't skipped).
  • Fresh start as a non-admin user: keystore.pfx was created, and its file properties show only that user, SYSTEM and Administrators, each with full control and none inherited.
  • Started as LocalSystem (psexec, then oieserver.ps1): icacls shows only NT AUTHORITY\SYSTEM and BUILTIN\Administrators, both with full control and not inherited.
  • Existing keystore.jks with a fresh mirth.properties: the server didn't create keystore.pfx.
  • Rewriting an existing keystore: after deleting the mirthconnect alias with keytool, the certificate was regenerated on startup and no keystore.pfx.tmp was left behind.
  • Read-only keystore with the mirthconnect alias deleted: logged "Could not initialize security settings" with an AccessDeniedException, and left no temp keystore. Clearing the read-only flag and restarting fixed it.
  • Keystore locked by another process (opened with FileShare.None) with the alias deleted: logged "Could not initialize security settings" with a FileSystemException, then "Could not start web server" with a FileNotFoundException. No temp keystore was left. Releasing the lock and restarting fixed it.
  • Keystore path longer than 260 characters: testWindowsLongPath failed with "The system cannot find the path specified" at "Test creating an owner-only file with a long path on Windows", and passed after "Support long paths when creating an owner-only file on Windows".
  • On the full branch, after "Flush the keystore to disk before moving it into place" changed how the keystore is written (through a FileChannel flushed to disk, then flushing the directory, which Windows doesn't allow, so only a debug message is logged): a fresh start, and regenerating a deleted mirthconnect certificate, both worked.

Claude checked on Linux

These ran against the built server/setup, with encryption.properties = 1 and a database password set, so the server stores encrypted data that depends on the keystore's key.

  • Fresh start: keystore.pfx is mode 600, contains the encryption and mirthconnect entries, and HTTPS answers. database.password in mirth.properties was encrypted.
  • Restart with an unchanged keystore: keystore.pfx keeps its timestamp and inode, HTTPS answers, and nothing is logged as an error.
  • Missing certificate: after deleting mirthconnect with keytool and loosening the file to 644, the next start regenerated the certificate, kept the same encryption key, set the file back to 600 and left no temp file.
  • Symlinked keystore: with keystore.path pointing at a symlink and the certificate deleted, the next start replaced the file the link points to (mode 600, certificate back), the link itself was left in place, and no temp file was left.
  • Symlink whose target doesn't exist yet: the first start created the target and its missing parent folder, with mode 600, kept the link, served HTTPS and logged no errors. Before "Create the keystore behind a symlink whose target doesn't exist yet", the same start failed with NoSuchFileException. On main (the oie-main:baseline image), it also worked and kept the link, but the target was created with mode 644.
  • Fresh start where the new keystore can't be saved (keystore directory is read-only): logs "Could not initialize security settings", creates no keystore and leaves no temp file. database.password stays plaintext instead of being encrypted with a key that was never saved. Startup then stops with a NullPointerException in initializeDatabaseSettings; see "Startup after a failed security initialization" below.
  • Existing keystore.jks with a fresh mirth.properties: the error names the existing keystore and no keystore.pfx is created. Startup then stops with the same NullPointerException.
  • Upgrade from 4.7.0, keeping conf and appdata as the installer does: keystore.path still points at keystore.jks, no keystore.pfx is created, the encryption key is the same as 4.7.0's, and keystore.jks isn't rewritten.
    • With the 4.7.0 Derby database kept: HTTPS answers, nothing is logged as an error, and database.password stays encrypted and decrypts on startup. Before the branch was rebased onto a main with b457938, startup stopped at the database, because Derby 10.11.1.1 couldn't open the 4.7.0 Derby database (the same problem as the Docker 4.6.0 volume below).

Claude checked in Docker

These used an image built from the branch with the repository's Dockerfile (the jdk-run target) and the oie-test:4.6.0-ubuntu-jdk image for an older volume.

  • Fresh volume: keystore.pfx is mode 600 and owned by engine, no keystore.jks is created, and HTTPS answers.
  • Volume from the 4.6.0 image: the container logs "Found an existing keystore", uses the JCEKS settings with changeme, keeps the same encryption key, doesn't rewrite keystore.jks and doesn't create keystore.pfx. HTTPS answers. The existing keystore.jks keeps its old 644 permissions, as expected.
    • The 4.6.0 Derby database was kept in the volume, and the server opened it with no errors. With an image built before the branch was rebased, the database had to be removed first: the branch was based on a main from before b457938 ("Align derby and derbytools on v4.6.0's 10.10.2.0"), so it shipped Derby 10.11.1.1, which can't open a 4.6.0 Derby database. This was unrelated to the keystore changes.
  • KEYSTORE_DOWNLOAD into a fresh volume: logs "KEYSTORE_DOWNLOAD is set, using jks keystore defaults.", the downloaded keystore.jks is mode 600, and the server uses its key without creating keystore.pfx.
  • KEYSTORE_DOWNLOAD over an existing keystore.jks owned by root (mode 666): logs the "could not restrict permissions" warning and the server still starts.
  • KEYSTORE_DOWNLOAD over an existing keystore.jks owned by engine with mode 644 ("Restrict an existing keystore before downloading over it" restricts the file before downloading): the file ends up mode 600, no warning is logged, and the server starts.

Notes

JNA files in appdata/temp. JNA extracts its native library into appdata/temp, because the server sets java.io.tmpdir from dir.tempdata. The files stay after the engine stops and are updated on the next start, so they don't seem to accumulate. I didn't check whether the old files are deleted and new ones created, or the same files reused. This PR is the first server code to use JNA at runtime, so these files are new on Windows.

Startup after a failed security initialization. This never stopped startup cleanly: before this PR, a failed keystore write was logged and the server kept going. After my read-only test on Windows, the log said the web server was running, but I couldn't connect to it. Now, when the legacy guard fires or a new encryption key can't be saved, the encryptor is left unset and startup ends with a NullPointerException in initializeDatabaseSettings. That keeps the server from using a key that wasn't saved, but a clear error and a clean stop would be better. I'd handle that in a separate issue rather than in this PR.

Docs. New keystores have an empty password, so keytool needs an explicit -storepass "" and -storetype PKCS12, because its password prompt won't take fewer than 6 characters. The instructions for replacing the HTTPS certificate should say this. They should also note that backups of appdata now contain the encryption key with no password protecting it.

Suggested release note

Once the commits are accepted, I suggest this release note for the whole PR, in two parts:

Release note

Security: The keystore is protected by file permissions instead of a password

The keystore holds the encryption key for data the engine encrypts (such as message content in channels with encryption turned on, and database.password in mirth.properties when encryption.properties = 1) and the private key of the HTTPS certificate. Before, it was protected by a password stored next to it in mirth.properties, and the file itself was created with default permissions, usually readable by every local account on Linux. Docker images always used the password changeme.

A new keystore is now created so that only the account the engine runs as can read it: mode 600 on Linux and macOS, and on Windows an access list that grants only that account, SYSTEM and Administrators, with nothing inherited from the folder. Whenever the engine rewrites a keystore, including an existing one, the new file gets the same owner-only permissions.

Other changes to how the keystore is written:

  • The keystore is only written when it's new or the engine added an entry to it, such as a regenerated HTTPS certificate. Before, it was rewritten on every startup.
  • It's written to a temporary file in the same folder and then moved into place, and flushed to disk first, so a failure part way through, or a crash or power loss, can no longer leave an empty or truncated keystore that stops the engine from starting.
  • If a new encryption key is generated but the keystore can't be saved, the engine doesn't use that key, so it can't encrypt data with a key that would be lost on restart.
  • If keystore.path is a symlink, the file it points to is replaced and the link is kept. The target doesn't need to exist yet.

Backups of appdata now contain the encryption key with no password protecting it, so protect them in the same way as the keystore.

An existing keystore that isn't rewritten keeps its current permissions. To restrict an existing keystore.jks on Linux, run chmod 600 on it as the account the engine runs as.

Breaking change: New installations use a PKCS12 keystore with no password

The default mirth.properties now has keystore.path = ${dir.appdata}/keystore.pfx, keystore.type = PKCS12, and empty keystore.storepass and keystore.keypass. Before, it was keystore.jks, of type JCEKS, with a random password that the engine generated on first start.

Existing installations keep their keystore:

  • Installer upgrades keep the existing mirth.properties, so the engine goes on using keystore.jks with its existing passwords.
  • Docker: if the appdata volume already has a keystore.jks, or KEYSTORE_DOWNLOAD is set, the container uses keystore.jks with type JCEKS and the password changeme, as before. A keystore fetched with KEYSTORE_DOWNLOAD is now saved with mode 600.
  • A new mirth.properties with an existing appdata: if the configured keystore doesn't exist but appdata/keystore.jks does, the engine doesn't create a new keystore, because a new encryption key would make data that's already encrypted unreadable. It logs "Could not initialize security settings" with a message naming the existing keystore, and doesn't finish starting. Set keystore.path, keystore.storepass, keystore.keypass and keystore.type in mirth.properties to match the existing keystore.

Scripts or instructions that change the keystore with keytool, such as replacing the HTTPS certificate, need updating for new installations. Use -keystore appdata/keystore.pfx -storetype PKCS12 -storepass "", and -keypass "" where a key password is needed. keytool won't accept an empty password at its prompt, so pass it on the command line.


🤖 Drafted with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants