diff --git a/README.md b/README.md index f652a6f2..5d155799 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,10 @@ English | **[中文]** # Tencent Kona SM Suite ## Overview -Tencent Kona SM Suite is a set of Java security providers, which service the ShangMi applications in Java ecosystem. This suite contains four providers: +Tencent Kona SM Suite is a set of Java security providers, which service the ShangMi applications in Java ecosystem. This suite contains five providers: -- [KonaCrypto],which implements SM2, SM3 and SM4 algorithms based on Java Cryptography Architecture. There are two implementations: based on pure Java; based on JNI/OpenSSL. The former is enabled by default, however the latter supports only `Linux x86_64/aarch64` platforms. +- [KonaCrypto],which implements SM2, SM3 and SM4 algorithms based on Java Cryptography Architecture. +- [KonaCrypto-Native],which implements as the same features as `KonaCrypto` does. However, it is based on `JNI` and `OpenSSL` and supports only `Linux x86_64/aarch64` platforms. - [KonaPKIX],which supports ShangMi algorithms on loading certificate and certificate chain verification. It also can load and write keystores containing ShangMi certificates. Additionally, this component provides two utility classes: - KeyTool, which is the same as `keytool` in JDK, can generate private keys, and create certificates and keystores. It can use `PBEWithHmacSM3AndSM4` to encrypt private keys and keystores, and use `HmacPBESM3` to validate the integrity of keystores. - KeyStoreTool, which can import the existing [PEM]-encoded private keys and certificates to keystores. @@ -111,6 +112,9 @@ In addition, your problems may be already raised by others. Before open a new is [KonaCrypto]: +[KonaCrypto-Native]: + + [KonaPKIX]: diff --git a/README_cn.md b/README_cn.md index 9e9fd365..79a4ffb1 100644 --- a/README_cn.md +++ b/README_cn.md @@ -6,9 +6,10 @@ # 腾讯Kona国密套件 ## 概览 -腾讯Kona国密套件是一组Java安全特性的Provider实现,主要服务于Java生态中的国密应用场景。具体地,该套件包含有四个Provider: +腾讯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]格式的私钥和证书导入密钥库。 diff --git a/kona-crypto/README.md b/kona-crypto/README.md index ecc402a9..925ea3b1 100644 --- a/kona-crypto/README.md +++ b/kona-crypto/README.md @@ -3,7 +3,7 @@ English | **[中文]** # Tencent Kona Crypto ## Introduction -Tencent Kona Crypto is a Java security provider, which is named `KonaCrypto`. Per the associated China's specifications, it implements the following ShangMi algorithms: +Tencent Kona Crypto contains two Java security providers, one is `KonaCrypto` and the other is `KonaCrypto-Native`. Per the associated China's specifications, they implement the following ShangMi algorithms: - SM2, which is [Elliptic Curve Cryptography (ECC)]-based public key algorithm. It complies with the below national specifications: - GB/T 32918.1-2016 Part 1:General @@ -16,15 +16,18 @@ Tencent Kona Crypto is a Java security provider, which is named `KonaCrypto`. Pe - SM4, which is a block encryption algorithm. It complies with the below national specification: - GB/T 32907-2016 SM4 block cipher algorithm -For providing the above features, `KonaCrypto` implements the JDK-specified Service Provider Interfaces (SPIs), such as KeyPairGeneratorSpi,SignatureSpi,CipherSpi,MessageDigestSpi,MacSpi and KeyAgreementSpi. +For providing the above features, the providers implements the JDK-specified Service Provider Interfaces (SPIs), such as KeyPairGeneratorSpi,SignatureSpi,CipherSpi,MessageDigestSpi,MacSpi and KeyAgreementSpi. ## Implementations -Tencent Kona Crypto provides pure Java-based and JNI/OpenSSL-based SM2, SM3 and SM4. The latter supports `Linux x86_64/aarch64` platforms. OpenSSL version 3.4.0 is used by default, but versions 3.0 and later can be supported. +Tencent Kona Crypto provides pure Java-based implementations via provider `KonaCrypto`, and JNI and OpenSSL-based implementations via provider `KonaCrypto-Native`. The latter provider supports `Linux x86_64/aarch64` platforms. OpenSSL version 3.4.0 is used by default, but versions 3.0 and later can be supported. -The pure Java-based implementations is enabled. The java system property `com.tencent.kona.useNativeCrypto` can be used to enable the OpenSSL-based implementation. The additional system property `com.tencent.kona.openssl.crypto.lib.path` is used to specify an alternative local OpenSSL crypto lib file (`libcrypto.so`). The value of this property is a local absolute path. +The system property `com.tencent.kona.openssl.crypto.lib.path` is used to specify an alternative OpenSSL crypto lib file (`libcrypto.so`). The value of this property is a local absolute path. ## Usages + +The application can use `KonaCrypto` and `KonaCrypto-Native` on the same way, so this doc just describe the usages with provider `KonaCrypto`. + Now that `KonaCrypto` is based on JCA framework, then the usages are the same as other JCA implementations, such as [SunJCE] and [SunEC]. Understanding the design and coding style on JCA really helps for applying `KonaCrypto`, please read the official [JCA reference]. ### Loading diff --git a/kona-crypto/README_cn.md b/kona-crypto/README_cn.md index a16c1f1b..951e22fe 100644 --- a/kona-crypto/README_cn.md +++ b/kona-crypto/README_cn.md @@ -3,7 +3,7 @@ # 腾讯Kona Crypto ## 简介 -腾讯Kona Crypto是一个Java安全Provider实现,其Provider名称为`KonaCrypto`。它遵循相关的国家标准实现了如下的国密基础算法: +腾讯Kona Crypto包含两个Java Security Provider,一个是`KonaCrypto`,另一个是`KonaCrypto-Native`。它们遵循相关的国家标准实现了如下的国密基础算法: - SM2,它是一个基于[椭圆曲线(ECC)]的公钥加密算法,在实现该算法时遵循了如下的国家标准: - GB/T 32918.1-2016 第1部分:总则 @@ -16,15 +16,18 @@ - SM4,它是一个分组加密算法,在实现该算法时遵循了如下的国家标准: - GB/T 32907-2016 SM4分组密码算法 -为了提供上述特性,`KonaCrypto`基于JDK标准的[Java Cryptography Architecture (JCA)]框架,实现了JDK定义的KeyPairGeneratorSpi,SignatureSpi,CipherSpi,MessageDigestSpi,MacSpi和KeyAgreementSpi等Service Provider Interface (SPI)。 +为了提供上述特性,这些Provider基于JDK标准的[Java Cryptography Architecture (JCA)]框架,实现了JDK定义的KeyPairGeneratorSpi,SignatureSpi,CipherSpi,MessageDigestSpi,MacSpi和KeyAgreementSpi等Service Provider Interface (SPI)。 ## 实现方式 -目前既提供了基于纯Java语言和基于JNI与OpenSSL实现的SM2,SM3和SM4算法。后者仅支持`Linux x86_64/aarch64`平台。本项目默认使用的OpenSSL版本为3.4.0,但可以支持3.0及之后的版本。 +目前提供了纯Java语言实现的`KonaCrypto` Provider,以及基于JNI与OpenSSL实现的`KonaCrypto-Native` Provider。后者仅支持`Linux x86_64/aarch64`平台。本项目默认使用的OpenSSL版本为3.4.0,但可以支持3.0及之后的版本。 -默认地,启用纯Java的实现。若要启用基于OpenSSL的实现,需要设置系统属性`com.tencent.kona.useNativeCrypto`的值为`true`。另外,还提供了系统属性`com.tencent.kona.openssl.crypto.lib.path`以指定使用本地的其他OpenSSL crypto库文件(`libcrypto.so`),该系统属性的值是一个本地绝对路径。 +可以使用系统属性`com.tencent.kona.openssl.crypto.lib.path`去指定使用其他的OpenSSL crypto库文件(`libcrypto.so`),该系统属性的值是一个本地绝对路径。 ## 使用 + +应用程序使用`KonaCrypto`和`KonaCrypto-Native`的方法完全相同,所以本文仅以`KonaCrypto`为例来描述用法。 + 由于`KonaCrypto`是基于JCA框架的,所以在使用风格上,与其它的JCA实现(如JDK自带的[SunJCE]和[SunEC])是一样的。正常地,应用程序并不需要直接访问`KonaCrypto`中的算法实现类,而是通过相关的JDK API去调用指定算法的实现。了解JCA的设计原理与代码风格,对于应用`KonaCrypto`是非常有帮助的,请阅读官方的[参考指南]。 ### 加载