Java Doc for X509CertSelector.java in  » 6.0-JDK-Core » security » java » security » cert » Java Source Code / Java DocumentationJava Source Code and Java Documentation

When first constructed, an X509CertSelector has no criteria enabled and each of the get methods return a default value (null, or -1 for the X509CertSelector.getBasicConstraintsgetBasicConstraints method). Therefore, the X509CertSelector.match match method would return true for any X509Certificate. Typically, several criteria are enabled (by calling X509CertSelector.setIssuer setIssuer or X509CertSelector.setKeyUsage setKeyUsage , for instance) and then the X509CertSelector is passed to CertStore.getCertificates CertStore.getCertificates or some similar method.

Several criteria can be enabled (by calling X509CertSelector.setIssuer setIssuer and X509CertSelector.setSerialNumber setSerialNumber , for example) such that the match method usually uniquely matches a single X509Certificate. We say usually, since it is possible for two issuing CAs to have the same distinguished name and each issue a certificate with the same serial number. Other unique combinations include the issuer, subject, subjectKeyIdentifier and/or the subjectPublicKey criteria.

Please refer to RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profile for definitions of the X.509 certificate 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:   CertSelector
See Also:   X509Certificate
version:
   1.29, 05/05/07
since:
   1.4
author:
   Steve Hanna

This method allows the caller to add a name to the set of names which the X509Certificates's name constraints must permit. The specified name is added to any previous value for the pathToNames criterion. If the name is a duplicate, it may be ignored.

The name is provided in string format. RFC 822, DNS, and URI names use the well-established string formats for those types (subject to the restrictions included in RFC 3280). IPv4 address names are supplied using dotted quad notation. OID address names are represented as a series of nonnegative integers separated by periods. And directory names (distinguished names) are supplied in RFC 2253 format. No standard string format is defined for otherNames, X.400 names, EDI party names, IPv6 address names, or any other type of names. They should be specified using the X509CertSelector.addPathToName(int type,byte[] name) addPathToName(int type, byte [] name) method.

Note: for distinguished names, use instead. This method should not be relied on as it can fail to match some certificates because of a loss of encoding information in the RFC 2253 String form of some distinguished names.
Parameters:
  type - the name type (0-8, as specified inRFC 3280, section 4.2.1.7)
Parameters:
  name - the name in string form
throws:
  IOException - if a parsing error occurs

This method allows the caller to add a name to the set of names which the X509Certificates's name constraints must permit. The specified name is added to any previous value for the pathToNames criterion. If the name is a duplicate, it may be ignored.

The name is provided as a byte array. This byte array should contain the DER encoded name, as it would appear in the GeneralName structure defined in RFC 3280 and X.509. The ASN.1 definition of this structure appears in the documentation for X509CertSelector.addSubjectAlternativeName(int type,byte[] name) addSubjectAlternativeName(int type, byte [] name) .

Note that the byte array supplied here is cloned to protect against subsequent modifications.
Parameters:
  type - the name type (0-8, as specified inRFC 3280, section 4.2.1.7)
Parameters:
  name - a byte array containing the name in ASN.1 DER encoded form
throws:
  IOException - if a parsing error occurs

This method allows the caller to add a name to the set of subject alternative names. The specified name is added to any previous value for the subjectAlternativeNames criterion. If the specified name is a duplicate, it may be ignored.

The name is provided in string format. RFC 822, DNS, and URI names use the well-established string formats for those types (subject to the restrictions included in RFC 3280). IPv4 address names are supplied using dotted quad notation. OID address names are represented as a series of nonnegative integers separated by periods. And directory names (distinguished names) are supplied in RFC 2253 format. No standard string format is defined for otherNames, X.400 names, EDI party names, IPv6 address names, or any other type of names. They should be specified using the X509CertSelector.addSubjectAlternativeName(int type,byte[] name) addSubjectAlternativeName(int type, byte [] name) method.

Note: for distinguished names, use instead. This method should not be relied on as it can fail to match some certificates because of a loss of encoding information in the RFC 2253 String form of some distinguished names.
Parameters:
  type - the name type (0-8, as specified inRFC 3280, section 4.2.1.7)
