Index

Overview

Starting with Wrapper version 3.6.0, the Standard and Professional Editions make it possible to obfuscate passwords or sensitive data to store them more securely in your configuration files. Obfuscation should be distinguished from true encryption, but provides some level of security by hiding the actual text or password and making it very difficult for a casual observer to remember the encoded value.

When loading the configuration, the Wrapper will decode any obfuscated tokens and mark the property values where they are referenced as sensitive. A property value marked as sensitive will be treated with additional precautions, firstly by ensuring that it was loaded from a secure file, and secondly by ensuring that it is only used for its intended purpose without clear-text disclosure.

To exclude the use of properties whose values may appear in the console, emails, logs, command line, etc., only a limited set of properties are allowed to contain obfuscated tokens in their values. Usage in variable definitions is also prohibited to prevent leakage to the environment.

NOTE

Properties allowed to contain obfuscated tokens in their values are limited to the following:

A property value containing sensitive data will be handled with the following security precautions:

  • The permissions of the file containing the sensitive text will be checked and restricted read access will be required to load the file. Please read this page for details.

  • Any sensitive text will be masked in the logs, and replaced by a mask composed of a fixed number of '*' characters.

  • The property value will not be allowed to be referenced in the Java command line to prevent clear-text exposure in process listing tools such as "Task Manager" (on Windows) or "ps" (on Unix). Note that wrapper.app.parameter.backend must be set to TRUE to allow sensitive data in application parameters to be passed through the backend channel instead of the command line.

Several methods are available to encode/obfuscate your passwords. For some of them a private key can be used. The Wrapper provide commands to encode your data and generate private keys. This page will describe the options for each command.

WARNING

The obfuscation methods offered by the Wrapper, along with the associated security measures described above, are primarily designed to prevent the leakage of sensitive data in clear text outside the Java application. By using the wrapper.app.property.<n> properties or setting wrapper.app.parameter.backend to TRUE, it is possible to pass the system properties and application parameters safely to your Java application. However, keep in mind that once received by the Java code, these values will be stored as clear text in system properties or in a string array.

Please be aware of the following issues:

- Someone who came into possession of your obfuscated secrets (or configuration files) could create a simple Java application to dump system properties, use the Wrapper to launch it, and thus easily discover your passwords. It is therefore important that the Wrapper configuration files containing sensitive data are always accessible only to authorized users. That is why the Wrapper checks the permissions of sensitive files everytime it starts and provide guidance on how to adjust them, but it is up to you to actually edit the file permissions. It is also recommended to use a private key file with file permissions set as restricted as possible.

- Someone with access to your machine could use a debugger to trace the memory of your Java application and discover the String values where clear text passwords are stored. Always make sure to run your Java application in a secure environment.

Obfuscate data
Kompatibel :3.6.0
Editionen :Professional EditionStandard EditionCommunity Edition (Not Supported)
Betriebssysteme :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

The --cipher command can be used to encode passwords or sensitive data with the Wrapper and generate the associated "cipher" configuration.

To specify exactly how to encode your values, several parameters are needed when using the --cipher command. The section below will described how to configure each parameter, but first lets have a look at how encoded values will look like in your configuration file. The following syntax is used: 

%zrmVK5-Zp7qHptL9Yu66qr|<cipher_name>%

  • '% %' are delimiters for the encoded token,

  • 'zrmVK5-Zp7qHptL9Yu66qr' is the encoded value,

  • <cipher_name> is an identifier for the configuration used to encode the value (see below).

The encoding of value(s) can be configured with the following set of properties.

  • wrapper.cipher.<n>.name: identifier for the encoding configuration of index <n>,

  • wrapper.cipher.<n>.method: encoding method (see below),

  • wrapper.cipher.<n>.private_keyfile: path to the private key.

Some methods define a default configuration, in which case the above properties can be omitted. Such default configurations do not use a custom private key and the <cipher_name> is the same as the method name.


Now let's go into the details of using the --cipher command.

