Java KeyTool 的使用

 

keytool - 密钥和证书管理工具

 

管理由私钥和认证相关公钥的 X.509 证书链组成的密钥仓库（数据库）。还管理来自可信任实体的证书。

 

结构

 

keytool [ commands ]

 

说明

 

keytool 是个密钥和证书管理工具。它使用户能够管理自己的公钥/私钥对及相关证书，用于（通过数字签名）自我认证（用户向别的用户/服务认证自己）或数据完整性以及认证服务。它还允许用户储存他们的通信对等者的公钥（以证书形式）。

证书是来自一个实体（个人、公司等）的经数字签名的声明，它声明某些其它实体的公钥（及其它信息）具有某一的特定值（参见证书）。当数据被数字化签名后，校验签名即可检查数据的完整性和真实性。完整性的意思是数据没有被修改或损坏过，真实性的意思是数据的确是来自声称创建了该数据和对它进行了签名的实体。

keytool 将密钥和证书储存在一个所谓的密钥仓库中。缺省的密钥仓库实现将密钥仓库实现为一个文件。它用口令来保护私钥。

jarsigner 工具利用密钥仓库中的信息来产生或校验 Java 归档 (JAR) 文件的数字签名。（JAR 文件将类文件、图像、声音和/或其它数字化数据打包在一个文件中）。jarsigner 用 JAR 文件所附带的证书（包含于 JAR 文件的签名块文件中）来校验 JAR 文件的数字签名，然后检查该证书的公钥是否“可信任”，即是否包括在指定的密钥仓库中。

请注意：keytool 和 jarsigner 工具完全取代了 JDK 1.1 中提供的 javakey 工具。这些新工具所提供的功能比 javakey 提供的多，包括能够用口令来保护密钥仓库和私钥，以及除了能够生成签名外还可以校验它们。新的密钥仓库体系结构取代了 javakey 所创建和管理的身份数据库。可以利用 -identitydb keytool 命令将信息从身份数据库导入密钥仓库。

密钥仓库项

在密钥仓库中有两种不同类型的项：

 
1. 密钥项 - 每项都存放极为敏感的加密密钥信息，这种信息以一种受保护的格式储存以防止未授权的访问。通常，储存在这类项中的密钥是机密密钥，或是伴有用于认证相应公钥的证书“链”的私钥。keytool 和 jarsigner 工具只处理后一类型的项，即私钥及其关联的证书链。
2. 可信任的证书项 - 每项包含一个属于另一方的公钥证书。它之所以叫做“可信任的证书”，是因为密钥仓库的拥有者相信证书中的公钥确实属于证书“主体”（拥有者）所识别的身份。证书发人通过对证书签名来保证这点。

密钥仓库别名

对所有的密钥仓库项（密钥项和可信任的证书项）的访问都要通过唯一的 别名来进行。别名不区分大小写，即别名 Hugo 和 hugo 指的是同一密钥仓库项。

当用 -genkey 命令来生成密钥对（公钥和私钥）或用 -import 命令来将证书或证书链加到可信任证书的清单中以增加一个实体到密钥仓库时，必须指定一个别名。后续 keytool 命令必须使用这一相同的别名来引用该实体。

例如，假设您用别名 duke 生成了新的公钥/私钥对，并将公钥用以下命令打包到自签名证书中（参见证书链）：

    keytool -genkey -alias duke -keypass dukekeypasswd

这指定了一个初始口令“dukekeypasswd”，后续命令都需使用该口令才能访问与别名 duke 关联的私钥。如果后来想更改 duke 的私钥口令，可用类似下述的命令：

    keytool -keypasswd -alias duke -keypass dukekeypasswd -new newpass

这将把口令从“dukekeypasswd”改为“newpass”。

请注意：实际上，除非是作为测试目的或是在安全的系统上，否则不应在命令行或脚本中指定口令。如果没有在命令行上指定所要求的口令选项，您将会得到要求输入口令的提示。当在口令提示符下键入口令时，口令将被即时显示出来（键入什么就显示什么），因此，要小心，不要当着任何人的面键入口令。

密钥仓库位置

每个 keytool 命令都有一个 -keystore 选项，用于指定 keytool 管理的密钥仓库的持久密钥仓库文件名称及其位置。缺省情况下，密钥仓库储存在用户宿主目录（由系统属性的“user.home”决定）中名为 .keystore 的文件中。假如用户名为 uName，则“user.home”属性的缺省值为

C:\Winnt\Profiles\uName，在多用户 Windows NT 系统上
C:\Windows\Profiles\uName，在多用户 Windows 95 系统上
C:\Windows，在单用户 Windows 95 系统上

因此，如果用户名为“cathy”，则“user.home”的缺省值为

C:\Winnt\Profiles\cathy，在多用户 Windows NT 系统上
C:\Windows\Profiles\cathy，在多用户 Windows 95 系统上

密钥仓库的创建

当用 -genkey, -import 或 -identitydb 命令向某个尚不存在的密钥仓库添加数据时，即创建密钥仓库。

更具体地说，如果在 -keystore 选项中指定了一个并不存在的密钥仓库，即加以创建。

如果不指定 -keystore 选项，则缺省密钥仓库将是宿主目录中名为 .keystore 的文件。如果该文件不存在，即加以创建。

密钥仓库实现

java.security 包中提供的 KeyStore 类为访问和修改密钥仓库中的信息提供了相当固定的接口。可以有多个不同的具体实现，其中每个实现都是对某个特定 类型的密钥仓库的具体实现。

目前，有两个命令行工具（keytool 和 jarsigner）以及一个名为 Policy Tool 的基于 GUI 的工具使用密钥仓库实现。由于密钥仓库是公用的，JDK 用户可利用它来编写其它的安全性应用程序。

Sun Microsystems 公司提供了一个内置的缺省实现。它利用名为“JKS” 的专用密钥仓库类型（格式），将密钥仓库实现为文件。它用个人口令保护每个私钥，也用口令（可能为另一个口令）保护整个密钥仓库的完整性。

