Tuesday, December 20, 2011

CF: Setting up the OWASP ESAPI Library for use with ColdFusion and Railo

If you are taking application security seriously or have been curious about it you know by now that the native tools built into ColdFusion and Railo are not sufficient to hinder the serious hacker from making headway.

To truly use best practices you can do a lot of code development, or, fall back to a project that has already proven its merit through many years of practical use.

I am referring to the OWASP Enterprise Security API (ESAPI). Unfortunately, getting this puppy running in any shape requires some reading muscle and some luck and some powers of deduction.

I am summarizing here the findings, so you don't have to run through the maze of options and boiling it down to something simple.

First, you will have to download the jar file (as of this writing it would be esapi-2.0.1). The download is around 14MB but you only need the esapi-2.0.1.jar file. Copy the jar file to (backup any esapi file that already exists in there first):
[cfroot]/wwwroot/WEB-INF/lib in Adobe Coldfusion.
WEB-INF/lib in Railo

Then, download a good ESAPI.properties file. Most of my head banging and hair ripping surrounds finding the property definitions. Can't stress this enough. Start with the one from source code it has good comments. Go through this file carefully and make needed changes. Make sure all directories referenced in the properties file actually exist on your drive system and also change default Encryptor.MasterKey and Encryptor.MasterSalt to something you are comfortable with, e.g. do not use something like this:


After you made changes save it (e.g. c:\esapi\files).

Thirdly, make environment start up changes.
If you are using Adobe Coldfusion you will need to change the JVM startup properties in CF Administrator to add a property and point to place where you placed ESAPI.properties file. E.g.:
-D org.owasp.esapi.resources=c:\esapi\files

For Railo, the above is done in Tomcat/Jetty startup parameters.

Fourthly, change classpath (Yep, you heard right change JAVA classpath): Add the directory you placed the properties file in to Java classpath. This is something that had me stumped as well.

After all of the above, give your server a good schake (restart), and then test whether all works.
Simple code snippet:

<cfset esapi = CreateObject("java","org.owasp.esapi.ESAPI")>

<cfset encoder = esapi.encoder()>


 <cfset myInput="<script>some input for html context; 

  alert('doing something you don't want');</script>">

  #now()# <br/>

  #encoder.encodeForHTML(JavaCast("string", myInput))#


The good news is that Adobe is looking into bundling this in the future so you don't have to. However, in the meantime this is good practice ;o)



Jason Dean said...

Actually, in ColdFusion 8.0.1 and 9.0.1 security fixes ESAPI has now been included. So if you are properly patched with CF8 or higher you should already have ESAPI in your ColdFusion lib directory and it should be available.

It may be an older version than what is available, so dropping in the new ESAPI jars as the become available may not be the worst idea.

bman said...

Good point.
Thanks Jason.

Michal Hojcska said...


How do I override ESAPI.properties file in the code considering I don't have access to CF server bin directory?

This is how I get ESAPI from jar file:


Michal Hojcska said...

My previous code was not posted as this blog site might be using esapi already :-)

anyway, here is the code:

CreateObject("java", "org.owasp.esapi.ESAPI")

bman said...

this is a broad question. Each area where this applies has some capability to set processing directives during runtime.

I would review the JavaDoc associated with the library to see details:


If you want attempt to provide a completly new config file you can try to use the ConfigurationParser class. Though, if you don't have access to server, you may not have been granted permissions to use any non-native CF libraries.

Michal Hojcska said...


Thank you for your reply. Sounds like it my be easier to talk to server admins to have properties file updated on the server then.

Considering I can get to that property file...

Would you know what property needs to be modified to add/remove additional characters for output sanitization?


Unknown said...

why not drop the ESAPI.properties to the lib folder with the jar file instead of changing the classpath.

wouldn't that do the trick?

Unknown said...

Hi, just a quick question, is this all the same as this (https://www.owasp.org/index.php/OWASP_Java_Encoder_Project#tab=Main) or the same as this (https://code.google.com/p/owasp-esapi-java/). And when on CF8 or CF9 is it really as easy as just dropping in the latest JAR-file and then using the examples as stated here (https://www.owasp.org/index.php/OWASP_Java_Encoder_Project#tab=Use_the_Java_Encoder_Project)? Or should one use the built -in functions that are available in CF10 / CF11 / Railo 4.x? I have read that those are quite a memoryhog compared to the JAVA-implementation...
Thanx up front!