java.security
类 KeyStore

java.lang.Object
  java.security.KeyStore

public class KeyStore
extends Object

此类表示密钥和证书的存储设施。

KeyStore 管理不同类型的项。每种类型的项都实现 KeyStore.Entry 接口。提供了三种基本的 KeyStore.Entry 实现：

• KeyStore.PrivateKeyEntry

  此类型的项保存一个加密的 PrivateKey，可以选择以受保护格式存储该私钥来防止未授权访问。它也随附一个相应公钥的证书链。

  给定项使用私钥和证书链进行自验证 (self-authentication)。应用此验证的包括软件发布组织，它们将 JAR 文件签名为发布和/或许可软件的一部分。

• KeyStore.SecretKeyEntry

  此类型的项保存一个加密的 SecretKey，可以选择以受保护格式存储该密钥来防止未授权访问。

• KeyStore.TrustedCertificateEntry

  此类型的项包含一个属于另一方的单个公钥 Certificate。它被称为可信证书，因为 keystore 的所有者相信证书中的公钥确实属于由该证书的 subject（所有者）所标识的身份。

  此类型的项可以用来验证其他方。

keystore 中的每一项都用“别名”字符串标识。对于私钥和与它们相关的证书链，这些字符串用来区分实体验证自身可以采用的不同方式。例如，实体可以使用不同的证书授权或不同的公钥算法来验证本身。

在此没有指定 keystore 是否是持久性的，也没有指定 keystore 是持久性时所使用的机制。这允许使用各种技术保护敏感的（例如，私有的或秘密的）密钥。一种选择是使用智能卡或其他集成加密引擎 (SafeKeyper)，也可以使用诸如文件之类的更加简单的机制（以各种格式）。

请求 KeyStore 对象的典型方式包括使用默认类型和提供一个特定的 keystore 类型。

• 根据默认类型：

      KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());
   

  系统将返回默认类型的 keystore 实现。

• 提供特定的 keystore 类型：

        KeyStore ks = KeyStore.getInstance("JKS");
   

  系统将返回环境中可用的指定 keystore 类型的首选实现。

必须先加载 keystore 才能对其进行访问。

    KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());

    // get user password and file input stream
    char[] password = getPassword();
    java.io.FileInputStream fis =
        new java.io.FileInputStream("keyStoreName");
    ks.load(fis, password);
    fis.close();
 

要使用上述 load 方法创建一个空 keystore，传递 null 作为 InputStream 的参数。

一旦加载了 keystore，就能够从 keystore 读取现有项，或向 keystore 写入新项：

    // get my private key
    KeyStore.PrivateKeyEntry pkEntry = (KeyStore.PrivateKeyEntry)
        ks.getEntry("privateKeyAlias", password);
    PrivateKey myPrivateKey = pkEntry.getPrivateKey();

    // save my secret key
    javax.crypto.SecretKey mySecretKey;
    KeyStore.SecretKeyEntry skEntry =
        new KeyStore.SecretKeyEntry(mySecretKey);
    ks.setEntry("secretKeyAlias", skEntry, password);

    // store away the keystore
    java.io.FileOutputStream fos =
        new java.io.FileOutputStream("newKeyStoreName");
    ks.store(fos, password);
    fos.close();
 

注意，可以使用相同的密码加载 keystore、保护私钥项、保护秘密密钥项以及存储 keystore（如以上示例代码所示），也可以使用不同的密码或其他保护参数。

从以下版本开始：

1.2

另请参见：

PrivateKey, SecretKey, Certificate

嵌套类摘要

