cert-toolkit使用¶
前置依赖¶
在使用本组件前，请确认系统环境已安装相关依赖软件，清单如下：
| 依赖软件 | 说明 | 备注 |
|---|---|---|
| Java | JDK[1.8] | |
| Git | 下载的安装包使用Git |
如果您还未安装这些依赖，请参考附录。
重要
FISCO-BCOS 2.0与3.0对比、JDK版本、WeBankBlockChain-Governance及其他子系统的 兼容版本说明
部署说明¶
目前支持从源码进行部署。
获取源码¶
通过git下载源码：
git clone https://github.com/WeBankBlockchain/Governance-Cert.git
注解
如果因为网络问题导致长时间无法下载，请尝试：git clone https://gitee.com/WeBankBlockchain/Governance-Cert.git
进入目录：
cd Governance-Cert
cd cert-toolkit
编译源码¶
方式一：如果服务器已安装Gradle
gradle build -x test
方式二：如果服务器未安装Gradle，使用gradlew编译
chmod +x ./gradlew && ./gradlew build -x test
导入jar包¶
cert-toolkit编译之后在cert-toolkit目录下会生成dist文件夹，文件夹中包含cert-toolkit.jar。可以将cert-toolkit.jar导入到自己的项目中，例如libs目录下。然后进行依赖配置。gradle依赖配置如下，然后再对自己的项目进行编译。
repositories {
maven {
url "http://maven.aliyun.com/nexus/content/groups/public/"
}
maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
maven { url "https://dl.bintray.com/ethereum/maven/" }
mavenLocal()
jcenter()
}
dependencies {
testCompile 'junit:junit:4.12'
compile 'org.slf4j:slf4j-api:1.7.30'
compile ('org.projectlombok:lombok:1.18.6')
annotationProcessor ('org.projectlombok:lombok:1.18.6')
compile('ch.qos.logback:logback-core:1.2.3')
compile('ch.qos.logback:logback-classic:1.2.3')
compile "org.apache.commons:commons-lang3:3.6"
compile "commons-io:commons-io:2.6"
compile 'commons-codec:commons-codec:1.4'
compile 'com.lhalcyon:bip32:1.0.0'
compile 'org.web3j:core:3.4.0'
compile 'com.lambdaworks:scrypt:1.4.0'
compile group: 'org.bouncycastle', name: 'bcprov-jdk15on', version: '1.60'
compile group: 'org.bouncycastle', name: 'bcpkix-jdk15on', version: '1.60'
compile fileTree(dir:'libs',include:['*.jar'])
}
示例说明¶
下面介绍下证书的生成流程
根证书生成¶
根据生成的私钥自签名生成根证书，可以指定私钥也可选择自动生成，组件封装了多种入参方法，可按需使用，参照根证书生成
以generateKPAndRootCert方法为例，示例代码如下：
CertService certService = new CertService();
X500NameInfo info = X500NameInfo.builder()
.commonName("chain")
.organizationName("fisco-bcos")
.organizationalUnitName("chain")
.build();
//自动生成私钥（默认为RSA），并写入指定路径"out/ca"，
certService.generateKPAndRootCert(info,"out/ca");
执行上述方法，会在控制台打印出证书、私钥文件保存结果和路径，证书会保存在out/ca/ca.crt文件中
子证书csr生成¶
csr全称为Certificate Signing Request，即证书请求文件，根（父）证书通过其私钥对请求文件签名来颁发子证书
csr的生成提供了多种入参方法，参照证书申请生成
以generateCertRequestByDefaultConf为例，可快速生成csr，示例代码如下：
CertService certService = new CertService();
X500NameInfo info = X500NameInfo.builder()
.commonName("chain")
.organizationName("fisco-bcos")
.organizationalUnitName("chain")
.build();
//自动生成RSA私钥，KeyUtils为证书组件密钥工具类
KeyPair keyPair = KeyUtils.generateKeyPair();
//CertUtils工具提供了证书读写解析的相关能力
String priStr = CertUtils.readPEMAsString(keyPair.getPrivate());
String csrStr = certService.generateCertRequestByDefaultConf(info, priStr, "out/agency", "agency");
System.out.println(csrStr);
执行上述方法会在控制台打印出csr文件内容，并写入out/agency/agency.csr文件中
其中涉及的CertUtils工具类，该类提供了证书读写解析的相关能力，参照CertUtils详情
子证书颁发¶
通过根证书和其私钥对子证书申请进行签发, 提供多种入参方法，参照子证书签发
以文件路径为入参示例，示例代码如下：
//参数为生成相关文件路径
CertService certService = new CertService();
String childStr2 = certService.generateChildCertByDefaultConf("out/ca/ca.crt","out/agency/agency.csr","out/ca/ca_pri.key", "out/agency" ,
"agency");
System.out.println(childStr2);
执行上述方法会在控制台打印出子证书内容,并写入out/agency/agency.crt文件中，可从第二步开始，继续下一级证书的签发。
证书链验证¶
上述步骤中我们生成了多级证书，对生成的证书链进行验证，查看证书是否有效
示例代码如下：
CertService certService = new CertService();
try {
X509Certificate root = null;
root = CertUtils.readCrt("out/ca/ca.crt");
X509Certificate child = CertUtils.readCrt("out/agency/agency.crt");
List<X509Certificate> certChain = new ArrayList<>();
//可添加多级证书...这里以上述步骤中生成的两个证书为例
certChain.add(root);
certChain.add(child);
System.out.println("证书链验证结果 = " + certService.verify(root, certChain));
} catch (CertificateException | FileNotFoundException e) {
e.printStackTrace();
}
执行上述方法，可以在控制台看到证书链的验证结果为true，表明证书链的有效性
证书撤销¶
我们可以对有效期内的证书进行吊销操作
CertService certService = new CertService();
try {
//从文件中读取证书（上述步骤中生成的证书路径）
X509Certificate root = CertUtils.readCrt("out/ca/ca.crt");
X509Certificate child = CertUtils.readCrt("out/agency/agency.crt");
//从文件中读取私钥（上述步骤中生成的私钥路径）
PrivateKey caPrivateKey = (PrivateKey) CertUtils.readRSAKey("out/ca/ca_pri.key");
List<X509Certificate> revokeCertificates = new ArrayList<>();
revokeCertificates.add(child);
//撤销上述步骤中签发的子证书
X509CRL X509Crl = certService.createCRL(root,caPrivateKey,revokeCertificates,"SHA256WITHRSA");
System.out.println("吊销证书路径：out/agency/agency.crt");
X509Crl.getRevokedCertificates().forEach(x509CRLEntry -> {
System.out.println("吊销证书序列号：" + x509CRLEntry.getSerialNumber());
});
//验证吊销证书后的证书链
List<X509Certificate> certChain = new ArrayList<>();
//可添加多级证书...这里以上述步骤中生成的两个证书为例
certChain.add(root);
certChain.add(child);
System.out.println("证书链验证结果 = " + certService.verify(root,certChain,X509Crl));
} catch (Exception e) {
e.printStackTrace();
}
执行上述方法，可以在控制台看到吊销后的证书链验证结果为false，表明该子证书已经失效
PFX证书读写¶
crt证书只包含公钥信息
pfx由PKCS#12（Public Key Cryptography Standards #12）标准定义，包含了公钥和私钥信息。
CertUtils工具类提供了pfx的生成和读取方法，示例代码如下:
try {
List<X509Certificate> list = new ArrayList<>();
list.add(CertUtils.readCrt("out/ca/ca.crt"));
//生成pfx文件，参数分别为：证书别名，私钥，keyStore密码，证书信息，保存路径，证书名
CertUtils.savePfx("fisco",(PrivateKey) CertUtils.readRSAKey("out/ca/ca_pri.key"),"123",list,"out/ca","ca");
//从pfx中导出私钥信息
PrivateKey key = CertUtils.readPriKeyFromPfx("out/ca/ca.pfx","123");
//在控制台输出导出私钥的BASE64编码信息
System.out.println(Base64.toBase64String(key.getEncoded()));
} catch (Exception e) {
e.printStackTrace();
}
执行上述方法，可以在out/ca路径下看到ca.pfx证书文件的生成，以及从该pfx文件中导出的私钥Base64编码信息
接口说明¶
CertService提供了多种功能接口：
createRootCertificate：生成根证书，即自签名证书
createCertRequest：生成证书请求
createChildCertificate：生成子证书
verify：验证证书
createCRL：吊销证书
为方便调用，针对上述接口封装了默认配置（签名算法：SHA256WITHRSA,有效期10年）的生成接口：
generateRootCertByDefaultConf：生成根证书
generateCertRequestByDefaultConf：生成证书请求
generateChildCertByDefaultConf：生成子证书
generateKPAndRootCert：生成密钥对和根证书
KeyUtils和CertUtils两个工具类，提供了对证书和私钥的相关读写操作。
更多参照Java doc