Repository navigation
Conversation
jonbartels
left a comment
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Explan what this is checking and how it knows its a jceks?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I removed it in favor of a filename check.
36c06bd to
22cfb0a
Compare
|
|
||
| keyStore.load(null, keyStorePassword); | ||
| logger.debug("keystore file not found, created new one"); | ||
| FilePermissionUtil.createOwnerOnlyFile(keyStoreFile); |
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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.
63b3489 to
1ef3328
Compare
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>
1ef3328 to
399776b
Compare
tonygermano
left a comment
There was a problem hiding this comment.
@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:
- Add SPDX headers and fix keystore comments and imports: SPDX headers on the new files, an unused import removed, and the
mirth.propertiescomment reworded. Keeping a JCEKS keystore means setting the path, both passwords and the type, not just the type. - Modernize keystore file handling with NIO.2 and try-with-resources:
initializeSecuritySettingsandFilePermissionUtil.createOwnerOnlyFilenow usePath/Files. An exception from closing the output stream (for example, a full disk) is no longer swallowed. - Make FilePermissionUtilTest independent of the Windows display language: the test reads the ACL through JNA and compares SIDs instead of matching account names in
icaclsoutput, 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. - Refuse to create a new keystore when a legacy keystore.jks exists: if an existing
appdatais used with a freshmirth.properties, the server used to create a newkeystore.pfxwith 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. - Restrict permissions on a downloaded keystore and tidy configure-from-env:
KEYSTORE_DOWNLOADdownloads withumask 077and then runschmod 600. If the chmod fails, it only warns. The unusedKEYSTORE_FILEis removed, and the log says why the JCEKS defaults were chosen. - 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.
- 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.
- Test creating an owner-only file with a long path on Windows: this failed on Windows with "The system cannot find the path specified".
- Support long paths when creating an owner-only file on Windows: the path is passed to
CreateFilein the\\?\(or\\?\UNC\) extended-length form, after it's normalized. - Create the keystore behind a symlink whose target doesn't exist yet: this worked on
main, butFiles.createFilein your first commit and thentoRealPath()in the atomic write (6) broke it. The link is now followed withFiles.readSymbolicLink, so the target is created with owner-only permissions. A cycle of links fails after 40 steps. - Flush the keystore to disk before moving it into place: the temp file is written through a
FileChanneland 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. - Restrict an existing keystore before downloading over it: when
KEYSTORE_DOWNLOADreplaces akeystore.jksthat'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
-
FilePermissionUtilTestran on Windows, andtestWindowsPermissionspassed (it ran and wasn't skipped). - Fresh start as a non-admin user:
keystore.pfxwas created, and its file properties show only that user, SYSTEM and Administrators, each with full control and none inherited. - Started as LocalSystem (
psexec, thenoieserver.ps1):icaclsshows onlyNT AUTHORITY\SYSTEMandBUILTIN\Administrators, both with full control and not inherited. - Existing
keystore.jkswith a freshmirth.properties: the server didn't createkeystore.pfx. - Rewriting an existing keystore: after deleting the
mirthconnectalias withkeytool, the certificate was regenerated on startup and nokeystore.pfx.tmpwas left behind. - Read-only keystore with the
mirthconnectalias deleted: logged "Could not initialize security settings" with anAccessDeniedException, 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 aFileSystemException, then "Could not start web server" with aFileNotFoundException. No temp keystore was left. Releasing the lock and restarting fixed it. - Keystore path longer than 260 characters:
testWindowsLongPathfailed 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
FileChannelflushed to disk, then flushing the directory, which Windows doesn't allow, so only a debug message is logged): a fresh start, and regenerating a deletedmirthconnectcertificate, 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.pfxis mode600, contains theencryptionandmirthconnectentries, and HTTPS answers.database.passwordinmirth.propertieswas encrypted. - Restart with an unchanged keystore:
keystore.pfxkeeps its timestamp and inode, HTTPS answers, and nothing is logged as an error. - Missing certificate: after deleting
mirthconnectwithkeytooland loosening the file to644, the next start regenerated the certificate, kept the same encryption key, set the file back to600and left no temp file. - Symlinked keystore: with
keystore.pathpointing at a symlink and the certificate deleted, the next start replaced the file the link points to (mode600, 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 withNoSuchFileException. Onmain(theoie-main:baselineimage), it also worked and kept the link, but the target was created with mode644. - 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.passwordstays plaintext instead of being encrypted with a key that was never saved. Startup then stops with aNullPointerExceptionininitializeDatabaseSettings; see "Startup after a failed security initialization" below. - Existing
keystore.jkswith a freshmirth.properties: the error names the existing keystore and nokeystore.pfxis created. Startup then stops with the sameNullPointerException. - Upgrade from 4.7.0, keeping
confandappdataas the installer does:keystore.pathstill points atkeystore.jks, nokeystore.pfxis created, the encryption key is the same as 4.7.0's, andkeystore.jksisn't rewritten.- With the 4.7.0 Derby database kept: HTTPS answers, nothing is logged as an error, and
database.passwordstays encrypted and decrypts on startup. Before the branch was rebased onto amainwith 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).
- With the 4.7.0 Derby database kept: HTTPS answers, nothing is logged as an error, and
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.pfxis mode600and owned byengine, nokeystore.jksis 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 rewritekeystore.jksand doesn't createkeystore.pfx. HTTPS answers. The existingkeystore.jkskeeps its old644permissions, 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
mainfrom 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.
- 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
-
KEYSTORE_DOWNLOADinto a fresh volume: logs "KEYSTORE_DOWNLOAD is set, using jks keystore defaults.", the downloadedkeystore.jksis mode600, and the server uses its key without creatingkeystore.pfx. -
KEYSTORE_DOWNLOADover an existingkeystore.jksowned by root (mode666): logs the "could not restrict permissions" warning and the server still starts. -
KEYSTORE_DOWNLOADover an existingkeystore.jksowned byenginewith mode644("Restrict an existing keystore before downloading over it" restricts the file before downloading): the file ends up mode600, 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.pathis 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 usingkeystore.jkswith its existing passwords. - Docker: if the
appdatavolume already has akeystore.jks, orKEYSTORE_DOWNLOADis set, the container useskeystore.jkswith type JCEKS and the passwordchangeme, as before. A keystore fetched withKEYSTORE_DOWNLOADis now saved with mode600. - A new
mirth.propertieswith an existingappdata: if the configured keystore doesn't exist butappdata/keystore.jksdoes, 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. Setkeystore.path,keystore.storepass,keystore.keypassandkeystore.typeinmirth.propertiesto 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
Related to #307
Sets default access controls for key material created on first boot to only be accessible to the owner (600-equivalent):
Posix:
Windows:
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.