密钥仓库的实现基于提供者 (provider)。更具体地说，由密钥仓库所提供的应用程序接口是借助于“服务提供者接口”(SPI) 来实现的。也就是说，在 java.security 包中还有一个对应的抽象 KeystoreSpi 类，它定义了“提供者”必须实现的服务提供者接口方法。术语“提供者”指的是一个或一组包，这个或这组包提供了一部份可由 Java 安全 API 访问的服务子集的具体实现。因此，要提供某个密钥仓库实现，客户机必须实现一个“提供者”并实现 KeystoreSpi 子类，如“如何为 Java  加密体系结构实现 Provider”中所述。

通过使用 KeyStore 类中提供的“getInstance”工厂方法，应用程序可从不同的提供者中挑选不同类型的密钥仓库实现。密钥仓库类型定义密钥仓库信息的存储格式和数据格式，以及用于保护密钥仓库中的私钥和密钥仓库自身完整性的算法。不同类型的密钥仓库实现是不兼容的。

keytool 使用基于文件的密钥仓库实现（它把在命令行中传递给它的密钥仓库位置当成文件名处理并将之转换为文件输入流，从该文件输入流中加载密钥仓库信息）。另一方面，jarsigner 和 policytool 工具可从任何可用 URL 指定的位置读取某个密钥仓库。

对于 keytool 和 jarsigner，可在命令行用 -storetype 选项指定密钥仓库类型。对于 Policy Tool，可通过 “编辑”菜单中的“更改密钥仓库”命令来指定密钥仓库类型。

如果没有明确指定一个密钥仓库类型，这些工具将只是根据安全属性文件中指定的 keystore.type 属性值来选择密钥仓库实现。安全属性文件名为 java.security，它位于 JDK 安全属性目录 java.home\lib\security 中，其中 java.home 为 JDK 的安装目录。

每个工具都先获取 keystore.type 的值，然后检查所有当前已安装的提供者直到找到一个实现所要求类型的密钥仓库的实现为止。然后就使用该提供者的密钥仓库实现。

KeyStore 类定义了一个名为 getDefaultType 的静态方法，它可让应用程序或 applet 检索 keystore.type 属性的值。以下代码将创建缺省密钥仓库类型（此类型由 keystore.type 属性指定。）的一个实例：

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

缺省的密钥仓库类型是“jks”（这是由“SUN”提供者提供的密钥仓库实现的专用类型）。它在安全属性文件中由如下行进行指定：

    keystore.type=jks

要让工具使用不同于缺省类型的密钥仓库实现，可更改此行，指定不同的密钥仓库类型。

例如，如果您有一个这样的提供者包，它给出一个名为“pkcs12”的密钥仓库类型的密钥仓库实现，则可将上面那行改为：

    keystore.type=pkcs12

注意：密钥仓库类型的命名中大小写无关紧要。例如，“JKS”将被认为是与“jks”相同的。

支持的算法和密钥大小

keytool 允许用户指定任何注册了的密码服务提供者所提供的密钥对生成和签名算法。也就是说，各种命令中的 keyalg 和 sigalg 选项必须得到提供者的实现的支持。缺省的密钥对生成算法是“DSA”。签名算法是从所涉及私钥的算法推导来的：如果所涉及的私钥是“DSA”类型，则缺省的签名算法为“带 DSA 的 SHA1”，如果所涉及的私钥是“RSA”类型，则缺省的签名算法为“带 RSA 的 MD5”。

在生成 DSA 密钥对时，密钥大小的范围必须在 512 到 1024 位之间，且必须是 64 的倍数。缺省的密钥大小为 1024 位。

证书

证书（也叫 公钥证书）是来自某个实体（签 发人）的经数字签名的声明，它声明另一实体（ 主体）的公钥（及其它信息）具有某一特定的值。

下面详细解释本句中使用的主要术语：

 

公钥

是与特定实体相关联的数字。所有需要与该实体进行可信任交互的人都应知道该数字。公钥用于校验签名。

经数字签名

如果某些数据 经数字签名，说明它们已与某一实体的“身份”存储在一起，而且证明该实体的签名知道这些数据。通过用该实体的私钥对这些数据进行绘制，这些数据即无法进行伪造了。

身份

一种众所周知的表示实体的方式。某些系统中，身份是公钥，而在另一些系统中则可以是 Unix UID、电子邮件地址或 X.509 特征名等等。

签名

所谓签名，就是用实体的（ 签名人，在证书中也称为签 发人）私钥对某些数据进行计算。

私钥

是一些数字，每个数字都应仅被以该数字作为私钥的特定实体所知（即该数字应保密）。在所有公钥密码系统中，私钥和公钥均成对出现。在 DSA 等具体的公钥密码系统中，一个私钥只对应一个公钥。私钥用于计算签名。

实体

实体是您在某种程度上对其加以信任的个人、组织、程序、计算机、企业、银行等。

通常，公钥密码系统需要访问用户的公钥。在大型联网环境中，并不能确保通信实体之间已经预先建立起关系，也无法确保受信任的储存库与所用的公钥都存在。于是人们发明了证书作为公钥分配问题的解决方案。现在， 认证机构 (CA) 可充当可信任的第三方角色。CA 是可信任的、向其它实体签名（发放）证书的实体（例如企业）。由于 CA 受法律协议约束，因此可认为它们只提供可靠有效的证书。公共认证机构数量很多，例如 VeriSign、 Thawte、 Entrust 等等。您还可以使用诸如 Netscape/Microsoft Certificate Servers 或 Entrust CA 等产品来自己运营认证机构。

使用 keytool 可以显示、导入和导出证书。还可以生成自签名证书。

keytool 目前处理 X.509 证书。

X.509 证书

X.509 标准规定了证书可以包含什么信息，并说明了记录信息的方法（数据格式）。除了签名外，所有 X.509 证书还包含以下数据： 

版本

识别用于该证书的 X.509 标准的版本。该版本可以影响证书中所能指定的信息。迄今为止，已定义的版本有三个。 keytool 可导入和导出 v1、v2 和 v3 版的证书。它只能生成 v1 版证书。

序列号

发放证书的实体有责任为证书指定序列号，以使其区别于该实体发放的其它证书。此信息用途很多。例如，如果某一证书被撤消，其序列号将放到证书撤消清单 (CRL) 中。

