org.owasp.esapi
Interface AccessReferenceMap

All Known Implementing Classes:

RandomAccessReferenceMap

public interface 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.

 Set fileSet = new HashSet();
 fileSet.addAll(...); // add direct references (e.g. File objects)
 AccessReferenceMap map = new AccessReferenceMap( fileSet );
 // store the map somewhere safe - like the session!
 String indRef = map.getIndirectReference( file1 );
 String href = "http://www.aspectsecurity.com/esapi?file=" + indRef );
 ...
 String indref = request.getParameter( "file" );
 File file = (File)map.getDirectReference( indref );
 

Author:

Jeff Williams (jeff.williams@aspectsecurity.com)

Method Summary

java.lang.String	addDirectReference(java.lang.Object direct) Adds a direct reference to the AccessReferenceMap and generates an associated indirect reference.
java.lang.Object	getDirectReference(java.lang.String indirectReference) Get the original direct object reference from an indirect reference.
java.lang.String	getIndirectReference(java.lang.Object directReference) Get a safe indirect reference to use in place of a potentially sensitive direct object reference.
java.util.Iterator	iterator() Get an iterator through the direct object references.
java.lang.String	removeDirectReference(java.lang.Object direct) Removes a direct reference and its associated indirect reference from the AccessReferenceMap.

Method Detail

iterator

public java.util.Iterator iterator()

Get an iterator through the direct object references. No guarantee is made as to the order of items returned.

Returns:

the iterator

getIndirectReference

public java.lang.String getIndirectReference(java.lang.Object directReference)

Get a safe indirect reference to use in place of a potentially sensitive direct object reference. Developers should use this call when building URL's, form fields, hidden fields, etc... to help protect their private implementation information.

Parameters:

directReference - the direct reference

Returns:

the indirect reference

getDirectReference

public java.lang.Object getDirectReference(java.lang.String indirectReference)
                                    throws AccessControlException

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 indirectReference is requested, then an AccessControlException is thrown.

Parameters:

indirectReference - the indirect reference

Returns:

the direct reference

Throws:

AccessControlException - if no direct reference exists for the specified indirect reference

addDirectReference

public java.lang.String addDirectReference(java.lang.Object direct)

Adds a direct reference to the AccessReferenceMap and generates an associated indirect reference.

Parameters:

direct - the direct reference

Returns:

the corresponding indirect reference

removeDirectReference

public java.lang.String removeDirectReference(java.lang.Object direct)
                                       throws AccessControlException

Removes a direct reference and its associated indirect reference from the AccessReferenceMap.

Parameters:

direct - the direct reference to remove

Returns:

the corresponding indirect reference

Throws:

AccessControlException - FIXME Why might we throw an ACE here?