TrustAnchor

AI-generated Key Takeaways

• The TrustAnchor class represents a "most-trusted CA" used as an anchor for validating X.509 certification paths.

• It can be constructed using a trusted X509Certificate, or by specifying the CA's name and public key.

• TrustAnchor objects are immutable and thread-safe for concurrent access in various parts of the code.

• It includes methods to retrieve the CA's name, public key, name constraints, and the trusted certificate.

• Name constraints are optional and can be used for additional restrictions when validating certification paths.

public class TrustAnchor extends Object

A trust anchor or most-trusted Certification Authority (CA).

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 which may be validated using this key. These parameters can be specified in the form of a trusted X509Certificate or as individual parameters.

Concurrent Access

All TrustAnchor objects must be 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. This stipulation applies to all public fields and methods of this class and any added or overridden by subclasses.

See Also

• PKIXParameters.PKIXParameters(Set)
• PKIXBuilderParameters.PKIXBuilderParameters(Set, CertSelector)

Public Constructor Summary

	TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints) Creates an instance of TrustAnchor with the specified X509Certificate and optional name constraints, which are intended to be used as additional constraints when validating an X.509 certification path.
	TrustAnchor(X500Principal caPrincipal, PublicKey pubKey, byte[] nameConstraints) Creates an instance of TrustAnchor where the most-trusted CA is specified as an X500Principal and public key.
	TrustAnchor(String caName, PublicKey pubKey, byte[] nameConstraints) Creates an instance of TrustAnchor where the most-trusted CA is specified as a distinguished name and public key.

Public Method Summary

final X500Principal	getCA() Returns the name of the most-trusted CA as an X500Principal.
final String	getCAName() Returns the name of the most-trusted CA in RFC 2253 String format.
final PublicKey	getCAPublicKey() Returns the public key of the most-trusted CA.
final byte[]	getNameConstraints() Returns the name constraints parameter.
final X509Certificate	getTrustedCert() Returns the most-trusted CA certificate.
String	toString() Returns a formatted string describing the TrustAnchor.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

Public Constructors

public TrustAnchor (X509Certificate trustedCert, byte[] nameConstraints)

Creates an instance of TrustAnchor with the specified X509Certificate and optional name constraints, which are intended to be used as additional constraints when validating an X.509 certification path.

The name constraints are specified as a byte array. This byte array should contain the DER encoded form of the name constraints, as they would appear in the NameConstraints structure defined in RFC 3280 and X.509. The ASN.1 definition of this structure appears below.

NameConstraints ::= SEQUENCE {
       permittedSubtrees       [0]     GeneralSubtrees OPTIONAL,
       excludedSubtrees        [1]     GeneralSubtrees OPTIONAL }

  GeneralSubtrees ::= SEQUENCE SIZE (1..MAX) OF GeneralSubtree

  GeneralSubtree ::= SEQUENCE {
       base                    GeneralName,
       minimum         [0]     BaseDistance DEFAULT 0,
       maximum         [1]     BaseDistance OPTIONAL }

  BaseDistance ::= INTEGER (0..MAX)

  GeneralName ::= CHOICE {
       otherName                       [0]     OtherName,
       rfc822Name                      [1]     IA5String,
       dNSName                         [2]     IA5String,
       x400Address                     [3]     ORAddress,
       directoryName                   [4]     Name,
       ediPartyName                    [5]     EDIPartyName,
       uniformResourceIdentifier       [6]     IA5String,
       iPAddress                       [7]     OCTET STRING,
       registeredID                    [8]     OBJECT IDENTIFIER}
 

Note that the name constraints byte array supplied is cloned to protect against subsequent modifications.

Parameters

trustedCert	a trusted X509Certificate
nameConstraints	a byte array containing the ASN.1 DER encoding of a NameConstraints extension to be used for checking name constraints. Only the value of the extension is included, not the OID or criticality flag. Specify null to omit the parameter.

Throws

IllegalArgumentException	if the name constraints cannot be decoded
NullPointerException	if the specified X509Certificate is null

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

Creates an instance of TrustAnchor where the most-trusted CA is specified as an X500Principal and public key. Name constraints are an optional parameter, and are intended to be used as additional constraints when validating an X.509 certification path.

The name constraints are specified as a byte array. This byte array contains the DER encoded form of the name constraints, as they would appear in the NameConstraints structure defined in RFC 3280 and X.509. The ASN.1 notation for this structure is supplied in the documentation for TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints) .

Note that the name constraints byte array supplied here is cloned to protect against subsequent modifications.

Parameters

caPrincipal	the name of the most-trusted CA as X500Principal
pubKey	the public key of the most-trusted CA
nameConstraints	a byte array containing the ASN.1 DER encoding of a NameConstraints extension to be used for checking name constraints. Only the value of the extension is included, not the OID or criticality flag. Specify null to omit the parameter.

Throws

NullPointerException	if the specified caPrincipal or pubKey parameter is null

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

Creates an instance of TrustAnchor where the most-trusted CA is specified as a distinguished name and public key. Name constraints are an optional parameter, and are intended to be used as additional constraints when validating an X.509 certification path.

The name constraints are specified as a byte array. This byte array contains the DER encoded form of the name constraints, as they would appear in the NameConstraints structure defined in RFC 3280 and X.509. The ASN.1 notation for this structure is supplied in the documentation for TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints) .

Note that the name constraints byte array supplied here is cloned to protect against subsequent modifications.

Parameters

caName	the X.500 distinguished name of the most-trusted CA in RFC 2253 String format
pubKey	the public key of the most-trusted CA
nameConstraints	a byte array containing the ASN.1 DER encoding of a NameConstraints extension to be used for checking name constraints. Only the value of the extension is included, not the OID or criticality flag. Specify null to omit the parameter.

Throws

IllegalArgumentException	if the specified caName parameter is empty (caName.length() == 0) or incorrectly formatted or the name constraints cannot be decoded
NullPointerException	if the specified caName or pubKey parameter is null

Public Methods

public final X500Principal getCA ()

Returns the name of the most-trusted CA as an X500Principal.

Returns

• the X.500 distinguished name of the most-trusted CA, or null if the trust anchor was not specified as a trusted public key and name or X500Principal pair

public final String getCAName ()

Returns the name of the most-trusted CA in RFC 2253 String format.

Returns

• the X.500 distinguished name of the most-trusted CA, or null if the trust anchor was not specified as a trusted public key and name or X500Principal pair

public final PublicKey getCAPublicKey ()

Returns the public key of the most-trusted CA.

Returns

• the public key of the most-trusted CA, or null if the trust anchor was not specified as a trusted public key and name or X500Principal pair

public final byte[] getNameConstraints ()

Returns the name constraints parameter. The specified name constraints are associated with this trust anchor and are intended to be used as additional constraints when validating an X.509 certification path.

The name constraints are returned as a byte array. This byte array contains the DER encoded form of the name constraints, as they would appear in the NameConstraints structure defined in RFC 3280 and X.509. The ASN.1 notation for this structure is supplied in the documentation for TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints) .

Note that the byte array returned is cloned to protect against subsequent modifications.

Returns

• a byte array containing the ASN.1 DER encoding of a NameConstraints extension used for checking name constraints, or null if not set.

public final X509Certificate getTrustedCert ()

Returns the most-trusted CA certificate.

Returns

• a trusted X509Certificate or null if the trust anchor was not specified as a trusted certificate

public String toString ()

Returns a formatted string describing the TrustAnchor.

Returns

• a formatted string describing the TrustAnchor