sean.mullan@ireland 2001-07-12

The following changes should be made to the immutable classes in the CertPath
API to improve their security and overall design. The rationale is based on
item 13 in Josh Bloch's Effective Java book.

1) Make PolicyQualifierInfo final

This prevents developers from creating mutable subclasses.

2) Make all the methods of TrustAnchor final

We don't really want to mark TrustAnchor final, since a developer may have good
reason to create a subclass with new methods to support additional constraints
on the anchor, for example. Marking the methods final seems to be the next
best solution and prevents developers from creating subclasses that override
the immutable contract of these methods.

3) Remove the isImmutable() method from PolicyNode, and require that instances
always be completely immutable.

This simplifies the contract for this class considerably. This is one place
we tried to retrofit the API to fit our implementation, which is usually
an indication of bad design.

We can create a new internal class that implements PolicyNode. This class
should have a private constructor that takes a PolicyNodeImpl (in the
immutable state) as a parameter and each of the public methods will simply
call the corresponding methods in PolicyNodeImpl. This constructor would
be called by our PKIX builder and validator before returning the result
to the caller.

4) Change the class summary of CertPath to be more
explicit that it also applies to overridden methods, the last
sentence of the 3rd paragraph should probably say: "... and any
added or overridden by subclasses."

Note that we can't make CertPath final, since it is an abstract class. This
means it is possible for a developer to break the contract and create a
mutable subclass. I don't know how we can guard against this, other than
informing programmers to be wary of accepting a CertPath from untrusted
code. We should raise this as a more general issue since there are other
immutable classes which are not final and are also abstract, such as
Certificate and X509Certificate.