Parameters:
  name - the name in string form (not null)
throws:
  IOException - if a parsing error occurs

This method allows the caller to add a name to the set of subject alternative names. The specified name is added to any previous value for the subjectAlternativeNames criterion. If the specified name is a duplicate, it may be ignored.

The name is provided as a byte array. This byte array should contain the DER encoded name, as it would appear in the GeneralName structure defined in RFC 3280 and X.509. The encoded byte array should only contain the encoded value of the name, and should not include the tag associated with the name in the GeneralName structure. The ASN.1 definition of this structure appears below.

 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}
 

Note that the byte array supplied here is cloned to protect against subsequent modifications.
Parameters:
  type - the name type (0-8, as listed above)
Parameters:
  name - a byte array containing the name in ASN.1 DER encoded form
throws:
  IOException - if a parsing error occurs

Note that the byte array returned is cloned to protect against subsequent modifications. the key identifier (or null)
See Also:   X509CertSelector.setAuthorityKeyIdentifier

Note that the Date returned is cloned to protect against subsequent modifications. the Date to check (or null)
See Also:   X509CertSelector.setCertificateValid

If the value returned is not null, it is a byte array containing a single DER encoded distinguished name, as defined in X.501. The ASN.1 notation for this structure is supplied in the documentation for X509CertSelector.setIssuer(byte[] issuerDN) setIssuer(byte [] issuerDN) .

Note that the byte array returned is cloned to protect against subsequent modifications. a byte array containing the required issuer distinguished namein ASN.1 DER format (or null)
throws:
  IOException - if an encoding error occurs

Returns the issuer criterion as a String. This distinguished name must match the issuer distinguished name in the X509Certificate. If null, the issuer criterion is disabled and any issuer distinguished name will do.

If the value returned is not null, it is a distinguished name, in RFC 2253 format. the required issuer distinguished name in RFC 2253 format(or null)

Note that the boolean array returned is cloned to protect against subsequent modifications. a boolean array in the same format as the booleanarray returned byX509Certificate.getKeyUsage X509Certificate.getKeyUsage().Or null.
See Also:   X509CertSelector.setKeyUsage

The name constraints are returned as a byte array. This byte array contains the DER encoded form of the name constraints, as they would appear in the NameConstraints structure defined in RFC 3280 and X.509. The ASN.1 notation for this structure is supplied in the documentation for X509CertSelector.setNameConstraints(byte[] bytes) setNameConstraints(byte [] bytes) .

Note that the byte array returned is cloned to protect against subsequent modifications. a byte array containing the ASN.1 DER encoding ofa NameConstraints extension used for checking name constraints.null if no name constraints check will be performed.
See Also:   X509CertSelector.setNameConstraints

If the value returned is not null, it is a Collection with one entry for each name to be included in the pathToNames criterion. Each entry is a List whose first entry is an Integer (the name type, 0-8) and whose second entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). There can be multiple names of the same type. Note that the Collection returned may contain duplicate names (same name and name type).

Each name in the Collection may be specified either as a String or as an ASN.1 encoded byte array. For more details about the formats used, see X509CertSelector.addPathToName(int type,String name) addPathToName(int type, String name) and X509CertSelector.addPathToName(int type,byte[] name) addPathToName(int type, byte [] name) .

Note that a deep copy is performed on the Collection to protect against subsequent modifications. a Collection of names (or null)
See Also:   X509CertSelector.setPathToNames

Note that the Date returned is cloned to protect against subsequent modifications. the Date to check (or null)
See Also:   X509CertSelector.setPrivateKeyValid

If the value returned is not null, it is a Collection with one entry for each name to be included in the subject alternative name criterion. Each entry is a List whose first entry is an Integer (the name type, 0-8) and whose second entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). There can be multiple names of the same type. Note that the Collection returned may contain duplicate names (same name and name type).

Each subject alternative name in the Collection may be specified either as a String or as an ASN.1 encoded byte array. For more details about the formats used, see X509CertSelector.addSubjectAlternativeName(int type,String name) addSubjectAlternativeName(int type, String name) and X509CertSelector.addSubjectAlternativeName(int type,byte[] name) addSubjectAlternativeName(int type, byte [] name) .

