java.security.cert
类 X509CertSelector

java.lang.Object
  java.security.cert.X509CertSelector

所有已实现的接口：

Cloneable, CertSelector

public class X509CertSelector
     

      extends 
      Object
     
     

      implements 
      CertSelector
     

选择与所有指定标准匹配的 X509Certificates 的 CertSelector。从 CertStore 中选择证书以构建一个符合 PKIX 的证书路径时，此类特别有用。

最初构造 X509CertSelector 时，它没有启用任何标准，并且每个 get 方法都返回一个默认值（null，对于 getBasicConstraints 方法，则返回 -1）。因此，对于任意 X509Certificate 而言，match 方法都将返回 true。通常，启用多种标准（例如通过调用 setIssuer 或 setKeyUsage），然后将 X509CertSelector 传递到 CertStore.getCertificates 或某个类似方法。

可以启用多种标准（例如通过调用 setIssuer 和 setSerialNumber），这样通常 match 方法会唯一地匹配单个 X509Certificate。我们在此说“通常”，是因为两个发布证书的 CA 可能具有相同的标识名，并且这两个 CA 发布了具有相同序列号的证书。其他独特的组合包含 issuer、subject、subjectKeyIdentifier 和/或 subjectPublicKey 标准。

有关下面所述各个 X.509 证书扩展的定义，请参阅 RFC 2459。

并发访问

除非另行指定，否则此类中所定义的方法不是线程安全的。需要并发访问单个对象的多个线程应该在它们之间实现同步并提供所需的锁定。对于每个线程都操作一个不同对象的多个线程而言，无需实现同步。

从以下版本开始：

1.4

另请参见：

CertSelector, X509Certificate

X509CertSelector

public X509CertSelector()

创建一个 X509CertSelector。最初未设置任何标准，所以任何 X509Certificate 都匹配。

setCertificate

public void setCertificate(X509Certificate cert)

设置 certificateEquals 标准。指定的 X509Certificate 必须等于传入到 match 方法的 X509Certificate。如果它为 null，则不进行此项检查。

必需与单个证书匹配时，此方法特别有用。虽然可以与 certificateEquals 标准一起指定其他标准，但这样做通常不实用或不必要。

参数：

cert - 要匹配的 X509Certificate（或者为 null）

另请参见：

getCertificate()

setSerialNumber

public void setSerialNumber(BigInteger serial)

设置 serialNumber 标准。指定的 serialNumber 必须与 X509Certificate 中的证书 serialNumber 匹配。如果该 serialNumber 为 null，则与任何证书 serialNumber 匹配都可以。

参数：

serial - 要匹配的证书 serialNumber（或者为 null）

另请参见：

getSerialNumber()

setIssuer

public void setIssuer(X500Principal issuer)

设置 issuer 标准。指定的标识名必须与 X509Certificate 中的发布方标识名匹配。如果该发布方标识名为 null，则与任何发布方 标识名匹配都可以。

参数：

issuer - X500Principal 形式的标识名（或者为 null）

从以下版本开始：

1.5

setIssuer

public void setIssuer(String issuerDN)
               throws IOException

已过时，使用 setIssuer(X500Principal) 或 setIssuer(byte[]) 替代。由于某些 RFC 2253 String 形式的标识名中会丢失编码信息，所以当此方法与某些证书不匹配时不应该依赖它。

设置 issuer 标准。指定的标识名必须与 X509Certificate 中的发布方标识名匹配。如果该发布方标识名为 null，则与任何发布方标识名匹配都可以。

如果 issuerDN 不为 null，则应该包含一个 RFC 2253 格式的标识名。

参数：

issuerDN - RFC 2253 格式的标识名（或者为 null）

抛出：

IOException - 如果出现解析错误（错误的 DN 形式）

setIssuer

public void setIssuer(byte[] issuerDN)
               throws IOException

设置 issuer 标准。指定的标识名必须与 X509Certificate 中的发布方标识名匹配。如果指定了 null，则禁用 issuer 标准，且与任何发布方标识名匹配都可以。

如果 issuerDN 不为 null，则应该包含单个 DER 编码形式的标识名，正如 X.501 中定义的一样。此结构的 ASN.1 表示如下：

 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)) }
 