'wrapper --help' will print the following output, which we will further explain below: 

  --cipher Obfuscate a password and generate a token along with wrapper.cipher.*
    properties that can then be used in the configuration file for added safety.
    The value to be encoded can be piped to Stdin of the Wrapper.  Otherwise, it
    will be prompted.
    The following arguments are available:
      --method <method name> One of the following methods:
          base64   : to encode in Base64
          base64url: to encode in the modified Base64 for URLs
          obf      : to generate a fixed obfuscated string
          robf     : to generate a random obfuscated string
      --name <cipher name> Optional cipher name. This argument is required when
        '--private_keyfile' is specified.
      --private_keyfile <file path> Optional path to a private key file
        (available for method 'obf' and 'robf').
      --encoding <utf8 or utf-8> Encoding to use when reading Stdin.
      --echo Echo the input to debug encoding issues (do not use with real
        passwords).
      --simple If specified, the output will only contain the obfuscated string.

Methods

The --method parameter is used to specify the encoding method.

The following methods are available:

  • base64: standard base64 encoding

  • base64url: modified Base64 for URLs ('+' replaced by '-', '/' replaced by '_')

  • obf: proprietary obfuscation method (the same input will always generate the same output)

  • robf: proprietary reandomized obfuscation method (the same input will generate randomized outputs, which makes it stronger against cryptanalysis)

NOTE

'base64' and 'base64url' are publicly known encoding methods. The encoded value is longer and more difficult to remember than the corresponding plain text, however someone in possesion of the encoded string would very easily decode it.

'obf' and 'robf' cannot easily be decoded because the algorithms used are not publicly known. For enhanced security, a private key stored in a separate secure file can also be specified during encoding. Without claiming to achieve the same level of security as the strongest encryption methods (AES, RSA, etc.), using 'obf' or 'robf' in combination with a private key offers fairly good protection of your data.

Cipher Name

The --name parameter is optional. When used, it must be followed by an identifier for the configuration used to encode values.

This parameter is mandatory if '--private_keyfile' is specified.

The value specified will be used to set the wrapper.cipher.<n>.name property. For example, if --name obf1 is specified, the following configuration will be generated: 

wrapper.cipher.1.name=obf1

Private Key File

The --private_keyfile parameter is optional. When used, it must be followed by the path to a private key file.

This parameter can only be used if the encoding method is 'obf' or 'robf' and if the --name parameter is also specified.

Without a private key specified encoding only acts as obfuscation, which simply makes it difficult for unwanted observers to remember the values. While obfuscation may be sufficient if your configuration file is well protected and edited privately, specifying a private key file provides additional security. Decoding then requires this separate file whose sole purpose is to contain the private key and therefore never needs to be opened or edited. The key file must always be stored in a safe location with restricted permissions. Anyone getting access to your key would be able to easily decode your passwords.

The value specified will be used to set the wrapper.cipher.<n>.private_keyfile property. For example, 'wrapper --cipher --method obf --name obf1 --private_keyfile ../conf/my_private_key' will generate the following configuration: 

wrapper.cipher.1.name=obf1
wrapper.cipher.1.method=obf
wrapper.cipher.1.private_keyfile=../conf/my_private_key

Simple Output

The --simple parameter is a single parameter (with no value) used to generate an output with only the encoded value.

Without the --simple parameter, the output will look like this: 

Encoded Token:
    %K401JeI7GaHRplWDz15c6hmXkKM_9CoFrAo8P|r1%

Configuration:
    wrapper.cipher.1.name=r1
    wrapper.cipher.1.method=obf
    wrapper.cipher.1.private_keyfile=mykey

With the --simple parameter, the output will look like this: 

%K401JeI7GaHRplWDz15c6hmXkKM_9CoFrAo8P|r1%

Using the --simple parameter is useful when the output needs to be used by an automated process or passed to another command.

For example, the command below will encode the value "mypassword" with the 'obf' method. The output of the Wrapper will be passed to the sed command that will replace the token(s) '@pw1@' with the encoded value.

Example: (On Unix) 

