The TrustAnchor Class

This class represents a "most-trusted CA", which is used as a trust anchor for validating X.509 certification paths. A most-trusted CA includes the public key of the CA, the CA's name, and any constraints upon the set of paths that can be validated using this key. These parameters can be specified in the form of a trusted X509Certificate or as individual parameters.

All TrustAnchor objects are immutable and thread-safe. That is, multiple threads may concurrently invoke the methods defined in this class on a single TrustAnchor object (or more than one) with no ill effects. Requiring TrustAnchor objects to be immutable and thread-safe allows them to be passed around to various pieces of code without worrying about coordinating access.

Note that although this class is described as a PKIX class it can be used with other X.509 certification path validation algorithms.

Creating a TrustAnchor Object

To instantiate a TrustAnchor object, a caller must specify "the most-trusted CA" as a trusted X509Certificate or public key and distinguished name pair. The caller can also optionally specify name constraints that are applied to the trust anchor by the validation algorithm during initialization. Note that support for name constraints on trust anchors is not required by the PKIX algorithm; therefore, a PKIX CertPathValidator or CertPathBuilder can choose not to support this parameter and instead throw an exception. Use one of the following constructors to create a TrustAnchor object:

public TrustAnchor(X509Certificate trustedCert,
        byte[] nameConstraints)

public TrustAnchor(String caName, PublicKey pubKey,
        byte[] nameConstraints)

public TrustAnchor(X500Principal caPrincipal, PublicKey pubKey,
        byte[] nameConstraints)

The nameConstraints parameter is specified as a byte array containing the ASN.1 DER encoding of a NameConstraints extension. An IllegalArgumentException is thrown if the name constraints cannot be decoded (are not formatted correctly).

Getting Parameter Values

Each of the parameters can be retrieved using a corresponding get method:

public final X509Certificate getTrustedCert()

public final String getCAName()

public final PublicKey getCAPublicKey()

public final byte[] getNameConstraints()

public final X500Principal getCA()

Note that the getTrustedCert method returns null if the trust anchor was specified as a public key and name pair. Likewise, the getCAName, getCA, and getCAPublicKey methods return null if the trust anchor was specified as an X509Certificate.