java.security.cert: public class: TrustAnchor

java.security.cert
public class: TrustAnchor [javadoc | source]

java.lang.Object
   java.security.cert.TrustAnchor

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.

Also see:

PKIXParameters#PKIXParameters(Set)

PKIXBuilderParameters#PKIXBuilderParameters(Set, CertSelector)

since: 1.4 -

author: Sean - Mullan

Constructor:

Constructor:
public TrustAnchor(X509Certificate trustedCert, byte[] nameConstraints) { if (trustedCert == null) throw new NullPointerException("the trustedCert parameter must " + "be non-null"); this.trustedCert = trustedCert; this.pubKey = null; this.caName = null; this.caPrincipal = null; setNameConstraints(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) { if ((caPrincipal == null) \|\| (pubKey == null)) { throw new NullPointerException(); } this.trustedCert = null; this.caPrincipal = caPrincipal; this.caName = caPrincipal.getName(); this.pubKey = pubKey; setNameConstraints(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 byte[]) 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` since: `1.5` -
public TrustAnchor(String caName, PublicKey pubKey, byte[] nameConstraints) { if (pubKey == null) throw new NullPointerException("the pubKey parameter must be " + "non-null"); if (caName == null) throw new NullPointerException("the caName parameter must be " + "non-null"); if (caName.length() == 0) throw new IllegalArgumentException("the caName " + "parameter must be a non-empty String"); // check if caName is formatted correctly this.caPrincipal = new X500Principal(caName); this.pubKey = pubKey; this.caName = caName; this.trustedCert = null; setNameConstraints(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 byte[]) 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 TrustAnchor(X509Certificate trustedCert,
    byte[] nameConstraints) {
        if (trustedCert == null)
            throw new NullPointerException("the trustedCert parameter must " +
                "be non-null");
        this.trustedCert = trustedCert;
        this.pubKey = null;
        this.caName = null;
        this.caPrincipal = null;
        setNameConstraints(nameConstraints);
}

TrustAnchor

X509Certificate

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) {
        if ((caPrincipal == null) || (pubKey == null)) {
            throw new NullPointerException();
        }
        this.trustedCert = null;
        this.caPrincipal = caPrincipal;
        this.caName = caPrincipal.getName();
        this.pubKey = pubKey;
        setNameConstraints(nameConstraints);
}

TrustAnchor

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 byte[]) 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

Throws:

NullPointerException - if the specified caPrincipal or pubKey parameter is null

since: 1.5 -

 public TrustAnchor(String caName,
    PublicKey pubKey,
    byte[] nameConstraints) {
        if (pubKey == null)
            throw new NullPointerException("the pubKey parameter must be " +
                "non-null");
        if (caName == null)
            throw new NullPointerException("the caName parameter must be " +
                "non-null");
        if (caName.length() == 0)
            throw new IllegalArgumentException("the caName " +
                "parameter must be a non-empty String");
        // check if caName is formatted correctly
        this.caPrincipal = new X500Principal(caName);
        this.pubKey = pubKey;
        this.caName = caName;
        this.trustedCert = null;
        setNameConstraints(nameConstraints);
}

TrustAnchor

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

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

Method from java.security.cert.TrustAnchor Summary:
getCA, getCAName, getCAPublicKey, getNameConstraints, getTrustedCert, toString

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from java.security.cert.TrustAnchor Detail:
public final X500Principal getCA() { return this.caPrincipal; } Returns the name of the most-trusted CA as an X500Principal.
public final String getCAName() { return this.caName; } Returns the name of the most-trusted CA in RFC 2253 `String` format.
public final PublicKey getCAPublicKey() { return this.pubKey; } Returns the public key of the most-trusted CA.
public final byte[] getNameConstraints() { return ncBytes == null ? null : ncBytes.clone(); } 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 byte[]) trustedCert, byte[] nameConstraints) . Note that the byte array returned is cloned to protect against subsequent modifications.
public final X509Certificate getTrustedCert() { return this.trustedCert; } Returns the most-trusted CA certificate.
public String toString() { StringBuffer sb = new StringBuffer(); sb.append("[\n"); if (pubKey != null) { sb.append(" Trusted CA Public Key: " + pubKey.toString() + "\n"); sb.append(" Trusted CA Issuer Name: " + String.valueOf(caName) + "\n"); } else { sb.append(" Trusted CA cert: " + trustedCert.toString() + "\n"); } if (nc != null) sb.append(" Name Constraints: " + nc.toString() + "\n"); return sb.toString(); } Returns a formatted string describing the `TrustAnchor`.

Method from java.security.cert.TrustAnchor Detail:

 public final X500Principal getCA() {
        return this.caPrincipal;
}

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

 public final String getCAName() {
        return this.caName;
}

String

 public final PublicKey getCAPublicKey() {
        return this.pubKey;
}

Returns the public key of the most-trusted CA.

 public final byte[] getNameConstraints() {
        return ncBytes == null ? null : ncBytes.clone();
}

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 byte[]) trustedCert, byte[] nameConstraints) .

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

 public final X509Certificate getTrustedCert() {
        return this.trustedCert;
}

Returns the most-trusted CA certificate.

 public String toString() {
        StringBuffer sb = new StringBuffer();
        sb.append("[\n");
        if (pubKey != null) {
            sb.append("  Trusted CA Public Key: " + pubKey.toString() + "\n");
            sb.append("  Trusted CA Issuer Name: "
                + String.valueOf(caName) + "\n");
        } else {
            sb.append("  Trusted CA cert: " + trustedCert.toString() + "\n");
        }
        if (nc != null)
            sb.append("  Name Constraints: " + nc.toString() + "\n");
        return sb.toString();
}

TrustAnchor