Cinnabar Canner User's Guide

This list should encompass all the JAR files containing code and resources that should be encrypted and packaged into your output file. It is not required that all of your code be included here; a canned application can still load from external JARs if necessary (see JVM Options, in the next section, for more details). For instance, license restrictions may prohibit you from repackaging JDBC drivers or other third-party libraries. Of course, these external JARs will still need to be present when you distribute your application.

Note that all of your canned classes must reside in JAR files; "loose" or un-jarred classfiles cannot be included in your canned application.

If this option is enabled, Canner will examine the Class-Path manifest attribute of all included JAR files and include all referenced JAR files in the canned output. This process is recursive; for example, if a.jar is the only JAR file explicitly included in the configuration, and a.jar references b.jar, and b.jar references c.jar, then a.jar, b.jar, and c.jar will all be canned together.

This property must be the name of a template file supplied by Cinnabar Systems. The template file contains the native framework code needed to load the JRE and decrypt your classes as needed. Canner combines it with your application's JAR files to produce the output file.

Two template files are included with Canner, template.can and templatew.can. template.can should be used with applications that interact with the command line, and template.can should be used with GUI-only applications. These templates correspond to the java and javaw commands included with your JRE.

Check back with Cinnabar Systems for other template files which will provide additional functionality.

With this option, you may bundle one or more icon (.ico) files in your application's resource section. The first icon in the list will be the default icon for your application; your users can select from the others using Windows Explorer.

This property is the name of the executable (.exe) file which Canner should generate.

This property must be the fully-qualified name of a public class which has a main() method (e.g. com.mypackage.MainClass). If one of the included JAR files has a Main-Class manifest property, this setting may be omitted, and the first included JAR file which contains a Main-Class specification will determine the name of the main class.

If you do specify a class name here, it will override any Main-Class manifest entries in the included JAR files.

This property allows you to select which type of JVM should be loaded; available JVM types differ with the JRE release. This option provides the same functionality as, for example, the -classic or -server command line options in certain versions of the JRE. If the requested type is available, it will always be used. If it is not available, the canned application will attempt to load a fallback JVM based on the following table:

Most applications will want to leave this field empty, indicating to Canner that the default JVM should be used.

If this property is present, it specifies a minimum JRE version number that must be present in order for the application to be successfully launched. For example, if this property is set to "1.3.1", then a 1.3.1 or newer JRE must be present for the canned application to run. If an older JRE is found, the canned application will exit with an error message.

If this property is present, it specifies the name of an environment variable to use for the application's runtime classpath. The standard JRE uses the CLASSPATH environment variable for this purpose, but you can set it to a custom value to avoid conflicts with other Java applications that might have their own CLASSPATH settings.

Most applications will not need to set this property at all, as they will include all necessary JAR files to begin with and not need to load any external resources. Note that even if you specify an environment variable to use, canned applications will always attempt to load encrypted classes and resources first, even if the environment variable points to valid classfiles with the same name as your canned classes.

If you leave this setting blank, no external classes or resources will ever be loaded when the canned application runs, even if a CLASSPATH environment variable exists.

If this option is enabled, the CTRL-BREAK key will be ignored when your application is running. Normally, pressing CTRL-BREAK will cause the JRE to output a dump of all running threads along with their current stack backtraces, including class and method names. Disabling this ability will help limit the amount of information available to an attacker.

This option allows you to add any extra JRE options you might need to successfully launch your application. You will most likely need to use this option if your application expects system properties to be set with the -D option.

Note that the standard JVM options -classpath and -cp are not supported here. You will find that in most cases you will not need these options, since you will usually include all necessary JARs in your "canned" application. If you do find it necessary to specify a runtime classpath, however, you can use the option -Djava.class.path=<classpath spec> instead.

If this option is selected, Canner will generate a random key each time the application is canned.

If this option is selected, Canner will generate a random key when the application is canned, and save the key data into the specified keyfile.

If this option is selected, Canner will not generate a new key; instead, it will load the key from the specified file. The keyfile must exist in order for the canning process to complete successfully. To generate a keyfile, you can use the "Generate a new encryption key into file" option first.

The configuration file must have a top-level element called CannerConfiguration. All other elements must be nested inside it. For example:

<CannerConfiguration>
    <!-- other elements can be nested here -->
</CannerConfiguration>

The TemplateFile element specifies the name of the Canner template file to use. It must have one attribute, called value, whose value is the path to the template file. For example:

<CannerConfiguration>
    <TemplateFile value="template.can"/>
</CannerConfiguration>

The OutputFile element specifies the name of the executable file that Canner will create. It must have one attribute, called value, whose value is the path to the output file. For example:

<CannerConfiguration>
    <OutputFile value="application.exe"/>