签名算法标识符

用于身份 CA 签名证书时所用的算法。

签发人姓名

签名证书的实体的 X.500 特征名。它通常为一个 CA。使用该证书意味着信任签名该证书的实体。注意：有些情况下（例如 根或顶层 CA 证书），签发人会签名自己的证书。

有效期

每个证书均只能在一个有限的时间段内有效。该有效期以起始日期和时间及终止日期和时间表示，可以短至几秒或长至一世纪。所选有效期取决于许多因素，例如用于签名证书的私钥的使用频率及愿为证书支付的金钱等。它是在没有危及相关私钥的条件下，实体可以依赖公钥值的预计时间。

主体名

证书可以识别其公钥的实体名。此名称使用 X.500 标准，因此在Internet中应是唯一的。它是实体的 X.500 特征名 (DN)，例如，

    CN=Java Duke, OU=Java Software Division, O=Sun Microsystems Inc, C=US

（这些指主体的通用名、组织单位、组织和国家。）

主体公钥信息

这是被命名实体的公钥，同时包括指定该密钥所属公钥密码系统的算法 标识符及所有相关的密钥参数。

X.509 1 版 1988 年发布，已得到广泛使用，是最常用的版本。

X.509 2 版引入了主体和签发人唯一标识符的概念，以解决主体和/或签发人名称在一段时间后可能重复使用的问题。大多数证书监视文档都极力建议不要重复使用主体或签发人名称，而且建议证书不要使用唯一标识符。版本 2 证书尚未得到广泛使用。

X.509 3 版是最新的版本（1996 年）。它支持扩展的概念，因此任何人均可定义扩展并将其纳入证书中。现在常用的扩展包括：KeyUsage（仅限密钥用于特殊目的，例如“只签名”）和 AlternativeNames（允许其它身份也与该公钥关联，例如 DNS 名、电子邮件地址、IP 地址）。扩展可标记为“极重要”，以表示该扩展应被检查并执行或使用。例如，如果某一证书将 KeyUsage 扩展标记为“极重要”，而且设置为“keyCertSign”，则在 SSL 通讯期间该证书出现时将被拒绝，因为该证书扩展表示相关私钥应只用于签名证书，而不应该用于 SSL。

证书中的所有数据均用两个名为 ASN.1/DER 的相关标准进行编码。抽象语法注释 1 (Abstract Syntax Notation 1) 描述数据。确定性编码规则 (Definite Encoding Rules) 描述储存和传输该数据的唯一方式。

X.500 特征名

X.500 特征名用于身份实体，例如 X.509 证书的 主体和签发人（签名人）域所命名的实体。 keytool 支持以下的子组件：

 
• commonName - 个人常用名，例如“Susan Jones”
• organizationUnit - 小型组织（例如部门或分部）的名称，例如“Purchasing”
• organizationName - 大型组织的名称，例如“ABCSystems, Inc.”
• localityName - 地方（城市）名，例如“Palo Alto”
• stateName - 州或省份名，例如“California”
• country - 两个字母的国家代码，例如“CH”

当给出一个特征名字符串作为 -dname 选项的值时，例如 -genkey 或 -selfcert 命令中的该选项，字符串必须为以下格式：

CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode

其中所有的斜体字代表实际值而上面的关键字是以下缩写：

        CN=commonName
        OU=organizationUnit
        O=organizationName
        L=localityName
        S=stateName
        C=country

以下是特征名字符串样本：

CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino, S=California, C=US

以下是使用这一字符串的样本命令：

keytool -genkey -dname "CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino,
S=California, C=US" -alias mark

大小写对关键字缩写无关紧要。例如，“CN”、“cn”和“Cn”都将被当作是一样的。

但顺序是有关系的；每个子组件必须按设计好的顺序出现。但是，不是所有子组件都必须有。可以只用一部分，例如：

CN=Steve Meier, OU=SunSoft, O=Sun, C=US

如果特征名字符串的值含有逗号，当在命令行指定该字符串时，逗号必须用“\”字符来进行转义，如下所示：

   cn=peter schuster, o=Sun Microsystems\, Inc., o=sun, c=us

在命令行中指定特征名字符串是不必要的。如果某一命令需要指定特征名字符串，而在命令行中又未提供，则用户将得到每个子组件的提示。这种情况下，逗号不需要用“\”来转义。

Internet RFC 1421 证书编码标准

证书常用  Internet RFC 1421 标准中定义的可打印的编码格式来储存，而不用其二进制编码。这种证书格式，也称“Base 64 编码”，便于通过电子邮件或其它机制将证书导出到别的应用程序中。

用 -import 和 -printcert 命令读入的证书可以是这种格式的编码或是二进制格式的编码。

缺省情况下，-export 命令将以二进制编码格式输出证书，但如果指定了 -rfc 选项，则将以可打印的编码格式输出证书。

缺省情况下，-list 命令打印证书的 MD5 指纹。而如果指定了 -v 选项，将以可读格式打印证书，如果指定了 -rfc 选项，将以可打印的编码格式输出证书。

在其可打印的编码格式中，已编码证书的起始行是：

-----BEGIN CERTIFICATE-----

结束行是：

-----END CERTIFICATE-----

证书链

keytool 可创建和管理密钥仓库的“密钥”项，每个密钥项都含有私钥和相关证书“链”。链中的第一个证书含有与私钥对应的公钥。

当第一次产生密钥时（参见 -genkey 命令），链中只含有一个元素，即自签名证书。自签名证书是一个这样的证书：其签发人（签名人）与主体（证书所认证的公钥所属的实体）相同。当调用 -genkey 命令来生成新的公钥/私钥对时，它同时也把公钥打包进自签名证书中。

之后，当证书签名请求 (CSR)（参见 -certreq 命令）被生成并送至认证机构 (CA) 后，CA 的答复将被导入（参见 -import），证书链将取代自签名证书。在链的底部是认证主体公钥的 CA 所发放的证书（答复）。链中下一个证书是用于认证 CA 公钥的证书。

在许多情况下，这是个自签名证书（即来自认证其自身公钥的 CA 的证书）且是链中的最后一个证书。在其它情况下，CA 也许将返回证书链。这种情况下，链中底部的证书是相同的（由 CA 签名的证书，对密钥项的公钥进行认证），但链中第二个证书是由不同的 CA 所签名的，对您向其发送 CSR 的 CA 的公钥进行认证。然后，链中的下一个证书将是对第二个 CA 的公钥进行认证的证书，以此类推，直至到达自签名的“根”证书为止。因此，链中的每个证书（从第一个以后）都对链中前一个证书的签名人的公钥进行认证。

许多 CA 只返回所发放的证书，而不支持链，特别是当层次结构较简单时（无中介 CA）。这种情况下，必须用储存在密钥仓库中的可信任的证书信息来建立证书链。

另一种答复格式（由 PKCS#7 标准所定义）除了包含所发放的证书外，还支持证书链。两种答复格式都可由 keytool 处理。

顶层（根）CA 证书是自签名的。但是，对根公钥的信任并非来自根证书本身（任何人都可用特征名来产生自签名认证！譬如用 VeriSign 根 CA 的特征名）, 而是来自类似报纸之类的其它来源。根 CA 的公钥是广为人知的。它被储存在证书中的唯一原因是因为这是大多数工具所能理解的格式，因此这种情况下的证书只是作为一种传输根 CA 的公钥用的“交通工具”。在将根 CA 证书加到您的密钥仓库中之前，应该先对它进行查看（用 -printcert 选项）并将所显示的指纹与已知的指纹（从报纸、根 CA 的网页等中获取）进行比较。

导入证书

要从一个文件中导入某个证书，可用 -import 命令，如下所示：

    keytool -import -alias joe -file jcertfile.cer

此样本命令导入文件 jcertfile.cer 中的证书并将其储存在由别名 joe 身份的密钥仓库项中。

导入证书的两个理由如下：

 
1. 为将其添加到可信任的证书清单中，或
2. 为导入因向 CA 提交证书签名请求（参见 -certreq 命令）而收到的来自该 CA 的认证答复。

-alias 选项的值指明要进行何种类型的导入。如果数据库中存在别名，且该别名身份具有私钥的项，则将假定您要导入认证答复。 keytool 将检查认证答复中的公钥是否与用别名储存的私钥相匹配，如果两者不同，则程序退出。如果别名身份另一种类型的密钥仓库项，则不导入该证书。如果该别名不存在，则它将被创建并与导入的证书关联。

有关导入可信任证书的警告

要点：将证书作为可信任的证书导入之前，请务必先仔细检查该证书！

先查看一下（用 -printcert 命令，或用不带 -noprompt 选项的 -import 命令），确保所显示的证书指纹与所预计的相匹配。例如，假设某人给您送来或用电子邮件发来一个证书，您将它放在名为 /tmp/cert 的文件中。在将它加到可信任证书的清单中之前，可通过执行 -printcert 命令来查看它的指纹，如下所示：

  keytool -printcert -file /tmp/cert
    Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
    Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
    Serial Number: 59092b34
    Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
    Certificate Fingerprints:
         MD5： 11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
         SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE

然后给向您发送证书的人打电话或用其它方式联系，将您所看到的指纹与他们所提供的进行比较。只有两者相等才可保证证书在传送途中没有被其它人（例如，攻击者）的证书所更换。如果发生了这样的攻击，而您未检查证书即将其导入，您就会信任攻击者所签名的任何东西（例如，一个含有恶意类文件的 JAR 文件）。

注意：并不要求在导入证书前执行 -printcert 命令，因为在将证书添加到密钥仓库中可信任证书的清单中之前，-import 命令将会打印出该证书的信息，并提示您进行校验。这时，您可选择中止导入操作。但是注意，只有在调用不带 -noprompt 选项的 -import 命令时才能这样做。如果给出了 -noprompt 选项，则不存在与用户的交互。

导出证书

要将证书导出到文件中，请用 -export 命令，如下所示：

    keytool -export -alias jane -file janecertfile.cer

该样本命令将 jane 的证书导出到文件 janecertfile.cer 中。也就是说，如果 jane 是某个密钥项的别名，该命令将导出该密钥仓库项中所含证书链底部的证书。这是认证 jane 的公钥用的证书。

相反，如果 jane 是某个可信任证书项的别名，则导出的是该可信任的证书。

显示证书

要打印某个密钥仓库项的内容，请用 -list 命令，如下所示：

    keytool -list -alias joe

如果未指定别名，如下所示：

    keytool -list

则打印整个密钥仓库的内容。

要显示储存在文件中的证书的内容，请用 -printcert 命令，如下所示：

    keytool -printcert -file certfile.cer

这将打印储存在文件 certfile.cer 中的有关证书的信息。

注意：此操作与密钥仓库无关，也就是说，不需要密钥仓库即可显示储存在文件中的证书。

生成自签名证书

自签名证书是一个这样的证书：其签发人（签名人）与主体（证书所认证的公钥所属的实体）相同。当调用 -genkey 命令来生成新的公钥/私钥对时，它同时也把公钥打包进自签名证书中。

有时您也许希望生成新的自签名证书。例如，您也许想对不同的身份（特征名）使用相同的密钥对。例如，假设您换了个部门。此时您可以：

 
1. 复制原始的密钥项。参见 -keyclone。
2. 用新特征名为该复制项生成新的自签名证书。参见下文。
3. 为该复制项生成证书签名请求，并导入答复证书或证书链。参见 -certreq 和 -import 命令。
4. 删除原始（现在已过时）项。参见 -delete 命令。

要生成自签名证书，请用 -selfcert 命令，如下所示：

    keytool -selfcert -alias dukeNew -keypass b92kqmp
      -dname "cn=Duke Smith, ou=Purchasing, o=BlueSoft, c=US"

所生成的证书作为指定别名（本例中为“dukeNew”）所身份的密钥仓库项中的单元素证书来储存，它将取代现有的证书链。

 

命令和选项注意事项

 

下面列出各种命令及其选项，并对它们进行描述。注意：

 
• 所有的命令和选项名之前都有减号 (-) 。
• 每个命令的选项都可按任意顺序提供。
• 所有非斜体项或不在花括号和方括号内的项都不能改动。
• 选项周围的花括号通常表示如果在命令行中没有指定该选项，则使用缺省值。花括号还用在 -v、-rfc 和 -J 选项周围，这些选项只有在命令行中出现时才有意义（也就是说，它们没有任何缺省值，不然就是不存在该选项）。
• 选项周围的方括号表示如果在命令行中没有指定该选项，则用户将得到要求输入其值的提示。（对于 -keypass 选项，如果在命令行中没有指定该选项，keytool 将先是尝试用密钥仓库口令来访问私钥，如果失败，再提示您输入私钥口令。）
• 斜体项（选项）代表必须提供实际值。例如，下面是 -printcert 命令的格式：

    keytool -printcert {-file cert_file} {-v}

  当指定 -printcert 命令时，请用实际文件名来替代 cert_file，如下所示：

    keytool -printcert -file VScert.cer

• 如果选项值含有空白（空格），必须用引号把它们括起来。
• -help 命令是缺省命令。因此，命令行

    keytool

  等价于

    keytool -help

选项缺省值

下面是各选项的缺省值。

-alias "mykey"

-keyalg "DSA"

-keysize 1024

-validity 90

-keystore 用户宿主目录中名为的 .keystore 的文件

-file 读时为标准输入，写时为标准输出

签名算法（ -sigalg 选项）是由所涉及私钥的算法推导而来的：如果所涉及的私钥是“DSA”类型，则 -sigalg 选项将缺省为“带 DSA 的 SHA1”，如果所涉及的私钥是“RSA”类型，则 -sigalg 选项将缺省为“带 RSA 的 MD5”。

出现在大多数命令中的选项

-v 选项可出现在除 -help 之外的所有命令中。如果出现该选项，表示处在“长格式”模式下；将输出详细的证书信息。

-Jjavaoption 选项也可在任何命令中出现。如果出现该选项，则所指定的 javaoption 字符串将被直接传给 Java 解释器。（keytool 实际上是解释器周围的一个 “wrapper”。） 该选项不应含有任何空格。它有助于调整执行环境或内存使用。要获得可用的解释器选项的清单，可在命令行键入 java -h 或 java -X。

有三个选项可出现在用于操作密钥仓库的所有命令中：

 

-storetype storetype

此限定符指定将被实例化的密钥仓库类型。缺省的密钥仓库类型是安全属性文件中“keystore.type”属性值所指定的类型，由 java.security.KeyStore 中的静态方法 getDefaultType 返回。

-keystore keystore

密钥仓库（数据库文件）的位置。缺省情况下，密钥仓库指的是用户宿主目录的 .keystore 文件，它是由“user.home”的系统属性确定的，该属性值在 密钥仓库位置中有说明。

-storepass storepass

口令，用来保护密钥仓库的完整性。

storepass 的长度必须至少为 6 个字符。所有访问密钥仓库内容的命令都必须提供这一选项。对于这些命令，如果没有给出 -storepass 选项，则用户将得到要求输入该选项的提示。

当从密钥仓库中检索信息时，口令属于可选项；如果未给出口令，就不能检查所检索信息的完整性，而且将出现警告。

使用口令时必须小心 -- 参见与口令有关的警告。

与口令有关的警告

大多数对密钥仓库操作的命令都要求仓库口令。一些命令要求私钥口令。

口令可以在命令行上（分别在 -storepass 和 -keypass 选项上）指定。但是，除非是作为测试目的或是在一个安全的系统上，否则不应在命令行或脚本中指定口令。

如果没有在命令行上指定所要求的口令选项，您将会得到要求输入口令的提示。当在口令提示符下键入口令时，口令将被即时地显示出来（键入什么就显示什么），因此，要小心，不要当着任何人的面键入口令。

 

命令

 

另请参阅 命令和选项注释。

向密钥仓库添加数据

-genkey {-alias alias} {-keyalg keyalg} {-keysize keysize} {-sigalg sigalg} [-dname dname] [-keypass keypass] {-validity valDays} {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v} {-Jjavaoption}

产生密钥对（公钥和与之关联的私钥）。将公钥打包进 X.509 v1 的自签名证书中，该证书以单元素证书链的形式储存。该证书链和私钥将储存于 alias 所标识的新密钥仓库项中。

keyalg 指定了用于生成密钥对的算法，而 keysize 指定要生成的每个密钥的大小。sigalg 指定签名自签名证书所用的算法；这一算法必须与 keyalg 兼容。参见支持的算法和密钥大小。

dname 指定与 alias 关联的 X.500 特征名，并用作自签名证书中的 issuer 和 subject 域。如果在命令行中没有提供特征名，用户将得到要求输入该信息的提示。

keypass 是口令，用来保护生成的密钥对中的私钥。如果没有提供口令，用户将得到要求输入口令的提示。如果在提示符下按 RETURN 键，则密钥口令将被设置为与密钥仓库所用的口令相同。keypass 的长度必须至少为 6 个字符。使用口令时必须小心 - 参见与口令有关的警告。

valDays 指定证书的有效期。

-import {-alias alias} {-file cert_file} [-keypass keypass] {-noprompt} {-trustcacerts} {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v} {-Jjavaoption}

从文件 cert_file 中读取证书或证书链（后者在 PKCS#7 格式的答复中给出）并将其储存在 alias 所标识的密钥仓库项中。如果没有给出文件，则从标准输入设备中读取证书或 PKCS#7 答复。 keytool 可导入 X.509 v1、v2 和 v3 的证书以及由该类证书所组成的 PKCS#7 格式的证书链。要导入的数据必须是二进制编码格式或 Internet RFC 1421 标准所定义的可打印的编码格式（也称 Base64 编码）。在后一种情况下，编码必须用以“-----BEGIN”开头的字符串开始，用以“-----END”结尾的字符串来结束。

当导入新的可信任证书时，密钥仓库中还没有 alias。在把证书添加到密钥仓库中之前，keytool 将尝试用密钥仓库中已有的可信任证书来构造从该证书到自签名证书（属于根 CA）的信任链，以对证书进行校验。

如果指定了 -trustcacerts 选项，则将为该信任链考虑其它证书，即考虑名为“cacerts”的文件中的证书，该文件位于 JDK 安全属性目录 java.home\lib\security 中，其中 java.home 为 JDK 安装目录。“cacerts”文件代表含有 CA 证书的系统范围的密钥仓库。通过指定密钥仓库类型为“jks”，系统管理员可用 keytool 来配置和管理该文件。“cacerts”密钥仓库文件在发送时附有五个 VeriSign 根 CA 证书，其 X.500 特征名如下：

1. OU=Class 1 Public Primary Certification Authority, O="VeriSign, Inc.",
C=US

2. OU=Class 2 Public Primary Certification Authority, O="VeriSign,
Inc.", C=US

3. OU=Class 3 Public Primary Certification Authority,
O="VeriSign, Inc.", C=US

4. OU=Class 4 Public Primary Certification
Authority, O="VeriSign, Inc.", C=US

5. OU=Secure Server Certification
Authority, O="RSA Data Security, Inc.", C=US

“cacerts”密钥仓库文件的初始口令为“changeit” 。系统管理员在安装 JDK 后，就应该立即更改这个口令以及该文件的缺省访问权限。

如果 keytool 无法建立从要导入的证书到自签名证书的信任路径（利用密钥仓库或“cacerts”文件），则打印出该证书的信息，而用户将得到要求校验的提示，例如，系统将通知用户通过比较显示出的指纹和得自其它（可信任的）信息来源的指纹来进行校验，信息来源可能是证书拥有者本人。在将证书作为一个“可信任”证书导入之前，要十分小心，务必保证该证书是有效的！ -- 参见有关导入可信任证书的警告。然后，用户可以选择中止导入操作。但是，如果给了 -noprompt 选项，则不会有与用户的交互。

当导入认证答复时，该认证答复将用密钥仓库中可信任的证书来确认，有时也使用在“cacerts”密钥仓库文件中配置的证书（如果指定了 -trustcacerts 选项）。

如果答复是一个 X.509 证书，keytool 将尝试建立信任链，以该认证答复为头，以属于根 CA 的自签名证书为尾。该认证答复和用于认证该认证答复的证书层次形成了 alias 的新证书链。

如果答复是 PKCS#7 格式的证书链，则该链应首先被排序（用户证书在最前面，自签名的根 CA 证书在最后面），然后 keytool 尝试将答复中的根 CA 证书与密钥仓库或“cacerts”密钥仓库文件（如果指定了 -trustcacerts 选项）中的任何可信任证书进行匹配。如果找不到匹配，则打印出该根 CA 证书的信息，而用户将得到要求校验它的提示，例如，系统将通知用户通过比较显示出的指纹和得自其它（可信任的）信息来源的指纹来进行校验，信息来源可能是证书拥有者本人。因此，用户可以选择中止导入操作。但是，如果给了 -noprompt 选项，则不会有与用户的交互。

alias 的新证书链将取代与该项关联的旧证书链。只有提供了有效的 keypass，即提供了用于保护该项的私钥的口令时，旧链才可被取代。如果没有提供口令，而且私钥口令与密钥仓库口令不同，用户将得到要求输入口令的提示。使用口令时必须小心 -- 参见与口令有关的警告。

-selfcert {-alias alias} {-sigalg sigalg} {-dname dname} {-validity valDays} [-keypass keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v} {-Jjavaoption}

利用密钥仓库信息（包括与 alias 关联的私钥和公钥）生成 X.509 v1 自签名证书。如果在命令行提供了 dname，它将同时用作该证书的签发人和主体的 X.500 特征名。否则，将使用与 alias 关联的 X.500 特征名（位于其现有证书链底部）。

所生成的证书作为 alias 所标识的密钥仓库项中的单元素证书链来储存，它将取代现有的证书链。

sigalg 指定签名证书时用的算法。参见支持的算法和密钥大小。

要访问私钥，必须提供正确的口令，因为私钥在密钥仓库中是受口令保护的。如果在命令行中没有提供 keypass，且私钥口令与保护密钥仓库完整性所用的口令不同，则用户将得到要求输入口令的提示。使用口令时必须小心 -- 参见与口令有关的警告。

valDays 指定证书的有效期。

-identitydb {-file idb_file} {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v} {-Jjavaoption}

从 idb_file 文件中读取 JDK 1.1.x 格式的身份数据库，并将它的项加到密钥仓库中。如果没有给出文件名，则从标准输入设备中读取身份数据库。如果不存在密钥仓库，则创建它。

只有被标记为可信任的身份数据库项（“身份”）才能被导入密钥仓库中。所有其它身份都将被略去。对每个可信任的身份，将创建一个密钥仓库项。身份名用作该密钥仓库项的“别名”。

所有可信任身份的私钥都将在相同的口令 storepass 下得到加密。该口令与保护密钥仓库完整性所用的口令相同。用户随后可用 keytool 命令选项“-keypasswd”来对各私钥赋予单独的口令。

身份数据库中的一个身份可以存放多个证书，各证书所认证的都是同一公钥。但一个私钥的密钥仓库密钥项含有该私钥和单一的“证书链”（该链最初只有一个证书），链中的第一个证书含有与该私钥对应的公钥。当从身份导入信息时，只有该身份中的第一个证书被储存到密钥仓库中。这是因为身份数据库中的身份名被用作其相应密钥仓库项的别名，而别名在密钥仓库中是唯一的。

导出数据

-certreq {-alias alias} {-sigalg sigalg} {-file certreq_file} [-keypass keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v} {-Jjavaoption}

生成 PKCS#10 格式的证书签名请求 (CSR)。

CSR 用来发送给认证机构 (CA)。CA 对认证请求者进行认证（通常是离线的），并返回证书或证书链，以取代密钥仓库中现有的证书链（该证书链最初只含有自签名证书）。

私钥和与 alias 关联的 X.500 特征名用于创建 PKCS#10 证书请求。要访问私钥，必须提供正确的口令，因为私钥在库中是受口令保护的。如果在命令行没有提供 keypass，且私钥口令与保护密钥仓库完整性所用的口令不同，则用户将得到要求输入口令的提示。

使用口令时必须小心 -- 参见与口令有关的警告。

sigalg 指定签名 CSR 时用的算法。参见支持的算法和密钥大小。

CSR 储存在文件 certreq_file 中。如果没有给出文件名，CSR 将被输出到标准输出设备中。

用 import 命令来导入 CA 所返回的答复。

-export {-alias alias} {-file cert_file} {-storetype storetype} {-keystore keystore} [-storepass storepass] {-rfc} {-v} {-Jjavaoption}

从密钥仓库中读取与 alias 关联的证书，并将其储存在文件 cert_file 中。

如果没有给出文件名，证书将被输出到标准输出设备中。

缺省情况下，证书被输出为二进制编码格式，但如果指定了 -rfc 选项，则将被输出为 Internet RFC 1421 标准中定义的可打印格式。

如果 alias 引用的是可信任证书，则该证书将被输出。否则，alias 引用的是含有相关证书链的密钥项。在这种情况下，链中的第一个证书将被返回。该证书对由 alias 所指定的实体的公钥进行认证。

显示数据

-list {-alias alias} {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v | -rfc} {-Jjavaoption}

打印（到标准输出设备中） alias 所标识的密钥仓库项的内容。如果没有指定别名，则将打印整个密钥仓库的内容。

缺省情况下，该命令打印证书的 MD5 指纹。如果指定了 -v 选项，证书将以可读格式打印，同时包含拥有者、签发人序列号等附加信息。如果指定了� -rfc 选项，证书将以 Internet RFC 1421 标准所定义的可打印的编码格式打印。

不能同时指定 -v 和 -rfc 两个选项。

-printcert {-file cert_file} {-v} {-Jjavaoption}

从文件 cert_file 中读取证书并以可读格式打印其内容。如果没有给出文件名，则从标准输入设备中读取证书。

证书可以是用二进制编码或 Internet RFC 1421 标准所定义的可打印编码格式。

注意：该选项的使用与密钥仓库无关。

管理密钥仓库

-keyclone {-alias alias} [-dest dest_alias] [-keypass keypass] [-new new_keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v} {-Jjavaoption}

生成新的密钥仓库项，该项含有的私钥和证书链与原始项的相同。

原始项由 alias 身份（如果没有提供，则其值缺省为“mykey”）。新（目标）项由 dest_alias 标识。如果没有在命令行中提供目标别名，用户将得到要求输入该信息的提示。

如果私钥口令与密钥仓库口令不同，那么，只有提供了有效的 keypass 时该项才能被复制。keypass 是用于保护与 alias 关联的私钥的口令。如果没有在命令行提供密钥口令，且私钥口令与密钥仓库口令不同，用户将得到要求输入口令的提示。如果愿意，可用不同的口令来保护复制项中的私钥。如果没有在命令行提供 -new 选项，用户将得到提示要求输入新项的口令（可以选择让该口令与被复制项的私钥所用的口令相同）。

使用口令时必须小心 -- 参见与口令有关的警告。

该命令可用于建立多个与给定密钥对相对应的证书链，或用于备份。

-storepasswd [-new new_storepass] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v} {-Jjavaoption}

更改保护密钥仓库内容的完整性所用的口令。新口令为 new_storepass，其长度必须至少是 6 个字符。

使用口令时必须小心 -- 参见与口令有关的警告。

-keypasswd {-alias alias} [-keypass old_keypass] [-new new_keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v} {-Jjavaoption}

把保护 alias 所标识的私钥的口令从 old_keypass 更改为 new_keypass。

如果没有在命令行上提供 keypass 选项，且私钥口令与密钥仓库口令不同，则用户将得到要求输入该口令的提示。

如果没有在命令行给出 -new 选项，则用户将得到要求输入新口令的提示。

使用口令时必须小心 -- 参见与口令有关的警告。

-delete [-alias alias] {-storetype storetype} {-keystore keystore} [-storepass storepass] {-v} {-Jjavaoption}

从密钥仓库中删除 alias 所标识的项。如果没有在命令行上提供别名，则用户将得到要求输入别名的提示。

获取帮助

-help

列出所有的命令及其选项。

 

示例

 

假设您要创建一个密钥仓库以管理您的公钥/私钥对和来自您所信任实体的证书。

生成密钥对

您首先要做的是创建一个密钥仓库和生成密钥对。您可以使用以下命令：

    keytool -genkey -dname "cn=Mark Jones, ou=JavaSoft, o=Sun, c=US"
      -alias business -keypass kpi135 -keystore C:\working\mykeystore
      -storepass ab987c -validity 180

（请注意：键入该命令时必须使其成为一行。此处用多行来显示，主要是为了可读性。）

该命令将在 C 盘的“working”目录（假设它还不存在）中创建名为“mykeystore”的密钥仓库，并赋予它口令“ab987c”。它将为实体生成公钥/私钥对，该实体的“特征名”为：常用名“Mark Jones”、组织单位“JavaSoft”、组织“Sun”和两个字母的国家代码“US”。它使用缺省的“DSA”密钥生成算法来创建密钥，两个密钥（公钥与私钥）的长度都是 1024 位。

它创建自签名证书（使用缺省的“带 DSA 的 SHA1”签名算法），该证书包括公钥和特征名信息。该证书的有效期为 180 天，且与别名“business”所代表的密钥仓库项关联。私钥被赋予口令“kpi135”。

如果采用选项的缺省值，可以大大缩短该命令。实际上，这些选项并不是必需的；对于有缺省值的选项，未指定时将使用缺省值，对于任何被要求的值，您将会得到要求输入它的提示。因此，您可以只使用下面的命令：

    keytool -genkey

这种情况下，将创建一个具有别名“mykey”的密钥仓库项，它含有新生成的密钥对和有效期为 90 天的证书。该项被放在您的宿主目录下一个名为“.keystore”的密钥仓库中（如果该密钥仓库并不存在，则将创建它）。您将得到要求输入特征名信息、密钥仓库口令和私钥口令的提示。

其余示例假设您执行了未指定选项的 -genkey 命令，且用上述第一个 -genkey 命令中给出的值来回答提示要求（私钥口令为“kpi135”等等）。

从认证机构请求已签名的证书

目前为止我们所具有的就是自签名证书。证书如果由认证机构 (CA) 签名，将更有可能得到别人的信任。要得到这样的签名，首先要用以下命令生成证书签名请求 (CSR)：

    keytool -certreq -file MarkJ.csr

这将为缺省别名“mykey”所标识的实体生成 CSR，并将此请求放在名为“MarkJ.csr”的文件中。将此文件提交给某个 CA（例如 VeriSign, Inc.）。该 CA 将对您这个请求者进行认证（通常是离线的），然后返回它们所签名的证书，用于认证您的公钥。（某些情况下，它们实际上将返回证书链，链中每个证书都认证前一个证书的签名人的公钥。）

导入 CA 的证书

自签名证书必须用证书链代替，链中的每个证书都认证前一个证书的签名人的公钥，直到“根”CA 为止。

在导入 CA 的答复之前，在您的密钥仓库中或 cacerts 密钥仓库文件（如导入命令中所述）中需要有一个或多个“可信任证书”：

 
• 如果该认证答复是个证书链，您只需要链中最顶部的证书（即用于认证根 CA 的公钥的“根” CA 证书）。
• 如果该认证答复是单个证书，您需要发放 CA（即签名该证书的认证机构）的证书，如果此证书不是自签名的，则需其签名人的证书，以此类推，直到自签名的“根” CA 证书为止。

“cacerts”密钥仓库文件发送时附有五个 VeriSign 根 CA 证书，因此您可能并不需要导入 VeriSign 证书以作为密钥仓库中的可信任证书。但如果您请求由另一个 CA 签名的证书，而认证该 CA 的公钥的证书未被加到“cacerts”中，则您需要将来自该 CA 的证书作为“可信任证书”导入。

来自 CA 的证书通常是自签名的或是由另一个 CA 签名的（这种情况下您还需要认证该 CA 的公钥的证书）。假设 ABC, Inc. 公司是 CA，而您从该公司获得一个声称是自签名证书的名为“ABCCA.cer”的文件，它用于认证该 CA 的公钥。

在将证书作为一个“可信任”证书导入之前，要十分小心，务必保证该证书是有效的！先查看一下（用 keytool -printcert 命令，或用不带 -noprompt 选项的 keytool -import 命令）以确保所显示的证书指纹与所预计的相匹配。然后可以给发送证书的人打电话，将您所看到的指纹与他们所提供的（或安全公钥储存库所显示的）进行比较。只有两者相等才可保证证书在传送途中没有被其它人（例如，攻击者）的证书所更换。如果发生了这样的攻击，而您未检查证书即将其导入，那么您就会信任攻击者所签名的任何东西。

如果您相信证书是有效的，就可以用以下命令将其加到密钥仓库中：

    keytool -import -alias abc -file ABCCA.cer

这将在密钥仓库中用文件“ABCCA.cer”中的数据创建“可信任证书”项，并将别名“abc”赋予该项。

导入来自 CA 的认证答复

一旦导入了用于认证 CA（该 CA 是您将证书签名请求送往之处）公钥的证书后，或在“cacerts”文件中已有这种证书时，就可以导入该认证答复，从而用证书链取代您的自签名证书。如果 CA 的答复是证书链，则该链是 CA 响应您的请求而返回的证书链；如果 CA 的答复是一个证书，则该链是用认证答复和可信任证书建立的证书链，这些可信任证书是密钥仓库（您要将认证答复导入之处）或“cacerts”密钥仓库文件中已有的。

例如，假设您将证书签名请求送往 VeriSign。您可用以下命令来导入认证答复，该命令假定所返回的证书名为“VSMarkJ.cer”：

    keytool -import -trustcacerts -file VSMarkJ.cer

导出用于认证您的公钥的证书

假设您用 jarsigner 工具来签名 Java 归档 (JAR) 文件。需要使用这一文件的客户机将认证您的签名。

认证签名的一种方法是先将您的公钥证书作为“可信任”项导入它们的密钥仓库中。您可以将证书导出并将其提供给客户机。例如，假设项的别名为“mykey”，您可以用以下命令将您的证书导出到名为 MJ.cer 的文件中：

    keytool -export -alias mykey -file MJ.cer

有了该证书以及已签名的 JAR 文件，客户机就可以用 jarsigner 工具来认证您的签名。

更改特征名但保留密钥对

假设，譬如说因为您换了部门或搬到另一个城市去了而改变了您的特征名。如果愿意，您仍然可以使用您先前使用的公钥/私钥对而只对特征名进行更新。例如，假设您的名字叫 Susan Miller，并用别名 sMiller 和以下的特征名创建了初始密钥项：

  "cn=Susan Miller, ou=Finance Department, o=BlueSoft, c=us"

假设您从财务部门换到了会计部门。您仍然可使用先前所生成的公钥/私钥对，而用以下方法对特征名进行更新。首先，复制您的密钥项：

    keytool -keyclone -alias sMiller -dest sMillerNew

（您将得到要求输入密钥仓库口令和初始密钥口令及目标密钥口令的提示，因为在命令行没有提供这些信息。）现在，您需要更改与复制项关联的证书链以使链中的第一个证书使用您的新特征名。先用相应名称生成自签名证书：

    keytool -selfcert -alias sMillerNew
      -dname "cn=Susan Miller, ou=Accounting Department, o=BlueSoft, c=us"

然后根据该新证书中的信息生成证书签名请求：

    keytool -certreq -alias sMillerNew

当您得到 CA 认证答复后，将其导入：

    keytool -import -alias sMillerNew -file VSSMillerNew.cer

导入认证答复后，您也许要删除使用旧特征名的初始密钥项：

    keytool -delete -alias sMiller

 

另请参阅

 

• jar 工具文档
• jarsigner 工具文档
• Java 教程中，JDK 1.2 中的安全性中 keytool 的使用示例

