Skip to content

Latest commit

 

History

History
167 lines (116 loc) · 8.5 KB

README_cn.md

File metadata and controls

167 lines (116 loc) · 8.5 KB
Raw

Release Maven Central

English | 中文

腾讯Kona国密套件

概览

腾讯Kona国密套件是一组Java安全特性的Provider实现，主要服务于Java生态中的国密应用场景。具体地，该套件包含有五个Provider：

  • KonaCrypto，它遵循标准的JCA框架实现了国密密码学算法SM2，SM3和SM4。在实现方式上，分为基于纯Java的实现和基于JNI/OpenSSL的实现。默认启用前者，而后者仅支持Linux x86_64/aarch64平台。
  • [KonaCrypto-Native]，它实现的特性与KonaCrypto相同。然而，它是基于JNI和OpenSSL的，并且仅支持Linux x86_64/aarch64平台。
  • KonaPKIX，它实现了国密证书的解析与验证，并可加载和创建包含国密证书的密钥库。它需要依赖KonaCrypto。另外，该组件还提供了两个工具类：
    • KeyTool，它的功能与JDK中的keytool相同，可以生成密钥对，创建证书以及密钥库。它支持使用PBEWithHmacSM3AndSM4算法对私钥和密钥库进行加密，也可使用HmacPBESM3算法验证密钥库的完整性。
    • KeyStoreTool，它可以将已有的PEM格式的私钥和证书导入密钥库。
  • KonaSSL，它实现了中国的传输层密码协议（TLCP），并遵循RFC 8998规范将国密基础算法应用到了TLS 1.3协议中。它需要依赖KonaCrypto和KonaPKIX。
  • Kona，它将KonaCrypto，KonaPKIX和KonaSSL中的特性进行了简单的封装，所以它需要根据实际需求去依赖这些Provider中的一个或多个。一般地，建议使用这个Provider。

本项目还提供了一个Spring Boot模块，即kona-demo，作为服务端的示例。该模块演示了将腾讯Kona国密套件集成入第三方Web服务器，包括Jetty和Tomcat，的途径。但该模块并不是本项目的制品之一。另外，kona-ssl模块的测试集还提供了与Netty，gRPC，Apache HttpClient和OkHttp进行集成的示例。

系统要求

操作系统

腾讯Kona国密套件可以运行在任何支持JDK的操作系统上。

JDK

腾讯Kona国密套件支持JDK的全部四个长期支持（LTS）版本，即8，11，17和21。

注意：已经使用Oracle颁发的JCE代码签名证书对本套组件的jar文件签名，所以它们也可以运行在Oracle JDK上。

欢迎使用腾讯的OpenJDK发行版，即Tencent Kona JDK，它提供四个长期支持（LTS）版本8，11，17和21，支持Linux，macOS和Windows等主流操作系统以及x86_64和aarch64等主流CPU架构。最新的Tencent Kona JDK 8和17已经原生地支持了国密密码学算法，国密SSL/TLCP协议和RFC 8998规范。

Android

默认情况下，腾讯Kona国密套件并不需要依赖JDK的任何内部API实现，所以它也可以运行Android平台上。

安装

腾讯Kona国密套件的所有制品（jar文件）都已经上传到了Maven中央仓库。一般地，只需要在项目的构建脚本中把它们声明为依赖就可以了。比如，在Gradle的构建脚本中可以有如下的依赖声明，

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.tencent.kona:kona-crypto:<version>")
    implementation("com.tencent.kona:kona-pkix:<version>")
    implementation("com.tencent.kona:kona-ssl:<version>")
    implementation("com.tencent.kona:kona-provider:<version>")
}

注意，并不一定要将所有的Provider都加到类路径中，请根据实际需求去声明依赖。例如，只需要使用国密的密码学算法，且想使用Provider名称Kona时，那么依赖声明可能就像下面这样，

dependencies {
    implementation("com.tencent.kona:kona-crypto:<version>")
    implementation("com.tencent.kona:kona-provider:<version>")
}

构建

腾讯Kona国密套件使用Gradle进行构建，其脚本使用Kotlin DSL。该Gradle项目包含有四个子模块，即kona-crypto，kona-pkix，kona-ssl和kona-provider，它们分别对应于四个Provider，即KonaCrypto，KonaPKIX，KonaSSL和Kona。

构建该项目的一个典型方法就是在项目的根目录下执行命令：

./gradlew build

它会编译源代码，并执行单元测试，最后制作出jar文件。也可以仅构建某个子模块，比如像下面这样：

./gradlew :kona-pkix:build

贡献

非常欢迎与我们一起改进和维护腾讯Kona国密套件，请阅读CONTRIBUTING.md以了解如何报告缺陷，安全漏洞，提出需求和贡献代码。

许可协议

腾讯Kona国密套件使用的许可协议是GNU GPL v2.0 license with classpath exception，请详见附带的许可协议文本。

常见问题

问：为何使用SM2 Cipher时会遇到异常java.security.InvalidKeyException: Illegal key size or default parameters？
答：在JDK 8u161之前，JDK默认不能支持较强的加密算法和密钥长度。它们就不能支持256位长度的加密算法，如AES-256。而SM2加密算法的密钥长度也是256，所以也存在这个问题。具体解决方法，请见这个Stack Overflow的问题。

问：能否在TLS 1.2中支持ECC_SM4_GCM_SM3和ECDHE_SM4_GCM_SM3？
答：由于没有任何RFC规范将国密密码套件引入TLS 1.2协议，所以无法在该协议中支持上述密码套件。但本项目基于RFC 8998支持在TLS 1.3协议中使用国密密码套件TLS_SM4_GCM_SM3。

问：是否支持GMSSL或GMSSL 1.1协议？
答：国家标准GB/T 38636-2020定义的这个类TLS安全通信协议是传输层密码协议，其英文为Transport layer cryptography protocol。本组件使用它的简称TLCP，版本为1.1。而TLCP或TLCP 1.1就是GMSSL或GMSSL 1.1。

问：为什么不能在Oracle JDK下执行本项目中的测试用例？
答：Oracle JDK会验证JCE实现（此处为KonaCrypto）是否被签名，并且其关联的证书要由JCE Code Signing CA颁发。而在执行本项目中的测试用例时，其使用的KonaCrypto Provider还没有签名，所以不能在Oracle JDK中执行它们。但发布到Maven中央仓库中的jar文件都被签名了，所以它们都可以在Oracle JDK中运行。

问：本项目与BoucyCastle中的国密实现有何关系？
答：本项目的早期版本会依赖BouncyCastle中的国密密码学算法，但从1.0.5版开始，已经不再对BouncyCastle有任何的依赖。由于都是遵循中国相关标准来实现的国密密码学算法，所以这两个组件之间可以正常交互。另外，需要了解的是，BouncyCastle并不支持国密安全通信协议，包括TLCP和TLS 1.3/RFC 8998。

问：可以支持的JDK 8最低版本是多少？
答：根据不同的应用场景，对JDK 8的版本的要求也不尽相同。

  • 仅使用国密密码学算法和/或TLCP协议，最多需要8u141（甚至更老的版本)。
    • 要在TLCP协议中使用ALPN扩展，要求的最低版本则为8u251。
  • 为了使用TLS 1.3/RFC 8998协议，要求的最低版本为8u261。

你所遇到的问题，之前可能已经有人提出来过了。在提出新的问题之前，请先浏览这些已有的问题。