Note that a deep copy is performed on the Collection to protect against subsequent modifications. a Collection of names (or null)
See Also:   X509CertSelector.setSubjectAlternativeNames

If the value returned is not null, it is a byte array containing a single DER encoded distinguished name, as defined in X.501. The ASN.1 notation for this structure is supplied in the documentation for X509CertSelector.setSubject(byte[] subjectDN) setSubject(byte [] subjectDN) .

Note that the byte array returned is cloned to protect against subsequent modifications. a byte array containing the required subject distinguished namein ASN.1 DER format (or null)
throws:
  IOException - if an encoding error occurs

Returns the subject criterion as a String. This distinguished name must match the subject distinguished name in the X509Certificate. If null, the subject criterion is disabled and any subject distinguished name will do.

If the value returned is not null, it is a distinguished name, in RFC 2253 format. the required subject distinguished name in RFC 2253 format(or null)

Note that the byte array returned is cloned to protect against subsequent modifications. the key identifier (or null)
See Also:   X509CertSelector.setSubjectKeyIdentifier

If authorityKeyID is not null, it should contain a single DER encoded value corresponding to the contents of the extension value (not including the object identifier, criticality setting, and encapsulating OCTET STRING) for an AuthorityKeyIdentifier extension. The ASN.1 notation for this structure follows.

 AuthorityKeyIdentifier ::= SEQUENCE {
 keyIdentifier             [0] KeyIdentifier           OPTIONAL,
 authorityCertIssuer       [1] GeneralNames            OPTIONAL,
 authorityCertSerialNumber [2] CertificateSerialNumber OPTIONAL  }
 KeyIdentifier ::= OCTET STRING
 

Authority key identifiers are not parsed by the X509CertSelector. Instead, the values are compared using a byte-by-byte comparison.

When the keyIdentifier field of AuthorityKeyIdentifier is populated, the value is usually taken from the SubjectKeyIdentifier extension in the issuer's certificate. Note, however, that the result of X509Certificate.getExtensionValue(<SubjectKeyIdentifier Object Identifier>) on the issuer's certificate may NOT be used directly as the input to setAuthorityKeyIdentifier. This is because the SubjectKeyIdentifier contains only a KeyIdentifier OCTET STRING, and not a SEQUENCE of KeyIdentifier, GeneralNames, and CertificateSerialNumber. In order to use the extension value of the issuer certificate's SubjectKeyIdentifier extension, it will be necessary to extract the value of the embedded KeyIdentifier OCTET STRING, then DER encode this OCTET STRING inside a SEQUENCE. For more details on SubjectKeyIdentifier, see X509CertSelector.setSubjectKeyIdentifier(byte[] subjectKeyID) .

Note also that the byte array supplied here is cloned to protect against subsequent modifications.
Parameters:
  authorityKeyID - the authority key identifier (or null)
See Also:   X509CertSelector.getAuthorityKeyIdentifier

