Top Description Fields Constructors Methods
java.security.cert

public Class TrustAnchor

extends Object
Class Inheritance
Imports
java.io.IOException, java.security.PublicKey, javax.security.auth.x500.X500Principal, sun.security.util.AnchorCertificates, sun.security.x509.NameConstraintsExtension
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.

Author
Sean Mullan
Since
1.4
See Also
PKIXParameters#PKIXParameters(Set), PKIXBuilderParameters#PKIXBuilderParameters(Set, CertSelector)

Field Summary

Modifier and TypeField and Description
private final String
caName

private final X500Principal
caPrincipal

private boolean
hasJdkCABeenChecked

private boolean
jdkCA

private NameConstraintsExtension
nc

private byte[]
ncBytes

private final PublicKey
pubKey

private final X509Certificate
trustedCert

Constructor Summary

AccessConstructor and Description
public
TrustAnchor(X509Certificate
a trusted X509Certificate
trustedCert, byte[]
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.
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.

public
TrustAnchor(X500Principal
the name of the most-trusted CA as X500Principal
caPrincipal, PublicKey
the public key of the most-trusted CA
pubKey, byte[]
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.
nameConstraints)

Creates an instance of TrustAnchor where the most-trusted CA is specified as an X500Principal and public key.

public
TrustAnchor(String
the X.500 distinguished name of the most-trusted CA in RFC 2253 String format
caName, PublicKey
the public key of the most-trusted CA
pubKey, byte[]
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.
nameConstraints)

Creates an instance of TrustAnchor where the most-trusted CA is specified as a distinguished name and public key.

Method Summary

Modifier and TypeMethod and Description
public final 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
getCA()

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

public final String

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
getCAName()

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

public final PublicKey

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
getCAPublicKey()

Returns the public key of the most-trusted CA.

public final byte[]

Returns:

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

Returns the name constraints parameter.

public final X509Certificate

Returns:

a trusted X509Certificate or null if the trust anchor was not specified as a trusted certificate
getTrustedCert()

Returns the most-trusted CA certificate.

pack-priv synchronized boolean
isJdkCA()

Returns true if anchor is a JDK CA (a root CA that is included by default in the cacerts keystore).

private void
setNameConstraints(byte[] bytes)

Decode the name constraints and clone them if not null.

public String

Returns:

a formatted string describing the TrustAnchor
toString()

Overrides java.lang.Object.toString.

Returns a formatted string describing the TrustAnchor.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

caNameback to summary
private final String caName
caPrincipalback to summary
private final X500Principal caPrincipal
hasJdkCABeenCheckedback to summary
private boolean hasJdkCABeenChecked
jdkCAback to summary
private boolean jdkCA
ncback to summary
private NameConstraintsExtension nc
ncBytesback to summary
private byte[] ncBytes
pubKeyback to summary
private final PublicKey pubKey
trustedCertback to summary
private final X509Certificate trustedCert

Constructor Detail

TrustAnchorback to summary
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 5280 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:X509Certificate

a trusted X509Certificate

nameConstraints:byte[]

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.

Exceptions
IllegalArgumentException:
if the name constraints cannot be decoded
NullPointerException:
if the specified X509Certificate is null
TrustAnchorback to summary
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 5280 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:X500Principal

the name of the most-trusted CA as X500Principal

pubKey:PublicKey

the public key of the most-trusted CA

nameConstraints:byte[]

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.

Exceptions
NullPointerException:
if the specified caPrincipal or pubKey parameter is null
Since
1.5
TrustAnchorback to summary
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 5280 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:String

the X.500 distinguished name of the most-trusted CA in RFC 2253 String format

pubKey:PublicKey

the public key of the most-trusted CA

nameConstraints:byte[]

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.

Exceptions
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 Detail

getCAback to summary
public final X500Principal getCA()

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

Returns:X500Principal

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

Since
1.5
getCANameback to summary
public final String getCAName()

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

Returns:String

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

getCAPublicKeyback to summary
public final PublicKey getCAPublicKey()

Returns the public key of the most-trusted CA.

Returns:PublicKey

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

getNameConstraintsback to summary
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 5280 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:byte[]

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

getTrustedCertback to summary
public final X509Certificate getTrustedCert()

Returns the most-trusted CA certificate.

Returns:X509Certificate

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

isJdkCAback to summary
pack-priv synchronized boolean isJdkCA()

Returns true if anchor is a JDK CA (a root CA that is included by default in the cacerts keystore).

setNameConstraintsback to summary
private void setNameConstraints(byte[] bytes)

Decode the name constraints and clone them if not null.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a formatted string describing the TrustAnchor.

Returns:String

a formatted string describing the TrustAnchor