Module  java.base
软件包  java.security

Class KeyStore


  • public class KeyStore
extends Object
    该类代表加密密钥和证书的存储设备。

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

    • KeyStore.PrivateKeyEntry

      这种类型的条目保存加密PrivateKey ，其可选地以受保护的格式存储以防止未经授权的访问。 还附有相应公钥的证书链。

      私钥和证书链由给定实体用于自身认证。 用于此认证的应用程序包括在发布和/或许可软件时签署JAR文件的软件分发机构。

    • KeyStore.SecretKeyEntry

      这种类型的条目保存加密SecretKey ，其可选地以受保护的格式存储以防止未经授权的访问。

    • KeyStore.TrustedCertificateEntry

      这种类型的条目包含属于另一方的单个公钥Certificate 。 它被称为可信证书，因为密钥库所有者信任证书中的公钥确实属于由证书的主体 （所有者）标识的身份。

      这种类型的条目可用于验证其他方。

    密钥库中的每个条目都由“别名”字符串标识。 在私钥及其关联的证书链的情况下，这些字符串区分实体可以自己认证的不同方式。 例如，实体可以使用不同的证书颁发机构或使用不同的公钥算法对其进行身份验证。

    别名区分大小写是否依赖于实现。 为了避免出现问题，建议不要在KeyStore中使用只有不同的别名。

    密钥库是否是持久的，如果密钥库是持久的，则使用密钥库的机制，这里没有指定。 这允许使用各种技术来保护敏感（例如，私人或秘密）密钥。 智能卡或其他集成的加密引擎（SafeKeyper）是一种选择，也可以使用诸如文件的更简单的机制（以各种格式）。

    请求KeyStore对象的典型方法包括指定现有密钥库文件，依赖于默认类型并提供特定的密钥库类型。

    • 指定现有密钥库文件： 
        // get keystore password
    char[] password = getPassword();

    // probe the keystore file and load the keystore entries
    KeyStore ks = KeyStore.getInstance(new File("keyStoreName"), password);
      系统将探测指定的文件以确定其密钥库类型，并返回其加载条目的密钥库实现。 当使用这种方法时，不需要调用密钥库的load方法。
    • 要依靠默认类型： 
        KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());
      系统将返回默认类型的密钥库实现。
    • 提供特定的密钥库类型： 
        KeyStore ks = KeyStore.getInstance("JKS");
      系统将返回在环境中可用的指定密钥库类型的最优选实现。

    在可以访问密钥库之前，它必须是loaded （除非在实例化期间已经加载）。 

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

    // get user password and file input stream
    char[] password = getPassword();

    try (FileInputStream fis = new FileInputStream("keyStoreName")) {
        ks.load(fis, password);
    }
    要使用上述load方法创建一个空密钥库，请通过null作为InputStream参数。

    一旦加载了密钥库，就可以从密钥库中读取现有条目，或者将新条目写入密钥库中： 

      KeyStore.ProtectionParameter protParam =
        new KeyStore.PasswordProtection(password);

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

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

    // store away the keystore
    try (FileOutputStream fos = new FileOutputStream("newKeyStoreName")) {
        ks.store(fos, password);
    }
    请注意，虽然可以使用相同的密码来加载密钥库，以保护私钥条目，保护密钥条目，并存储密钥库（如上面的示例代码所示），不同的密码或其他保护参数也可以使用。

    Java平台的每个实现都需要支持以下标准KeyStore类型：

    • PKCS12
    这种类型在Java安全标准算法名称规范的KeyStore section中进行了描述。 请参阅发行说明文件以了解是否支持其他类型。
    从以下版本开始：
    1.2
    另请参见：
    PrivateKey ， SecretKey ， Certificate

    • 构造方法详细信息

      • KeyStore

        protected KeyStore​(KeyStoreSpi keyStoreSpi,
                   Provider provider,
                   String type)
        创建给定类型的KeyStore对象，并封装给定的提供者实现（SPI对象）。
        参数
        keyStoreSpi - 提供者实现。
        provider - 提供商。
        type - 密钥库类型。

    • 方法详细信息

      • getInstance

        public static KeyStore getInstance​(String type)
                            throws KeyStoreException
        返回指定类型的密钥库对象。

        此方法遍历已注册的安全提供程序列表，从最优选的提供程序开始。 返回从支持指定类型的第一个Provider中封装KeyStoreSpi实现的新KeyStore对象。

        请注意，注册提供商的列表可以通过Security.getProviders()方法检索。

        Implementation Note:
        JDK参考实现另外使用jdk.security.provider.preferred Security属性来确定指定算法的首选提供者顺序。 这可能与Security.getProviders()返回的提供商的顺序不同。
        参数
        type - 密钥库的类型。 有关标准密钥库类型的信息，请参阅Java Security Standard Algorithm Names Specification中的KeyStore部分。
        结果
        指定类型的密钥库对象
        异常
        KeyStoreException - 如果否 Provider支持指定类型的 KeyStoreSpi实现
        NullPointerException - 如果 type是 null
        另请参见：
        Provider

      • getDefaultType

        public static final String getDefaultType​()
        返回由keystore.type security属性指定的默认密钥库类型，或者如果没有这样的属性，则返回字符串“jks”（“Java keystore”的缩写）。

        默认密钥库类型可以由不想使用硬编码密钥库类型的应用程序使用，当调用其中一个getInstance方法时，如果用户未指定自己的密钥库类型，则希望提供默认的密钥库类型。

        通过将keystore.type安全属性的值设置为所需的密钥库类型，可以更改默认密钥库类型。

        结果
        由 keystore.type安全属性指定的默认密钥仓库类型，如果没有此类属性，则为字符串“jks”。
        另请参见：
        security properties

      • getProvider

        public final Provider getProvider​()
        返回此密钥库的提供者。
        结果
        这个密钥库的提供者。

      • getType

        public final String getType​()
        返回此密钥库的类型。
        结果
        这个密钥库的类型。

      • getKey

        public final Key getKey​(String alias,
                        char[] password)
                 throws KeyStoreException,
                        NoSuchAlgorithmException,
                        UnrecoverableKeyException
        返回与给定别名相关联的密钥，使用给定的密码恢复它。 密钥必须已经通过调用别名关联到setKeyEntry ，或者通过将呼叫setEntry与PrivateKeyEntry或者SecretKeyEntry 。
        参数
        alias - 别名
        password - 恢复密钥的密码
        结果
        请求的密钥，如果给定的别名不存在或不标识与密钥相关的条目，则为null。
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载）。
        NoSuchAlgorithmException - 如果无法找到恢复密钥的算法
        UnrecoverableKeyException - 如果密钥无法恢复（例如，给定的密码错误）。

      • getCertificateChain

        public final Certificate[] getCertificateChain​(String alias)
                                        throws KeyStoreException
        返回与给定别名关联的证书链。 证书链必须已经通过调用setKeyEntry与别名相关联，或通过调用setEntry与PrivateKeyEntry 。
        参数
        alias - 别名
        结果
        证书链（以用户的证书首先跟随着零个或多个证书颁发机构排序），如果给定的别名不存在或不包含证书链，则为null
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载）。

      • getCertificate

        public final Certificate getCertificate​(String alias)
                                 throws KeyStoreException
        返回与给定别名相关联的证书。

        如果给定的别名标识了通过调用setCertificateEntry创建的条目，或通过调用setEntry与TrustedCertificateEntry创建的条目，则返回该条目中包含的受信任证书。

        如果给定的别名标识由setKeyEntry的调用创建的条目，或通过调用setEntry与PrivateKeyEntry创建的条目，则返回该条目中证书链的第一个元素。

        参数
        alias - 别名
        结果
        证书，如果给定的别名不存在或不包含证书，则为null。
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载）。

      • getCreationDate

        public final Date getCreationDate​(String alias)
                           throws KeyStoreException
        返回由给定别名标识的条目的创建日期。
        参数
        alias - 别名
        结果
        此条目的创建日期，如果给定的别名不存在，则为null
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载）。

      • setKeyEntry

        public final void setKeyEntry​(String alias,
                              Key key,
                              char[] password,
                              Certificate[] chain)
                       throws KeyStoreException
        将给定的密钥分配给给定的别名，并使用给定的密码进行保护。

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

        如果给定的别名已经存在，与它相关联的密钥库信息将被给定的密钥（也可能是证书链）覆盖。

        参数
        alias - 别名
        key - 与别名关联的关键
        password - 密码保护密钥
        chain - 相应公钥的证书链（仅当给定键为 java.security.PrivateKey类型 java.security.PrivateKey ）。
        异常
        KeyStoreException - 如果密钥存储库尚未初始化（加载），则给定的密钥不能被保护，或者由于其他原因导致该操作失败

      • setKeyEntry

        public final void setKeyEntry​(String alias,
                              byte[] key,
                              Certificate[] chain)
                       throws KeyStoreException
        将给定的密钥（已经被保护）分配给给定的别名。

        如果受保护的密钥是java.security.PrivateKey型，则必须附有一个证书链，证明相应的公钥。 如果基础密钥库实现类型为jks ，则key必须编码为PKCS＃8标准中定义的EncryptedPrivateKeyInfo 。

        如果给定的别名已经存在，与它相关联的密钥库信息将被给定的密钥（也可能是证书链）覆盖。

        参数
        alias - 别名
        key - 与别名关联的密钥（以受保护的格式）
        chain - 相应公钥的证书链（仅当受保护的密钥为 java.security.PrivateKey类型时才有用）。
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载），或者由于其他原因导致此操作失败。

      • setCertificateEntry

        public final void setCertificateEntry​(String alias,
                                      Certificate cert)
                               throws KeyStoreException
        将给定的可信证书分配给给定的别名。

        如果给定的别名标识通过调用创建现有条目setCertificateEntry ，或者创建通过调用setEntry与TrustedCertificateEntry ，在现有条目中的可信证书被给定证书重写。

        参数
        alias - 别名
        cert - 证书
        异常
        KeyStoreException - 如果密钥库尚未初始化，或者给定的别名已经存在，并且不标识包含受信任证书的条目，否则此操作由于某些其他原因而失败。

      • deleteEntry

        public final void deleteEntry​(String alias)
                       throws KeyStoreException
        从此密钥库中删除由给定别名标识的条目。
        参数
        alias - 别名
        异常
        KeyStoreException - 如果密钥库尚未初始化，或者条目无法删除。

      • containsAlias

        public final boolean containsAlias​(String alias)
                            throws KeyStoreException
        检查此密钥库中是否存在给定的别名。
        参数
        alias - 别名
        结果
        如果别名存在则为true，否则为false
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载）。

      • size

        public final int size​()
               throws KeyStoreException
        检索此密钥库中的条目数。
        结果
        此密钥库中的条目数
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载）。

      • isKeyEntry

        public final boolean isKeyEntry​(String alias)
                         throws KeyStoreException
        如果由给定别名标识的条目是通过调用 setKeyEntry创建的，或通过调用 setEntry与 PrivateKeyEntry或 SecretKeyEntry创建的条目，则返回true。
        参数
        alias - 要检查的密钥库条目的别名
        结果
        如果给定别名标识的条目是与密钥相关的条目，则为true，否则为false。
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载）。

      • isCertificateEntry

        public final boolean isCertificateEntry​(String alias)
                                 throws KeyStoreException
        如果给定别名标识的条目是通过调用 setCertificateEntry创建的，或者通过调用 setEntry与 TrustedCertificateEntry创建的条目，则返回true。
        参数
        alias - 要检查密钥库条目的别名
        结果
        如果给定别名标识的条目包含受信任的证书，则为true，否则为false。
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载）。

      • getCertificateAlias

        public final String getCertificateAlias​(Certificate cert)
                                 throws KeyStoreException
        返回其证书与给定证书匹配的第一个密钥库条目的（别名）名称。

        此方法尝试将给定证书与每个密钥库条目相匹配。 如果考虑的条目是通过调用setCertificateEntry创建的，或者通过调用setEntry与TrustedCertificateEntry ，则将给定的证书与该条目的证书进行比较。

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

        参数
        cert - 证书匹配。
        结果
        具有匹配证书的第一个条目的别名，如果此密钥库中没有此类条目，则为null。
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载）。

      • load

        public final void load​(InputStream stream,
                       char[] password)
                throws IOException,
                       NoSuchAlgorithmException,
                       CertificateException
        从给定的输入流加载此KeyStore。

        可以提供密码来解锁密钥库（例如，密钥库驻留在硬件令牌设备上），或者检查密钥库数据的完整性。 如果没有为完整性检查提供密码，则不执行完整性检查。

        为了创建一个空的密钥库，或者如果密钥库不能从流初始化，请传递null作为stream参数。

        请注意，如果此密钥库已经加载，则会从给定的输入流重新初始化并加载该密钥库。

        参数
        stream - 加载密钥库的输入流，或 null
        password - 用于检查密钥库完整性的密码，用于解锁密钥仓库的密码，或 null
        异常
        IOException - 如果密钥库数据存在I / O或格式问题，如果需要密码但未提供密码，或者给定的密码不正确。 如果错误是由于错误的密码， IOException的IOException应该是一个UnrecoverableKeyException
        NoSuchAlgorithmException - 如果用于检查密钥库完整性的算法无法找到
        CertificateException - 如果密钥库中的任何证书无法加载

      • load

        public final void load​(KeyStore.LoadStoreParameter param)
                throws IOException,
                       NoSuchAlgorithmException,
                       CertificateException
        使用给定的LoadStoreParameter加载此密钥库。

        请注意，如果此KeyStore已经加载，它将从给定的参数重新初始化并重新加载。

        参数
        param -所述 LoadStoreParameter指定如何加载密钥库，其可以是 null
        异常
        IllegalArgumentException - 如果给定的 LoadStoreParameter输入未被识别
        IOException - 如果存在密钥库数据的I / O或格式问题。 如果错误是由于不正确的ProtectionParameter （如密码错误）的cause的的IOException应该是UnrecoverableKeyException
        NoSuchAlgorithmException - 如果用于检查密钥库的完整性的算法无法找到
        CertificateException - 如果密钥库中的任何证书无法加载
        从以下版本开始：
        1.5

      • entryInstanceOf

        public final boolean entryInstanceOf​(String alias,
                                     Class<? extends KeyStore.Entry> entryClass)
                              throws KeyStoreException
        确定密钥库 Entry为指定 alias是指定的一个实例或亚类 entryClass 。
        参数
        alias - 别名
        entryClass - 入门课
        结果
        如果指定的 alias的密钥库 Entry是指定的 alias的实例或子类， entryClass true，否则为false
        异常
        NullPointerException - 如果 alias或 entryClass是 null
        KeyStoreException - 如果密钥库尚未初始化（加载）
        从以下版本开始：
        1.5

      • getInstance

        public static final KeyStore getInstance​(File file,
                                         char[] password)
                                  throws KeyStoreException,
                                         IOException,
                                         NoSuchAlgorithmException,
                                         CertificateException
        返回相应密钥库类型的加载密钥库对象。 首先，通过探测指定的文件确定密钥库类型。 然后使用该文件中的数据实例化和加载密钥库对象。

        可以提供密码来解锁密钥库（例如，密钥库驻留在硬件令牌设备上），或者检查密钥库数据的完整性。 如果没有为完整性检查提供密码，则不执行完整性检查。

        此方法遍历已注册的安全性列表providers ，从最优选的提供程序开始。 对于由Provider提供的每个KeyStoreSpi实现，它将调用engineProbe方法来确定它是否支持指定的密钥库。 返回一个新的KeyStore对象，它从支持指定文件的第一个Provider中封装KeyStoreSpi实现。

        注意，可以通过Security.getProviders()方法检索注册提供商的列表。

        参数
        file - 密钥库文件
        password - 密钥库密码，可能是 null
        结果
        加载了密钥库数据的密钥库对象
        异常
        KeyStoreException - 如果没有提供者支持指定密钥库文件的KeyStoreSpi实现。
        IOException - 如果密钥库数据存在I / O或格式问题，如果需要密码但未提供密码，或者给定的密码不正确。 如果错误是由于错误的密码， cause的IOException应为UnrecoverableKeyException 。
        NoSuchAlgorithmException - 如果用于检查密钥库的完整性的算法无法找到。
        CertificateException - 如果密钥库中的任何证书无法加载。
        IllegalArgumentException - 如果文件不存在或不引用正常文件。
        NullPointerException - 如果文件是 null 。
        SecurityException - 如果安全管理器存在，并且其 SecurityManager.checkRead(java.io.FileDescriptor)方法拒绝对指定文件的读取访问。
        从以下版本开始：
        9
        另请参见：
        Provider

      • getInstance

        public static final KeyStore getInstance​(File file,
                                         KeyStore.LoadStoreParameter param)
                                  throws KeyStoreException,
                                         IOException,
                                         NoSuchAlgorithmException,
                                         CertificateException
        返回相应密钥库类型的加载密钥库对象。 首先，通过探测指定的文件确定密钥库类型。 然后使用该文件中的数据实例化和加载密钥库对象。 可以提供A LoadStoreParameter ，其指定如何解锁密钥仓库数据或执行完整性检查。

        该方法从最优先的提供程序开始，遍历注册安全性列表providers 。 对于由Provider提供的每个KeyStoreSpi实现，它将调用engineProbe方法来确定它是否支持指定的密钥库。 返回一个新的KeyStore对象，它从支持指定文件的第一个Provider中封装KeyStoreSpi实现。

        请注意，可以通过Security.getProviders()方法检索注册提供商的列表。

        参数
        file - 密钥库文件
        param -所述 LoadStoreParameter指定如何加载密钥库，其可以是 null
        结果
        加载了密钥库数据的密钥库对象
        异常
        KeyStoreException - 如果没有提供程序支持指定密钥库文件的KeyStoreSpi实现。
        IOException - 如果存在密钥库数据的I / O或格式问题。 如果错误是由于ProtectionParameter （例如错误的密码） 造成的， IOException应为UnrecoverableKeyException 。
        NoSuchAlgorithmException - 如果用于检查密钥库的完整性的算法无法找到。
        CertificateException - 如果密钥库中的任何证书无法加载。
        IllegalArgumentException - 如果文件不存在或不引用正常文件，或者如果无法识别参数。
        NullPointerException - 如果文件是 null 。
        SecurityException - 如果存在安全管理员，并且其 SecurityManager.checkRead(java.io.FileDescriptor)方法拒绝对指定文件的读取访问。
        从以下版本开始：
        9
        另请参见：
        Provider