java.lang.Object java.security.cert.X509CertSelector
A CertSelector that selects X509Certificates that match all specified criteria. This class is particularly useful when selecting certificates from a CertStore to build a PKIX-compliant certification path.
When first constructed, an X509CertSelector has no criteria enabled and each of the get methods return a default value (null, or -1 for the
getBasicConstraints
method). Therefore, the
match
method would return true for any X509Certificate. Typically, several criteria are enabled (by calling
setIssuer
setIssuer
or
setKeyUsage
, for instance) and then the X509CertSelector is passed to
CertStore.getCertificates
or some similar method.
Several criteria can be enabled (by calling
setIssuer
setIssuer
and
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 2459 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.
Constructor Summary | |
---|---|
X509CertSelector
() Creates an X509CertSelector. |
Method Summary | |
---|---|
void |
addPathToName
(int type, byte[] name) Adds a name to the pathToNames criterion. |
void |
addPathToName
(int type,
String
name) Adds a name to the pathToNames criterion. |
void |
addSubjectAlternativeName
(int type, byte[] name) Adds a name to the subjectAlternativeNames criterion. |
void |
addSubjectAlternativeName
(int type,
String
name) Adds a name to the subjectAlternativeNames criterion. |
Object |
clone
() Returns a copy of this object. |
byte[] |
getAuthorityKeyIdentifier
() Returns the authorityKeyIdentifier criterion. |
int |
getBasicConstraints
() Returns the basic constraints constraint. |
X509Certificate |
getCertificate
() Returns the certificateEquals criterion. |
Date |
getCertificateValid
() Returns the certificateValid criterion. |
Set |
getExtendedKeyUsage
() Returns the extendedKeyUsage criterion. |
X500Principal |
getIssuer
()
Returns the issuer criterion as an X500Principal. |
byte[] |
getIssuerAsBytes
() Returns the issuer criterion as a byte array. |
String |
getIssuerAsString
() Returns the issuer criterion as a String. |
boolean[] |
getKeyUsage
() Returns the keyUsage criterion. |
boolean |
getMatchAllSubjectAltNames
() Indicates if the X509Certificate must contain all or at least one of the subjectAlternativeNames specified in the setSubjectAlternativeNames |
byte[] |
getNameConstraints
() Returns the name constraints criterion. |
Collection |
getPathToNames
() Returns a copy of the pathToNames criterion. |
Set |
getPolicy
() Returns the policy criterion. |
Date |
getPrivateKeyValid
() Returns the privateKeyValid criterion. |
BigInteger |
getSerialNumber
() Returns the serialNumber criterion. |
X500Principal |
getSubject
()
Returns the subject criterion as an X500Principal. |
Collection |
getSubjectAlternativeNames
() Returns a copy of the subjectAlternativeNames criterion. |
byte[] |
getSubjectAsBytes
() Returns the subject criterion as a byte array. |
String |
getSubjectAsString
() Returns the subject criterion as a String. |
byte[] |
getSubjectKeyIdentifier
() Returns the subjectKeyIdentifier criterion. |
PublicKey |
getSubjectPublicKey
() Returns the subjectPublicKey criterion. |
String |
getSubjectPublicKeyAlgID
() Returns the subjectPublicKeyAlgID criterion. |
boolean |
match
(
Certificate
cert) Decides whether a Certificate should be selected. |
void |
setAuthorityKeyIdentifier
(byte[] authorityKeyID) Sets the authorityKeyIdentifier criterion. |
void |
setBasicConstraints
(int minMaxPathLen) Sets the basic constraints constraint. |
void |
setCertificate
(
X509Certificate
cert) Sets the certificateEquals criterion. |
void |
setCertificateValid
(
Date
certValid) Sets the certificateValid criterion. |
void |
setExtendedKeyUsage
(
Set
<
String
Sets the extendedKeyUsage criterion. |
void |
setIssuer
(byte[] issuerDN) Sets the issuer criterion. |
void |
setIssuer
(
String
issuerDN) Sets the issuer criterion. |
void |
setIssuer
(
X500Principal
Sets the issuer criterion. |
void |
setKeyUsage
(boolean[] keyUsage) Sets the keyUsage criterion. |
void |
setMatchAllSubjectAltNames
(boolean matchAllNames) Enables/disables matching all of the subjectAlternativeNames specified in the setSubjectAlternativeNames |
void |
setNameConstraints
(byte[] bytes) Sets the name constraints criterion. |
void |
setPathToNames
Sets the pathToNames criterion. |
void |
setPolicy
(
Set
<
String
Sets the policy constraint. |
void |
setPrivateKeyValid
(
Date
privateKeyValid) Sets the privateKeyValid criterion. |
void |
setSerialNumber
(
BigInteger
serial) Sets the serialNumber criterion. |
void |
setSubject
(byte[] subjectDN) Sets the subject criterion. |
void |
setSubject
(
String
subjectDN) Sets the subject criterion. |
void |
setSubject
Sets the subject |
void |
setSubjectAlternativeNames
(
Collection
<
List
Sets the subjectAlternativeNames criterion. |
void |
setSubjectKeyIdentifier
(byte[] subjectKeyID) Sets the subjectKeyIdentifier criterion. |
void |
setSubjectPublicKey
(byte[] key) Sets the subjectPublicKey criterion. |
void |
setSubjectPublicKey
(
PublicKey
key) Sets the subjectPublicKey criterion. |
void |
setSubjectPublicKeyAlgID
(
String
oid) Sets the subjectPublicKeyAlgID criterion. |
String |
toString
() Return a printable representation of the CertSelector. |
Methods inherited from class java.lang. Object |
---|
equals , finalize , getClass , hashCode , notify , notifyAll , wait , wait , wait |
Constructor Detail |
---|
public X509CertSelector()
Method Detail |
---|
public void setCertificate(X509Certificate cert)
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.
public void setSerialNumber(BigInteger serial)
public void setIssuer ( X500Principal issuer)
public void setIssuer(String issuerDN) throws IOException
If issuerDN is not null, it should contain a distinguished name, in RFC 2253 format.
public void setIssuer(byte[] issuerDN) throws IOException
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.
public void setSubject ( X500Principal subject)
public void setSubject(String subjectDN) throws IOException
If subjectDN is not null, it should contain a distinguished name, in RFC 2253 format.
public void setSubject(byte[] subjectDN) throws IOException
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 setIssuer(byte [] issuerDN) .
public void setSubjectKeyIdentifier(byte[] subjectKeyID)
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.
public void setAuthorityKeyIdentifier(byte[] authorityKeyID)
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 setSubjectKeyIdentifier(byte[] subjectKeyID) .
Note also that the byte array supplied here is cloned to protect against subsequent modifications.
public void setCertificateValid(Date certValid)
Note that the Date supplied here is cloned to protect against subsequent modifications.
public void setPrivateKeyValid(Date privateKeyValid)
Note that the Date supplied here is cloned to protect against subsequent modifications.
public void setSubjectPublicKeyAlgID(String oid) throws IOException
public void setSubjectPublicKey(PublicKey key)
public void setSubjectPublicKey(byte[] key) throws IOException
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.
public void setKeyUsage(boolean[] keyUsage)
Note that the boolean array supplied here is cloned to protect against subsequent modifications.
public void setExtendedKeyUsage(Set< StringkeyPurposeSet) throwsIOException> keyPurposeSet) throws IOException
Note that the Set is cloned to protect against subsequent modifications.
public void setMatchAllSubjectAltNames(boolean matchAllNames)
The matchAllNames flag is true by default.
public void setSubjectAlternativeNames(Collection< Listnames) throwsIOException<?>> names) throws IOException
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 addSubjectAlternativeName(int type, String name) and addSubjectAlternativeName(int type, byte [] name) .
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 getSubjectAlternativeNames method.
Note that a deep copy is performed on the Collection to protect against subsequent modifications.
public void addSubjectAlternativeName(int type, String name) throws IOException
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 2459). 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 addSubjectAlternativeName(int type, byte [] name) method.
public void addSubjectAlternativeName(int type, byte[] name) throws IOException
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 2459 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.
public void setNameConstraints(byte[] bytes) throws IOException
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 2459 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.
public void setBasicConstraints(int minMaxPathLen)
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.
public void setPolicy(Set< StringcertPolicySet) throwsIOException> certPolicySet) throws IOException
Note that the Set is cloned to protect against subsequent modifications.
public void setPathToNames(Collection< Listnames) throwsIOException<?>> names) throws IOException
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 addPathToName(int type, String name) and addPathToName(int type, byte [] name) .
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 getPathToNames method.
Note that a deep copy is performed on the Collection to protect against subsequent modifications.
public void addPathToName(int type, String name) throws IOException
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 2459). 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 addPathToName(int type, byte [] name) method.
public void addPathToName(int type, byte[] name) throws IOException
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 2459 and X.509. The ASN.1 definition of this structure appears in the documentation for addSubjectAlternativeName(int type, byte [] name) .
Note that the byte array supplied here is cloned to protect against subsequent modifications.
public X509Certificate getCertificate()
public BigInteger getSerialNumber()
public X500PrincipalgetIssuer ()
public String getIssuerAsString()
If the value returned is not null, it is a distinguished name, in RFC 2253 format.
public byte[] getIssuerAsBytes() throws IOException
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 setIssuer(byte [] issuerDN) .
Note that the byte array returned is cloned to protect against subsequent modifications.
public X500PrincipalgetSubject ()
public String getSubjectAsString()
If the value returned is not null, it is a distinguished name, in RFC 2253 format.
public byte[] getSubjectAsBytes() throws IOException
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 setSubject(byte [] subjectDN) .
Note that the byte array returned is cloned to protect against subsequent modifications.
public byte[] getSubjectKeyIdentifier()
Note that the byte array returned is cloned to protect against subsequent modifications.
public byte[] getAuthorityKeyIdentifier()
Note that the byte array returned is cloned to protect against subsequent modifications.
public Date getCertificateValid()
Note that the Date returned is cloned to protect against subsequent modifications.
public Date getPrivateKeyValid()
Note that the Date returned is cloned to protect against subsequent modifications.
public String getSubjectPublicKeyAlgID()
public PublicKey getSubjectPublicKey()
public boolean[] getKeyUsage()
Note that the boolean array returned is cloned to protect against subsequent modifications.
public Set getExtendedKeyUsage()
public boolean getMatchAllSubjectAltNames()
public Collection getSubjectAlternativeNames()
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 addSubjectAlternativeName(int type, String name) and addSubjectAlternativeName(int type, byte [] name) .
Note that a deep copy is performed on the Collection to protect against subsequent modifications.
public byte[] getNameConstraints()
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 2459 and X.509. The ASN.1 notation for this structure is supplied in the documentation for setNameConstraints(byte [] bytes) .
Note that the byte array returned is cloned to protect against subsequent modifications.
public int getBasicConstraints()
public Set getPolicy()
public Collection getPathToNames()
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 addPathToName(int type, String name) and addPathToName(int type, byte [] name) .
Note that a deep copy is performed on the Collection to protect against subsequent modifications.
public String toString()
public boolean match(Certificate cert)
public Object clone()