The X509CertSelector Class

The X509CertSelector class is an implementation of the CertSelector interface that defines a set of criteria for selecting X.509 certificates. An X509Certificate object must match all of the specified criteria to be selected by the match method. The selection criteria are designed to be used by a CertPathBuilder implementation to discover potential certificates as it builds an X.509 certification path.

For example, the setSubject method of X509CertSelector allows a PKIX CertPathBuilder to filter out X509Certificates that do not match the issuer name of the preceding X509Certificate in a partially completed chain. By setting this and other criteria in an X509CertSelector object, a CertPathBuilder is able to discard irrelevant certificates and more easily find an X.509 certification path that meets the requirements specified in the CertPathParameters object.

Refer to http://www.ietf.org/rfc/rfc3280.txt for definitions of the X.509 certificate extensions mentioned in this section.

Creating an X509CertSelector Object

An X509CertSelector object is created by calling the default constructor:

public X509CertSelector()

No criteria are initially set (any X509Certificate will match).

Setting Selection Criteria

The selection criteria allow a caller to match on different components of an X.509 certificate. A few of the methods for setting selection criteria are described here. Refer to the X509CertSelector API documentation for details on the other methods.

The setIssuer methods set the issuer criterion:

        public void setIssuer(String issuerDN)

        public void setIssuer(byte[] issuerDN)

        public void setIssuer(X500Principal issuer)

The specified distinguished name (in RFC 2253 String or ASN.1 DER encoded form or a X500Principal object) must match the issuer distinguished name in the certificate. If null, any issuer distinguished name is valid.

Similarly, the setSubject methods set the subject criterion:

        public void setSubject(String subjectDN)

        public void setSubject(byte[] subjectDN)

        public void setSubject(X500Principal subject)

The specified distinguished name (in RFC 2253 String or ASN.1 DER encoded form or a X500Principal object) must match the subject distinguished name in the certificate. If null, any subject distinguished name is valid.

The setSerialNumber method sets the serialNumber criterion:

        public void setSerialNumber(BigInteger serial)

The specified serial number must match the certificate serial number in the certificate. If null, any certificate serial number is valid.

The setAuthorityKeyIdentifier method sets the authorityKeyIdentifier criterion:

        public void setAuthorityKeyIdentifier(byte[] authorityKeyID)

The certificate must contain an Authority Key Identifier extension matching the specified value. If null, no check will be done on the authorityKeyIdentifier criterion.

The setCertificateValid method sets the certificateValid criterion:

        public void setCertificateValid(Date certValid)

The specified date must fall within the certificate validity period for the certificate. If null, any date is valid.

The setKeyUsage method sets the keyUsage criterion:

        public void setKeyUsage(boolean[] keyUsage)

The certificate's Key Usage Extension must allow the specified key usage values (those which are set to true). If null, no keyUsage check will be done.

Getting Selection Criteria

The current values for each of the selection criteria can be retrieved using an appropriate get method. Refer to the X509CertSelector API documentation for further details on these methods.

Example

Here is an example of retrieving X.509 certificates from an LDAP CertStore with the X509CertSelector class.

First, we create the LDAPCertStoreParameters object that we will use to initialize the CertStore object with the hostname and port of the LDAP server:

        LDAPCertStoreParameters lcsp = new
               LDAPCertStoreParameters("ldap.sun.com", 389);

Next, create the CertStore object, and pass it the LDAPCertStoreParameters object, as in the following statement:

        CertStore cs = CertStore.getInstance("LDAP", lcsp);

This call creates a CertStore object that retrieves certificates and CRLs from an LDAP repository using the schema defined in RFC 2587.

The following block of code establishes an X509CertSelector to retrieve all unexpired (as of the current date and time) end-entity certificates issued to a particular subject with a key usage that allows digital signatures, and a subject alternative name with a specific e-mail address:

        X509CertSelector xcs = new X509CertSelector();
        // select only unexpired certificates
        xcs.setCertificateValid(new Date());
        // select only certificates issued to
        // 'CN=alice, O=xyz, C=us'
        xcs.setSubject("CN=alice, O=xyz, C=us");
        // select only end-entity certificates
        xcs.setBasicConstraints(-2);
        // select only certificates with a digitalSignature
        // keyUsage bit set (set the first entry in the
        // boolean array to true)
        boolean[] keyUsage = {true};
        xcs.setKeyUsage(keyUsage);
        // select only certificates with a subjectAltName of
        // 'alice@xyz.com' (1 is the integer value of
        // an RFC822Name)
        xcs.addSubjectAlternativeName(1, "alice@xyz.com");

Then we pass the selector to the getCertificates method of our CertStore object that we previously created:

        Collection certs = cs.getCertificates(xcs);

A PKIX CertPathBuilder can use similar code to help discover and sort through potential certificates by discarding those that do not meet validation constraints or other criteria.