This constraint is useful when building a certification path forward (from the target toward the trust anchor. If a partial path has been built, any candidate certificate must have a maxPathLen value greater than or equal to the number of certificates in the partial path.
Parameters:
  minMaxPathLen - the value for the basic constraints constraint
throws:
  IllegalArgumentException - if the value is less than -2
See Also:   X509CertSelector.getBasicConstraints

This method is particularly useful when it is necessary to match a single certificate. Although other criteria can be specified in conjunction with the certificateEquals criterion, it is usually not practical or necessary.
Parameters:
  cert - the X509Certificate to match (or null)
See Also:   X509CertSelector.getCertificate

Note that the Date supplied here is cloned to protect against subsequent modifications.
Parameters:
  certValid - the Date to check (or null)
See Also:   X509CertSelector.getCertificateValid

Note that the Set is cloned to protect against subsequent modifications.
Parameters:
  keyPurposeSet - a Set of key purpose OIDs in string format (or null). Each OID is represented by a set of nonnegative integers separated by periods.
throws:
  IOException - if the OID is invalid, such asthe first component being not 0, 1 or 2 or the second componentbeing greater than 39.
See Also:   X509CertSelector.getExtendedKeyUsage

Sets the issuer criterion. The specified distinguished name must match the issuer distinguished name in the X509Certificate. If null, any issuer distinguished name will do.

If issuerDN is not null, it should contain a distinguished name, in RFC 2253 format.
Parameters:
  issuerDN - a distinguished name in RFC 2253 format(or null)
throws:
  IOException - if a parsing error occurs (incorrect form for DN)

If issuerDN is not null, 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 the byte array specified here is cloned to protect against subsequent modifications.
Parameters:
  issuerDN - a byte array containing the distinguished namein ASN.1 DER encoded form (or null)
throws:
  IOException - if an encoding error occurs (incorrect form for DN)

Note that the boolean array supplied here is cloned to protect against subsequent modifications.
Parameters:
  keyUsage - a boolean array in the same format as the booleanarray returned byX509Certificate.getKeyUsage X509Certificate.getKeyUsage().Or null.
See Also:   X509CertSelector.getKeyUsage

The matchAllNames flag is true by default.
Parameters:
  matchAllNames - if true, the flag is enabled;if false, the flag is disabled.
See Also:   X509CertSelector.getMatchAllSubjectAltNames

The name constraints are specified as a byte array. This byte array should contain the DER encoded form of the name constraints, as they would appear in the NameConstraints structure defined in RFC 3280 and X.509. The ASN.1 definition of this structure appears below.

 NameConstraints ::= SEQUENCE {
 permittedSubtrees       [0]     GeneralSubtrees OPTIONAL,
 excludedSubtrees        [1]     GeneralSubtrees OPTIONAL }
 GeneralSubtrees ::= SEQUENCE SIZE (1..MAX) OF GeneralSubtree
 GeneralSubtree ::= SEQUENCE {
 base                    GeneralName,
 minimum         [0]     BaseDistance DEFAULT 0,
 maximum         [1]     BaseDistance OPTIONAL }
 BaseDistance ::= INTEGER (0..MAX)
 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}
 

Note that the byte array supplied here is cloned to protect against subsequent modifications.
Parameters:
  bytes - a byte array containing the ASN.1 DER encoding ofa NameConstraints extension to be used for checkingname constraints. Only the value of the extension isincluded, not the OID or criticality flag. Can benull,in which case no name constraints check will be performed.
throws:
  IOException - if a parsing error occurs
See Also:   X509CertSelector.getNameConstraints

This method allows the caller to specify, with a single method call, the complete set of names which the X509Certificates's name constraints must permit. The specified value replaces the previous value for the pathToNames criterion.

This constraint is useful when building a certification path forward (from the target toward the trust anchor. If a partial path has been built, any candidate certificate must not include name constraints that would prohibit building a path to any of the names in the partial path.

The names parameter (if not null) is a Collection with one entry for each name to be included in the pathToNames criterion. Each entry is a List whose first entry is an Integer (the name type, 0-8) and whose second entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). There can be multiple names of the same type. If null is supplied as the value for this argument, no pathToNames check will be performed.

Each name in the Collection may be specified either as a String or as an ASN.1 encoded byte array. For more details about the formats used, see X509CertSelector.addPathToName(int type,String name) addPathToName(int type, String name) and X509CertSelector.addPathToName(int type,byte[] name) addPathToName(int type, byte [] name) .

Note: for distinguished names, specify the byte array form instead of the String form. See the note in X509CertSelector.addPathToName(int,String) for more information.

Note that the names parameter can contain duplicate names (same name and name type), but they may be removed from the Collection of names returned by the X509CertSelector.getPathToNames getPathToNames method.

Note that a deep copy is performed on the Collection to protect against subsequent modifications.
Parameters:
  names - a Collection with one entry per name(or null)
throws:
  IOException - if a parsing error occurs
See Also:   X509CertSelector.getPathToNames

Note that the Set is cloned to protect against subsequent modifications.
Parameters:
  certPolicySet - a Set of certificate policy OIDs instring format (or null). Each OID is represented by a set of nonnegative integers separated by periods.