static class	KeyStore.Builder 将被实例化的 KeyStore 对象的描述。
static class	KeyStore.CallbackHandlerProtection 封装 CallbackHandler 的 ProtectionParameter。
static interface	KeyStore.Entry 用于 KeyStore 项类型的标记接口。
static interface	KeyStore.LoadStoreParameter 用于 KeyStore load 和 store 参数的标记接口。
static class	KeyStore.PasswordProtection ProtectionParameter 的一个基于密码的实现。
static class	KeyStore.PrivateKeyEntry 保存 PrivateKey 和相应证书链的 KeyStore 项。
static interface	KeyStore.ProtectionParameter 用于 keystore 保护参数的标记接口。
static class	KeyStore.SecretKeyEntry 保存 SecretKey 的 KeyStore 项。
static class	KeyStore.TrustedCertificateEntry 保存可信的 Certificate 的 KeyStore 项。

构造方法摘要

protected

KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type) 创建给定类型的 KeyStore 对象，并在其中封装给定的 provider 实现（SPI 对象）。

方法摘要

Enumeration<String>	aliases() 列出此 keystore 的所有别名。
boolean	containsAlias(String alias) 检查给定别名是否存在于在此 keystore 中。
void	deleteEntry(String alias) 删除由此 keystore 中给定的别名标识的项。
boolean	entryInstanceOf(String alias, Class<? extends KeyStore.Entry> entryClass) 确定指定 alias 的 keystore Entry 是否是指定 entryClass 的实例或子类。
Certificate	getCertificate(String alias) 返回与给定别名相关联的证书。
String	getCertificateAlias(Certificate cert) 返回其证书和给定证书匹配的第一个 keystore 项的别名。
Certificate[]	getCertificateChain(String alias) 返回与给定别名相关联的证书链。
Date	getCreationDate(String alias) 返回给定别名标识的项的创建日期。
static String	getDefaultType() 返回 Java 安全属性文件中指定的默认 keystore 类型，如果不存在此类属性则返回 "jks"（"Java keystore" 的首字母缩写）。
KeyStore.Entry	getEntry(String alias, KeyStore.ProtectionParameter protParam) 使用指定保护参数获取指定别名的 keystore Entry。
static KeyStore	getInstance(String type) 生成给定类型的 keystore 对象。
static KeyStore	getInstance(String type, Provider provider) 生成指定 provider 中指定 keystore 类型的 keystore 对象。
static KeyStore	getInstance(String type, String provider) 生成指定 provider 中指定 keystore 类型的 keystore 对象。
Key	getKey(String alias, char[] password) 返回与给定别名相关联的密钥，使用给定密码来恢复它。
Provider	getProvider() 返回此 keystore 的 provider。
String	getType() 返回此 keystore 的类型。
boolean	isCertificateEntry(String alias) 如果给定别名标识的项是通过调用 setCertificateEntry 或者调用使用 TrustedCertificateEntry 作为参数的 setEntry 来创建的，则返回 true。
boolean	isKeyEntry(String alias) 如果给定别名标识的项是通过调用 setKeyEntry 或者调用使用 PrivateKeyEntry 或 SecretKeyEntry 作为参数的 setEntry 创建的，则返回 true。
void	load(InputStream stream, char[] password) 从指定的输入流中加载此 KeyStore。
void	load(KeyStore.LoadStoreParameter param) 使用给定的 LoadStoreParameter 加载此 keystore。
void	setCertificateEntry(String alias, Certificate cert) 将给定可信证书分配给给定别名。
void	setEntry(String alias, KeyStore.Entry entry, KeyStore.ProtectionParameter protParam) 用指定别名保存 keystore Entry。
void	setKeyEntry(String alias, byte[] key, Certificate[] chain) 将给定密钥（已经被保护）分配给给定别名。
void	setKeyEntry(String alias, Key key, char[] password, Certificate[] chain) 将给定的密钥分配给给定的别名，用给定的密码保护它。
int	size() 检索此 keystore 中项的数目。
void	store(KeyStore.LoadStoreParameter param) 使用给定的 LoadStoreParameter 存储此 keystore。
void	store(OutputStream stream, char[] password) 将此 keystore 存储到给定输出流中，并用给定的密码保护其完整性。

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

KeyStore

