Class X509CertSelector
- All Implemented Interfaces:
Cloneable
,CertSelector
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(X500Principal)
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(X500Principal)
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 5280: 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.
- Since:
- 1.4
- External Specifications
- See Also:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
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.clone()
Returns a copy of this object.byte[]
Returns the authorityKeyIdentifier criterion.int
Returns the basic constraints constraint.Returns the certificateEquals criterion.Returns the certificateValid criterion.Returns the extendedKeyUsage criterion.Returns the issuer criterion as anX500Principal
.byte[]
Returns the issuer criterion as a byte array.Deprecated.boolean[]
Returns the keyUsage criterion.boolean
Indicates if theX509Certificate
must contain all or at least one of the subjectAlternativeNames specified in thesetSubjectAlternativeNames
oraddSubjectAlternativeName
methods.byte[]
Returns the name constraints criterion.Collection
<List<?>> Returns a copy of the pathToNames criterion.Returns the policy criterion.Returns the privateKeyValid criterion.Returns the serialNumber criterion.Returns the subject criterion as anX500Principal
.Collection
<List<?>> Returns a copy of the subjectAlternativeNames criterion.byte[]
Returns the subject criterion as a byte array.Deprecated.UsegetSubject()
orgetSubjectAsBytes()
instead.byte[]
Returns the subjectKeyIdentifier criterion.Returns the subjectPublicKey criterion.Returns the subjectPublicKeyAlgID criterion.boolean
match
(Certificate cert) Decides whether aCertificate
should be selected.void
setAuthorityKeyIdentifier
(byte[] authorityKeyID) Sets the authorityKeyIdentifier criterion.void
setBasicConstraints
(int minMaxPathLen) Sets the basic constraints constraint.void
Sets the certificateEquals criterion.void
setCertificateValid
(Date certValid) Sets the certificateValid criterion.void
setExtendedKeyUsage
(Set<String> keyPurposeSet) Sets the extendedKeyUsage criterion.void
setIssuer
(byte[] issuerDN) Sets the issuer criterion.void
Deprecated.UsesetIssuer(X500Principal)
orsetIssuer(byte[])
instead.void
setIssuer
(X500Principal issuer) 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 thesetSubjectAlternativeNames
oraddSubjectAlternativeName
methods.void
setNameConstraints
(byte[] bytes) Sets the name constraints criterion.void
setPathToNames
(Collection<List<?>> names) Sets the pathToNames criterion.void
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) Deprecated.UsesetSubject(X500Principal)
orsetSubject(byte[])
instead.void
setSubject
(X500Principal subject) Sets the subject criterion.void
setSubjectAlternativeNames
(Collection<List<?>> names) Sets the subjectAlternativeNames criterion.void
setSubjectKeyIdentifier
(byte[] subjectKeyID) Sets the subjectKeyIdentifier criterion.void
setSubjectPublicKey
(byte[] key) Sets the subjectPublicKey criterion.void
Sets the subjectPublicKey criterion.void
Sets the subjectPublicKeyAlgID criterion.toString()
Return a printable representation of theCertSelector
.
-
Constructor Details
-
X509CertSelector
public X509CertSelector()Creates anX509CertSelector
. Initially, no criteria are set so anyX509Certificate
will match.
-
-
Method Details
-
setCertificate
Sets the certificateEquals criterion. The specifiedX509Certificate
must be equal to theX509Certificate
passed to thematch
method. Ifnull
, then this check is not applied.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
- theX509Certificate
to match (ornull
)- See Also:
-
setSerialNumber
Sets the serialNumber criterion. The specified serial number must match the certificate serial number in theX509Certificate
. Ifnull
, any certificate serial number will do.- Parameters:
serial
- the certificate serial number to match (ornull
)- See Also:
-
setIssuer
Sets the issuer criterion. The specified distinguished name must match the issuer distinguished name in theX509Certificate
. Ifnull
, any issuer distinguished name will do.- Parameters:
issuer
- a distinguished name as X500Principal (ornull
)- Since:
- 1.5
-
setIssuer
Deprecated.UsesetIssuer(X500Principal)
orsetIssuer(byte[])
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.Sets the issuer criterion. The specified distinguished name must match the issuer distinguished name in theX509Certificate
. Ifnull
, any issuer distinguished name will do.If
issuerDN
is notnull
, it should contain a distinguished name, in RFC 2253 format.- Parameters:
issuerDN
- a distinguished name in RFC 2253 format (ornull
)- Throws:
IOException
- if a parsing error occurs (incorrect form for DN)- External Specifications
-
setIssuer
Sets the issuer criterion. The specified distinguished name must match the issuer distinguished name in theX509Certificate
. Ifnull
is specified, the issuer criterion is disabled and any issuer distinguished name will do.If
issuerDN
is notnull
, 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 name in ASN.1 DER encoded form (ornull
)- Throws:
IOException
- if an encoding error occurs (incorrect form for DN)
-
setSubject
Sets the subject criterion. The specified distinguished name must match the subject distinguished name in theX509Certificate
. Ifnull
, any subject distinguished name will do.- Parameters:
subject
- a distinguished name as X500Principal (ornull
)- Since:
- 1.5
-
setSubject
Deprecated.UsesetSubject(X500Principal)
orsetSubject(byte[])
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.Sets the subject criterion. The specified distinguished name must match the subject distinguished name in theX509Certificate
. Ifnull
, any subject distinguished name will do.If
subjectDN
is notnull
, it should contain a distinguished name, in RFC 2253 format.- Parameters:
subjectDN
- a distinguished name in RFC 2253 format (ornull
)- Throws:
IOException
- if a parsing error occurs (incorrect form for DN)- External Specifications
-
setSubject
Sets the subject criterion. The specified distinguished name must match the subject distinguished name in theX509Certificate
. Ifnull
, any subject distinguished name will do.If
subjectDN
is notnull
, it should contain a single DER encoded distinguished name, as defined in X.501. For the ASN.1 notation for this structure, seesetIssuer(byte[])
.- Parameters:
subjectDN
- a byte array containing the distinguished name in ASN.1 DER format (ornull
)- Throws:
IOException
- if an encoding error occurs (incorrect form for DN)
-
setSubjectKeyIdentifier
public void setSubjectKeyIdentifier(byte[] subjectKeyID) Sets the subjectKeyIdentifier criterion. TheX509Certificate
must contain a SubjectKeyIdentifier extension for which the contents of the extension matches the specified criterion value. If the criterion value isnull
, no subjectKeyIdentifier check will be done.If
subjectKeyID
is notnull
, 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 (ornull
)- See Also:
-
setAuthorityKeyIdentifier
public void setAuthorityKeyIdentifier(byte[] authorityKeyID) Sets the authorityKeyIdentifier criterion. TheX509Certificate
must contain an AuthorityKeyIdentifier extension for which the contents of the extension value matches the specified criterion value. If the criterion value isnull
, no authorityKeyIdentifier check will be done.If
authorityKeyID
is notnull
, 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 ofAuthorityKeyIdentifier
is populated, the value is usually taken from theSubjectKeyIdentifier
extension in the issuer's certificate. Note, however, that the result ofX509Certificate.getExtensionValue(<SubjectKeyIdentifier Object Identifier>)
on the issuer's certificate may NOT be used directly as the input tosetAuthorityKeyIdentifier
. 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'sSubjectKeyIdentifier
extension, it will be necessary to extract the value of the embeddedKeyIdentifier
OCTET STRING, then DER encode this OCTET STRING inside a SEQUENCE. For more details on SubjectKeyIdentifier, seesetSubjectKeyIdentifier(byte[] subjectKeyID)
.Note also that the byte array supplied here is cloned to protect against subsequent modifications.
- Parameters:
authorityKeyID
- the authority key identifier (ornull
)- See Also:
-
setCertificateValid
Sets the certificateValid criterion. The specified date must fall within the certificate validity period for theX509Certificate
. Ifnull
, no certificateValid check will be done.Note that the
Date
supplied here is cloned to protect against subsequent modifications.- Parameters:
certValid
- theDate
to check (ornull
)- See Also:
-
setPrivateKeyValid
Sets the privateKeyValid criterion. The specified date must fall within the private key validity period for theX509Certificate
. Ifnull
, no privateKeyValid check will be done.Note that the
Date
supplied here is cloned to protect against subsequent modifications.- Parameters:
privateKeyValid
- theDate
to check (ornull
)- See Also:
-
setSubjectPublicKeyAlgID
Sets the subjectPublicKeyAlgID criterion. TheX509Certificate
must contain a subject public key with the specified algorithm. Ifnull
, no subjectPublicKeyAlgID check will be done.- Parameters:
oid
- The object identifier (OID) of the algorithm to check for (ornull
). An OID is represented by a set of nonnegative integers separated by periods.- Throws:
IOException
- if the OID is invalid, such as the first component being not 0, 1 or 2 or the second component being greater than 39.- See Also:
-
setSubjectPublicKey
Sets the subjectPublicKey criterion. TheX509Certificate
must contain the specified subject public key. Ifnull
, no subjectPublicKey check will be done.- Parameters:
key
- the subject public key to check for (ornull
)- See Also:
-
setSubjectPublicKey
Sets the subjectPublicKey criterion. TheX509Certificate
must contain the specified subject public key. Ifnull
, no subjectPublicKey check will be done.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 notnull
, 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 DER form (ornull
)- Throws:
IOException
- if an encoding error occurs (incorrect form for subject public key)- See Also:
-
setKeyUsage
public void setKeyUsage(boolean[] keyUsage) Sets the keyUsage criterion. TheX509Certificate
must allow the specified keyUsage values. Ifnull
, no keyUsage check will be done. Note that anX509Certificate
that has no keyUsage extension implicitly allows all keyUsage values.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 boolean array returned byX509Certificate.getKeyUsage()
. Ornull
.- See Also:
-
setExtendedKeyUsage
Sets the extendedKeyUsage criterion. TheX509Certificate
must allow the specified key purposes in its extended key usage extension. IfkeyPurposeSet
is empty ornull
, no extendedKeyUsage check will be done. Note that anX509Certificate
that has no extendedKeyUsage extension implicitly allows all key purposes.Note that the
Set
is cloned to protect against subsequent modifications.- Parameters:
keyPurposeSet
- aSet
of key purpose OIDs in string format (ornull
). Each OID is represented by a set of nonnegative integers separated by periods.- Throws:
IOException
- if the OID is invalid, such as the first component being not 0, 1 or 2 or the second component being greater than 39.- See Also:
-
setMatchAllSubjectAltNames
public void setMatchAllSubjectAltNames(boolean matchAllNames) Enables/disables matching all of the subjectAlternativeNames specified in thesetSubjectAlternativeNames
oraddSubjectAlternativeName
methods. If enabled, theX509Certificate
must contain all of the specified subject alternative names. If disabled, theX509Certificate
must contain at least one of the specified subject alternative names.The matchAllNames flag is
true
by default.- Parameters:
matchAllNames
- iftrue
, the flag is enabled; iffalse
, the flag is disabled.- See Also:
-
setSubjectAlternativeNames
Sets the subjectAlternativeNames criterion. TheX509Certificate
must contain all or at least one of the specified subjectAlternativeNames, depending on the value of the matchAllNames flag (seesetMatchAllSubjectAltNames
).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 notnull
) is aCollection
with one entry for each name to be included in the subject alternative name criterion. Each entry is aList
whose first entry is anInteger
(the name type, 0-8) and whose second entry is aString
or a byte array (the name, in string or ASN.1 DER encoded form, respectively). There can be multiple names of the same type. Ifnull
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 aString
or as an ASN.1 encoded byte array. For more details about the formats used, seeaddSubjectAlternativeName(int type, String name)
andaddSubjectAlternativeName(int type, byte [] name)
.Note: for distinguished names, specify the byte array form instead of the String form. See the note in
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 theCollection
of names returned by thegetSubjectAlternativeNames
method.Note that a deep copy is performed on the
Collection
to protect against subsequent modifications.- Parameters:
names
- aCollection
of names (ornull
)- Throws:
IOException
- if a parsing error occurs- See Also:
-
addSubjectAlternativeName
Adds a name to the subjectAlternativeNames criterion. TheX509Certificate
must contain all or at least one of the specified subjectAlternativeNames, depending on the value of the matchAllNames flag (seesetMatchAllSubjectAltNames
).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 5280). 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.Note: for distinguished names, use addSubjectAlternativeName(int, byte[]) 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 in RFC 5280, section 4.2.1.6)name
- the name in string form (notnull
)- Throws:
IOException
- if a parsing error occurs- External Specifications
-
addSubjectAlternativeName
Adds a name to the subjectAlternativeNames criterion. TheX509Certificate
must contain all or at least one of the specified subjectAlternativeNames, depending on the value of the matchAllNames flag (seesetMatchAllSubjectAltNames
).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 5280 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)name
- a byte array containing the name in ASN.1 DER encoded form- Throws:
IOException
- if a parsing error occurs
-
setNameConstraints
Sets the name constraints criterion. TheX509Certificate
must have subject and subject alternative names that meet the specified name constraints.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 5280 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 of a NameConstraints extension to be used for checking name constraints. Only the value of the extension is included, 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:
-
setBasicConstraints
public void setBasicConstraints(int minMaxPathLen) Sets the basic constraints constraint. If the value is greater than or equal to zero,X509Certificates
must include a basicConstraints extension with a pathLen of at least this value. If the value is -2, only end-entity certificates are accepted. If the value is -1, no check is done.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:
-
setPolicy
Sets the policy constraint. TheX509Certificate
must include at least one of the specified policies in its certificate policies extension. IfcertPolicySet
is empty, then theX509Certificate
must include at least some specified policy in its certificate policies extension. IfcertPolicySet
isnull
, no policy check will be performed.Note that the
Set
is cloned to protect against subsequent modifications.- Parameters:
certPolicySet
- aSet
of certificate policy OIDs in string format (ornull
). Each OID is represented by a set of nonnegative integers separated by periods.- Throws:
IOException
- if a parsing error occurs on the OID such as the first component is not 0, 1 or 2 or the second component is greater than 39.- See Also:
-
setPathToNames
Sets the pathToNames criterion. TheX509Certificate
must not include name constraints that would prohibit building a path to the specified names.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 notnull
) is aCollection
with one entry for each name to be included in the pathToNames criterion. Each entry is aList
whose first entry is anInteger
(the name type, 0-8) and whose second entry is aString
or a byte array (the name, in string or ASN.1 DER encoded form, respectively). There can be multiple names of the same type. Ifnull
is supplied as the value for this argument, no pathToNames check will be performed.Each name in the
Collection
may be specified either as aString
or as an ASN.1 encoded byte array. For more details about the formats used, seeaddPathToName(int type, String name)
andaddPathToName(int type, byte [] name)
.Note: for distinguished names, specify the byte array form instead of the String form. See the note in
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 theCollection
of names returned by thegetPathToNames
method.Note that a deep copy is performed on the
Collection
to protect against subsequent modifications.- Parameters:
names
- aCollection
with one entry per name (ornull
)- Throws:
IOException
- if a parsing error occurs- See Also:
-
addPathToName
Adds a name to the pathToNames criterion. TheX509Certificate
must not include name constraints that would prohibit building a path to the specified name.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 5280). 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.Note: for distinguished names, use addPathToName(int, byte[]) 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 in RFC 5280, section 4.2.1.6)name
- the name in string form- Throws:
IOException
- if a parsing error occurs
-
addPathToName
Adds a name to the pathToNames criterion. TheX509Certificate
must not include name constraints that would prohibit building a path to the specified name.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 5280 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.
- Parameters:
type
- the name type (0-8, as specified in RFC 5280, section 4.2.1.6)name
- a byte array containing the name in ASN.1 DER encoded form- Throws:
IOException
- if a parsing error occurs
-
getCertificate
Returns the certificateEquals criterion. The specifiedX509Certificate
must be equal to theX509Certificate
passed to thematch
method. Ifnull
, this check is not applied.- Returns:
- the
X509Certificate
to match (ornull
) - See Also:
-
getSerialNumber
Returns the serialNumber criterion. The specified serial number must match the certificate serial number in theX509Certificate
. Ifnull
, any certificate serial number will do.- Returns:
- the certificate serial number to match
(or
null
) - See Also:
-
getIssuer
Returns the issuer criterion as anX500Principal
. This distinguished name must match the issuer distinguished name in theX509Certificate
. Ifnull
, the issuer criterion is disabled and any issuer distinguished name will do.- Returns:
- the required issuer distinguished name as X500Principal
(or
null
) - Since:
- 1.5
-
getIssuerAsString
Deprecated.UsegetIssuer()
orgetIssuerAsBytes()
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.Returns the issuer criterion as aString
. This distinguished name must match the issuer distinguished name in theX509Certificate
. Ifnull
, 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.- Returns:
- the required issuer distinguished name in RFC 2253 format
(or
null
) - External Specifications
-
getIssuerAsBytes
Returns the issuer criterion as a byte array. This distinguished name must match the issuer distinguished name in theX509Certificate
. Ifnull
, the issuer criterion is disabled and any issuer distinguished name will do.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 forsetIssuer(byte[])
.Note that the byte array returned is cloned to protect against subsequent modifications.
- Returns:
- a byte array containing the required issuer distinguished name
in ASN.1 DER format (or
null
) - Throws:
IOException
- if an encoding error occurs
-
getSubject
Returns the subject criterion as anX500Principal
. This distinguished name must match the subject distinguished name in theX509Certificate
. Ifnull
, the subject criterion is disabled and any subject distinguished name will do.- Returns:
- the required subject distinguished name as X500Principal
(or
null
) - Since:
- 1.5
-
getSubjectAsString
Deprecated.UsegetSubject()
orgetSubjectAsBytes()
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.Returns the subject criterion as aString
. This distinguished name must match the subject distinguished name in theX509Certificate
. Ifnull
, 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.- Returns:
- the required subject distinguished name in RFC 2253 format
(or
null
) - External Specifications
-
getSubjectAsBytes
Returns the subject criterion as a byte array. This distinguished name must match the subject distinguished name in theX509Certificate
. Ifnull
, the subject criterion is disabled and any subject distinguished name will do.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 forsetSubject(byte[])
.Note that the byte array returned is cloned to protect against subsequent modifications.
- Returns:
- a byte array containing the required subject distinguished name
in ASN.1 DER format (or
null
) - Throws:
IOException
- if an encoding error occurs
-
getSubjectKeyIdentifier
public byte[] getSubjectKeyIdentifier()Returns the subjectKeyIdentifier criterion. TheX509Certificate
must contain a SubjectKeyIdentifier extension with the specified value. Ifnull
, no subjectKeyIdentifier check will be done.Note that the byte array returned is cloned to protect against subsequent modifications.
- Returns:
- the key identifier (or
null
) - See Also:
-
getAuthorityKeyIdentifier
public byte[] getAuthorityKeyIdentifier()Returns the authorityKeyIdentifier criterion. TheX509Certificate
must contain a AuthorityKeyIdentifier extension with the specified value. Ifnull
, no authorityKeyIdentifier check will be done.Note that the byte array returned is cloned to protect against subsequent modifications.
- Returns:
- the key identifier (or
null
) - See Also:
-
getCertificateValid
Returns the certificateValid criterion. The specified date must fall within the certificate validity period for theX509Certificate
. Ifnull
, no certificateValid check will be done.Note that the
Date
returned is cloned to protect against subsequent modifications.- Returns:
- the
Date
to check (ornull
) - See Also:
-
getPrivateKeyValid
Returns the privateKeyValid criterion. The specified date must fall within the private key validity period for theX509Certificate
. Ifnull
, no privateKeyValid check will be done.Note that the
Date
returned is cloned to protect against subsequent modifications.- Returns:
- the
Date
to check (ornull
) - See Also:
-
getSubjectPublicKeyAlgID
Returns the subjectPublicKeyAlgID criterion. TheX509Certificate
must contain a subject public key with the specified algorithm. Ifnull
, no subjectPublicKeyAlgID check will be done.- Returns:
- the object identifier (OID) of the signature algorithm to check
for (or
null
). An OID is represented by a set of nonnegative integers separated by periods. - See Also:
-
getSubjectPublicKey
Returns the subjectPublicKey criterion. TheX509Certificate
must contain the specified subject public key. Ifnull
, no subjectPublicKey check will be done.- Returns:
- the subject public key to check for (or
null
) - See Also:
-
getKeyUsage
public boolean[] getKeyUsage()Returns the keyUsage criterion. TheX509Certificate
must allow the specified keyUsage values. If null, no keyUsage check will be done.Note that the boolean array returned is cloned to protect against subsequent modifications.
- Returns:
- a boolean array in the same format as the boolean
array returned by
X509Certificate.getKeyUsage()
. Ornull
. - See Also:
-
getExtendedKeyUsage
Returns the extendedKeyUsage criterion. TheX509Certificate
must allow the specified key purposes in its extended key usage extension. If thekeyPurposeSet
returned is empty ornull
, no extendedKeyUsage check will be done. Note that anX509Certificate
that has no extendedKeyUsage extension implicitly allows all key purposes.- Returns:
- an immutable
Set
of key purpose OIDs in string format (ornull
) - See Also:
-
getMatchAllSubjectAltNames
public boolean getMatchAllSubjectAltNames()Indicates if theX509Certificate
must contain all or at least one of the subjectAlternativeNames specified in thesetSubjectAlternativeNames
oraddSubjectAlternativeName
methods. Iftrue
, theX509Certificate
must contain all of the specified subject alternative names. Iffalse
, theX509Certificate
must contain at least one of the specified subject alternative names.- Returns:
true
if the flag is enabled;false
if the flag is disabled. The flag istrue
by default.- See Also:
-
getSubjectAlternativeNames
Returns a copy of the subjectAlternativeNames criterion. TheX509Certificate
must contain all or at least one of the specified subjectAlternativeNames, depending on the value of the matchAllNames flag (seegetMatchAllSubjectAltNames
). If the value returned isnull
, no subjectAlternativeNames check will be performed.If the value returned is not
null
, it is aCollection
with one entry for each name to be included in the subject alternative name criterion. Each entry is aList
whose first entry is anInteger
(the name type, 0-8) and whose second entry is aString
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 theCollection
returned may contain duplicate names (same name and name type).Each subject alternative name in the
Collection
may be specified either as aString
or as an ASN.1 encoded byte array. For more details about the formats used, seeaddSubjectAlternativeName(int type, String name)
andaddSubjectAlternativeName(int type, byte [] name)
.Note that a deep copy is performed on the
Collection
to protect against subsequent modifications.- Returns:
- a
Collection
of names (ornull
) - See Also:
-
getNameConstraints
public byte[] getNameConstraints()Returns the name constraints criterion. TheX509Certificate
must have subject and subject alternative names that meet the specified name constraints.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 5280 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.
- Returns:
- a byte array containing the ASN.1 DER encoding of
a NameConstraints extension used for checking name constraints.
null
if no name constraints check will be performed. - See Also:
-
getBasicConstraints
public int getBasicConstraints()Returns the basic constraints constraint. If the value is greater than or equal to zero, theX509Certificates
must include a basicConstraints extension with a pathLen of at least this value. If the value is -2, only end-entity certificates are accepted. If the value is -1, no basicConstraints check is done.- Returns:
- the value for the basic constraints constraint
- See Also:
-
getPolicy
Returns the policy criterion. TheX509Certificate
must include at least one of the specified policies in its certificate policies extension. If theSet
returned is empty, then theX509Certificate
must include at least some specified policy in its certificate policies extension. If theSet
returned isnull
, no policy check will be performed.- Returns:
- an immutable
Set
of certificate policy OIDs in string format (ornull
) - See Also:
-
getPathToNames
Returns a copy of the pathToNames criterion. TheX509Certificate
must not include name constraints that would prohibit building a path to the specified names. If the value returned isnull
, no pathToNames check will be performed.If the value returned is not
null
, it is aCollection
with one entry for each name to be included in the pathToNames criterion. Each entry is aList
whose first entry is anInteger
(the name type, 0-8) and whose second entry is aString
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 theCollection
returned may contain duplicate names (same name and name type).Each name in the
Collection
may be specified either as aString
or as an ASN.1 encoded byte array. For more details about the formats used, seeaddPathToName(int type, String name)
andaddPathToName(int type, byte [] name)
.Note that a deep copy is performed on the
Collection
to protect against subsequent modifications.- Returns:
- a
Collection
of names (ornull
) - See Also:
-
toString
-
match
Decides whether aCertificate
should be selected.- Specified by:
match
in interfaceCertSelector
- Parameters:
cert
- theCertificate
to be checked- Returns:
true
if theCertificate
should be selected,false
otherwise
-
clone
Returns a copy of this object.- Specified by:
clone
in interfaceCertSelector
- Overrides:
clone
in classObject
- Returns:
- the copy
- See Also:
-
getIssuer()
orgetIssuerAsBytes()
instead.