throws:
  IOException - if a parsing error occurs on the OID such asthe first component is not 0, 1 or 2 or the second component isgreater than 39.
See Also:   X509CertSelector.getPolicy

Note that the Date supplied here is cloned to protect against subsequent modifications.
Parameters:
  privateKeyValid - the Date to check (ornull)
See Also:   X509CertSelector.getPrivateKeyValid

Sets the subject criterion. The specified distinguished name must match the subject distinguished name in the X509Certificate. If null, any subject distinguished name will do.

If subjectDN is not null, it should contain a distinguished name, in RFC 2253 format.
Parameters:
  subjectDN - a distinguished name in RFC 2253 format(or null)
throws:
  IOException - if a parsing error occurs (incorrect form for DN)

If subjectDN is not null, it should contain a single DER encoded distinguished name, as defined in X.501. For the ASN.1 notation for this structure, see X509CertSelector.setIssuer(byte[] issuerDN) setIssuer(byte [] issuerDN) .
Parameters:
  subjectDN - a byte array containing the distinguished name inASN.1 DER format (or null)
throws:
  IOException - if an encoding error occurs (incorrect form for DN)

This method allows the caller to specify, with a single method call, the complete set of subject alternative names for the subjectAlternativeNames criterion. The specified value replaces the previous value for the subjectAlternativeNames criterion.

The names parameter (if not null) is a Collection with one entry for each name to be included in the subject alternative name criterion. Each entry is a List whose first entry is an Integer (the name type, 0-8) and whose second entry is a String or a byte array (the name, in string or ASN.1 DER encoded form, respectively). There can be multiple names of the same type. If null is supplied as the value for this argument, no subjectAlternativeNames check will be performed.

Each subject alternative name in the Collection may be specified either as a String or as an ASN.1 encoded byte array. For more details about the formats used, see X509CertSelector.addSubjectAlternativeName(int type,String name) addSubjectAlternativeName(int type, String name) and X509CertSelector.addSubjectAlternativeName(int type,byte[] name) addSubjectAlternativeName(int type, byte [] name) .

Note: for distinguished names, specify the byte array form instead of the String form. See the note in X509CertSelector.addSubjectAlternativeName(int,String) for more information.

Note that the names parameter can contain duplicate names (same name and name type), but they may be removed from the Collection of names returned by the X509CertSelector.getSubjectAlternativeNames getSubjectAlternativeNames method.

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:   X509CertSelector.getSubjectAlternativeNames

If subjectKeyID is not null, it should contain a single DER encoded value corresponding to the contents of the extension value (not including the object identifier, criticality setting, and encapsulating OCTET STRING) for a SubjectKeyIdentifier extension. The ASN.1 notation for this structure follows.

 SubjectKeyIdentifier ::= KeyIdentifier
 KeyIdentifier ::= OCTET STRING
 

Since the format of subject key identifiers is not mandated by any standard, subject key identifiers are not parsed by the X509CertSelector. Instead, the values are compared using a byte-by-byte comparison.

Note that the byte array supplied here is cloned to protect against subsequent modifications.
Parameters:
  subjectKeyID - the subject key identifier (or null)
See Also:   X509CertSelector.getSubjectKeyIdentifier

Because this method allows the public key to be specified as a byte array, it may be used for unknown key types.

If key is not null, it should contain a single DER encoded SubjectPublicKeyInfo structure, as defined in X.509. The ASN.1 notation for this structure is as follows.

 SubjectPublicKeyInfo  ::=  SEQUENCE  {
 algorithm            AlgorithmIdentifier,
 subjectPublicKey     BIT STRING  }
 AlgorithmIdentifier  ::=  SEQUENCE  {
 algorithm               OBJECT IDENTIFIER,
 parameters              ANY DEFINED BY algorithm OPTIONAL  }
 -- contains a value of the type
 -- registered for use with the
 -- algorithm object identifier value
 

Note that the byte array supplied here is cloned to protect against subsequent modifications.
Parameters:
  key - a byte array containing the subject public key in ASN.1 DERform (or null)
throws:
  IOException - if an encoding error occurs (incorrect form for subject public key)
See Also:   X509CertSelector.getSubjectPublicKey