APIdia Launch Partner
Top Description Fields Constructors Methods
java.security.cert

public Class X509CRLSelector

extends Object
implements CRLSelector
Class Inheritance
All Implemented Interfaces
java.security.cert.CRLSelector, java.lang.Cloneable
Imports
java.io.IOException, java.math.BigInteger, java.util.*, javax.security.auth.x500.X500Principal, sun.security.util.Debug, .DerInputStream, .KnownOIDs, sun.security.x509.CRLNumberExtension, .X500Name
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 5280: 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.

Author
Steve Hanna
Since
1.4
External Specification
https://www.rfc-editor.org/info/rfc5280
See Also
CRLSelector, X509CRL

Field Summary

Modifier and TypeField and Description
private X509Certificate
certChecking

private Date
dateAndTime

private static final Debug
debug

private HashSet<Object>
issuerNames

private HashSet<X500Principal>
issuerX500Principals

private BigInteger
maxCRL

private BigInteger
minCRL

private long
skew

Constructor Summary

AccessConstructor and Description
public
X509CRLSelector()

Creates an X509CRLSelector.

Method Summary

Modifier and TypeMethod and Description
public void
addIssuer(X500Principal
the issuer as X500Principal
issuer)

Adds a name to the issuerNames criterion.

public void
addIssuerName(String
the name in RFC 2253 form
name)
Deprecated since 16. Use addIssuer(X500Principal) or addIssuerName(byte[]) instead.

Adds a name to the issuerNames criterion.

public void
addIssuerName(byte[]
a byte array containing the name in ASN.1 DER encoded form
name)

Adds a name to the issuerNames criterion.

private void
addIssuerNameInternal(Object
the name in string or byte array form
name, X500Principal
the name in X500Principal form
principal)

A private method that adds a name (String or byte array) to the issuerNames criterion.

public Object

Returns:

the copy
clone()

Overrides java.lang.Object.clone.

Implements java.security.cert.CRLSelector.clone.

Returns a copy of this object.

private static HashSet<Object>

Returns:

a deep copy of the specified Collection
cloneAndCheckIssuerNames(Collection<?>
a Collection of names. Each entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). null is not an acceptable value.
names)

Clone and check an argument of the form passed to setIssuerNames.

private static HashSet<Object>

Returns:

a deep copy of the specified Collection
cloneIssuerNames(Collection<Object>
a Collection of names. Each entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). null is not an acceptable value.
names)

Clone an argument of the form passed to setIssuerNames.

public X509Certificate

Returns:

the certificate being checked (or null)
getCertificateChecking()

Returns the certificate being checked.

public Date

Returns:

the Date to match against (or null)
getDateAndTime()

Returns the dateAndTime criterion.

public Collection<Object>

Returns:

a Collection of names (or null)
getIssuerNames()

Returns a copy of the issuerNames criterion.

public Collection<X500Principal>

Returns:

an unmodifiable Collection of names (or null)
getIssuers()

Returns the issuerNames criterion.

public BigInteger

Returns:

the maximum CRL number accepted (or null)
getMaxCRL()

Returns the maxCRLNumber criterion.

public BigInteger

Returns:

the minimum CRL number accepted (or null)
getMinCRL()

Returns the minCRLNumber criterion.

public boolean

Returns:

true if the CRL should be selected, false otherwise
match(CRL
the CRL to be checked
crl)

Implements java.security.cert.CRLSelector.match.

Decides whether a CRL should be selected.

private static HashSet<X500Principal>

Returns:

a HashSet of issuerX500Principals
parseIssuerNames(Collection<Object>
a Collection of names. Each entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). Null is not an acceptable value.
names)

Parse an argument of the form passed to setIssuerNames, returning a Collection of issuerX500Principals.

public void
setCertificateChecking(X509Certificate
the X509Certificate being checked (or null)
cert)

Sets the certificate being checked.

public void
setDateAndTime(Date
the Date to match against (or null)
dateAndTime)

Sets the dateAndTime criterion.

pack-priv void
setDateAndTime(Date dateAndTime, long skew)

Sets the dateAndTime criterion and allows for the specified clock skew (in milliseconds) when checking against the validity period of the CRL.

public void
setIssuerNames(Collection<?>
a Collection of names (or null)
names)

Sets the issuerNames criterion.

public void
setIssuers(Collection<X500Principal>
a Collection of X500Principals (or null)
issuers)

Sets the issuerNames criterion.

public void
setMaxCRLNumber(BigInteger
the maximum CRL number accepted (or null)
maxCRL)

Sets the maxCRLNumber criterion.

public void
setMinCRLNumber(BigInteger
the minimum CRL number accepted (or null)
minCRL)

Sets the minCRLNumber criterion.

public String

Returns:

a String describing the contents of the X509CRLSelector.
toString()

Overrides java.lang.Object.toString.

Returns a printable representation of the X509CRLSelector.

Inherited from java.lang.Object:
equalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

certCheckingback to summary
private X509Certificate certChecking
dateAndTimeback to summary
private Date dateAndTime
debugback to summary
private static final Debug debug
issuerNamesback to summary
private HashSet<Object> issuerNames
issuerX500Principalsback to summary
private HashSet<X500Principal> issuerX500Principals
maxCRLback to summary
private BigInteger maxCRL
minCRLback to summary
private BigInteger minCRL
skewback to summary
private long skew