注意，要复制此处指定的 byte 数组以防后续修改。

参数：

issuerDN - 一个 byte 数组，包含 ASN.1 DER 编码形式的标识名（或者为 null）

抛出：

IOException - 如果出现编码错误（错误的 DN 形式）

setSubject

public void setSubject(X500Principal subject)

设置 subject 标准。指定的标识名必须与 X509Certificate 中的主体标识名匹配。如果该主体标识名为 null，则与任何主体标识名匹配都可以。

参数：

subject - X500Principal 形式的标识名（或者为 null）

从以下版本开始：

1.5

setSubject

public void setSubject(String subjectDN)
                throws IOException

已过时，使用 setSubject(X500Principal) 或 setSubject(byte[]) 替代。由于某些 RFC 2253 String 形式的标识名中会丢失编码信息，所以当此方法与某些证书不匹配时不应该依赖它。

设置 subject 标准。指定的标识名必须与 X509Certificate 中的 主体标识名匹配。如果该主体标识名为 null，则与任何主体标识名匹配都可以。

如果 subjectDN 不为 null，则应该包含一个 RFC 2253 格式的标识名。

参数：

subjectDN - RFC 2253 格式的标识名（或者为 null）

抛出：

IOException - 如果出现解析错误（错误的 DN 形式）

setSubject

public void setSubject(byte[] subjectDN)
                throws IOException

设置 subject 标准。指定的标识名必须与 X509Certificate 中的主体标识名匹配。如果该主体标识名为 null，则与任何主体标识名匹配都可以。

如果 subjectDN 不为 null，则应该包含单个 DER 编码形式的标识名，正如 X.501 中定义的一样。有关此结构的 ASN.1 表示，请参阅 setIssuer(byte [] issuerDN)。

参数：

subjectDN - 一个 byte 数组，包含 ASN.1 DER 格式的标识名（或者为 null）

抛出：

IOException - 如果出现编码错误（错误的 DN 形式）

setSubjectKeyIdentifier

public void setSubjectKeyIdentifier(byte[] subjectKeyID)

设置 subjectKeyIdentifier 标准。 X509Certificate 必须包含一个 SubjectKeyIdentifier 扩展，且该扩展的内容与指定的标准值匹配。如果该标准值为 null，则不执行 subjectKeyIdentifier 检查。

如果 subjectKeyID 不为 null，则应该包含与 SubjectKeyIdentifier 扩展的扩展值内容（不包括对象标识符、关键性设置和封装 OCTET STRING）相对应的 DER 编码形式的值。此结构的 ASN.1 表示如下：

 SubjectKeyIdentifier ::= KeyIdentifier

 KeyIdentifier ::= OCTET STRING
 

由于任何标准都没有要求 SubjectKeyIdentifier 的格式，所以 X509CertSelector 不解析 SubjectKeyIdentifier。相反，使用逐字节比较的方式来比较该值。

注意，要复制此处提供的 byte 数组以防后续修改。

参数：

subjectKeyID - SubjectKeyIdentifier（或者为 null）

另请参见：

getSubjectKeyIdentifier()

setAuthorityKeyIdentifier

public void setAuthorityKeyIdentifier(byte[] authorityKeyID)

设置 authorityKeyIdentifier 扩展。 X509Certificate 必须包含一个 AuthorityKeyIdentifier 扩展，且该扩展值的内容与指定的标准值匹配。如果该标准值为 null，则不执行 authorityKeyIdentifier 检查。

如果 authorityKeyID 不为 null，则应该包含单个与 AuthorityKeyIdentifier 扩展的扩展值内容（不包括对象标识符、关键性设置和封装 OCTET STRING）相对应的 DER 编码形式的值。此结构的 ASN.1 表示如下：

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

 KeyIdentifier ::= OCTET STRING
 

X509CertSelector 不解析 AuthorityKeyIdentifier。相反，使用逐字节比较的方式来比较该值。

