X509CRLSelector

AI-generated Key Takeaways

• X509CRLSelector is used for selecting X.509 Certificate Revocation Lists (CRLs) based on criteria such as issuer names, date/time, and CRL number range.

• It offers methods to set criteria, check if a CRL matches those criteria, and integrate with CertStore for CRL retrieval.

• Important methods include setIssuers, setDateAndTime, setCertificateChecking, and addIssuerName, enabling fine-grained selection.

• The class is generally not thread-safe and requires synchronization for concurrent access.

• Understanding ASN.1 notation is helpful for interpreting issuer criteria, and this class is vital for filtering CRLs effectively within security-sensitive applications.

public class X509CRLSelector extends Object
implements CRLSelector

A CRLSelector that selects X509CRLs that match all specified criteria. This class is particularly useful when selecting CRLs from a CertStore to check revocation status of a particular certificate.

When first constructed, an X509CRLSelector has no criteria enabled and each of the get methods return a default value (null). Therefore, the match method would return true for any X509CRL. Typically, several criteria are enabled (by calling setIssuers or setDateAndTime, for instance) and then the X509CRLSelector is passed to CertStore.getCRLs or some similar method.

Please refer to RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profile for definitions of the X.509 CRL fields and extensions mentioned below.

Concurrent Access

Unless otherwise specified, the methods defined in this class are not thread-safe. Multiple threads that need to access a single object concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating separate objects need not synchronize.

See Also

• CRLSelector
• X509CRL

Public Constructor Summary

X509CRLSelector() Creates an X509CRLSelector.

Public Method Summary