Constructor Detail

X509CRLSelectorback to summary
public X509CRLSelector()

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

Method Detail

addIssuerback to summary
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:X500Principal

the issuer as X500Principal

Since
1.5
addIssuerNameback to summary
public void addIssuerName(String name) throws IOException

Deprecated

since 16.

Use addIssuer(X500Principal) or 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:String

the name in RFC 2253 form

Annotations
@Deprecated
since:16
Exceptions
IOException:
if a parsing error occurs
External Specification
https://www.rfc-editor.org/info/rfc2253
addIssuerNameback to summary
public void addIssuerName(byte[] name) throws IOException

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:byte[]

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

Exceptions
IOException:
if a parsing error occurs
addIssuerNameInternalback to summary
private void addIssuerNameInternal(Object name, X500Principal principal)

A private method that adds a name (String or byte array) to the issuerNames criterion. The issuer distinguished name in the X509CRL must match at least one of the specified distinguished names.

Parameters
name:Object

the name in string or byte array form

principal:X500Principal

the name in X500Principal form

Exceptions
IOException:
if a parsing error occurs
cloneback to summary
public Object clone()

Overrides java.lang.Object.clone.

Implements java.security.cert.CRLSelector.clone.

Returns a copy of this object.

Returns:Object

the copy

cloneAndCheckIssuerNamesback to summary
private static HashSet<Object> cloneAndCheckIssuerNames(Collection<?> names) throws IOException

Clone and check an argument of the form passed to setIssuerNames. Throw an IOException if the argument is malformed.

Parameters
names:Collection<?>

a Collection of names. Each entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). null is not an acceptable value.

Returns:HashSet<Object>

a deep copy of the specified Collection

Exceptions
IOException:
if a parsing error occurs
cloneIssuerNamesback to summary
private static HashSet<Object> cloneIssuerNames(Collection<Object> names)

Clone an argument of the form passed to setIssuerNames. Throw a RuntimeException if the argument is malformed.

This method wraps cloneAndCheckIssuerNames, changing any IOException into a RuntimeException. This method should be used when the object being cloned has already been checked, so there should never be any exceptions.

Parameters
names:Collection<Object>

a Collection of names. Each entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). null is not an acceptable value.

Returns:HashSet<Object>

a deep copy of the specified Collection

Exceptions
RuntimeException:
if a parsing error occurs
getCertificateCheckingback to summary
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:X509Certificate

the certificate being checked (or null)

See Also
setCertificateChecking
getDateAndTimeback to summary
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:Date

the Date to match against (or null)

See Also
setDateAndTime
getIssuerNamesback to summary
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:Collection<Object>

a Collection of names (or null)

External Specification
https://www.rfc-editor.org/info/rfc2253
See Also
setIssuerNames
getIssuersback to summary
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:Collection<X500Principal>

an unmodifiable Collection of names (or null)

Since
1.5
See Also
setIssuers
getMaxCRLback to summary
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:BigInteger

the maximum CRL number accepted (or null)

getMinCRLback to summary
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:BigInteger

the minimum CRL number accepted (or null)

matchback to summary
public boolean match(CRL crl)

Implements java.security.cert.CRLSelector.match.

Decides whether a CRL should be selected.

Parameters
crl:CRL

the CRL to be checked

Returns:boolean

true if the CRL should be selected, false otherwise

parseIssuerNamesback to summary
private static HashSet<X500Principal> parseIssuerNames(Collection<Object> names) throws IOException

Parse an argument of the form passed to setIssuerNames, returning a Collection of issuerX500Principals. Throw an IOException if the argument is malformed.

Parameters
names:Collection<Object>

a Collection of names. Each entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). Null is not an acceptable value.

Returns:HashSet<X500Principal>

a HashSet of issuerX500Principals

Exceptions
IOException:
if a parsing error occurs
setCertificateCheckingback to summary
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:X509Certificate

the X509Certificate being checked (or null)

See Also
getCertificateChecking
setDateAndTimeback to summary
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:Date

the Date to match against (or null)

See Also
getDateAndTime
setDateAndTimeback to summary
pack-priv void setDateAndTime(Date dateAndTime, long skew)

Sets the dateAndTime criterion and allows for the specified clock skew (in milliseconds) when checking against the validity period of the CRL.

setIssuerNamesback to summary
public void setIssuerNames(Collection<?> names) throws IOException

Note

use 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:Collection<?>

a Collection of names (or null)

Exceptions
IOException:
if a parsing error occurs
External Specification
https://www.rfc-editor.org/info/rfc2253
See Also
getIssuerNames
setIssuersback to summary
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:Collection<X500Principal>

a Collection of X500Principals (or null)

Since
1.5
See Also
getIssuers
setMaxCRLNumberback to summary
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:BigInteger

the maximum CRL number accepted (or null)

setMinCRLNumberback to summary
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:BigInteger

the minimum CRL number accepted (or null)

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a printable representation of the X509CRLSelector.

Returns:String

a String describing the contents of the X509CRLSelector.