From a3662a3efa166a55cc32d7a5319c40b32a0f0797 Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Thu, 29 Oct 2026 12:27:49 +0100 Subject: [PATCH 1/3] Update admin config --- docs/desktop/admin-config.mdx | 42 ++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/desktop/admin-config.mdx b/docs/desktop/admin-config.mdx index 0d8f549..b34859c 100644 --- a/docs/desktop/admin-config.mdx +++ b/docs/desktop/admin-config.mdx @@ -43,9 +43,49 @@ cryptomator.pluginDir=@{userhome}/cryptomator/plugins :::warning After creating/editing the file, ensure correct file access permissions! -We recommend read access for all users, **write access only for system/device admins**. +We recommend read access for all users, **write access only for system/device admins**. On Windows, Cryptomator enforces this and ignores the file otherwise, see [File Permissions on Windows](#file-permissions-on-windows). ::: +## File Permissions on Windows {/* #file-permissions-on-windows */} + +Since Cryptomator 1.20.0, the admin configuration is **only loaded on Windows if it cannot be edited by standard users**. Cryptomator checks the following requirements on every start and ignores the admin configuration if any of them is not met: + +* `config.properties`, its directory and all parent directories up to the drive root are owned by `SYSTEM`, `Administrators` or `TrustedInstaller`. +* No other user or group has permissions to modify the file (meaning write, append, delete, change permissions, take ownership) or to delete or replace one of the directories (delete, delete subfolders and files, change permissions, take ownership). Permissions to create new files in a directory are fine. +* The path does not contain junctions or symbolic links. + +If the admin configuration is ignored, the application log contains a warning starting with `Ignoring admin config`, followed by the reason. + +During installation (including repair and upgrade) the directoy `C:\ProgramData\Cryptomator` is set up and, if no admin config exists, places an empty `config.properties` with correct permissions inside it. + +An existing `config.properties` is left untouched, **including its owner and permissions**. To make an existing config trusted, run the following commands in an elevated command prompt: + +:::warning +Before running these commands on an existing `config.properties`, review its content for unexpected values, especially `cryptomator.pluginDir`. +::: + +```batch +icacls "C:\ProgramData\Cryptomator" /setowner *S-1-5-32-544 /L +icacls "C:\ProgramData\Cryptomator" /reset /L +icacls "C:\ProgramData\Cryptomator" /inheritance:r /grant:r *S-1-5-18:(OI)(CI)F *S-1-5-32-544:(OI)(CI)F *S-1-5-32-545:(OI)(CI)RX /L +icacls "C:\ProgramData\Cryptomator\config.properties" /setowner *S-1-5-32-544 /L +icacls "C:\ProgramData\Cryptomator\config.properties" /reset /L +``` + +They secure the directory like the installer does and set `Administrators` as owner of the file and remove all explicit permissions, so that only the permissions inherited from the directory remain. + +For verification, run the following commands: + +```batch +icacls "C:\ProgramData\Cryptomator" +icacls "C:\ProgramData\Cryptomator\config.properties" +dir /q "C:\ProgramData\Cryptomator" +``` +The output of `icacls` must only contain the three entries granted above, without `(I)` markers. `dir /q` must list `BUILTIN\Administrators` (or its localized name) as owner of `config.properties` and of the `.` entry, which represents the directory itself: + + +Files created by elevated processes, such as deployment tools running as `SYSTEM` or an elevated administrator shell, are owned by `Administrators` or `SYSTEM` and inherit the directory permissions, so they are trusted without further steps as long as they are created after the installation. + ## Configurable Properties {/* #configurable-properties */} The following property keys are supported. From c658565f85085fcf065f738243401f78165f81c1 Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Thu, 29 Oct 2026 13:29:19 +0100 Subject: [PATCH 2/3] Fix wording --- docs/desktop/admin-config.mdx | 45 +++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/docs/desktop/admin-config.mdx b/docs/desktop/admin-config.mdx index b34859c..f98d146 100644 --- a/docs/desktop/admin-config.mdx +++ b/docs/desktop/admin-config.mdx @@ -48,43 +48,48 @@ We recommend read access for all users, **write access only for system/device ad ## File Permissions on Windows {/* #file-permissions-on-windows */} -Since Cryptomator 1.20.0, the admin configuration is **only loaded on Windows if it cannot be edited by standard users**. Cryptomator checks the following requirements on every start and ignores the admin configuration if any of them is not met: +Since Cryptomator 1.19.5, the admin configuration is **only loaded on Windows if it cannot be edited by standard users**. Cryptomator checks the following requirements on every start and ignores the admin configuration if any of them is not met: * `config.properties`, its directory and all parent directories up to the drive root are owned by `SYSTEM`, `Administrators` or `TrustedInstaller`. * No other user or group has permissions to modify the file (meaning write, append, delete, change permissions, take ownership) or to delete or replace one of the directories (delete, delete subfolders and files, change permissions, take ownership). Permissions to create new files in a directory are fine. * The path does not contain junctions or symbolic links. -If the admin configuration is ignored, the application log contains a warning starting with `Ignoring admin config`, followed by the reason. +If the admin configuration is ignored, the application log contains a warning starting with `Ignoring admin config`. The warning logged right before it names the concrete cause, e.g. the path and its untrusted owner, the modifying rights granted to an untrusted principal, or the link a path element resolves to. -During installation (including repair and upgrade) the directoy `C:\ProgramData\Cryptomator` is set up and, if no admin config exists, places an empty `config.properties` with correct permissions inside it. +During installation (including repair and upgrade) the installer sets up the directory `C:\ProgramData\Cryptomator` and, if no admin config exists, places an empty `config.properties` with correct permissions inside it. -An existing `config.properties` is left untouched, **including its owner and permissions**. To make an existing config trusted, run the following commands in an elevated command prompt: +An existing `config.properties` is left untouched, **including its owner and permissions**. To replace it with one the installer creates, proceed as follows with elevated privileges: + +1. Rename `C:\ProgramData\Cryptomator\config.properties`, e.g. to `config.properties.old`. +2. Repair the installation, e.g. by running the Cryptomator installer again and choosing *Repair*. This secures the directory and places a new, empty `config.properties` with correct permissions inside it. +3. Copy the entries you need from the renamed file into the new `config.properties` and delete the renamed file afterwards. :::warning -Before running these commands on an existing `config.properties`, review its content for unexpected values, especially `cryptomator.pluginDir`. +Before copying entries, review the content of the renamed file for unexpected values, especially `cryptomator.pluginDir`. ::: -```batch -icacls "C:\ProgramData\Cryptomator" /setowner *S-1-5-32-544 /L -icacls "C:\ProgramData\Cryptomator" /reset /L -icacls "C:\ProgramData\Cryptomator" /inheritance:r /grant:r *S-1-5-18:(OI)(CI)F *S-1-5-32-544:(OI)(CI)F *S-1-5-32-545:(OI)(CI)RX /L -icacls "C:\ProgramData\Cryptomator\config.properties" /setowner *S-1-5-32-544 /L -icacls "C:\ProgramData\Cryptomator\config.properties" /reset /L -``` +For verification, run the following commands in PowerShell: -They secure the directory like the installer does and set `Administrators` as owner of the file and remove all explicit permissions, so that only the permissions inherited from the directory remain. +```powershell +(Get-Acl "C:\ProgramData\Cryptomator").Sddl +(Get-Acl "C:\ProgramData\Cryptomator\config.properties").Sddl +``` -For verification, run the following commands: +Each command prints owner and permissions in [SDDL](https://learn.microsoft.com/en-us/windows/win32/secauthz/security-descriptor-definition-language) form. For a configuration created by the installer, the output is: -```batch -icacls "C:\ProgramData\Cryptomator" -icacls "C:\ProgramData\Cryptomator\config.properties" -dir /q "C:\ProgramData\Cryptomator" ``` -The output of `icacls` must only contain the three entries granted above, without `(I)` markers. `dir /q` must list `BUILTIN\Administrators` (or its localized name) as owner of `config.properties` and of the `.` entry, which represents the directory itself: +O:BAG:SYD:PAI(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(A;OICI;0x1200a9;;;BU) +O:SYG:SYD:AI(A;ID;0x1200a9;;;BU)(A;ID;FA;;;BA)(A;ID;FA;;;SY) +``` + +`SY` stands for `SYSTEM`, `BA` for `Administrators` and `BU` for `Users`; `TrustedInstaller` has no abbreviation and appears as its full SID. `FA` grants full access, `0x1200a9` read and execute. Both outputs must meet the following conditions: +* The owner (`O:`) is `SY`, `BA` or `S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464` (`TrustedInstaller`). +* The permissions after `D:` consist of exactly three entries, one each for `SY`, `BA` and `BU` (order may differ). +* The directory's permissions contain the `P` flag (`D:PAI`). +* The file's entries carry the `ID` flag. -Files created by elevated processes, such as deployment tools running as `SYSTEM` or an elevated administrator shell, are owned by `Administrators` or `SYSTEM` and inherit the directory permissions, so they are trusted without further steps as long as they are created after the installation. +A deployment tool that creates the admin config must set owner and permissions accordingly. ## Configurable Properties {/* #configurable-properties */} From b84c895a285be3173f25cd2bd57098f2b17f7522 Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Thu, 29 Oct 2026 13:45:18 +0100 Subject: [PATCH 3/3] Clarify ownership and permissions in admin-config Updated admin-config documentation to clarify ownership and permissions requirements for deployment tools. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/desktop/admin-config.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/desktop/admin-config.mdx b/docs/desktop/admin-config.mdx index f98d146..c845f80 100644 --- a/docs/desktop/admin-config.mdx +++ b/docs/desktop/admin-config.mdx @@ -82,14 +82,14 @@ O:BAG:SYD:PAI(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(A;OICI;0x1200a9;;;BU) O:SYG:SYD:AI(A;ID;0x1200a9;;;BU)(A;ID;FA;;;BA)(A;ID;FA;;;SY) ``` -`SY` stands for `SYSTEM`, `BA` for `Administrators` and `BU` for `Users`; `TrustedInstaller` has no abbreviation and appears as its full SID. `FA` grants full access, `0x1200a9` read and execute. Both outputs must meet the following conditions: +`SY` stands for `SYSTEM`, `BA` for `Administrators` and `BU` for `Users`; `TrustedInstaller` has no abbreviation and appears as its full SID. `FA` grants full access, `0x1200a9` read and execute. The installer-generated defaults have the following characteristics: * The owner (`O:`) is `SY`, `BA` or `S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464` (`TrustedInstaller`). * The permissions after `D:` consist of exactly three entries, one each for `SY`, `BA` and `BU` (order may differ). * The directory's permissions contain the `P` flag (`D:PAI`). * The file's entries carry the `ID` flag. -A deployment tool that creates the admin config must set owner and permissions accordingly. +A deployment tool that creates the admin config must meet the ownership, access and link restrictions described above; it does not need to reproduce the installer's ACLs exactly. ## Configurable Properties {/* #configurable-properties */}