Package org.owasp.esapi
Interface AccessReferenceMap<K>
-
- All Superinterfaces:
java.io.Serializable
- All Known Implementing Classes:
AbstractAccessReferenceMap
,IntegerAccessReferenceMap
,RandomAccessReferenceMap
public interface AccessReferenceMap<K> extends java.io.Serializable
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 ); ... // if the indirect reference doesn't exist, it's likely an attack // getDirectReference throws an AccessControlException // you should handle as appropriate String indref = request.getParameter( "file" ); File file = (File)map.getDirectReference( indref );
- Author:
- Jeff Williams (jeff.williams@aspectsecurity.com), Chris Schmidt (chrisisbeef@gmail.com)
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description <T> K
addDirectReference(T direct)
Adds a direct reference to the AccessReferenceMap, then generates and returns an associated indirect reference.<T> T
getDirectReference(K indirectReference)
Get the original direct object reference from an indirect reference.<T> K
getIndirectReference(T 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.<T> K
removeDirectReference(T direct)
Removes a direct reference and its associated indirect reference from the AccessReferenceMap.void
update(java.util.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.
-
-
-
Method Detail
-
iterator
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
<T> K getIndirectReference(T 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
<T> T getDirectReference(K 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 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. For example:UserProfile profile = arm.getDirectReference( indirectRef );
Will throw a AccessControlException if the object stored in memory is not of type UserProfile. However,Object uncastObject = arm.getDirectReference( indirectRef );
Will never throw a AccessControlException as long as the object exists. If you are unsure of the object type of that an indirect reference references you should get the uncast object and test for type in the calling code.Object uncastProfile = arm.getDirectReference( indirectRef ); if ( uncastProfile instanceof UserProfile ) { UserProfile userProfile = (UserProfile) uncastProfile; // ... } else { EmployeeProfile employeeProfile = (EmployeeProfile) uncastProfile; // ... }
- Parameters:
indirectReference
- the indirect reference- Returns:
- the direct reference
- Throws:
AccessControlException
- if no direct reference exists for the specified indirect referencejava.lang.ClassCastException
- if the implied type is not the same as the referenced object type
-
addDirectReference
<T> K addDirectReference(T direct)
Adds a direct reference to the AccessReferenceMap, then generates and returns an associated indirect reference.- Parameters:
direct
- the direct reference- Returns:
- the corresponding indirect reference
-
removeDirectReference
<T> K removeDirectReference(T 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
- if the reference does not exist.
-
update
void update(java.util.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. New indirect references could be generated every time, but that might mess up anything that previously used an indirect reference, such as a URL parameter.- Parameters:
directReferences
- a Set of direct references to add
-
-