protected KeyStore(KeyStoreSpi keyStoreSpi,
                   Provider provider,
                   String type)

创建给定类型的 KeyStore 对象，并在其中封装给定的 provider 实现（SPI 对象）。

参数：

keyStoreSpi - provider 实现

provider - provider

type - keystore 类型。

方法详细信息

getInstance

public static KeyStore getInstance(String type)
                            throws KeyStoreException

生成给定类型的 keystore 对象。

如果默认的 provider 包提供了给定类型的 keystore 实现，则返回包含该实现的 KeyStore 实例。如果默认包中不存在请求的 keystore 类型，则搜索其他的包。

参数：

type - keystore 的类型。有关标准 keystore 类型的信息，请参阅 Java Cryptography Architecture API Specification & Reference 中的附录 A。

返回：

指定类型的 keystore 对象。

抛出：

KeyStoreException - 如果默认 provider 包或任何其他搜索过的 provider 包中不存在请求的 keystore 类型。

getInstance

public static KeyStore getInstance(String type,
                                   String provider)
                            throws KeyStoreException,
                                   NoSuchProviderException

生成指定 provider 中指定 keystore 类型的 keystore 对象。

参数：

type - keystore 的类型。有关标准 keystore 类型的信息，请参阅 Java Cryptography Architecture API Specification & Reference 中的附录 A。

provider - provider 的名称。

返回：

指定类型的 keystore 对象，类型由指定的 provider 提供。

抛出：

KeyStoreException - 如果请求的 keystore 类型不能从 provider 中得到。

NoSuchProviderException - 如果尚未配置 provider。

IllegalArgumentException - 如果 provider 的名称为 null 或空。

另请参见：

Provider

getInstance

public static KeyStore getInstance(String type,
                                   Provider provider)
                            throws KeyStoreException

生成指定 provider 中指定 keystore 类型的 keystore 对象。注：不必注册 provider。

参数：

type - keystore 的类型。有关标准 keystore 类型的信息，请参阅 Java Cryptography Architecture API Specification & Reference 中的附录 A。

provider - provider。

返回：

指定类型的 keystore 对象，类型由指定的 provider 提供。

抛出：

KeyStoreException - 如果请求的 keystore 类型不能从 provider 中得到。

IllegalArgumentException - 如果 provider 为 null。

从以下版本开始：

1.4

另请参见：

Provider

getDefaultType

public static final String getDefaultType()

返回 Java 安全属性文件中指定的默认 keystore 类型，如果不存在此类属性则返回 "jks"（"Java keystore" 的首字母缩写）。Java 安全属性文件位于名为 <JAVA_HOME>/lib/security/java.security 的文件中，其中 <JAVA_HOME> 指的是安装 JDK 的目录。

对于调用某个 getInstance 方法时不想使用硬编码 keystore 类型，以及在用户未指定所用 keystore 类型的情况下希望提供默认 keystore 类型的应用程序而言，可以使用默认的 keystore 类型。

通过将 "keystore.type" 安全属性（在 Java 安全属性文件中）的值设置为所需的 keystore 类型可以更改默认的 keystore 类型。

返回：

Java 安全属性文件中指定的默认 keystore 类型，如果不存在此类属性，则返回字符串 "jks"。

getProvider

public final Provider getProvider()

返回此 keystore 的 provider。

返回：

此 keystore 的 provider。

getType

public final String getType()

返回此 keystore 的类型。

返回：

此 keystore 的类型。

getKey

public final Key getKey(String alias,
                        char[] password)
                 throws KeyStoreException,
                        NoSuchAlgorithmException,
                        UnrecoverableKeyException

返回与给定别名相关联的密钥，使用给定密码来恢复它。必须已经通过调用 setKeyEntry 或者调用使用 PrivateKeyEntry 或 SecretKeyEntry 作为参数的 setEntry 将密钥与别名建立了关联。

参数：

alias - 别名

password - 恢复密钥所用的密码

