java.security.cert

Class X509CertSelector

public class X509CertSelector extends Object implements CertSelector, Cloneable

A concrete implementation of {@link 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
voidaddSubjectAlternativeName(int id, String name)
Add a name to the subject alternative names criterion.
voidaddSubjectAlternativeName(int id, byte[] name)
Add a name, as DER-encoded bytes, to the subject alternative names criterion.
Objectclone()
byte[]getAuthorityKeyIdentifier()
Returns the authority key identifier criterion, or null if this value was not set.
intgetBasicConstraints()
Returns the basic constraints criterion, or -1 if this value is not set.
X509CertificategetCertificate()
Returns the certificate criterion, or null if this value was not set.
DategetCertificateValid()
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.
StringgetIssuerAsString()
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.
booleangetMatchAllSubjectAltNames()
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.
DategetPrivateKeyValid()
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.
BigIntegergetSerialNumber()
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.
StringgetSubjectAsString()
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.
PublicKeygetSubjectPublicKey()
Returns the subject public key criterion, or null if this value is not set.
StringgetSubjectPublicKeyAlgID()
Returns the public key algorithm ID that matching certificates must have, or null if this criterion was not set.
booleanmatch(Certificate certificate)
Match a certificate.
voidsetAuthorityKeyIdentifier(byte[] authKeyId)
Sets the authority key identifier criterion, or null to clear this criterion.
voidsetBasicConstraints(int basicConstraints)
Sets the basic constraints criterion.
voidsetCertificate(X509Certificate cert)
Sets the certificate criterion.
voidsetCertificateValid(Date certValid)
Sets the date at which certificates must be valid.
voidsetExtendedKeyUsage(Set<String> keyPurposeSet)
Sets the extended key usage criterion, as a set of OID strings.
voidsetIssuer(String name)
Sets the issuer, specified as a string representation of the issuer's distinguished name.
voidsetIssuer(byte[] name)
Sets the issuer, specified as the DER encoding of the issuer's distinguished name.
voidsetKeyUsage(boolean[] keyUsage)
Sets the public key usage criterion.
voidsetMatchAllSubjectAltNames(boolean matchAllNames)
Sets whether or not all subject alternative names must be matched.
voidsetNameConstraints(byte[] nameConstraints)
Sets the name constraints criterion; specify null to clear this criterion.
voidsetPrivateKeyValid(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.
voidsetSerialNumber(BigInteger serialNo)
Sets the serial number of the desired certificate.
voidsetSubject(String name)
Sets the subject, specified as a string representation of the subject's distinguished name.
voidsetSubject(byte[] name)
Sets the subject, specified as the DER encoding of the subject's distinguished name.
voidsetSubjectAlternativeNames(Collection<List<?>> altNames)
Sets the subject alternative names critertion.
voidsetSubjectKeyIdentifier(byte[] subjectKeyId)
Sets the subject key identifier criterion, or null to clear this criterion.
voidsetSubjectPublicKey(PublicKey key)
Sets the subject public key criterion as an opaque representation.
voidsetSubjectPublicKey(byte[] key)
Sets the subject public key criterion as a DER-encoded key.
voidsetSubjectPublicKeyAlgID(String sigId)
Sets the public key algorithm ID that matching certificates must have.
StringtoString()

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 {@link X509Certificate}).

Method Detail

addSubjectAlternativeName

public void addSubjectAlternativeName(int id, String name)
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)
Add a name, as DER-encoded bytes, to the subject alternative names criterion.

Parameters: id The type of name this is.

clone

public Object clone()

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()
Returns the issuer criterion as a sequence of DER bytes, or null if this value was not set.

Returns: The issuer.

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.

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.

getSubjectAsBytes

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

Returns: The subject.

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.

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)
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(String name)
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)
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.

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

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(String name)
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)
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.

setSubjectAlternativeNames

public void setSubjectAlternativeNames(Collection<List<?>> altNames)
Sets the subject alternative names critertion. Each element of the argument must be a {@link java.util.List} that contains exactly two elements: the first an {@link Integer}, representing the type of name, and the second either a {@link 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(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)
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.

setSubjectPublicKeyAlgID

public void setSubjectPublicKeyAlgID(String sigId)
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()