Overview

General recommendations to store password securely

Should a password be stored in a configuration file, it is essential to restrict access to that file to only those users who need to know it and to prevent accidental openings that would reveal your secret in clear text. There are some best practices for keeping your sensitive data safe.

The first rule is to isolate your password(s) in an include file that will only be opened for changing passwords, not when editing unrelated configuration. It is recommended to include the file using the @include.required directive (or use @include.default_mode=required) to ensure that it will always be checked by the Wrapper (otherwise it would be silently ignored).

At the very least, the Wrapper process will need to read and load your include file, so please make sure it will run with a user being able to read the file. Ideally, read access to the file should only be granted to that user, and only administrators should be able to log in with that user. On Unix, the RUN_AS_USER variable of the Shell Script can be used to run with a substitute user. On Windows, the wrapper.ntservice.account property can be set to specify the account to use when running as a service.

The Wrapper also provides a "cipher" notation to mark a property value (or a part of it) as sensitive. This cipher notation consists of an opening '%' delimiter, followed by the sensitive text (that can optionally be obfuscated), followed by a vertical bar ('|'), an identifier of a method used to handle or decode the text, and a closing '%' delimiter. The page "Encode passwords and sensitive data" explains in detail this notation and the obfuscation methods that can be used with it. Using the cipher notation is essential for the Wrapper to process a text securely. It ensures that a sensitive value will not be printed in clear text to the log or appear in the Java command line, but also induces a permission check on the containing file, which we will describe below.

注意

How does the Wrapper help checking file permissions?

The Wrapper version 3.6.0 has a mechanism to help setting appropriate permissions to files containing sensitive data.

Each time the Wrapper starts, the following files will be verified:

  • configuration files containing masked or obfuscated values (with the %...|<cipher_name>% notation)
  • parameter files containing masked or obfuscated values (with the %...|<cipher_name>% notation)
  • additional secure files listed with wrapper.secure_file.additional.<n> properties (Standard Edition)

File permission management works quite different between Windows and Unix, and so the way the Wrapper checks permissions also differs depending on the platform:

  • On Windows, file permissions can be granted to an unlimited list of users or groups. The Wrapper takes a strict approach by requiring that all users with permissions to the file be explicitly allowed in the Wrapper configuration file.

    Additionally, certain users considered as insecure are blacklisted and cannot be allowed (see the section below).

  • On Unix, files permissions can be set for three different classes: the owner, the group, and other users.

    The Wrapper has different security policies for each class:

    • There is no restriction for the "owner". It can be anyone with any permissions.

    • If the "group" class has read-writable mode, the name of the group must be explicitly allowed in the Wrapper configuration file.

      Additionally, certain groups that are too broad are blacklisted and cannot be allowed (see the section below).

    • The "other" class must always have a non-read-writable mode (zero).

注意

One can legitimately ask the following question: Isn't it a security flaw that a simple configuration property can allow an arbitrary user or group to access a secure file?

Well, is important to understand that allowing a specific account in the configuration does not change the actual permissions of files. The wrapper.secure_file.check.windows.allowed_account.<n> properties are designed to detect issues before the Wrapper even starts and help you fix file permissions as early as possible during the first setup. Even if an attacker added their own account later, this would not change the actual permissions of the file, which at that point should already have been configured correctly.


Please use the following properties to explicitly allow accounts or groups in your configuration file:


When a file is located on a volume whose format does not support file permissions, the above security checks cannot be performed. By default, such volumes are considered unsecure, but this behavior can be changed with the following properties:


If any of the above conditions are not met for any of the files being checked, the default behavior of the Wrapper is to print messages indicating how the permissions should be adjusted and then stop.

This behavior can however be customized with the following properties:

wrapper.secure_file.check.windows.allowed_account.<n> Property

対応バージョン :3.6.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSX (未対応)Linux (未対応)IBM AIX (未対応)FreeBSD (未対応)HP-UX (未対応)Solaris (未対応)IBM z/Linux (未対応)

These properties can be used to specify a list of allowed accounts when checking permissions of secure files on Windows.

For simplicity, these properties apply to all secured files. So if different files grant permissions to different accounts, these properties should form a common list of allowed accounts across all secured files.

Note that the following accounts are inherently insecure and cannot be allowed:

  • World or Everyone

  • ANONYMOUS LOGON

  • Authenticated users

  • Guests

  • Users

Let's assume a file containing passwords was created with permissions for NT AUTHORITY\SYSTEM, BUILTIN\Administrators and DESKTOP-06SJR11\john. Since the file contains passwords, it is considered sensitive and as such the following log output will be printed:

Wrapper output:
wrapper  | The file 'C:\mayapp\conf\wrapper.conf' contains sensitive data but its permissions are too open.
wrapper  |   Problematic Permissions:
wrapper  |     NT AUTHORITY\SYSTEM    : Either allow this account in the configuration or remove the read and write file permissions.
wrapper  |     BUILTIN\Administrators : Either allow this account in the configuration or remove the read and write file permissions.
wrapper  |     DESKTOP-06SJR11\john   : Either allow this account in the configuration or remove the read and write file permissions.
wrapper  |
wrapper  |   If you want to run the Wrapper as a Windows Service, please add '.\LocalSystem' to the list of allowed accounts.
wrapper  |   If you want to run the Wrapper as a Console Application, please add 'DESKTOP-06SJR11\john' to the list of allowed accounts.
wrapper  |
wrapper  |   The Wrapper will stop.

The first action to take is to remove any permissions that are not necessary: Right click on the file, select Properties, go to the Security Tab, click Edit, select a User or Group, click Remove. For example, you may remove 'john'.

If the remaining permissions are necessary, you will need to explicitly allow them in the Wrapper configuration as follow:

Example:
wrapper.secure_file.check.windows.allowed_account.1=NT AUTHORITY\SYSTEM
wrapper.secure_file.check.windows.allowed_account.2=BUILTIN\Administrators

After restarting the Wrapper, the message should no longer appear and it should start your application normally.


警告

Windows often has permission inheritance enabled. This means that if a file is created, it will automatically inherit the permissions of its parent folder. Additional permissions can be added, but attempting to remove an inherited permission will result in the following message:

In order to remove a permission that is inherited, you need to either store the file in a parent folder that has permission inheritance disabled, or remove permission inheritance for the file itself.

wrapper.secure_file.check.unix.allowed_group.<n> Property

対応バージョン :3.6.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :Windows (未対応)Mac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

These properties can be used to specify a list of allowed groups when checking permissions of secure files on Unix systems.

Group ownership can only be set to one group on Unix system, but these properties form a list of groups allowed across all secured files. If you need to allow multiple groups for separate secure files, you can list them by adding as many wrapper.secure_file.check.unix.allowed_group.<n> properties as needed, remembering to increment the <n> index for each group.

Note that the following groups are too broad and thus not permitted:

  • users

  • other

  • everyone

  • staff

Let's assume a file containing passwords was created with the following ownership and permissions:

ls -la ../conf/wrapper-secure.conf
-rw-rw-r-- 1 john team 9489 Nov 21 17:00 ../conf/wrapper-secure.conf
Wrapper output:
wrapper  | The file '/home/john/wrapper/conf/wrapper.conf' contains sensitive data but its permissions are too open.
wrapper  |   Problematic Permissions:
wrapper  |     Permission '04' ('r--') was granted to others. It must be '00'.
wrapper  |     Permission '060' ('rw-') was granted to group 'team' but this group was not allowed in the configuration.
wrapper  | 
wrapper  |   When the Wrapper is intended to be run by a single user, it is best to set the
wrapper  |    ownership of secured files to that user and remove all other permissions.
wrapper  |    To allow multiple users to access your secure files, you can grant read
wrapper  |    permissions to a group that only a restricted list of users belong to,
wrapper  |    but this group must be explicitly allowed in the Wrapper configuration.
wrapper  | 
wrapper  |   The Wrapper will stop.

The first action to take is to remove permissions for the 'other' class, for example using the following command: chmod o-r ../conf/wrapper.conf.

In most cases, group permissions should also be removed, but scenarios such as multiple users belonging to the same group and being allowed to run the Wrapper are possible. If permissions for the group "team" should be kept, you may add it to the list of allowed groups by using the following configuration:

Example:
wrapper.secure_file.check.unix.allowed_group.1=team

After restarting the Wrapper, the message should no longer appear and it should start your application normally.

wrapper.secure_file.check.windows.allow_unsecured_volumes Property

対応バージョン :3.6.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSX (未対応)Linux (未対応)IBM AIX (未対応)FreeBSD (未対応)HP-UX (未対応)Solaris (未対応)IBM z/Linux (未対応)

This property allows files containing sensitive data to be stored on volumes whose format does not support file permissions.

On Windows, file systems such as FAT32 or exFAT do not support file permissions. This means that anyone with access to the volume can access the files on it.

Unless you know that the access to the volume itself is secure (for example, when it is mounted only by authorized users), it is recommended that you store files containing sensitive data on a volume with a file system (like 'NTFS') that supports permissions and lock down these permissions to the essentials.

By default, storing sensitive files on unsecured volumes is not allowed (the default value is FALSE).

