InstallBuilder User Guide 23

Encryption and password protection

This section specifies how InstallBuilder can be used to create an installer that requires specifying a valid password and its payload is encrypted.

Encrypting payload of the installer

InstallBuilder provides support for encrypting contents of the installer so that a valid password must be specified in order to be able to install or unpack files from the installer.

Enabling the encryption requires specifying <enableEncryption> and <encryptionPassword> in the project.

<project>
    <enableEncryption>1</enableEncryption>
    <encryptionPassword>RandomGeneratedPassword</encryptionPassword>
</project>

This will cause the installer to be encrypted. As password is only used at build time, it has to be specified at runtime by the user.

InstallBuilder will require user to specify password before doing any operations. A dialog window will be shown requesting the user to specify a valid password.

Figure 78: Prompt for providing password

The user cannot continue until a correct password is entered. Specifying an empty password or closing the window causes the installer to exit immediately.

Support for platforms and build types

Supported platforms

Encryption is supported on the following platforms:

Linux x86 and x64
Microsoft Windows
Mac OS X

When building an installer for other platforms, encryption is not enabled and the <setEncryptionPassword> action must not be invoked.

Note

Support for older operating systems

Encryption is not supported on Mac OS X 10.2 and Linux x86 when legacy mode is enabled. On those platforms, if encryption is enabled, InstallBuilder will not allow be able to decrypt its contents and <setEncryptionPassword> action will report appropriate error.

RPM and DEB packages

Encryption is not supported for creation of RPM and DEB packages creation. In those modes, files are copied and installed by native package system and not InstallBuilder.

Enabling encryption in these targets is ignored and built same as when encryption is disabled.

Downloadable components

When encryption is enabled, all downloadable components are also encrypted using the same key as files embedded in the installer.

An installer with downloadable components will work the same both when its contents is encrypted and when encryption is disabled.

Multiplatform CD-ROM mode

Creating a CD-ROM mode installer with encrypted contents requires enabling both <enableEncryption> and <compressPackedFiles>.

<project>
    <enableEncryption>1</enableEncryption>
    <encryptionPassword>RandomGeneratedPassword</encryptionPassword>
    <compressPackedFiles>1</compressPackedFiles>
    ...
</project>

When encryption is enabled and building CD-ROM installer, contents of all files is encrypted and installers only for supported platforms will be able to properly perform the installation. Installers for platforms without support for encryption will not be able to access the data due to it being encrypted.

Therefore it is recommended to specify platforms to build for CD-ROM mode using <cdromPlatforms,project.cdromPlatforms) tag.

<project>
    <enableEncryption>1</enableEncryption>
    <encryptionPassword>RandomGeneratedPassword</encryptionPassword>
    <compressPackedFiles>1</compressPackedFiles>
    <cdromPlatforms>osx windows linux linux-x64</cdromPlatforms>
    ...
</project>

This will not create installers for platforms that will be able to access encrypted files.

Manually specifying password

It is also possible to disable the default dialog that prompts the user for password and use <setEncryptionPassword> action to specify the password. This can be done by specifying 0 for <requirePasswordOnStartup>.

<project>
    <enableEncryption>1</enableEncryption>
    <encryptionPassword>RandomGeneratedPassword</encryptionPassword>
    <requirePasswordOnStartup>0</requirePasswordOnStartup>
</project>

With the password prompt disabled, the installer will show the frontend, however, any file operations will fail until <setEncryptionPassword> action is run with correct password. It can be put in a parameter’s <validationActionList> to disallow continuing until a valid password is specified.

The following parameter will ask the user for payload password and run the <setEncryptionPassword> action to verify and set the password.

<project>
    <enableEncryption>1</enableEncryption>
    <encryptionPassword>RandomGeneratedPassword</encryptionPassword>
    ...
    <parameterList>
        ...
        <stringParameter>
            <name>password</name>
            ...
            <validationActionList>
                <setEncryptionPassword>
                    <password>${password}</password>
                </setEncryptionPassword>
            </validationActionList>
        </stringParameter>
    </parameterList>
</project>

The action <setEncryptionPassword> throws an error whenever password is incorrect and user will not be able to proceed until a valid password is specified. The action may take up to 1 second as the number of computations to verify the password is very large.

After the action is run without errors, the installation may proceed.

Note

Accessing files and folders using actions

Since payload is encrypted, it is not possible to use actions such as <unpackFile> and <unpackDirectory> before user specifies the password and <setEncryptionPassword> action is run if <requirePasswordOnStartup> is set to 0. After the action is invoked, the actions to unpack contents of installer may be invoked freely and will work normally.

Retrieving password over the Internet

Often it is more feasible not to provide end users with password to extract the payload but to allow users to specify their individual key or login and password. This, combined with HTTPS protocol, can be used to request a password based on other information.

<project>
    <enableEncryption>1</enableEncryption>
    <encryptionPassword>RandomGeneratedPassword</encryptionPassword>
    <requirePasswordOnStartup>0</requirePasswordOnStartup>
    ...
    <parameterList>
        <parameterGroup>
            <name>retrievepassword</name>
            <title>Activate application</title>
            <explanation>Please specify example.com username and password</explanation>
            <parameterList>
                <stringParameter>
                    <name>username</name>
                    <description>Username</description>
                    <allowEmptyValue>0</allowEmptyValue>
                </stringParameter>
                <passwordParameter>
                    <name>password</name>
                    <description>Password</description>
                    <allowEmptyValue>0</allowEmptyValue>
                    <askForConfirmation>0</askForConfirmation>
                </passwordParameter>
            </parameterList>
            <validationActionList>
                <httpPost>
                    <customErrorMessage>Unable to contact activation server</customErrorMessage>
                    <filename>${system_temp_directory}/encryptionpassword</filename>
                    <url>https://example.com/api/installer/getpasswordkey</url>
                    <queryParameterList>
                        <queryParameter>
                            <name>username</name>
                            <value>${username}</value>
                        </queryParameter>
                        <queryParameter>
                            <name>password</name>
                            <value>${password}</value>
                        </queryParameter>
                    </queryParameterList>
                </httpPost>
                <readFile>
                    <name>encryptionpassword</name>
                    <path>${system_temp_directory}/encryptionpassword</path>
                </readFile>
                <deleteFile>
                    <path>${system_temp_directory}/encryptionpassword</path>
                </deleteFile>
                <setEncryptionPassword>
                    <customErrorMessage>Activation failed</customErrorMessage>
                    <password>${encryptionpassword}</password>
                </setEncryptionPassword>
            </validationActionList>
        </parameterGroup>
    </parameterList>
</project>

Example above shows how to ask for username and password so that remote server will either accept and provide a password valid for this product version or reject the request and provide an empty result.