Date of release: 2012-02-29

Don't miss the security related changes, they may affect your application!

Changes on the FTL side

  • Attention: The output of ISO 8601 date/time formatting built-ins, introduced in 2.3.17, was slightly changed. From now on, the time zone offset, when it's displayed and it isn't Z, always includes the minutes. For example, 15:30:15+02 becomes to 15:30:15+02:00 in the template output. Both formats are valid according to ISO 8601 (so anything that expects ISO 8601 date/times should continue working), but only the last format complies with the XML Schema date/time formats, hence this change.

  • New built-in for escaping inside JSON string literals: json_string.

  • Bugfix: Wrong # tags were printed as static text instead of causing parsing error if there was no correct # tag earlier in the same template. Since fixing this would not be 100% backward compatible, the old behavior has remained, unless you set the incompatible_enhancements setting (Configuration.setIncompatibleEnhancements(String)) to "2.3.19" or higher.

Changes on the Java side

  • Attention: This release contains two important security workarounds that unavoidably make it obvious how some applications can be exploited. FreeMarker can't solve these issues on all configurations, so please read the details instead of just updating FreeMarker! Also, these changes are not 100% backward compatible in theory, however it's not probable that they will break anything. The two changes are:

    • The character with character code 0 (\u0000) is not allowed in template paths anymore. When a path contains it, FreeMarker behaves as if the template was not found.

      This is to fix the security problem where a template path like "secret.txt\u0000.ftl" is used to bypass extension filtering in an application. FreeMarker itself doesn't care about the extension, but some applications decide based on the extension if they will delegate a path to FreeMarker. When they do with such a path, the C/C++ implementation behind the storage mechanism may sees the path as "secret.txt" as the 0 terminates the string in C/C++, and thus load a non-FTL file as a template, returning the file contents to the attacker.

      Note that some HTTP servers, notably Tomcat and the Apache HTTP Server blocks URL-s where the URL contains 0 (%00) outside the query string, thus this wasn't exploitable there through such Web URL-s. Some other HTTP servers however, like Jetty, doesn't block such URL-s.

    • ClassTemplateLoader, when it's created with base path "/" (like with new ClassTemplateLoader(someClass, "/")), will not allow template paths that contain colon earlier than any /, and will act like if the template was not found in such case.

      This is to fix the security problem where a template path like "file:/etc/secret" or "http://example.com/malware.ftl" is interpreted as a full URL by a java.net.URLClassLoader in the class-loader hierarchy, and thus allow loading files from these URL-s as templates. This is a quirk (or bug) of java.net.URLClassLoader, thus this problem only exists on systems that use such class-loaders.

      Beware, some frameworks use their own TemplateLoader implementations, and if those are vulnerable, they will remain so after updating FreeMarker too! Note that this exploit only works if the class-loader hierarchy contains an URLClassLoader and the class-loader is used to load templates without adding any prefix before the template path (other than "/").

    These security issues mostly only affect applications where the user (the visitor) can supply arbitrary template paths to the application. This is not the case with properly built MVC applications, as there only the MVC Controller can be addressed directly, and it's the Controller that specifies the template paths. But legacy MVC applications based on JSP Model-2 often expose the MVC Views as public URL-s ending with .ftl, thus allowing the user to give arbitrary paths to FreeMarker. Such applications should be secured with a security-constratint in web.xml as shown in the related Manual section. This should be done regardless of the current security fixes.

    In general, you should not allow users to specify arbitrary template paths, or if you do allow that, you should be extra careful with the TemplateLoader used.

  • Configuration has new methods: removeTemplateFromCache(...). This will remove the given template for the given locale from the cache, so it will be re-loaded regardless of the template update delay when it's next time requested.

  • BeansWrapper ignores setter methods from now when introspecting classes. They weren't used anyway, so they unnecessarily caused "java.beans.IntrospectionException: type mismatch between read and write methods" errors.

  • TemplateClassResolver.SAFER_RESOLVER now disallows creating freemarker.template.utility.JythonRuntime and freemarker.template.utility.Execute. This change affects the behavior of the new built-in if FreeMarker was configured to use SAFER_RESOLVER, which is not the default until 2.4 and is hence improbable.

  • Bug fixed: Calling varargs methods now indeed works. (Earlier it only worked for overloaded methods.)

  • Bug fixed [1837697] [2831150] [3039096] [3165425]: Jython support now works with Jython 2.2 and 2.5.

  • Bug fixed [3325103]: TemplateException-s and ParseException-s are now serializable.