模块  java.base
软件包  java.security

Class KeyStore

  • public class KeyStore
extends Object
    此类表示加密密钥和证书的存储工具。

    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
        返回指定类型的keystore对象。

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

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

        Implementation Note:
        JDK Reference Implementation还使用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安全属性指定的默认密钥库类型，或字符串“jks”（“Java密钥库”的首字母缩写词）。

        默认密钥库类型可以由不希望在调用其中一个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时才需要）。
        异常
        KeyStoreException - 如果密钥库尚未初始化（加载），则无法保护给定密钥，或者此操作因某些其他原因而失败

      • setKeyEntry

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

        如果受保护密钥的类型为java.security.PrivateKey ，则必须附带证明相应公钥的证书链。 如果基础密钥库实现的类型为jks ， key必须将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 - 如果无法加载密钥库中的任何证书

      • entryInstanceOf

        public final boolean entryInstanceOf​(String alias,
                                     类<? extends KeyStore.Entry> entryClass)
                              throws KeyStoreException
        确定密钥库 Entry为指定 alias是指定的一个实例或亚类 entryClass 。
        参数
        alias - 别名
        entryClass - 入门级
        结果
        如果指定的 alias的密钥库 Entry是指定的 alias的实例或子类，则 entryClass true，否则 entryClass 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 - 如果没有Provider支持指定密钥库文件的KeyStoreSpi实现。
        IOException - 如果密钥库数据存在I / O或格式问题，如果需要密码但未给出密码，或者给定的密码不正确。 如果错误是由于密码错误引起的， IOException的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
        返回相应密钥库类型的已加载密钥库对象。 首先，通过探测指定的文件来确定密钥库类型。 然后使用该文件中的数据实例化并加载密钥库对象。 可以提供LoadStoreParameter ，其指定如何解锁密钥库数据或执行完整性检查。

        此方法遍历已注册安全性列表providers ，从最喜欢的Provider开始。 对于Provider支持的每个KeyStoreSpi实现，它调用engineProbe方法以确定它是否支持指定的密钥库。 返回一个新的KeyStore对象，该对象封装了第一个支持指定文件的Provider的KeyStoreSpi实现。

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

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