If a sensitive file is found on an unsecured volume, the Wrapper will print the following message and then stop:

Wrapper output:
wrapper  | The file 'A:\wrapper-secret.conf' is located on a volume whose format does not support file permissions. Anyone with access to the volume can read the file.
wrapper  |   Use 'wrapper.secure_file.check.windows.allow_unsecured_volumes=TRUE' or move the file to a different volume.
wrapper  |
wrapper  |   The Wrapper will stop.

The Wrapper will no longer show this message and be allowed to start if wrapper.secure_file.check.windows.allow_unsecured_volumes is set to TRUE.

Example (allow storing sensitive files on unsecured volumes):
wrapper.secure_file.check.windows.allow_unsecured_volumes=TRUE

wrapper.secure_file.check.unix.allow_unsecured_volumes Property

対応バージョン :3.6.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :Windows (未対応)Mac OSXLinuxIBM AIX (未対応)FreeBSDHP-UX (未対応)Solaris (未対応)IBM z/Linux

This property allows files containing sensitive data to be stored on volumes whose format does not support file permissions.

On Unix systems, file systems such as FAT32 or NTFS do not support file permissions. This means that anyone with access to the volume can access the files on it. This is the case, for example, of volumes hosted on a Windows server and shared with Linux systems.

Unless you know that the access to the volume itself is secure (for example, when it is mounted only by authorized users), it is recommended that you store files containing sensitive data on a volume with a file system (like 'ext4') that supports permissions and lock down these permissions to the essentials.

By default, storing sensitive files on unsecured volumes is not allowed (the default value is FALSE).

If a sensitive file is found on an unsecured volume, the Wrapper will print the following message and then stop:

Wrapper output:
wrapper  | The file '/mnt/myvolume/wrapper-secret.conf' is located on a volume whose format does not support file permissions. Anyone with access to the volume can read the file.
wrapper  |   Use 'wrapper.secure_file.check.unix.allow_unsecured_volumes=TRUE' or move the file to a different volume.
wrapper  | 
wrapper  |   The Wrapper will stop.

The Wrapper will no longer show this message and be allowed to start if wrapper.secure_file.check.unix.allow_unsecured_volumes is set to TRUE.

Example (allow storing sensitive files on unsecured volumes):
wrapper.secure_file.check.unix.allow_unsecured_volumes=TRUE

wrapper.secure_file.check.disable Property

対応バージョン :3.6.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

This property can be used to disable permission checking for secure files. Note, however, that usage of forbidden accounts listed in red in the above sections will remain invalid and prevent the Wrapper from starting.

The default value is FALSE.

Example (disable permission checking for secure files):
wrapper.secure_file.check.disable=TRUE

wrapper.secure_file.check.loglevel Property

対応バージョン :3.6.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

This property can be used to set the log level of messages printed when a problem with the permissions of a secured file has been detected.

The default value is FATAL if wrapper.secure_file.check.srict is TRUE, WARN otherwise.

Example (changing the log level of messages to DEBUG):
wrapper.secure_file.check.loglevel=DEBUG

wrapper.secure_file.check.srict Property

対応バージョン :3.6.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

This property can be used to define whether the Wrapper should stop or continue whenever a problem with the permissions of a secured file has been detected.

It is recommended to keep this property set to TRUE so that permissions issues are detected and resolved as early as possible. For cases where the Wrapper is configured to start automatically without human interaction (e.g. when starting as a service), it may be useful to set this property to FALSE. The Wrapper will still report permissions issues with a default loglevel of WARN, and continue its execution. It is recommended that the user who later checks the logs, corrects the file permissions as soon as possible if any warnings were reported.

The default value is TRUE.

Example (still report permissions issues, but continue execution):
wrapper.secure_file.check.srict=FALSE

wrapper.secure_file.additional.<n> Property

対応バージョン :3.6.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版 (未対応)
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

The Standard and Professional Editions offer the ability to list additional files that should be checked using the same rules as for files automatically detected as sensitive by the Wrapper. This can be useful for example for sensitive files that are not read by the Wrapper but by the Java application.

<n> component:

Each element has a property name that starts with "wrapper.secure_file.additional." and the "<n>" component of the property name is an integer number counting up from "1". By default the numbering should be in sequence without gaps". The wrapper.ignore_sequence_gaps property can optionally be set to allow gaps in the sequence.

Example (list additional files for which permissions should be checked):
wrapper.secure_file.additional.1=../conf/db-credentials.xml
wrapper.secure_file.additional.2=../conf/settings.json

参照: セキュリティ

暗号設定:

セキュアファイル:

コマンド: