java.security.cert
Class X509CertSelector

java.lang.Object
  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.

Constructor Summary

X509CertSelector()
Creates a new X.509 certificate selector.

Method Summary

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() clone creates a shallow clone of this.
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	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.
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.
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 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	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 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() toString creates a printable string that represents this object for debugging purposes.

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

getCertificate

public X509Certificate getCertificate()

Returns the certificate criterion, or null if this value was not set.

Returns:

The certificate.

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.

getSerialNumber

public BigInteger getSerialNumber()

Returns the serial number criterion, or null if this value was not set.

Returns:

The serial number.

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.

getIssuerAsString

public String getIssuerAsString()

Returns the issuer criterion as a string, or null if this value was not set.

Returns:

The issuer.

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

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.

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.

getSubjectAsString

public String getSubjectAsString()

Returns the subject criterion as a string, of null if this value was not set.

Returns:

The subject.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

getSubjectPublicKey

public PublicKey getSubjectPublicKey()

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

Returns:

The subject public 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.

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.

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.

setKeyUsage

public void setKeyUsage(boolean[] keyUsage)

Sets the public key usage criterion. Specify null to clear this value.

Parameters:

keyUsage - The public key usage.

getExtendedKeyUsage

public Set 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).

setExtendedKeyUsage

public void setExtendedKeyUsage(Set 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.

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.

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.

setSubjectAlternativeNames

public void setSubjectAlternativeNames(Collection 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.

addSubjectAlternativeName

public void addSubjectAlternativeName(int id,
                                      String name)
                               throws IOException

Add a name to the subject alternative names criterion.

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.

addSubjectAlternativeName

public void addSubjectAlternativeName(int id,
                                      byte[] name)
                               throws IOException

Add a name, as DER-encoded bytes, to the subject alternative names criterion.

Parameters:

id - The type of name this is.

Throws:

IOException

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.

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.

getBasicConstraints

public int getBasicConstraints()

Returns the basic constraints criterion, or -1 if this value is not set.

Returns:

The basic constraints.

setBasicConstraints

public void setBasicConstraints(int basicConstraints)

Sets the basic constraints criterion. Specify -1 to clear this parameter.

Parameters:

basicConstraints - The new basic constraints value.

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.

toString

public String toString()

Description copied from class: Object

toString creates a printable string that represents this object for debugging purposes.

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

Overrides:

toString in class Object

Returns:

a string identifying this object.

clone

public Object clone()

Description copied from class: Object

clone creates a shallow clone of this.

Specified by:

clone in interface CertSelector

Overrides:

clone in class Object

Returns:

a clone of this object.