cat file_containing_password | ./wrapper --cipher --method obf --simple | sed -i "s/@pw1@/$(cat)/g" ../conf/wrapper-private.conf

Encoding

The --encoding parameter is optional. It specifies the encoding to use when reading Stdin.

If this option is not specified, the ANSI code page will be used on Windows and the encoding of the locale in the current session will be used on Unix.

Currently, only the following values are supported:

  • default

  • utf8 or utf-8

Example: (With cmd.exe: Read the first line of input.txt in utf-8) 

type input.txt | wrapper.exe --cipher --method obf --encoding utf8

NOTE

In PowerShell consoles, the variable $OutputEncoding determines the encoding to use when piping data into native applications. In some environments, the default value may be ASCII, which would replace all non-ASCII characters with question marks. When reading the contents of a file that contains UTF-8 characters, make sure that $OutputEncoding is correctly set to '[System.Text.Encoding]::UTF8'.

Example: (With PowerShell: Read the first line of input.txt in utf-8) 

$OutputEncoding = [System.Text.Encoding]::UTF8
Get-Content .\input.txt -Encoding UTF8 | .\wrapper.exe --cipher --method obf --encoding utf8

Echo

The --echo parameter is an optional single parameter (no value) that can be used to print the input data received by the Wrapper before it is obfuscated. This is useful to detect encoding problems.

WARNING

IMPORTANT: This option is available for debugging purposes only. It should never be used with real passwords, as it causes the input to be displayed in clear text on the terminal. Please clear your terminal if you printed sensitive data by mistake.

NOTE

The --echo and --simple options cannot be used together.

Explanation

When the Wrapper reads its standard input stream, it interprets it with its own encoding or with the value of the --encoding option if specified. In most cases, it has no way of determining whether the encoding used is correct or not, and will obfuscate the data in any case. With only the obfuscated output, it can be very difficult to notice encoding problems on the input string. By adding the --echo option, the user can confirm whether the input was correctly received by the Wrapper.

Example: (wrong encoding) 
type inpututf8.txt | wrapper.exe --cipher --method obf --echo

...

Input data: 'Niño'

Encoded Token:
    %59qW5A=k2naYbzKiXOUcGc5OA598K0Kq6|obf%

Example: (correct encoding) 
type input.txt | wrapper.exe --cipher --method obf --echo --encoding utf8

...

Input data: 'Ni�o'

Encoded Token:
    %_G2moKq5aFVvtwAn6pyk5MS4G6Hm4mR|obf%

Generate Private Keys
Kompatibel :3.6.0
Editionen :Professional EditionStandard EditionCommunity Edition (Not Supported)
Betriebssysteme :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

The Wrapper provides the --keygen command to generate private keys that are used by certain encoding methods.

WARNING

By default, the Wrapper will generate a key with read and write permissions granted to only the user running the Wrapper. On Unix systems, this user will be the "owner" of the file and only the owner will have read-write permissions. These permissions can be changed afterwards, but please keep in mind that they should be granted to the bare minimum. Usually only the user running the Wrapper should be allowed to access the private key.

Please read this page to learn how to adjust the permissions of your private key.

'wrapper --help' will print the following output, which we will further explain below: 

  --keygen Generate a private key file to be used when obfuscating passwords.
    The following arguments are available:
      --method <method name> Obfuscation method for which the private key is
        intended to be used:
          obf : to generate a key for fixed obfuscation
          robf: to generate a key for random obfuscation
      --private_keyfile <file path> Specifies the filename of the key file.

Methods

Currently, only the 'obf' and 'robf' methods can use of a private key. Moreover, they both use the same key format, so a key generated by specifying the 'obf' method can be used for the 'robf' method and vice versa.

The --method parameter exists for compatilibity with future versions of the Wrapper which will add new encoding or encryption methods using different key formats.

Private Key File

The --private_keyfile parameter is used to specify the path to a file where the generated key will be written.

Verweis: Sicherheit

Cipher configuration:

Secure Files:

Commands: