public class KeyStore extends Object
A KeyStore
管理不同类型的条目。 每种类型的条目实现了KeyStore.Entry
接口。 提供了三个基本的KeyStore.Entry
实现:
这种类型的条目保存加密PrivateKey
,其可选地以受保护的格式存储以防止未经授权的访问。 还附有相应公钥的证书链。
私钥和证书链由给定实体用于自身认证。 用于此认证的应用程序包括在发布和/或许可软件时签署JAR文件的软件分发机构。
这种类型的条目保存加密SecretKey
,其可选地以受保护的格式存储以防止未经授权的访问。
这种类型的条目包含属于另一方的单个公钥Certificate
。 它被称为可信证书 ,因为密钥库所有者信任证书中的公钥确实属于由证书的主体 (所有者)标识的身份。
这种类型的条目可用于验证其他方。
密钥库中的每个条目都由“别名”字符串标识。 在私钥及其关联的证书链的情况下,这些字符串区分实体可以自己认证的不同方式。 例如,实体可以使用不同的证书颁发机构或使用不同的公钥算法对其进行身份验证。
别名区分大小写是否依赖于实现。 为了避免出现问题,建议不要在KeyStore中使用只有不同的别名。
密钥库是否是持久的,如果密钥库是持久的,则使用密钥库的机制,这里没有指定。 这允许使用各种技术来保护敏感(例如,私人或秘密)密钥。 智能卡或其他集成的加密引擎(SafeKeyper)是一种选择,也可以使用诸如文件的更简单的机制(以各种格式)。
请求KeyStore对象的典型方法包括依赖于默认类型并提供特定的密钥库类型。
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
PrivateKey
, SecretKey
, Certificate
Modifier and Type | Class and Description |
---|---|
static class |
KeyStore.Builder
要实例化的KeyStore对象的描述。
|
static class |
KeyStore.CallbackHandlerProtection
一个封装CallbackHandler的ProtectionParameter。
|
static interface |
KeyStore.Entry
KeyStore 条目类型的标记界面。
|
static interface |
KeyStore.LoadStoreParameter
|
static class |
KeyStore.PasswordProtection
基于密码的ProtectionParameter
ProtectionParameter 。
|
static class |
KeyStore.PrivateKeyEntry
一个
KeyStore 条目,包含一个
PrivateKey 和相应的证书链。
|
static interface |
KeyStore.ProtectionParameter
用于密钥库保护参数的标记界面。
|
static class |
KeyStore.SecretKeyEntry
一个
KeyStore 条目,保存一个
SecretKey 。
|
static class |
KeyStore.TrustedCertificateEntry
一个
KeyStore 条目,持有一个值得信赖的
Certificate 。
|
Modifier | Constructor and Description |
---|---|
protected |
KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type)
创建给定类型的KeyStore对象,并封装给定的提供者实现(SPI对象)。
|
Modifier and Type | Method and Description |
---|---|
Enumeration<String> |
aliases()
列出此密钥库的所有别名。
|
boolean |
containsAlias(String alias)
检查此密钥库中是否存在给定的别名。
|
void |
deleteEntry(String alias)
从此密钥库中删除由给定别名标识的条目。
|
boolean |
entryInstanceOf(String alias, 类<? extends KeyStore.Entry> entryClass)
确定密钥库
Entry 为指定
alias 是指定的一个实例或亚类
entryClass 。
|
Certificate |
getCertificate(String alias)
返回与给定别名相关联的证书。
|
String |
getCertificateAlias(Certificate cert)
返回其证书与给定证书匹配的第一个密钥库条目的(别名)名称。
|
Certificate[] |
getCertificateChain(String alias)
返回与给定别名关联的证书链。
|
Date |
getCreationDate(String alias)
返回由给定别名标识的条目的创建日期。
|
static String |
getDefaultType()
返回由
keystore.type 安全属性指定的默认密钥库类型,或者如果没有此类属性,则返回字符串“jks”(“Java密钥库”的缩写)。
|
KeyStore.Entry |
getEntry(String alias, KeyStore.ProtectionParameter protParam)
使用
Entry 的保护参数获取指定别名的密钥库Entry。
|
static KeyStore |
getInstance(String type)
返回指定类型的密钥库对象。
|
static KeyStore |
getInstance(String type, Provider provider)
返回指定类型的密钥库对象。
|
static KeyStore |
getInstance(String type, String provider)
返回指定类型的密钥库对象。
|
Key |
getKey(String alias, char[] password)
返回与给定别名相关联的密钥,使用给定的密码恢复它。
|
Provider |
getProvider()
返回此密钥库的提供者。
|
String |
getType()
返回此密钥库的类型。
|
boolean |
isCertificateEntry(String alias)
如果由给定别名标识的条目是通过调用
setCertificateEntry 创建的,或通过调用
setEntry 与
TrustedCertificateEntry 创建的条目,则返回true。
|
boolean |
isKeyEntry(String alias)
如果给定别名标识的条目是通过调用
setKeyEntry 创建的,或通过调用
setEntry (
PrivateKeyEntry 或
SecretKeyEntry 创建的条目,则返回true。
|
void |
load(InputStream stream, char[] password)
从给定的输入流加载此KeyStore。
|
void |
load(KeyStore.LoadStoreParameter param)
使用给定的
LoadStoreParameter 加载此密钥库。
|
void |
setCertificateEntry(String alias, Certificate cert)
将给定的可信证书分配给给定的别名。
|
void |
setEntry(String alias, KeyStore.Entry entry, KeyStore.ProtectionParameter protParam)
在指定的别名下保存密钥库
Entry 。
|
void |
setKeyEntry(String alias, byte[] key, Certificate[] chain)
将给定的密钥(已经被保护)分配给给定的别名。
|
void |
setKeyEntry(String alias, Key key, char[] password, Certificate[] chain)
将给定的密钥分配给给定的别名,并使用给定的密码进行保护。
|
int |
size()
检索此密钥库中的条目数。
|
void |
store(KeyStore.LoadStoreParameter param)
使用给定的
LoadStoreParameter 存储此密钥库。
|
void |
store(OutputStream stream, char[] password)
将此密钥库存储到给定的输出流,并使用给定的密码保护其完整性。
|
protected KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type)
keyStoreSpi
- 提供者实现。
provider
- 提供商。
type
- 密钥库类型。
public static KeyStore getInstance(String type) throws KeyStoreException
此方法遍历已注册的安全提供程序列表,从最优选的提供程序开始。 返回从支持指定类型的第一个Provider中封装KeyStoreSpi实现的新KeyStore对象。
请注意,注册提供商的列表可以通过Security.getProviders()
方法检索 。
type
- 密钥库的类型。
有关标准密钥库类型的信息,请参阅Java Cryptography Architecture Standard Algorithm Name Documentation中的KeyStore部分。
KeyStoreException
- 如果没有提供者支持指定类型的KeyStoreSpi实现。
Provider
public static KeyStore getInstance(String type, String provider) throws KeyStoreException, NoSuchProviderException
返回从指定提供程序封装KeyStoreSpi实现的新KeyStore对象。 指定的提供者必须在安全提供程序列表中注册。
请注意,注册提供商的列表可以通过Security.getProviders()
方法检索 。
type
- 密钥库的类型。
有关标准密钥库类型的信息,请参阅Java Cryptography Architecture Standard Algorithm Name Documentation中的KeyStore部分。
provider
- 提供者的名称。
KeyStoreException
- 如果指定类型的KeyStoreSpi实现不可用于指定的提供程序。
NoSuchProviderException
- 如果指定的提供程序未在安全提供程序列表中注册。
IllegalArgumentException
- 如果提供者名称为空或为空。
Provider
public static KeyStore getInstance(String type, Provider provider) throws KeyStoreException
返回从指定的Provider对象封装KeyStoreSpi实现的新KeyStore对象。 请注意,指定的Provider对象不必在提供者列表中注册。
type
- 密钥库的类型。
有关标准密钥库类型的信息,请参阅Java Cryptography Architecture Standard Algorithm Name Documentation中的KeyStore部分。
provider
- 提供商。
KeyStoreException
- 如果指定类型的KeyStoreSpi实现不可用于指定的Provider对象。
IllegalArgumentException
- 如果指定的提供者为空。
Provider
public static final String getDefaultType()
keystore.type
安全属性指定的默认密钥库类型,或者如果没有这样的属性,则返回字符串“jks”(“Java密钥库”的缩写)。
当调用其中一个getInstance
方法时,不希望使用硬编码密钥库类型的getInstance
程序可以使用默认密钥库类型,并希望在用户未指定自己的密钥库类型时提供默认密钥库类型。
可以通过将keystore.type
安全属性的值设置为所需的密钥库类型来更改默认密钥库类型。
keystore.type
安全属性指定的默认密钥仓库类型,如果没有此类属性,则为字符串“jks”。
security properties
public final Provider getProvider()
public final String getType()
public final Key getKey(String alias, char[] password) throws KeyStoreException, NoSuchAlgorithmException, UnrecoverableKeyException
setKeyEntry
,或将呼叫setEntry
与PrivateKeyEntry
或SecretKeyEntry
。
alias
- 别名
password
- 恢复密钥的密码
KeyStoreException
- 如果密钥库尚未初始化(加载)。
NoSuchAlgorithmException
- 如果无法找到恢复密钥的算法
UnrecoverableKeyException
- 如果密钥无法恢复(例如,给定的密码错误)。
public final Certificate[] getCertificateChain(String alias) throws KeyStoreException
setKeyEntry
,或通过调用setEntry
与PrivateKeyEntry
。
alias
- 别名
KeyStoreException
- 如果密钥库尚未初始化(加载)。
public final Certificate getCertificate(String alias) throws KeyStoreException
如果给定的别名标识通过调用创建一个条目setCertificateEntry
,或创建一个呼叫setEntry
与TrustedCertificateEntry
,则包含在该条目中的可信证书被返回。
如果给定的别名标识通过一个调用创建一个条目setKeyEntry
,或创建通过调用setEntry
与PrivateKeyEntry
,则返回该条目中的证书链的第一个元素。
alias
- 别名
KeyStoreException
- 如果密钥库尚未初始化(加载)。
public final Date getCreationDate(String alias) throws KeyStoreException
alias
- 别名
KeyStoreException
- 如果密钥库尚未初始化(加载)。
public final void setKeyEntry(String alias, Key key, char[] password, Certificate[] chain) throws KeyStoreException
如果给定的密钥是类型java.security.PrivateKey
,它必须附有一个证书链,证明相应的公钥。
如果给定的别名已经存在,与它相关联的密钥库信息将被给定的密钥(也可能是证书链)覆盖。
alias
- 别名
key
- 与别名
key
的关键
password
- 密码保护密钥
chain
- 相应公钥的证书链(仅当给定键为
java.security.PrivateKey
类型
java.security.PrivateKey
)。
KeyStoreException
- 如果密钥库尚未初始化(加载),给定的密钥不能被保护,或者由于某些其他原因导致此操作失败
public final void setKeyEntry(String alias, byte[] key, Certificate[] chain) throws KeyStoreException
如果受保护的密钥类型为java.security.PrivateKey
,则必须附有证书链,证明相应的公钥。 如果基础密钥库实现类型为jks
, key
必须编码为PKCS#8标准中定义的EncryptedPrivateKeyInfo
。
如果给定的别名已经存在,与它相关联的密钥库信息将被给定的密钥(也可能是证书链)覆盖。
alias
- 别名
key
- 与别名
key
的关键字(以受保护的格式)
chain
- 相应公钥的证书链(仅当受保护的密钥为
java.security.PrivateKey
类型
java.security.PrivateKey
)。
KeyStoreException
- 如果密钥库尚未初始化(加载),或者由于其他原因导致此操作失败。
public final void setCertificateEntry(String alias, Certificate cert) throws KeyStoreException
如果给定的别名标识通过调用setCertificateEntry
创建的现有条目,或通过调用setEntry
与TrustedCertificateEntry
,则现有条目中的受信任证书将被给定证书覆盖。
alias
- 别名
cert
- 证书
KeyStoreException
- 如果密钥存储库尚未初始化,或者给定的别名已经存在,并且不标识包含受信任证书的条目,否则此操作由于某些其他原因而失败。
public final void deleteEntry(String alias) throws KeyStoreException
alias
- 别名
KeyStoreException
- 如果密钥库尚未初始化,或者条目无法删除。
public final Enumeration<String> aliases() throws KeyStoreException
KeyStoreException
- 如果密钥库尚未初始化(加载)。
public final boolean containsAlias(String alias) throws KeyStoreException
alias
- 别名
KeyStoreException
- 如果密钥库尚未初始化(加载)。
public final int size() throws KeyStoreException
KeyStoreException
- 如果密钥库尚未初始化(加载)。
public final boolean isKeyEntry(String alias) throws KeyStoreException
setKeyEntry
,或创建一个呼叫
setEntry
与
PrivateKeyEntry
或
SecretKeyEntry
。
alias
- 要检查密钥库条目的别名
KeyStoreException
- 如果密钥库尚未初始化(加载)。
public final boolean isCertificateEntry(String alias) throws KeyStoreException
setCertificateEntry
创建的,或通过调用
setEntry
与
TrustedCertificateEntry
创建的条目,则返回true。
alias
- 要检查密钥库条目的别名
KeyStoreException
- 如果密钥库尚未初始化(加载)。
public final String getCertificateAlias(Certificate cert) throws KeyStoreException
此方法尝试将给定证书与每个密钥库条目相匹配。 如果考虑的条目是通过调用setCertificateEntry
创建的,或通过调用setEntry
与TrustedCertificateEntry
,则将给定的证书与该条目的证书进行比较。
如果考虑的条目是通过调用setKeyEntry
创建的,或通过调用setEntry
与PrivateKeyEntry
,则将给定的证书与该条目的证书链的第一个元素进行比较。
cert
- 证书匹配。
KeyStoreException
- 如果密钥库尚未初始化(加载)。
public final void store(OutputStream stream, char[] password) throws KeyStoreException, IOException, NoSuchAlgorithmException, CertificateException
stream
- 写入此密钥库的输出流。
password
- 生成密钥库完整性检查的密码
KeyStoreException
- 如果密钥库尚未初始化(加载)。
IOException
- 如果数据存在I / O问题
NoSuchAlgorithmException
- 如果找不到适当的数据完整性算法
CertificateException
- 如果密钥库数据中包含的任何证书无法存储
public final void store(KeyStore.LoadStoreParameter param) throws KeyStoreException, IOException, NoSuchAlgorithmException, CertificateException
LoadStoreParameter
存储此密钥库。
param
-在
LoadStoreParameter
指定如何存储密钥库,这可能是
null
IllegalArgumentException
- 如果给定的
LoadStoreParameter
输入未被识别
KeyStoreException
- 如果密钥库尚未初始化(加载)
IOException
- 如果数据有I / O问题
NoSuchAlgorithmException
- 如果找不到适当的数据完整性算法
CertificateException
- 如果密钥库数据中包含的任何证书无法存储
public final void load(InputStream stream, char[] password) throws IOException, NoSuchAlgorithmException, CertificateException
可以提供密码来解锁密钥库(例如,密钥库驻留在硬件令牌设备上),或者检查密钥库数据的完整性。 如果没有为完整性检查提供密码,则不执行完整性检查。
为了创建一个空的密钥库,或者如果密钥库不能从流null
,请传递null
作为stream
参数。
请注意,如果此密钥库已经加载,则会从给定的输入流重新初始化并加载该密钥库。
stream
- 加载密钥库的输入流,或
null
password
- 用于检查密钥库完整性的密码,用于解锁密钥库的密码,或
null
IOException
- 如果密钥库数据存在I / O或格式问题,如果需要密码但未提供密码,或者给定的密码不正确。
如果错误是由于错误的密码, cause
的的IOException
应该是UnrecoverableKeyException
NoSuchAlgorithmException
- 如果用于检查密钥库完整性的算法无法找到
CertificateException
- 如果密钥库中的任何证书无法加载
public final void load(KeyStore.LoadStoreParameter param) throws IOException, NoSuchAlgorithmException, CertificateException
LoadStoreParameter
加载这个密钥库。
请注意,如果此KeyStore已经加载,它将从给定的参数重新初始化并重新加载。
param
-所述
LoadStoreParameter
指定如何加载密钥库,其可以是
null
IllegalArgumentException
- 如果给定的
LoadStoreParameter
输入未被识别
IOException
- 如果密钥库数据存在I / O或格式问题。
如果错误是由于ProtectionParameter
(例如错误的密码) 造成的, IOException
应为UnrecoverableKeyException
NoSuchAlgorithmException
- 如果用于检查密钥库完整性的算法无法找到
CertificateException
- 如果密钥库中的任何证书无法加载
public final KeyStore.Entry getEntry(String alias, KeyStore.ProtectionParameter protParam) throws NoSuchAlgorithmException, UnrecoverableEntryException, KeyStoreException
Entry
的指定别名的密钥库Entry。
alias
- 获取此别名的密钥库
Entry
protParam
-
ProtectionParameter
用于保护
Entry
,其中可能是
null
Entry
库
Entry
为指定的别名,或
null
如果没有这样的条目
NullPointerException
- 如果
alias
是
null
NoSuchAlgorithmException
- 如果无法找到恢复条目的算法
UnrecoverableEntryException
- 如果指定的
protParam
不足或无效
UnrecoverableKeyException
- 如果条目是
PrivateKeyEntry
或
SecretKeyEntry
,并且指定的
protParam
不包含恢复密钥所需的信息(例如错误的密码)
KeyStoreException
- 如果密钥库尚未初始化(加载)。
setEntry(String, KeyStore.Entry, KeyStore.ProtectionParameter)
public final void setEntry(String alias, KeyStore.Entry entry, KeyStore.ProtectionParameter protParam) throws KeyStoreException
Entry
。
保护参数用于保护Entry
。
如果指定别名的条目已存在,则会被覆盖。
alias
- 保存此别名下的密钥库
Entry
entry
- 要保存的
Entry
protParam
-
ProtectionParameter
用于保护
Entry
,可能是
null
NullPointerException
- 如果
alias
或
entry
是
null
KeyStoreException
- 如果密钥库尚未初始化(加载),或者由于其他原因导致此操作失败
getEntry(String, KeyStore.ProtectionParameter)
public final boolean entryInstanceOf(String alias, 类<? extends KeyStore.Entry> entryClass) throws KeyStoreException
Entry
为指定
alias
是指定的一个实例或亚类
entryClass
。
alias
- 别名
entryClass
- 入门课
Entry
指定的
alias
是一个实例或指定的子类
entryClass
,否则为false
NullPointerException
- 如果
alias
或
entryClass
是
null
KeyStoreException
- 如果密钥存储库尚未初始化(加载)