java.security.cert
Class X509CertSelector

java.lang.Object
  extended by java.security.cert.X509CertSelector
All Implemented Interfaces:
Cloneable, CertSelector

public class X509CertSelector
extends Object
implements CertSelector, Cloneable

A concrete implementation of CertSelector for X.509 certificates, which allows a number of criteria to be set when accepting certificates, from validity dates, to issuer and subject distinguished names, to some of the various X.509 extensions.

Use of this class requires extensive knowledge of the Internet Engineering Task Force's Public Key Infrastructure (X.509). The primary document describing this standard is RFC 3280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.

Note that this class is not thread-safe. If multiple threads will use or modify this class then they need to synchronize on the object.

Since:
1.4

Constructor Summary
X509CertSelector()
          Creates a new X.509 certificate selector.
 
Method Summary
 void addPathToName(int id, byte[] name)
          Add a name to match in the NameConstraints extension.
 void addPathToName(int id, String name)
          Add a name to match in the NameConstraints extension.
 void addSubjectAlternativeName(int id, byte[] name)
          Add a name, as DER-encoded bytes, to the subject alternative names criterion.
 void addSubjectAlternativeName(int id, String name)
          Add a name to the subject alternative names criterion.
 Object clone()
          This method may be called to create a new copy of the Object.
 byte[] getAuthorityKeyIdentifier()
          Returns the authority key identifier criterion, or null if this value was not set.
 int getBasicConstraints()
          Returns the basic constraints criterion, or -1 if this value is not set.
 X509Certificate getCertificate()
          Returns the certificate criterion, or null if this value was not set.
 Date getCertificateValid()
          Returns the date at which certificates must be valid, or null if this criterion was not set.
 Set<String> getExtendedKeyUsage()
          Returns the set of extended key purpose IDs, as an unmodifiable set of OID strings.
 byte[] getIssuerAsBytes()
          Returns the issuer criterion as a sequence of DER bytes, or null if this value was not set.
 String getIssuerAsString()
          Returns the issuer criterion as a string, or null if this value was not set.
 boolean[] getKeyUsage()
          Returns the public key usage criterion, or null if this value is not set.
 boolean getMatchAllSubjectAltNames()
          Returns whether or not all specified alternative names must match.
 byte[] getNameConstraints()
          Returns the name constraints criterion, or null if this value is not set.
 Collection<List<?>> getPathToNames()
           
 Set<String> getPolicy()
          Returns the certificate policy extension that will be matched by this selector, or null if the certificate policy will not be matched.
 Date getPrivateKeyValid()
          This method, and its related X.509 certificate extension — the private key usage period — is not supported under the Internet PKI for X.509 certificates (PKIX), described in RFC 3280.
 BigInteger getSerialNumber()
          Returns the serial number criterion, or null if this value was not set.
 Collection<List<?>> getSubjectAlternativeNames()
          Get the subject alternative names criterion.
 byte[] getSubjectAsBytes()
          Returns the subject criterion as a sequence of DER bytes, or null if this value is not set.
 String getSubjectAsString()
          Returns the subject criterion as a string, of null if this value was not set.
 byte[] getSubjectKeyIdentifier()
          Returns the subject key identifier criterion, or null if this value was not set.
 PublicKey getSubjectPublicKey()
          Returns the subject public key criterion, or null if this value is not set.
 String getSubjectPublicKeyAlgID()
          Returns the public key algorithm ID that matching certificates must have, or null if this criterion was not set.
 boolean match(Certificate certificate)
          Match a certificate.
 void setAuthorityKeyIdentifier(byte[] authKeyId)
          Sets the authority key identifier criterion, or null to clear this criterion.
 void setBasicConstraints(int basicConstraints)
          Sets the basic constraints criterion.
 void setCertificate(X509Certificate cert)
          Sets the certificate criterion.
 void setCertificateValid(Date certValid)
          Sets the date at which certificates must be valid.
 void setExtendedKeyUsage(Set<String> keyPurposeSet)
          Sets the extended key usage criterion, as a set of OID strings.
 void setIssuer(byte[] name)
          Sets the issuer, specified as the DER encoding of the issuer's distinguished name.
 void setIssuer(String name)
          Sets the issuer, specified as a string representation of the issuer's distinguished name.
 void setKeyUsage(boolean[] keyUsage)
          Sets the public key usage criterion.
 void setMatchAllSubjectAltNames(boolean matchAllNames)
          Sets whether or not all subject alternative names must be matched.
 void setNameConstraints(byte[] nameConstraints)
          Sets the name constraints criterion; specify null to clear this criterion.
 void setPathToNames(Collection<List<?>> names)
          Sets the pathToNames criterion.
 void setPolicy(Set<String> policy)
          Sets the certificate policy to match, or null if this criterion should not be checked.
 void setPrivateKeyValid(Date UNUSED)
          This method, and its related X.509 certificate extension — the private key usage period — is not supported under the Internet PKI for X.509 certificates (PKIX), described in RFC 3280.
 void setSerialNumber(BigInteger serialNo)
          Sets the serial number of the desired certificate.
 void setSubject(byte[] name)
          Sets the subject, specified as the DER encoding of the subject's distinguished name.
 void setSubject(String name)
          Sets the subject, specified as a string representation of the subject's distinguished name.
 void setSubjectAlternativeNames(Collection<List<?>> altNames)
          Sets the subject alternative names critertion.
 void setSubjectKeyIdentifier(byte[] subjectKeyId)
          Sets the subject key identifier criterion, or null to clear this criterion.
 void setSubjectPublicKey(byte[] key)
          Sets the subject public key criterion as a DER-encoded key.
 void setSubjectPublicKey(PublicKey key)
          Sets the subject public key criterion as an opaque representation.
 void setSubjectPublicKeyAlgID(String sigId)
          Sets the public key algorithm ID that matching certificates must have.
 String toString()
          Convert this Object to a human-readable String.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

X509CertSelector

public X509CertSelector()
Creates a new X.509 certificate selector. The new selector will be empty, and will accept any certificate (provided that it is an X509Certificate).

Method Detail

addPathToName

public void addPathToName(int id,
                          byte[] name)
                   throws IOException
Add a name to match in the NameConstraints extension. The argument is the DER-encoded bytes of a GeneralName structure. See the method addSubjectAlternativeName(int, byte[]) for the format of the GeneralName structure.

Parameters:
id - The name identifier. Must be between 0 and 8.
name - The DER-encoded bytes of the name to match.
Throws:
IOException - If the name DER is malformed.

addPathToName

public void addPathToName(int id,
                          String name)
                   throws IOException
Add a name to match in the NameConstraints extension. This method will only recognize certain types of name that have convenient string encodings. For robustness, you should use the addPathToName(int, byte[]) method whenever possible.

Parameters:
id - The name identifier. Must be between 0 and 8.
name - The name.
Throws:
IOException - If the name cannot be decoded.

addSubjectAlternativeName

public void addSubjectAlternativeName(int id,
                                      byte[] name)
                               throws IOException
Add a name, as DER-encoded bytes, to the subject alternative names criterion. The name is a GeneralName structure, which has the ASN.1 format:
  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 }

Parameters:
id - The type of name this is.
name - The DER-encoded name.
Throws:
IOException - If the name is not a valid DER sequence.

addSubjectAlternativeName

public void addSubjectAlternativeName(int id,
                                      String name)
                               throws IOException
Add a name to the subject alternative names criterion. This method will only recognize certain types of name that have convenient string encodings. For robustness, you should use the addSubjectAlternativeName(int, byte[]) method whenever possible. This method can only decode certain name kinds of names as strings.

Parameters:
id - The type of name this is. Must be in the range [0,8].
name - The name.
Throws:
IOException - If the id is out of range, or if the name is null.

clone

public Object clone()
Description copied from class: Object
This method may be called to create a new copy of the Object. The typical behavior is as follows:

However, these are not strict requirements, and may be violated if necessary. Of the three requirements, the last is the most commonly violated, particularly if the subclass does not override Object.equals(Object).

If the Object you call clone() on does not implement Cloneable (which is a placeholder interface), then a CloneNotSupportedException is thrown. Notice that Object does not implement Cloneable; this method exists as a convenience for subclasses that do.

Object's implementation of clone allocates space for the new Object using the correct class, without calling any constructors, and then fills in all of the new field values with the old field values. Thus, it is a shallow copy. However, subclasses are permitted to make a deep copy.

All array types implement Cloneable, and override this method as follows (it should never fail):

 public Object clone()
 {
   try
     {
       super.clone();
     }
   catch (CloneNotSupportedException e)
     {
       throw new InternalError(e.getMessage());
     }
 }
 

Specified by:
clone in interface CertSelector
Overrides:
clone in class Object
Returns:
a copy of the Object
See Also:
Cloneable

getAuthorityKeyIdentifier

public byte[] getAuthorityKeyIdentifier()
Returns the authority key identifier criterion, or null if this value was not set. Note that the byte array is cloned to prevent modification.

Returns:
The authority key identifier.

getBasicConstraints

public int getBasicConstraints()
Returns the basic constraints criterion, or -1 if this value is not set.

Returns:
The basic constraints.

getCertificate

public X509Certificate getCertificate()
Returns the certificate criterion, or null if this value was not set.

Returns:
The certificate.

getCertificateValid

public Date getCertificateValid()
Returns the date at which certificates must be valid, or null if this criterion was not set.

Returns:
The target certificate valitity date.

getExtendedKeyUsage

public Set<String> getExtendedKeyUsage()
Returns the set of extended key purpose IDs, as an unmodifiable set of OID strings. Returns null if this criterion is not set.

Returns:
The set of key purpose OIDs (strings).

getIssuerAsBytes

public byte[] getIssuerAsBytes()
                        throws IOException
Returns the issuer criterion as a sequence of DER bytes, or null if this value was not set.

Returns:
The issuer.
Throws:
IOException

getIssuerAsString

public String getIssuerAsString()
Returns the issuer criterion as a string, or null if this value was not set.

Returns:
The issuer.

getKeyUsage

public boolean[] getKeyUsage()
Returns the public key usage criterion, or null if this value is not set. Note that the array is cloned to prevent modification.

Returns:
The public key usage.

getMatchAllSubjectAltNames

public boolean getMatchAllSubjectAltNames()
Returns whether or not all specified alternative names must match. If false, a certificate is considered a match if one of the specified alternative names matches.

Returns:
true if all names must match.

getNameConstraints

public byte[] getNameConstraints()
Returns the name constraints criterion, or null if this value is not set. Note that the byte array is cloned to prevent modification.

Returns:
The name constraints.

getPathToNames

public Collection<List<?>> getPathToNames()

getPolicy

public Set<String> getPolicy()
Returns the certificate policy extension that will be matched by this selector, or null if the certificate policy will not be matched.

Returns:
The policy to be matched, or null.

getPrivateKeyValid

public Date getPrivateKeyValid()
This method, and its related X.509 certificate extension — the private key usage period — is not supported under the Internet PKI for X.509 certificates (PKIX), described in RFC 3280. As such, this method is not supported either.

Do not use this method. It is not deprecated, as it is not deprecated in the Java standard, but it is basically a no-operation and simply returns null.

Returns:
Null.

getSerialNumber

public BigInteger getSerialNumber()
Returns the serial number criterion, or null if this value was not set.

Returns:
The serial number.

getSubjectAlternativeNames

public Collection<List<?>> getSubjectAlternativeNames()
Get the subject alternative names criterion. The collection returned is a collection of pairs: the first element is an Integer containing the name type, and the second is a byte array containing the DER-encoded name bytes.

Returns:
The subject alternative names criterion. Returns null if this criterion is not set.

getSubjectAsBytes

public byte[] getSubjectAsBytes()
                         throws IOException
Returns the subject criterion as a sequence of DER bytes, or null if this value is not set.

Returns:
The subject.
Throws:
IOException

getSubjectAsString

public String getSubjectAsString()
Returns the subject criterion as a string, of null if this value was not set.

Returns:
The subject.

getSubjectKeyIdentifier

public byte[] getSubjectKeyIdentifier()
Returns the subject key identifier criterion, or null if this value was not set. Note that the byte array is cloned to prevent modification.

Returns:
The subject key identifier.

getSubjectPublicKey

public PublicKey getSubjectPublicKey()
Returns the subject public key criterion, or null if this value is not set.

Returns:
The subject public key.

getSubjectPublicKeyAlgID

public String getSubjectPublicKeyAlgID()
Returns the public key algorithm ID that matching certificates must have, or null if this criterion was not set.

Returns:
The public key algorithm ID.

match

public boolean match(Certificate certificate)
Match a certificate. This method will check the given certificate against all the enabled criteria of this selector, and will return true if the given certificate matches.

Specified by:
match in interface CertSelector
Parameters:
certificate - The certificate to check.
Returns:
true if the certificate matches all criteria.

setAuthorityKeyIdentifier

public void setAuthorityKeyIdentifier(byte[] authKeyId)
Sets the authority key identifier criterion, or null to clear this criterion. Note that the byte array is cloned to prevent modification.

Parameters:
authKeyId - The authority key identifier.

setBasicConstraints

public void setBasicConstraints(int basicConstraints)
Sets the basic constraints criterion. Specify -1 to clear this parameter.

Parameters:
basicConstraints - The new basic constraints value.

setCertificate

public void setCertificate(X509Certificate cert)
Sets the certificate criterion. If set, only certificates that are equal to the certificate passed here will be accepted.

Parameters:
cert - The certificate.

setCertificateValid

public void setCertificateValid(Date certValid)
Sets the date at which certificates must be valid. Specify null to clear this criterion.

Parameters:
certValid - The certificate validity date.

setExtendedKeyUsage

public void setExtendedKeyUsage(Set<String> keyPurposeSet)
                         throws IOException
Sets the extended key usage criterion, as a set of OID strings. Specify null to clear this value.

Parameters:
keyPurposeSet - The set of key purpose OIDs.
Throws:
IOException - If any element of the set is not a valid OID string.

setIssuer

public void setIssuer(byte[] name)
               throws IOException
Sets the issuer, specified as the DER encoding of the issuer's distinguished name. Only certificates issued by this issuer will be accepted.

Parameters:
name - The DER encoding of the issuer's distinguished name.
Throws:
IOException - If the given name is incorrectly formatted.

setIssuer

public void setIssuer(String name)
               throws IOException
Sets the issuer, specified as a string representation of the issuer's distinguished name. Only certificates issued by this issuer will be accepted.

Parameters:
name - The string representation of the issuer's distinguished name.
Throws:
IOException - If the given name is incorrectly formatted.

setKeyUsage

public void setKeyUsage(boolean[] keyUsage)
Sets the public key usage criterion. Specify null to clear this value.

Parameters:
keyUsage - The public key usage.

setMatchAllSubjectAltNames

public void setMatchAllSubjectAltNames(boolean matchAllNames)
Sets whether or not all subject alternative names must be matched. If false, then a certificate will be considered a match if one alternative name matches.

Parameters:
matchAllNames - Whether or not all alternative names must be matched.

setNameConstraints

public void setNameConstraints(byte[] nameConstraints)
                        throws IOException
Sets the name constraints criterion; specify null to clear this criterion. Note that if non-null, the argument will be cloned to prevent modification.

Parameters:
nameConstraints - The new name constraints.
Throws:
IOException - If the argument is not a valid DER-encoded name constraints.

setPathToNames

public void setPathToNames(Collection<List<?>> names)
                    throws IOException
Sets the pathToNames criterion. The argument is a collection of pairs, the first element of which is an Integer giving the ID of the name, and the second element is either a String or a byte array. See addPathToName(int, byte[]) and addPathToName(int, String) for how these arguments are handled.

Parameters:
names - The names.
Throws:
IOException - If any argument is malformed.

setPolicy

public void setPolicy(Set<String> policy)
               throws IOException
Sets the certificate policy to match, or null if this criterion should not be checked. Each element if the set must be a dotted-decimal form of certificate policy object identifier.

Parameters:
policy - The policy to match.
Throws:
IOException - If some element of the policy is not a valid policy extenison OID.

setPrivateKeyValid

public void setPrivateKeyValid(Date UNUSED)
This method, and its related X.509 certificate extension — the private key usage period — is not supported under the Internet PKI for X.509 certificates (PKIX), described in RFC 3280. As such, this method is not supported either.

Do not use this method. It is not deprecated, as it is not deprecated in the Java standard, but it is basically a no-operation.

Parameters:
UNUSED - Is silently ignored.

setSerialNumber

public void setSerialNumber(BigInteger serialNo)
Sets the serial number of the desired certificate. Only certificates that contain this serial number are accepted.

Parameters:
serialNo - The serial number.

setSubject

public void setSubject(byte[] name)
                throws IOException
Sets the subject, specified as the DER encoding of the subject's distinguished name. Only certificates with the given subject will be accepted.

Parameters:
name - The DER encoding of the subject's distinguished name.
Throws:
IOException - If the given name is incorrectly formatted.

setSubject

public void setSubject(String name)
                throws IOException
Sets the subject, specified as a string representation of the subject's distinguished name. Only certificates with the given subject will be accepted.

Parameters:
name - The string representation of the subject's distinguished name.
Throws:
IOException - If the given name is incorrectly formatted.

setSubjectAlternativeNames

public void setSubjectAlternativeNames(Collection<List<?>> altNames)
                                throws IOException
Sets the subject alternative names critertion. Each element of the argument must be a List that contains exactly two elements: the first an Integer, representing the type of name, and the second either a String or a byte array, representing the name itself.

Parameters:
altNames - The alternative names.
Throws:
IOException - If any element of the argument is invalid.

setSubjectKeyIdentifier

public void setSubjectKeyIdentifier(byte[] subjectKeyId)
Sets the subject key identifier criterion, or null to clear this criterion. Note that the byte array is cloned to prevent modification.

Parameters:
subjectKeyId - The subject key identifier.

setSubjectPublicKey

public void setSubjectPublicKey(byte[] key)
                         throws IOException
Sets the subject public key criterion as a DER-encoded key. Specify null to clear this value.

Parameters:
key - The DER-encoded key bytes.
Throws:
IOException - If the argument is not a valid DER-encoded key.

setSubjectPublicKey

public void setSubjectPublicKey(PublicKey key)
Sets the subject public key criterion as an opaque representation. Specify null to clear this criterion.

Parameters:
key - The public key.

setSubjectPublicKeyAlgID

public void setSubjectPublicKeyAlgID(String sigId)
                              throws IOException
Sets the public key algorithm ID that matching certificates must have. Specify null to clear this criterion.

Parameters:
sigId - The public key ID.
Throws:
IOException - If the specified ID is not a valid object identifier.

toString

public String toString()
Description copied from class: Object
Convert this Object to a human-readable String. There are no limits placed on how long this String should be or what it should contain. We suggest you make it as intuitive as possible to be able to place it into System.out.println() and such.

It is typical, but not required, to ensure that this method never completes abruptly with a RuntimeException.

This method will be called when performing string concatenation with this object. If the result is null, string concatenation will instead use "null".

The default implementation returns getClass().getName() + "@" + Integer.toHexString(hashCode()).

Overrides:
toString in class Object
Returns:
the String representing this Object, which may be null
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)