生成 AuthorityKeyIdentifier 的 keyIdentifier 字段时，通常从发布方证书中的 SubjectKeyIdentifier 扩展中获取该值。但是要注意，在发布方的证书上执行 X509Certificate.getExtensionValue(<SubjectKeyIdentifier Object Identifier>) 所得到的结果可能无法直接用作 setAuthorityKeyIdentifier 的输入。这是因为 SubjectKeyIdentifier 只包含一个 KeyIdentifier OCTET STRING（八位字节字符串），而不是 KeyIdentifier、GeneralNames 和 CertificateSerialNumber 的 SEQUENCE。为了使用发布方证书的 SubjectKeyIdentifier 扩展的扩展值，必需提取嵌入的 KeyIdentifier OCTET STRING 值，然后将此 OCTET STRING 以 DER 编码方式放入一个 SEQUENCE 中。有关 SubjectKeyIdentifier 的更多详细信息，请参见 setSubjectKeyIdentifier(byte[] subjectKeyID)。

还要注意，要复制此处提供的 byte 数组以防后续修改。

参数：

authorityKeyID - AuthorityKeyIdentifier（或者为 null）

另请参见：

getAuthorityKeyIdentifier()

setCertificateValid

public void setCertificateValid(Date certValid)

设置 certificateValid 标准。指定的日期必须在 X509Certificate 的证书有效期内。如果其值为 null，则不执行 certificateValid 检查。

注意，要复制此处提供的 Date 以防后续修改。

参数：

certValid - 要检查的 Date（或者为 null）

另请参见：

getCertificateValid()

setPrivateKeyValid

public void setPrivateKeyValid(Date privateKeyValid)

设置 privateKeyValid 标准。指定的日期必须在 X509Certificate 的私钥有效期内。如果为 null，则不执行 privateKeyValid 检查。

注意，要复制此处提供的 Date 以防后续修改。

参数：

privateKeyValid - 要检查的 Date（或者为 null）

另请参见：

getPrivateKeyValid()

setSubjectPublicKeyAlgID

public void setSubjectPublicKeyAlgID(String oid)
                              throws IOException

设置 subjectPublicKeyAlgID 标准。 X509Certificate 必须包含一个具有指定算法的主体公钥。如果其值为 null，则不执行 subjectPublicKeyAlgID 检查。

参数：

oid - 用于检查的算法的对象标识符 (OID)（或者为 null）。OID 由一组句点分隔的非负整数来表示。

抛出：

IOException - 如果该 OID 无效，例如其第一部分不是 0、1 或 2，或第二部分大于 39。

另请参见：

getSubjectPublicKeyAlgID()

setSubjectPublicKey

public void setSubjectPublicKey(PublicKey key)

设置 subjectPublicKey 标准。 X509Certificate 必须包含指定的主体公钥。如果其值为 null，则不执行 subjectPublicKey 检查。

参数：

key - 用于检查的 subjectPublicKey（或者为 null）

另请参见：

getSubjectPublicKey()

setSubjectPublicKey

public void setSubjectPublicKey(byte[] key)
                         throws IOException

设置 subjectPublicKey 标准。 X509Certificate 必须包含指定的主体公钥。如果其值为 null，则不执行 subjectPublicKey 检查。

因为此方法允许以 byte 数组的方式指定公钥，所以可将其用于未知的密钥类型。

如果 key 不为 null，则它应该包含单个 DER 编码形式的 SubjectPublicKeyInfo 结构，正如 X.509 中定义的一样。此结构的 ASN.1 表示如下：

 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
 

注意，要复制此处提供的 byte 数组以防后续修改。

参数：

key - 一个 byte 数组，包含 ASN.1 DER 编码形式的 subjectPublicKey（或者为 null）

抛出：

IOException - 如果出现编码错误（subjectPublicKey 形式不正确）

另请参见：

getSubjectPublicKey()

setKeyUsage

public void setKeyUsage(boolean[] keyUsage)

设置 keyUsage 标准。 X509Certificate 必须允许使用指定的 keyUsage 值。如果其值为 null，则不执行 keyUsage 检查。注意，没有 keyUsage 扩展的 X509Certificate 隐式地允许使用所有 keyUsage 值。

注意，要复制此处提供的 boolean 数组以防后续修改。

参数：

keyUsage - 一个 boolean 数组，其格式与 X509Certificate.getKeyUsage() 返回的 boolean 数组格式相同。或者为 null。

另请参见：

getKeyUsage()

setExtendedKeyUsage

