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

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

addPathToName

public void addPathToName(int id, byte[] name)

Add a name to match in the NameConstraints extension. The argument is the DER-encoded bytes of a GeneralName structure. See the method {@link #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)

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 {@link #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)

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)

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 {@link #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()

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.

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 {@link 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()

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

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.

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.

setPathToNames

public void setPathToNames(Collection<List<?>> names)

Sets the pathToNames criterion. The argument is a collection of pairs, the first element of which is an {@link Integer} giving the ID of the name, and the second element is either a {@link String} or a byte array. See {@link #addPathToName(int, byte[])} and {@link #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)

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)

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)

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)

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)

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

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)

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