返回：

请求的密钥，如果给定别名不存在或不标识与密钥相关的项，则返回 null。

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

NoSuchAlgorithmException - 如果不能找到恢复密钥的算法

UnrecoverableKeyException - 如果不能恢复密钥（例如，给定的密码错误）。

getCertificateChain

public final Certificate[] getCertificateChain(String alias)
                                        throws KeyStoreException

返回与给定别名相关联的证书链。必须已经通过调用 setKeyEntry，或者调用使用 PrivateKeyEntry 做参数的 setEntry 将证书链与别名建立了关联。

参数：

alias - 别名

返回：

证书链（按用户证书在前根证书授权中心在后的顺序），如果给定别名不存在或不包含证书链，则返回 null

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

getCertificate

public final Certificate getCertificate(String alias)
                                 throws KeyStoreException

返回与给定别名相关联的证书。

如果给定的别名标识通过调用 setCertificateEntry 创建的项，或标识通过调用使用 TrustedCertificateEntry 参数的 setEntry 创建的项，则返回包含在该项中的可信证书。

如果给定的别名标识通过调用 setKeyEntry 创建的项，或标识通过调用使用 PrivateKeyEntry 作为参数的 setEntry 创建的项，则返回该证书链中的第一个元素。

参数：

alias - 别名

返回：

证书，如果给定别名不存在或不包含证书，则返回 null。

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

getCreationDate

public final Date getCreationDate(String alias)
                           throws KeyStoreException

返回给定别名标识的项的创建日期。

参数：

alias - 别名

返回：

此项的创建日期，如果给定的别名不存在，则返回 null

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

setKeyEntry

public final void setKeyEntry(String alias,
                              Key key,
                              char[] password,
                              Certificate[] chain)
                       throws KeyStoreException

将给定的密钥分配给给定的别名，用给定的密码保护它。

如果给定密钥的类型为 java.security.PrivateKey 类型，则它必须附带证明相应公钥的证书链。

如果给定的别名已经存在，则与别名关联的 keystore 信息将被给定的密钥（还可能包括证书链）重写。

参数：

alias - 别名

key - 要与别名关联的密钥

password - 保护密钥的密码

chain - 相应公钥的证书链（只在给定密钥的类型为 java.security.PrivateKey 时需要）。

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）、给定的密钥不能被保护、或者此操作由于某些其他原因而失败

setKeyEntry

public final void setKeyEntry(String alias,
                              byte[] key,
                              Certificate[] chain)
                       throws KeyStoreException

将给定密钥（已经被保护）分配给给定别名。

如果被保护密钥的类型为 java.security.PrivateKey，则它必须附带证明相应公钥的证书链。如果底层 keystore 实现的类型为 jks，则必须按 PKCS #8 标准中的定义将 key 编码为 EncryptedPrivateKeyInfo。

如果给定的别名已经存在，则与别名关联的 keystore 信息将被给定的密钥（还可能包括证书链）重写。

参数：

alias - 别名

key - 要与别名关联的密钥（以受保护格式）

chain - 相应公钥的证书链（只在受保护密钥的类型为 java.security.PrivateKey 时有用）。

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载），或者此操作由于某些其他原因而失败。

setCertificateEntry

public final void setCertificateEntry(String alias,
                                      Certificate cert)
                               throws KeyStoreException

将给定可信证书分配给给定别名。

如果给定的别名标识通过调用 setCertificateEntry 创建的现有项，或者标识通过调用使用 TrustedCertificateEntry 作为参数的 setEntry 创建的现有项，则现有项中的可信证书被给定证书重写。

参数：

alias - 别名

cert - 证书

抛出：

KeyStoreException - 如果 keystore 尚未被初始化，或者给定别名已存在但不标识任何包含可信证书的项，或者此操作由于其他某些原因失败。

deleteEntry

public final void deleteEntry(String alias)
                       throws KeyStoreException