</CannerConfiguration>

The JarFile element specifies the name of a JAR file to include in the canned application. It must have one attribute, called value, whose value is the path to the JAR file to include. This element may occur multiple times in the configuration, in order to include multiple JAR files. For example:

<CannerConfiguration>
    <JarFile value="main.jar"/>
    <JarFile value="lib1.jar"/>
    <JarFile value="lib2.jar"/>
</CannerConfiguration>

The RecurseJars element specifies whether the included JAR files should have their manifest Class-Paths scanned recursively for additional JARs to include. It must have one attribute, called value, whose value must be either true or false. If this element is omitted, the option will default to false. For example:

<CannerConfiguration>
    <RecurseJars value="true"/>
</CannerConfiguration>

The IconFile element specifies the name of an icon (.ico) file to include. It must have one attribute, called value, whose value is the path to the icon file to include. This element may occur multiple times in the configuration, in order to include multiple icon files. For example:

<CannerConfiguration>
    <IconFile value="primary.ico"/>
    <IconFile value="secondary.ico"/>
</CannerConfiguration>

The MainClass element specifies the name of the application's main class. It must have one attribute, called value, whose value is the fully-qualified name of a class that has a main() method. This element may be omitted if one of the included JARs has a Main-Class attribute in its manifest. For example:

<CannerConfiguration>
    <MainClass value="com.mypackage.MainClass"/>
</CannerConfiguration>

The JVMName element specifies the name of a specific JVM to load. It must have one attribute, called value, whose value is the name of the JVM. If this element is omitted the default JVM type (normally client or classic, depending on the JRE version) will be used. For example:

<CannerConfiguration>
    <JVMName value="hotspot"/>
</CannerConfiguration>

The MinimumJREVersion element specifies the minimum version number of the JRE which must be present for the canned application to start. It must have one attribute, called value, whose value is the version number of the JRE to check against. If this element is omitted no version number check will be done. For example:

<CannerConfiguration>
    <MinimumJREVersion value="1.3.1"/>
</CannerConfiguration>

The ClasspathVariable element specifies the name of an environment variable to use to allow additional, external classes to be loaded when the canned application is run. It must have one attribute, called value, whose value is the name of the environment variable to use. If this element is omitted no additional classes will be loaded, even if a CLASSPATH environment variable is set. For example:

<CannerConfiguration>
    <ClasspathVariable value="MYCLASSPATH"/>
</CannerConfiguration>

The AllowCtrlBreak element specifies whether the canned application should respond to the CTRL-BREAK keystroke. Normally, pressing CTRL-BREAK will cause the JVM to output a dump of all running threads along with their current stack backtraces, including class and method names. Disabling this ability will help limit the amount of information available to an attacker. The AllowCtrlBreak element must have one attribute, called value, whose value must be either true or false. If this element is omitted, the option will default to false (i.e. CTRL-BREAK will be disabled). For example:

<CannerConfiguration>
    <AllowCtrlBreak value="true"/>
</CannerConfiguration>

The JVMArgument element specifies an argument to be passed to the JVM when the canned application is started. It must have one attribute, called value, whose value is the argument to pass to the JVM. This element may appear multiple times if more than one argument is needed. For example:

<CannerConfiguration>
    <JVMArgument value="-Dvar1=value1"/>
    <JVMArgument value="-Dvar2=value2"/>
</CannerConfiguration>

The GenerateNewKey element specifies whether Canner should create a new, random encryption key. It must have one attribute, called value, whose value must be either true or false. If this element is omitted, the option will default to false. For example:

<CannerConfiguration>
    <GenerateNewKey value="true"/>
</CannerConfiguration>

The EncryptionKeyFile element specifies the name of a key file. It must have one attribute, called value, whose value must be the path to a key file. If the GenerateNewKey element is present and has the value true, then the newly-generated key is writen to the file specified by this element. If the GenerateNewKey element is not present, or is present with the value false, then an encryption key is read from the file specified by this element. For example:

<CannerConfiguration>
    <EncryptionKeyFile value="mykey.key"/>
</CannerConfiguration>

The following example invokes Canner on the files main.jar, lib1.jar, and lib2.jar to produce the executable file application.exe. The template file is template.can and the main class is com.mypackage.Main. The JVM will be invoked with two arguments, -Dvar1=value1 and -Dvar2=value2. A new encryption key will be generated, but not saved to any file.

<canner
    outputExecutable="application.exe"
    templateFile="template.can"
    mainClass="com.mypackage.Main"
    jvmArguments="-Dvar1=value1,-Dvar2=value2"
    generateNewKey="true">
    <fileset>
        <include name="main.jar"/>
        <include name="lib1.jar"/>
        <include name="lib2.jar"/>
    </fileset>
</canner>