ESAPI Specification

This document is currently under development - Please use the Discussion page for threaded conversation

= Proposed Migration Roadmap =
 * ESAPI 2.1
 * Create new package org.owasp.esapi.core
 * Create new set of Interfaces in new package with each extending it's org.owasp.esapi counterpart
 * Deprecate methods in org.owasp.esapi Interfaces
 * ESAPI 2.5
 * Remove deprecated methods that were deprecated at or before ESAPI 2.0
 * Introduce new ServiceLocator API
 * ESAPI 3.0
 * Seperate Core API into it's own artifact/project called ESAPI-Core
 * Create new set of artifacts as outlined in ESAPI_Project_Structure
 * Introduce Core API Testing Suite

= Core API Specification =

AccessController
The AccessController is responsible for determining if the currently logged in user has access to a given resource. The resource can be anything that implements the Resource Interface.

Changes from ESAPI 2.0

 * Removed deprecated methods
 * Added Generic Stereotypes to the Resource and Context parameters)

 void assertAuthorized(Resource resource, Context context) throws AccessDeniedException
Assert that the currently logged in user can access the given Resource with the given Context parameters

 boolean isAuthorized(Resource resource, Context context)
Determine if the given resource is accessible by the currently logged in User

Return
Returns true if the resource is accessible to the currently logged in user and false if it is not.

AccessReferenceMap
The AccessReferenceMap 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. As a rule, developers should not expose their direct object references as it enables attackers to attempt to manipulate them.

Indirect references are handled as strings, to facilitate their use in HTML. Implementations can generate simple integers or more complicated random character strings as indirect references. Implementations should probably add a constructor that takes a list of direct references.

Note that in addition to defeating all forms of parameter tampering attacks, there is a side benefit of the AccessReferenceMap. Using random strings as indirect object references, as opposed to simple integers makes it impossible for an attacker to guess valid identifiers. So if per-user AccessReferenceMaps are used, then request forgery (CSRF) attacks will also be prevented.

 Key addDirectReference(Type direct)
Adds a direct reference to the AccessReferenceMap, then generates and returns an associated indirect reference.

Return
The key for the added Direct Reference

 Type getDirectReference(Key key)
Get the original direct object reference from an indirect reference. Developers should use this when they get an indirect reference from a request to translate it back into the real direct reference. If an invalid indirect reference is requested, then an AccessControlException is thrown. If a type is implied the requested object will be cast to that type, if the object is not of the requested type, a AccessControlException will be thrown to the caller.

Return
The direct reference

 Key getIndirectReference(Type directReference)
Get a safe indirect reference to use in place of a potentially sensitive direct object reference.

Return
The indirect reference

 Key removeDirectReference(Type directReference)
Removes a direct reference and its associated indirect reference from the AccessReferenceMap.

 void update(Set directReferences)
Updates the access reference map with a new set of direct references, maintaining any existing indirect references associated with items that are in the new list.

LogFactory
Still thinking this one through

Logger
Still thinking this one through

Resource
Marker Interface for Resources that a user can request access to.

IncorrectCredentialsException
= Web API Specification = This API describes the components that can be used in the context of a Web Application.

Extends

 * Resource

void removeSession(SecureHttpSession session)
= Mobile API Specification =

= Desktop API Specification =