删除由此 keystore 中给定的别名标识的项。

参数：

alias - 别名

抛出：

KeyStoreException - 如果 keystore 尚未被初始化，或者项不能被移除。

aliases

public final Enumeration<String> aliases()
                                  throws KeyStoreException

列出此 keystore 的所有别名。

返回：

别名的枚举

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

containsAlias

public final boolean containsAlias(String alias)
                            throws KeyStoreException

检查给定别名是否存在于在此 keystore 中。

参数：

alias - 别名

返回：

如果别名存在，则返回 true；否则，返回 false

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

size

public final int size()
               throws KeyStoreException

检索此 keystore 中项的数目。

返回：

此 keystore 中的项的数目

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

isKeyEntry

public final boolean isKeyEntry(String alias)
                         throws KeyStoreException

如果给定别名标识的项是通过调用 setKeyEntry 或者调用使用 PrivateKeyEntry 或 SecretKeyEntry 作为参数的 setEntry 创建的，则返回 true。

参数：

alias - 要检查的 keystore 项的别名

返回：

如果给定别名标识的项是与密钥相关的项，则返回 true；否则返回 false。

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

isCertificateEntry

public final boolean isCertificateEntry(String alias)
                                 throws KeyStoreException

如果给定别名标识的项是通过调用 setCertificateEntry 或者调用使用 TrustedCertificateEntry 作为参数的 setEntry 来创建的，则返回 true。

参数：

alias - 要检查的 keystore 项的别名

返回：

如果给定别名标识的项包含一个可信证书，则返回 true；否则，返回 false。

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

getCertificateAlias

public final String getCertificateAlias(Certificate cert)
                                 throws KeyStoreException

返回其证书和给定证书匹配的第一个 keystore 项的别名。

此方法试图将给定证书与每一个 keystore 项相匹配。如果将被考虑的项是通过调用 setCertificateEntry 或者调用使用 TrustedCertificateEntry 作为参数的 setEntry 创建的，则将给定证书与该项的证书进行比较。

如果将被考虑的项是通过调用 setKeyEntry 或者调用使用 PrivateKeyEntry 作为参数的 setEntry 创建的，则将给定证书与该项证书链的第一个元素进行比较。

参数：

cert - 要匹配的证书

返回：

带有匹配证书的第一个项的别名；如果在此 keystore 中没有此类项存在，则返回 null。

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

store

public final void store(OutputStream stream,
                        char[] password)
                 throws KeyStoreException,
                        IOException,
                        NoSuchAlgorithmException,
                        CertificateException

将此 keystore 存储到给定输出流中，并用给定的密码保护其完整性。

参数：

stream - 此 keystore 要被写入的输出流。

password - 生成 keystore 完整性检验的密码

抛出：

KeyStoreException - 如果 keystore 尚未被初始化（加载）。

IOException - 如果存在数据的 I/O 问题

NoSuchAlgorithmException - 如果不能找到恰当的数据完整性算法

CertificateException - 如果 keystore 数据中存在不能被存储的证书

store

public final void store(KeyStore.LoadStoreParameter param)
                 throws KeyStoreException,
                        IOException,
                        NoSuchAlgorithmException,
                        CertificateException

使用给定的 LoadStoreParameter 存储此 keystore。

参数：

param - 指定如何存储 keystore 的 LoadStoreParameter，可以为 null

抛出：

IllegalArgumentException - 如果给定的 LoadStoreParameter 输入无法识别

KeyStoreException - 如果 keystore 尚未被初始化（加载）

IOException - 如果存在数据的 I/O 问题

NoSuchAlgorithmException - 如果不能找到恰当的数据完整性算法

CertificateException - 如果 keystore 数据中存在不能被存储的证书

从以下版本开始：

1.5

load

public final void load(InputStream stream,
                       char[] password)
                throws IOException,
                       NoSuchAlgorithmException,
                       CertificateException

从指定的输入流中加载此 KeyStore。

