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.

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

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

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.

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.