void	addIssuer(X500Principal issuer) Adds a name to the issuerNames criterion.
void	addIssuerName(byte[] name) Adds a name to the issuerNames criterion.
void	addIssuerName(String name) Denigrated, use {@linkplain #addIssuer(X500Principal)} or {@linkplain #addIssuerName(byte[])} instead.
Object	clone() Returns a copy of this object.
X509Certificate	getCertificateChecking() Returns the certificate being checked.
Date	getDateAndTime() Returns the dateAndTime criterion.
Collection<Object>	getIssuerNames() Returns a copy of the issuerNames criterion.
Collection<X500Principal>	getIssuers() Returns the issuerNames criterion.
BigInteger	getMaxCRL() Returns the maxCRLNumber criterion.
BigInteger	getMinCRL() Returns the minCRLNumber criterion.
boolean	match(CRL crl) Decides whether a CRL should be selected.
void	setCertificateChecking(X509Certificate cert) Sets the certificate being checked.
void	setDateAndTime(Date dateAndTime) Sets the dateAndTime criterion.
void	setIssuerNames(Collection<?> names) Note: use {@linkplain #setIssuers(Collection)} instead or only specify the byte array form of distinguished names when using this method.
void	setIssuers(Collection<X500Principal> issuers) Sets the issuerNames criterion.
void	setMaxCRLNumber(BigInteger maxCRL) Sets the maxCRLNumber criterion.
void	setMinCRLNumber(BigInteger minCRL) Sets the minCRLNumber criterion.
String	toString() Returns a printable representation of the X509CRLSelector.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

From interface java.security.cert.CRLSelector

abstract Object	clone() Makes a copy of this CRLSelector.
abstract boolean	match(CRL crl) Decides whether a CRL should be selected.

Public Constructors

public X509CRLSelector ()

Creates an X509CRLSelector. Initially, no criteria are set so any X509CRL will match.

Public Methods

public void addIssuer (X500Principal issuer)

Adds a name to the issuerNames criterion. The issuer distinguished name in the X509CRL must match at least one of the specified distinguished names.

This method allows the caller to add a name to the set of issuer names which X509CRLs may contain. The specified name is added to any previous value for the issuerNames criterion. If the specified name is a duplicate, it may be ignored.

Parameters

issuer	the issuer as X500Principal

public void addIssuerName (byte[] name)

Adds a name to the issuerNames criterion. The issuer distinguished name in the X509CRL must match at least one of the specified distinguished names.

This method allows the caller to add a name to the set of issuer names which X509CRLs may contain. The specified name is added to any previous value for the issuerNames criterion. If the specified name is a duplicate, it may be ignored. If a name is specified as a byte array, it should contain a single DER encoded distinguished name, as defined in X.501. The ASN.1 notation for this structure is as follows.

The name is provided as a byte array. This byte array should contain a single DER encoded distinguished name, as defined in X.501. The ASN.1 notation for this structure appears in the documentation for setIssuerNames(Collection names).

Note that the byte array supplied here is cloned to protect against subsequent modifications.

Parameters

name	a byte array containing the name in ASN.1 DER encoded form

Throws

IOException	if a parsing error occurs

public void addIssuerName (String name)

Denigrated, use {@linkplain #addIssuer(X500Principal)} or {@linkplain #addIssuerName(byte[])} instead. This method should not be relied on as it can fail to match some CRLs because of a loss of encoding information in the RFC 2253 String form of some distinguished names.

Adds a name to the issuerNames criterion. The issuer distinguished name in the X509CRL must match at least one of the specified distinguished names.

This method allows the caller to add a name to the set of issuer names which X509CRLs may contain. The specified name is added to any previous value for the issuerNames criterion. If the specified name is a duplicate, it may be ignored.

Parameters

name	the name in RFC 2253 form

Throws

IOException	if a parsing error occurs

public Object clone ()

Returns a copy of this object.

Returns

• the copy

public X509Certificate getCertificateChecking ()

Returns the certificate being checked. This is not a criterion. Rather, it is optional information that may help a CertStore find CRLs that would be relevant when checking revocation for the specified certificate. If the value returned is null, then no such optional information is provided.

Returns

• the certificate being checked (or null)

See Also

• setCertificateChecking(X509Certificate)

public Date getDateAndTime ()

Returns the dateAndTime criterion. The specified date must be equal to or later than the value of the thisUpdate component of the X509CRL and earlier than the value of the nextUpdate component. There is no match if the X509CRL does not contain a nextUpdate component. If null, no dateAndTime check will be done.

Note that the Date returned is cloned to protect against subsequent modifications.

Returns

• the Date to match against (or null)

See Also

• setDateAndTime(Date)

public Collection<Object> getIssuerNames ()

Returns a copy of the issuerNames criterion. The issuer distinguished name in the X509CRL must match at least one of the specified distinguished names. If the value returned is null, any issuer distinguished name will do.

If the value returned is not null, it is a Collection of names. Each name is a String or a byte array representing a distinguished name (in RFC 2253 or ASN.1 DER encoded form, respectively). Note that the Collection returned may contain duplicate names.

If a name is specified as a byte array, it should contain a single DER encoded distinguished name, as defined in X.501. The ASN.1 notation for this structure is given in the documentation for setIssuerNames(Collection names).

Note that a deep copy is performed on the Collection to protect against subsequent modifications.

Returns

• a Collection of names (or null)

See Also

• setIssuerNames(Collection)

public Collection<X500Principal> getIssuers ()

Returns the issuerNames criterion. The issuer distinguished name in the X509CRL must match at least one of the specified distinguished names. If the value returned is null, any issuer distinguished name will do.

If the value returned is not null, it is a unmodifiable Collection of X500Principals.

Returns

• an unmodifiable Collection of names (or null)

See Also

• setIssuers(Collection)

public BigInteger getMaxCRL ()

Returns the maxCRLNumber criterion. The X509CRL must have a CRL number extension whose value is less than or equal to the specified value. If null, no maxCRLNumber check will be done.

Returns

• the maximum CRL number accepted (or null)

public BigInteger getMinCRL ()

Returns the minCRLNumber criterion. The X509CRL must have a CRL number extension whose value is greater than or equal to the specified value. If null, no minCRLNumber check will be done.

Returns

• the minimum CRL number accepted (or null)

public boolean match (CRL crl)

Decides whether a CRL should be selected.

Parameters

crl	the CRL to be checked

Returns

• true if the CRL should be selected, false otherwise

public void setCertificateChecking (X509Certificate cert)

Sets the certificate being checked. This is not a criterion. Rather, it is optional information that may help a CertStore find CRLs that would be relevant when checking revocation for the specified certificate. If null is specified, then no such optional information is provided.

Parameters

cert	the X509Certificate being checked (or null)

See Also

• getCertificateChecking()

public void setDateAndTime (Date dateAndTime)

Sets the dateAndTime criterion. The specified date must be equal to or later than the value of the thisUpdate component of the X509CRL and earlier than the value of the nextUpdate component. There is no match if the X509CRL does not contain a nextUpdate component. If null, no dateAndTime check will be done.

Note that the Date supplied here is cloned to protect against subsequent modifications.

Parameters

dateAndTime	the Date to match against (or null)

See Also

• getDateAndTime()

public void setIssuerNames (Collection<?> names)

Note: use {@linkplain #setIssuers(Collection)} instead or only specify the byte array form of distinguished names when using this method. See addIssuerName(String) for more information.

Sets the issuerNames criterion. The issuer distinguished name in the X509CRL must match at least one of the specified distinguished names. If null, any issuer distinguished name will do.

This method allows the caller to specify, with a single method call, the complete set of issuer names which X509CRLs may contain. The specified value replaces the previous value for the issuerNames criterion.

The names parameter (if not null) is a Collection of names. Each name is a String or a byte array representing a distinguished name (in RFC 2253 or ASN.1 DER encoded form, respectively). If null is supplied as the value for this argument, no issuerNames check will be performed.

Note that the names parameter can contain duplicate distinguished names, but they may be removed from the Collection of names returned by the getIssuerNames method.

If a name is specified as a byte array, it should contain a single DER encoded distinguished name, as defined in X.501. The ASN.1 notation for this structure is as follows.

Name ::= CHOICE {
   RDNSequence }

 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName

 RelativeDistinguishedName ::=
   SET SIZE (1 .. MAX) OF AttributeTypeAndValue

 AttributeTypeAndValue ::= SEQUENCE {
   type     AttributeType,
   value    AttributeValue }

 AttributeType ::= OBJECT IDENTIFIER

 AttributeValue ::= ANY DEFINED BY AttributeType
 ....
 DirectoryString ::= CHOICE {
       teletexString           TeletexString (SIZE (1..MAX)),
       printableString         PrintableString (SIZE (1..MAX)),
       universalString         UniversalString (SIZE (1..MAX)),
       utf8String              UTF8String (SIZE (1.. MAX)),
       bmpString               BMPString (SIZE (1..MAX)) }
 

Note that a deep copy is performed on the Collection to protect against subsequent modifications.

Parameters

names	a Collection of names (or null)

Throws

IOException	if a parsing error occurs

See Also

• getIssuerNames()

public void setIssuers (Collection<X500Principal> issuers)

Sets the issuerNames criterion. The issuer distinguished name in the X509CRL must match at least one of the specified distinguished names. If null, any issuer distinguished name will do.

This method allows the caller to specify, with a single method call, the complete set of issuer names which X509CRLs may contain. The specified value replaces the previous value for the issuerNames criterion.

The names parameter (if not null) is a Collection of X500Principals.

Note that the names parameter can contain duplicate distinguished names, but they may be removed from the Collection of names returned by the getIssuers method.

Note that a copy is performed on the Collection to protect against subsequent modifications.

Parameters

issuers	a Collection of X500Principals (or null)

See Also

• getIssuers()

public void setMaxCRLNumber (BigInteger maxCRL)

Sets the maxCRLNumber criterion. The X509CRL must have a CRL number extension whose value is less than or equal to the specified value. If null, no maxCRLNumber check will be done.

Parameters

maxCRL	the maximum CRL number accepted (or null)

public void setMinCRLNumber (BigInteger minCRL)

Sets the minCRLNumber criterion. The X509CRL must have a CRL number extension whose value is greater than or equal to the specified value. If null, no minCRLNumber check will be done.

Parameters

minCRL	the minimum CRL number accepted (or null)

public String toString ()

Returns a printable representation of the X509CRLSelector.

Returns

• a String describing the contents of the X509CRLSelector.