可以指定一个密码来解锁 keystore（例如驻留在硬件标记设备上的 keystore ）或检验 keystore 数据的完整性。如果没有指定用于完整性检验的密码，则不会执行完整性检验。

如果要创建空 keystore，或者不能从流中初始化 keystore，则传递 null 作为 stream 的参数。

注意，如果此 keystore 已经被加载，则它将再次从给定输出流中被初始化和加载。

参数：

stream - 从其加载 keystore 的输入流，或 null

password - 用来检验 keystore 完整性的密码，用来解锁 keystore 的密码，或 null

抛出：

IOException - 如果存在 keystore 数据的 I/O 或格式问题，如果需要密码却没有指定，或者指定的密码错误

NoSuchAlgorithmException - 如果不能找到用来检验 keystore 完整性的算法

CertificateException - 如果不能加载 keystore 中的任何证书

load

public final void load(KeyStore.LoadStoreParameter param)
                throws IOException,
                       NoSuchAlgorithmException,
                       CertificateException

使用给定的 LoadStoreParameter 加载此 keystore。

注意，如果此 KeyStore 已经被加载，则它将再次从给定参数中被初始化和加载。

参数：

param - 指定如何加载 keystore 的 LoadStoreParameter，可以为 null

抛出：

IllegalArgumentException - 如果给定的 LoadStoreParameter 输入无法识别

IOException - 如果存在 keystore 数据的 I/O 或格式问题

NoSuchAlgorithmException - 如果不能找到用来检验 keystore 完整性的算法

CertificateException - 如果不能加载 keystore 中的任何证书

从以下版本开始：

1.5

getEntry

public final KeyStore.Entry getEntry(String alias,
                                     KeyStore.ProtectionParameter protParam)
                              throws NoSuchAlgorithmException,
                                     UnrecoverableEntryException,
                                     KeyStoreException

使用指定保护参数获取指定别名的 keystore Entry。

参数：

alias - 获取此别名的 keystore Entry

protParam - 用来保护 Entry 的 ProtectionParameter，可以为 null

返回：

指定别名的 keystore Entry，如果不存在这样的项则返回 null

抛出：

NullPointerException - 如果 alias 为 null

NoSuchAlgorithmException - 如果不能找到用来恢复项的算法

UnrecoverableEntryException - 如果指定的 protParam 不足或无效

KeyStoreException - 如果 keystore 尚未被初始化（加载）

从以下版本开始：

1.5

另请参见：

setEntry(String, KeyStore.Entry, KeyStore.ProtectionParameter)

setEntry

public final void setEntry(String alias,
                           KeyStore.Entry entry,
                           KeyStore.ProtectionParameter protParam)
                    throws KeyStoreException

用指定别名保存 keystore Entry。保护参数用来保护 Entry。

如果指定别名的项已经存在，它将被重写。

参数：

alias - 以此别名保存 keystore Entry

entry - 要保存的 Entry

protParam - 用来保护 Entry 的 ProtectionParameter，可以为 null

抛出：

NullPointerException - 如果 alias 或 entry 为 null

KeyStoreException - 如果 keystore 尚未被初始化（加载），或者此操作由于其他原因失败

从以下版本开始：

1.5

另请参见：

getEntry(String, KeyStore.ProtectionParameter)

entryInstanceOf

public final boolean entryInstanceOf(String alias,
                                     Class<? extends KeyStore.Entry> entryClass)
                              throws KeyStoreException

确定指定 alias 的 keystore Entry 是否是指定 entryClass 的实例或子类。

参数：

alias - 别名

entryClass - 项的类

返回：

true 如果指定 alias 的 keystore Entry 是指定 entryClass 的实例或子类，则返回 true；否则返回 false。

抛出：

NullPointerException - 如果 alias 或 entryClass 为 null

KeyStoreException - 如果 keystore 尚未被初始化（加载）

从以下版本开始：

1.5