OWASP .NET ESAPI 0.2 Released

Jul 30, 2009

The second version of the .NET port of the ESAPI project is available for general review. The code is available on Google Code here.

The ESAPI (Enterprise Security API) is a set of OWASP projects that support secure software in a variety of languages. I've worked closely with the ESAPI team to create a .NET version. While there has been .NET ESAPI code available for quite some time, this release should be much more applicable to real-world projects, especially ASP.NET development. This blog post is meant to cover some of the highlights in an FAQ format.

What is the general design of the .NET ESAPI?

If you've looked at the Java ESAPI before, you won't be surprised about the structure and design of the .NET version. The .NET ESAPI is split into three projects: Esapi, EsapiTest, and SwingSet.

The first project is named Esapi, and contains the interfaces and the reference implementation. This is all you need if you are developing a .NET application from scratch. You would simply add the assembly from this project as a reference (along with the other required references), update your configuration file to add the appropriate ESAPI configuration elements, and extend the reference classes as you see fit.

This project contains four sub-namespaces.The Codecs and ValidationRules namespaces are used for the reference implementation of the Encoder and the Validator components, respectively. The Errors namespace contains the Exceptions used in the reference implementation. The Interfaces namespace contains the interfaces, which are implemented in the reference implementation, which is in the base namespace.

The EsapiTest project is a Visual Studio test project which contains several test cases for the reference implementation. If you have a patch, you could create a test case for whatever functionality you are updating and include it in the patch. There are over fifty unit tests currently in the project.

The SwingSet project is an ASP.NET application that has a few different purposes. One purpose is to demonstrate how to integrate the ESAPI components into an ASP.NET application. However, it also demonstrates security best practices outside of the scope of the the ESAPI. For example, it contains an example of how Membership can be configured securely. Additionally, the web.config file is annotated with security descriptions for some settings.

What different ESAPI components are supported?

The following components are supported:

IAccessController: The IAccessController interface defines a set of methods that can be used in a wide variety of applications to enforce access control. In most applications, access control must be performed in multiple different locations across the various application layers. The interface is built around the idea of subjects, actions, and resources. A specific subject/action/resource combination is known as a rule.
IAccessReferenceMap:The IAccessReferenceMap interface is used to map from a set of internal direct object references to a set of indirect references that are safe to disclose publicly. This can be used to help protect database keys, filenames, and other types of direct object references.
IEncoder: The IEncoder interface contains a number of methods related to encoding input so that it will be safe for a variety of interpreters.
IEncryptor:The IEncryptor interface provides a set of methods for performing common encryption, random number, and hashing operations.
IHttpUtilities:The IHTTPUtilities interface is a collection of methods that provide additional security related to HTTP requests, responses, sessions, cookies, headers, and logging. This class handles CSRF protection.
IIntrusionDetector: The IIntrusionDetector interface is intended to track security relevant events and identify attack behavior.
ILogger: The ILogger interface defines a set of methods that can be used to log events.
IRandomizer: The IRandomizer interface defines a set of methods for creating cryptographically random numbers and strings.
ISecurityConfiguration: The ISecurityConfiguration interface stores all configuration information that directs the behavior of the ESAPI implementation.
IValidator: The Validator interface defines a set of methods for validating untrusted input.

How is the .NET ESAPI different from the Java ESAPI?

The two projects are very similar in spirit, but there are some key differences. Most of the differences exist because the .NET ESAPI is a less complex project, although in some cases they exist because I disagree with the direction of the Java team.

There is no User component in the .NET ESAPI. While this is a big piece of the Java functionality, it significantly overlaps with the existing .NET Membership API. I've decided to use the Membership API in the reference classes, rather than re-invent the wheel of user management.
The Encoder class uses the AntiXss library. Again, there was significant overlap, and I felt there was no need to duplicate functionality. However, this means that canonicalization is not fully supported yet, since AntiXss only does encoding, not decoding.
HttpUtilities is extremely simple, with only a few supported methods. There are no wholesale request validation or logging methods, and interactions with the request itself are not protected.
The Logger implementation is very simple. It points to the Log4Net logger, which is configured independently of the ESAPI. There is no requirement to use Log4Net - you can write your own ILogger implementation that uses a different library.
IAccessReferenceMap has a somewhat different and, in my opinion, more consistent interface.
IAccessController is significantly simpler. It is based on the subject, action, resource access control paradigm (who does what to whom) and makes no assumption about how you will store these rules in your project.
SwingSet is both a reference and a starter kit. It contains examples of how to use the ESAPI in addition to other secure ASP.NET best practices.

How do I use the .NET ESAPI?

There are a couple of ways to get started with the .NET ESAPI.

If you simply want to start using the functionality, you can download the assembly and supporting files here. You will need to add Owasp.Esapi.dll and log4net.dll as references, and add the App.config settings to your configuration file. The documentation is available for download as a .chm file here or online here.

I would recommend downloading and exploring the entire solution so that you can become comfortable with the code. You can download the solution from Google Code with SVN. The solution is created with VS 2008 and .NET 3.5 (the actual code should be compatible with .NET 2.0, so it should be pretty simple to get it to compile in most environments). You can then run the unit test project and the SwingSet project to see how the .NET ESAPI works.

You will need to download and install the AntiXss library separately, in order to respect the code licensing.

The SwingSet application requires you to login - first you need to register a username. To do this, you also need to supply a SMTP host in the web.config file in SwingSet so that you can get an activation email. You can just use the external SMTP server for an email account you own and use that – i.e.

Is the .NET ESAPI mature/stable?

It's getting there. At this point, it's still a little early to call the .NET ESAPI a beta project - I hope that this release will allow enough people to provide feedback and join the team that we can get there soon.

How can I contribute?

First and foremost, join the ESAPI list. Feel free to contact me (me AT alexsmolen DOT com) and let me know if your interested in helping out - my first reply will be to download, use, and provide feedback on the current project. So far, I've had some real help from people like Paul Apostolescu and Taco Ditiecher. Thanks!