public void setExtendedKeyUsage(Set<String> keyPurposeSet)
                         throws IOException

设置 extendedKeyUsage 标准。 X509Certificate 必须允许其 extendedKeyUsage 扩展中的指定 keyPurpose。如果 keyPurposeSet 为空或为 null，则不执行 extendedKeyUsage 检查。注意，没有 extendedKeyUsage 扩展的 X509Certificate 隐式地允许所有 keyPurpose。

注意，要复制该 Set 以防后续修改。

参数：

keyPurposeSet - string 格式的 keyPurpose OID 的 Set（或者为 null）。每个 OID 都由一组句点分隔的非负整数来表示。

抛出：

IOException - 如果该 OID 无效，例如其第一部分不是 0、1 或 2，或第二部分大于 39。

另请参见：

getExtendedKeyUsage()

setMatchAllSubjectAltNames

public void setMatchAllSubjectAltNames(boolean matchAllNames)

允许/禁止匹配 setSubjectAlternativeNames 或 addSubjectAlternativeName 方法中所指定的所有 subjectAlternativeNames。如果允许匹配，则 X509Certificate 必须包含所有指定的 subjectAlternativeNames。如果禁止匹配，则 X509Certificate 至少必须包含某个指定的 subjectAlternativeName。

默认情况下，matchAllNames 标志为 true。

参数：

matchAllNames - 如果为 true，则启用该标志；如果为 false，则禁用该标志。

另请参见：

getMatchAllSubjectAltNames()

setSubjectAlternativeNames

public void setSubjectAlternativeNames(Collection<List<?>> names)
                                throws IOException

设置 subjectAlternativeNames 标准。 X509Certificate 必须包含所有或至少某个指定的 subjectAlternativeNames，这取决于 matchAllNames 标志的值（参见 setMatchAllSubjectAltNames）。

此方法允许调用方（使用单个方法调用）为 subjectAlternativeNames 标准指定完整的 subjectAlternativeNames 集。指定的值会替换 subjectAlternativeNames 标准以前的值。

names 参数（如果不为 null）是一个 Collection，subjectAlternativeNames 标准中所包括的每个名称都对应该集合中的一项。每一项都是一个 List，该 List 的第一项是一个 Integer（0-8，表示名称类型），第二项是一个 String 或 byte 数组（分别为 string 或 ASN.1 DER 编码形式，表示名称）。相同类型可以有多个名称。如果为此参数提供的值为 null，则不执行 subjectAlternativeNames 检查。

Collection 中的每个 subjectAlternativeNames 都可以指定为一个 String 或 一个 ASN.1 编码的 byte 数组。有关所用格式的更多详细信息，请参阅 addSubjectAlternativeName(int type, String name) 和 addSubjectAlternativeName(int type, byte [] name)。

注：对于标识名，应指定为 byte 数组，而不是 String。有关更多信息，请参阅 addSubjectAlternativeName(int, String) 中的注视。

注意，names 参数可以包含重复的名称（相同的名称和名称类型），但是可能从 getSubjectAlternativeNames 方法返回的名称 Collection 中将这些名称移除。

注意，要对该 Collection 执行深层复制以防后续修改。

参数：

names - 一个名称 Collection（或者为 null）

抛出：

IOException - 如果出现解析错误

另请参见：

getSubjectAlternativeNames()

addSubjectAlternativeName

public void addSubjectAlternativeName(int type,
                                      String name)
                               throws IOException

向 subjectAlternativeNames 标准中添加一个名称。 X509Certificate 必须包含所有或至少某个指定的 subjectAlternativeNames，这取决于 matchAllNames 标志的值（参见 setMatchAllSubjectAltNames）。

此方法允许调用方向 subjectAlternativeNames 集中添加一个名称。将指定的名称添加到 subjectAlternativeNames 标准的以前值中。如果指定的名称是重复的，则忽略它。

以 string 格式提供该名称。RFC 822、DNS 和 URI 名称使用这些类型（受 RFC 2459 中所包括的限制的影响）的 string 格式。使用四点表示法（dotted quad notation）提供 IPv4 地址名。OID 地址名用一系列句点分隔的非负整数来表示。以 RFC 2253 格式提供目录名（标识名）。对于 otherNames、X.400 名、EDI 方的名