## 1. Project Overview & Quickstart (Tencent/Hippy) ## File: README.md # Hippy Cross Platform Framework [](https://github.com/Tencent/Hippy/blob/master/LICENSE) [](https://github.com/Tencent/Hippy/pulls) [](https://github.com/Tencent/Hippy/actions) [](https://codecov.io/gh/Tencent/Hippy) [](https://github.com/Tencent/Hippy/releases) [Homepage](https://framework.tds.qq.com) ## 💡 Introduction Hippy is a cross-platform development framework, that aims to help developers write once, and run on multiple platforms(iOS, Android, Web, and so on). Hippy is quite friendly to Web developers, especially those who are familiar with React or Vue. With Hippy, developers can create the cross-platform app easily. Hippy is now applied in [Tencent](http://www.tencent.com/) major apps such as Mobile QQ, Mobile QQ Browser, Tencent Video App, QQ Music App, and Tencent News, reaching hundreds of millions of ordinary users. ## 💯 Advantages * Designed for Web developers, officially support Web frameworks like `React` and `Vue`. * Same APIs for different platforms. * Excellent performance with JS engine binding communication. * Build-in recyclable component with better performance. * Smoothly and gracefully migrate to Web browser. * Fully supported Flex [Layout engine](https://github.com/Tencent/taitank). ## 🔨 Getting started ### Preparing environment Make sure you have [git](https://git-scm.com/) and [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed locally. Run `git clone https://github.com/Tencent/Hippy.git` and `npm install` at project root directory. > The Hippy repository applies [git-lfs](https://git-lfs.github.com/) to manage so,gz,otf files, make sure you have installed [git-lfs](https://git-lfs.github.com/) first. For macOS developers: * [Xcode](https://developer.apple.com/xcode/) with iOS sdk: build the iOS app. * [Android Studio](https://developer.android.com/studio) with NDK: build the android app. * [Node.JS](https://nodejs.org/en/): run the build scripts. [homebrew](https://brew.sh/) is recommended to install the dependencies. For Windows developers: * [Android Studio](https://developer.android.com/studio) with NDK: build the android app. * [Node.JS](https://nodejs.org/en/): run the build scripts. > Windows can't run the iOS development environment so far. ### Build the iOS simulator with js demo For iOS, we recommend to use iOS simulator when first try. However, you can change the Xcode configuration to install the app to iPhone if you are an iOS expert. 1. `cd` to `driver/js/`. 2. Run `npm run init`. > This command is combined with `npm install && npx lerna bootstrap && npm run build`. > > `npm install`: Install the project build scripts dependencies. > > `npx lerna bootstrap`: Install dependencies of each npm package.（Hippy uses [Lerna](https://lerna.js.org/) to manage multi js packages, if `lerna` command is not found, execute `npm install lerna -g` first.） > > `npm run build`: Build each front-end sdk package. 3. Choose a demo to build with `npm run buildexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo]`. 4. Install CocoaPods with `brew install cocoapods`, install cmake with `brew install cmake`, then execute `pod install` command at `framework/examples/ios-demo` directory, which will create `HippyDemo.xcworkspace` files and install Cocoapods dependencies. 5. Start the Xcode and build the iOS app with opening `framework/examples/ios-demo/HippyDemo.xcworkspace`. > If `Step 2` throw error, you can `cd` to `driver/js/examples` hippy-react-demo or hippy-vue-demo, and run `npm install` to install demo dependencies first. > > More details for [iOS SDK integration](https://doc.openhippy.com/#/development/ios-3.0-integration-guidelines). ### Build the Android app with js demo For Android, we recommend using the real cellphone for better develop experience, because Hippy is using [X5](https://x5.tencent.com/) JS engine which can't support x86 simulator, as well as ARM simulator has a low performance. Before build the android app, please make sure the SDK and NDK is installed, And *DO NOT* update the build toolchain. 1. `cd` to `driver/js/`. 2. Run `npm run init`. > This command is combined with `npm install && npx lerna bootstrap && npm run build`. > > `npm install`: Install the project build scripts dependencies. > > `npx lerna bootstrap`: Install dependencies of each npm package.（Hippy uses [Lerna](https://lerna.js.org/) to manage multi js packages, if `lerna` command is not found, execute `npm install lerna -g` first.） > > `npm run build`: Build each front-end sdk package. 3. Choose a demo to build with `npm run buildexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo]`. 4. Open the `Hippy Project` at root directory with Android Studio. 5. Connect Android phone with USB cable and make sure USB debugging mode is enabled(Run `adb devices` on the computer terminal to check cellphone connection status). 6. Open the project with Android Studio, run and install the apk. > If `Step 2` throw error, you can `cd` to `driver/js/examples` hippy-react-demo, hippy-vue-demo or hippy-vue-next-demo, and run `npm install` to install demo dependencies first. > > If you encounter the issue of `No toolchains found in the NDK toolchains folder for ABI with prefix: mips64el-linux-android`, here is the [solution](https://github.com/google/filament/issues/15#issuecomment-415423557). > > More details for [Android SDK integration](https://doc.openhippy.com/#/development/android-3.0-integration-guidelines). ### Debug the js demo 1. Follow [Build the iOS simulator with js demo](https://github.com/Tencent/Hippy#build-the-ios-simulator-with-js-demo) or [Build the Android app with js demo](https://github.com/Tencent/Hippy#build-the-android-app-with-js-demo) first to build the App. 2. `cd` to `driver/js/`. 3. Run `npm run init:example [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo]`. 4. Run `npm run debugexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo] dev`. > Or you can `cd` to `driver/js/examples/hippy-react-demo`, `driver/js/examples/hippy-vue-demo` or `driver/js/examples/hippy-vue-next-demo` directory to run `npm run hippy:dev` instead. > > On example debug mode, npm packages such as @hippy/react, @hippy/vue, @hippy/vue-next are linked to `driver/js/packages` > `[different package]` > `dist`(not node_modules), so if you have changed js package source code and want to make it take effect in target example, please call `npm run build` again. > > More details for debugging can be read in [Hippy Debug Document](https://doc.openhippy.com/#/development/debug). ### Build the js production demo 1. Follow [Build the iOS simulator with js demo](https://github.com/Tencent/Hippy#build-the-ios-simulator-with-js-demo) or [Build the Android app with js demo](https://github.com/Tencent/Hippy#build-the-android-app-with-js-demo) first to build the App. 2. `cd` to `driver/js/examples/hippy-react-demo`, `driver/js/examples/hippy-vue-demo` or `driver/js/examples/hippy-vue-next-demo`. 3. Run `npm install` to install demo js dependencies. 4. Run `npm run hippy:vendor` and `npm run hippy:build` in sequence to build the production `vendor.[android|ios].js` and `index.[android|ios].js`. > Hippy demo uses DllPlugin to split the common chunk and app chunk. ## 📁 Documentation To check out [hippy examples](https://github.com/Tencent/Hippy/tree/master/examples) and visit [framework.tds.qq.com](https://framework.tds.qq.com/). ## 📅 Changelog Detailed changes for each release version are documented in the [project release notes](https://github.com/Tencent/Hippy/releases). ## 🧱 Project structure ```text Hippy ├── devtools # Devtools for Hippy. ├── dom # DOM Layer for Hippy. ├── driver # Different UI Driver Layers for Hippy. │   └── js # JS Driver Layer for Hippy. │   ├── examples # Related examples for JS Driver. │   ├── include │   ├── packages # Related JS Packages for JS Driver. │   │   ├── hippy-react │   │   ├── hippy-react-web │   │   ├── hippy-vue │   │   ├── hippy-vue-css-loader │   │   ├── hippy-vue-loader │   │   ├── hippy-vue-native-components │   │   └── hippy-vue-router │   └── src ├── framework │   ├── android │   ├── examples │   │   ├── android-demo │   │   └── ios-demo │   └── ios ├── layout # Layout engine for Hippy. ├── modules │   ├── android │   └── footstone ├── renderer # Different Renderers for Hippy. │   ├── flutter │   └── native │   ├── android │   └── ios └── static ``` ## 🤝 Contribution Developers are welcome to contribute to Tencent's open source, and we will also give them incentives to acknowledge and thank them. Here we provide an official description of Tencent's open source contribution. Specific contribution rules for each project are formulated by the project team. Developers can choose the appropriate project and participate according to the corresponding rules. The Tencent Project Management Committee will report regularly to qualified contributors and awards will be issued by the official contact. Before making a pull request or issue to Hippy, please make sure to read [Contributing Guide](https://github.com/Tencent/Hippy/blob/master/.github/CONTRIBUTING.md). All the people who already contributed to Hippy can be seen in [Contributors](https://github.com/Tencent/Hippy/graphs/contributors) and [Authors File](https://github.com/Tencent/Hippy/blob/master/AUTHORS). ## ❤️ Stargazers over time [](https://starchart.cc/Tencent/Hippy) ## 📄 License Hippy is [Apache-2.0 licensed](./LICENSE). ## 🔗 Links [Hippy Eco-System](https://github.com/hippy-contrib) [Taitank Layout Engine](https://github.com/Tencent/Taitank) --- ## File: docs/index.md

Hippy

为开发者设计的跨端框架 [GitHub](//github.com/Tencent/Hippy) [开始接入](#/guide/integration)

⚡ 高性能

提供极致流畅体验的可复用列表，通过 binding 模式实现高效的前端-终端通讯。

📱 跨平台

不同的平台保持了相同的接口，可平滑迁移到 Web 浏览器。

📚 易学习

支持 React 和 Vue 两套界面框架，完整支持 Flex 布局。
# Hippy 概述 Hippy 可以理解为一个精简版的浏览器，从底层做了大量工作，抹平了 iOS 和 Android 双端差异，提供了接近 Web 的开发体验，目前上层支持了 React 和 Vue 两套界面框架，前端开发人员可以通过它，将前端代码转换为终端的原生指令，进行原生终端 App 的开发。 同时，Hippy 从底层进行了大量优化，在启动速度、可复用列表组件、渲染效率、动画速度、网络通信等方面都提供了业内顶尖的性能表现。 ## 功能对比 Hippy 从底层增加了很多和浏览器相同的接口，方便了开发者使用，这里有几个 Hippy 的独有功能。 | 分类 | 特性 | 说明 | 支持情况 | | ---- | ------------------------ | ------------------------ | -------- | | 接口 | fetch | Http/Https 协议请求 | ✅ 支持 | | | WebSocket | 基于 Http 协议的即时通讯 | ✅ 支持 | | 事件 | onClick | 点击事件 | ✅ 支持 | | | onTouchStart/onTouchDown | 触屏开始事件 | ✅ 支持 | | | onTouchMove | 触屏移动事件 | ✅ 支持 | | | onTouchEnd | 触屏结束事件 | ✅ 支持 | | | onTouchCancel | 触屏取消事件 | ✅ 支持 | | 样式 | zIndex | 界面层级 | ✅ 支持 | | | backgroundImage | 背景图片 | ✅ 支持 | ## 包体积 Hippy 的包体积在业内也是非常具有竞争力的。 上图是一个空的APK，在引入后终端包大小对比。 上图是在前端搭建了一个最简单的 ListView 后，前端打出的 JS 的包大小对比。 ## 渲染性能 ListView 在滑动时的性能对比，Hippy 可以一直保持十分流畅的状态 ## 内存占用 而在内存占用上，初始化 List 时 Hippy 就略占优势，在滑动了几屏后内存开销的差距越来越大。 ## 跟 Web 接近的开发体验 Hippy 在开发体验上也进行了大量优化，包含但不限于，跟浏览器一样的 onClick、onTouch 系列触屏事件，更加简单的动画方案，hippy-vue 提供了和 Vue 的完全兼容等等。 ## 大家都在用 QQ浏览器 手机QQ 腾讯新闻 全民K歌 QQ音乐 腾讯地图 王者营地 闪现 云视听极光 Start云游戏(TV) 微视 应用宝 理财通 腾讯自选股 NOW直播 心悦俱乐部 WiFi管家 大丰满满 企鹅号 VOOV直播 ## 团队贡献 TME 全民K歌团队 TME QQ音乐团队 CDG大丰满满/自选股团队 QGraphics团队 IVWEB团队 游云南WII团队 ## 贡献者 Super Zheng XQ Kuang siguangli2018 luomy churchill-zhang old kidd Zoom Chan ilikethese Box Tsang jerome han tsangint RonkTsang Elf Sundae 三点 dequanzhu kassadin Arylo Yeung ## 交流链接 * [文章专栏](https://cloud.tencent.com/developer/column/84006) * 企业微信交流群，使用微信或者企业微信扫描加入 ## 总结 如果您准备好了，那就 [开始接入 Hippy](guide/integration.md) 吧。 --- ## File: docs/README.md # Hippy 简介 版本：3.3.7 更新时间：2025-09-25 SDK介绍：Hippy 是腾讯端框架（Tencent Device-oriented Service Framework）下的开源跨平台应用开发解决方案。Hippy 可以理解为一个精简版的浏览器，从底层做了大量工作，抹平了 iOS、Android、Ohos 三端差异，提供了接近 Web 的开发体验，目前上层支持了 React 和 Vue 两套界面框架，前端开发人员可以通过它，将前端代码转换为终端的原生指令，进行原生终端 App 的开发。同时，Hippy 从底层进行了大量优化，在启动速度、渲染性能、动画速度、内存占用、包体积等方面都提供了业内顶尖的性能表现。 更新日志：[Change log](https://github.com/Tencent/Hippy/releases) 服务提供方：深圳市腾讯计算机系统有限公司 [接入指引](development/react-vue-3.0-integration-guidelines.md) [Hippy SDK隐私保护指引](development/privacy.md) ## 和 Web 接近的开发体验 * Hippy 对齐浏览器 DOM 的事件、网络、日志、定时器、Performance 等API, 前端开发同学没有太高的学习成本。 * Hippy-Vue、Hippy-React兼容 Vue 和 React 框架, 使用 Vue、React 开发的 Web 项目基本无缝迁移。 * 完全支持 Flex 布局, 和常用的 CSS 属性。 * 兼容 Webpack/Rollup 等打包工具, 支持分包, 代码动态加载, 有完善的 devtools 工具, 对齐前端的开发体验。 ## 一次开发，多端运行 使用 Hippy 框架开发后，代码可以同时运行在 Android、iOS、Ohos、Web等多个平台。 ## 出色的性能表现 Hippy 有比竞品更出色的性能表现。 ### 渲染性能 ListView 在滑动时的性能对比，Hippy 可以一直保持十分流畅的状态。 ### 内存占用 而在内存占用上，初始化 List 时 Hippy 就略占优势，在滑动了几屏后内存开销的差距越来越大。 ### 包体积 Hippy 的包体积在业内也是非常具有竞争力的。 上图是一个空的APK，在引入后终端包大小对比。 上图是在前端搭建了一个最简单的 ListView 后，前端打出的 JS 的包大小对比。 ## 可扩展的架构设计 在Hippy 3.0版本，我们对 Hippy 架构做了一次比较大的重构, 采用 Driver，Dom Manager，Renderer 分层解耦的设计理念，其设计目标就是希望框架在未来具有很好的可扩展性，以复用的 DOM 管理、排版布局为核心连接上层 Driver 和下层 Renderer，同时支持不同 Driver 和 Renderer 的接入和自由切换。 ### 驱动层 驱动层为业务封装了对接DOM层的渲染指令和底层接口, 用户可以使用 Hippy 框架提供的 React/Vue 驱动层来开发业务，也支持扩展其它任意 DSL 语言进行驱动。详见 [Hippy-React](api/hippy-react/introduction)、[Hippy-Vue](api/hippy-vue/introduction)。 ### DOM层 DOM Manager 从 Java/OC 抽离到 C++，作为中间枢纽，除了接收处理来自上层的消息，进行 DOM Tree 的创建和维护外，还负责与不同渲染引擎，排版引擎和调试工具的对接通信。 ### 渲染层 * Native Renderer：使用 Android/iOS/Ohos 原生组件进行渲染, 详见 [Android](architecture/render/android/native-render)、[iOS](architecture/render/ios/native-render)、[Ohos](architecture/render/ohos/native-render)。 * Voltron Renderer：使用 Flutter 渲染, 详见 [Voltron](architecture/render/voltron/voltron-render)。 * Web Renderer：使用 WebView 渲染（Web 同构）, 详见 [Web](architecture/render/web/web-render)。 ## 交流链接 * [文章专栏](https://cloud.tencent.com/developer/column/84006) * 企业微信交流群，使用微信或者企业微信扫描加入 ## 总结 如果您准备好了，那就 [开始接入 Hippy](development/demo.md) 吧。 ## 2. Official Technical Reference & Guides (Tencent/Tencent.github.io) ## File: konajdk/sm/README.md # Tencent Kona JDK ShangMi Reference Guide ## Overview of ShangMi ShangMi is a set of cryptographic techniques and tools in commercial or business applications, including the encryption of sensitive business data, secure communication channels, digital signatures for document verification, and even more. Generally, the below ShangMi cryptographic algorithms and secure communication protocols are widely applied. ### ShangMi cryptographic algorithms - SM2, which is a public key algorithm based on Elliptic Curve Cryptography (ECC). It complies with China's specifications: - GB/T 32918.1-2016 Part 1：General - GB/T 32918.2-2016 Part 2：Digital signature algorithm - GB/T 32918.3-2016 Part 3：Key exchange protocol - GB/T 32918.4-2016 Part 4：Public key encryption algorithm - GB/T 32918.5-2017 Part 5：Parameter definition - SM3, which is a cryptographic hash algorithm. It complies with China's specification: - GB/T 32905-2016 SM3 cryptographic hash algorithm - SM4, which is a block encryption algorithm. It complies with China's specification: - GB/T 32907-2016 SM4 block cipher algorithm ### ShangMi secure communication protocols - Transport Layer Cryptography Protocol (TLCP), which is a TLS liked protocol. This protocol requires an endpoint must have two certificates, one for signature and the other for encryption. It complies China's specification: - GB/T 38636-2020 Information security technology-Transport layer cryptography protocol (TLCP) - ShangMi (SM) Cipher Suites for TLS 1.3, which defines elements for applying ShangMi algorithms over TLS 1.3. It complies IETF's Informational specification: - RFC 8998 ShangMi (SM) Cipher Suites for TLS 1.3 ## Providers and implementations Tencent Kona JDK extends Java Cryptography Architecture (JCA) and Java Cryptography Extension (JCE) providers, exactly SUN, SunEC and SunJCE, to support ShangMi cryptographic algorithms, and extends Java Secure Socket Extension (JSSE) provider, exactly SunJSSE, to support ShangMi secure communication protocols. The algorithms are implemented by the different security providers in the JDK. The followings list the security providers and the corresponding supported ShangMi algorithms and protocols. - SUN - MessageDigest - SM3 - SunEC - KeyAgreement - SM2 - KeyFactory - SM2 - Signature - SM3withSM2 - SunJCE - Cipher - SM4 - KeyGenerator - HmacSM3 - SM4 - Mac - HmacSM3 - SunJSSE - SSLContext - TLCP 1.1 - ECC_SM4_GCM_SM3 - ECC_SM4_CBC_SM3 - ECDHE_SM4_GCM_SM3 - ECDHE_SM4_CBC_SM3 - TLS 1.3/RFC 8998 - TLS_SM4_GCM_SM3 Since Tencent Kona JDK just uses the existing OpenJDK security providers to accommodate the ShangMi stuff, and these providers are already installed with the highest priorities, so the application developers can use these out-of-the-box features as those JDK built-in algorithms (e.g. EC and AES) and protocols (e.g. TLS 1.3). The following sections will unveil the details on using the above algorithms and protocols. ## SM2 ### Key pair Generating SM2 key pair is the same as generating the key pairs on other EC curves. It just needs to invoke the standard JDK APIs. The JDK builtin ECKeyPairGenerator. In the key pair generated by this implementation, the format of private key is PKCS#8 and the format of public key is X.509. Create KeyPairGenerator implementation for EC algorithm. ``` KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("EC); keyPairGenerator.initialize(spec); ``` `spec` can be `SM2ParameterSpec` (use `SM2ParameterSpec.instance()` to create the instance) or `ECGenParameterSpec` (use `new ECGenParameterSpec("curveSM2")` to create the instance). Generate key pair. ``` KeyPair keyPair = keyPairGenerator.generateKeyPair(); ECPublicKey publicKey = (ECPublicKey) keyPair.getPublic(); ECPrivateKey privateKey = (ECPrivateKey) keyPair.getPrivate(); ``` SM2 key pair is also EC key pair, so the public key and private key are also ECPublicKey and ECPrivateKey respectively. For more information on key pair generation, please refer to the official [KeyPairGenerator](https://docs.oracle.com/en/java/javase/21/security/java-cryptography-architecture-jca-reference-guide.html#GUID-7EA29AC2-28B5-405D-BD2F-7055EC9E1EDD) docs. Generally, in the signing and encrypting operations, the key pairs are already generated. They are not generated on the runtime. It just reads the existing public key and private key to create PublicKey and PrivateKey instances respectively. ``` byte[] encodedPublicKey = ; byte[] encodedPrivateKey = ; KeyFactory keyFactory = KeyFactory.getInstance("SM2"); SM2PublicKeySpec publicKeySpec = new SM2PublicKeySpec(encodedPublicKey); PublicKey publicKey = keyFactory.generatePublic(publicKeySpec); SM2PrivateKeySpec privateKeySpec = new SM2PrivateKeySpec(encodedPrivateKey); PrivateKey privateKey = keyFactory.generatePrivate(privateKeySpec); ``` ### Signature Using SM2 signature is the same as using other existing signatures, like ECDSA, though the parameters are different. Create Signature instance. ``` Signature signature = Signature.getInstance("SM3withSM2); ``` Initialize the Signature instance with the private key for signing. ``` signature.initSign(privateKey); ``` Behind the above initialization, it uses the default SM2 ID, exactly `1234567812345678`. It also derives the public key from the private key. According to the associated specification, public key must be used for generating SM2 signature data. This is a significant difference between the international algorithms, like ECDSA, and SM2 signature algorithm. Note that calculating the public key leads to some overhead. That is harmful for the performance. If not using the default ID or expect to eliminate the cost on calculating public key, it would provide an AlgorithmParameterSpec, exactly SM2SignatureParameterSpec, instance. ``` byte[] altID = ; ECPublicKey publicKey = ; SM2SignatureParameterSpec paramSpec = new SM2SignatureParameterSpec(altID, publicKey); signature.setParameter(paramSpec); signature.initSign(privateKey); ``` After parameter setup and initialization, it is time to pass the message data in. ``` byte[] message = ; signature.update(message); ``` Generate signature data. ``` byte[] sign = signature.sign(); ``` Initialize the Signature instance with public key for verifying. ``` signature.initVerify(publicKey); ``` Pass the message in. ``` byte[] message = ; signature.update(message); ``` Pass the signature data in. ``` boolean verified = signature.verify(sign); ``` If the verification is successful, the result is true, otherwise false. It has to know that the private key is used for signing, however the public key is used for verifying. For detailed information about Signature APIs, please refer to the official [Signature](https://docs.oracle.com/en/java/javase/21/security/java-cryptography-architecture-jca-reference-guide.html#GUID-9CF09CE2-9443-4F4E-8095-5CBFC7B697CF) docs. ### Encryption Because of the performance concern, public key encryption is only used for encrypting short but critical data. The same to SM2 encryption. Create Cipher instance. ``` Cipher cipher = Cipher.getInstance("SM2"); ``` Initialize the Cipher instance with public key and set the mode to encryption. ``` cipher.init(Cipher.ENCRYPT_MODE, publicKey); ``` Pass the message in and generate the ciphertext. ``` byte[] message = ; byte[] ciphertext = cipher.doFinal(message); ``` Initialize the Cipher instance with private key and set the mode to decryption. ``` cipher.init(Cipher.DECRYPT_MODE, privateKey); ``` Pass the ciphertext in and generate the plaintext. ``` byte[] cleartext = cipher.doFinal(ciphertext); ``` It has to know that public key is used for encryption, however the private key is used for decryption. For detailed information on Cipher APIs, please refer to the official [Cipher](https://docs.oracle.com/en/java/javase/21/security/java-cryptography-architecture-jca-reference-guide.html#GUID-94225C88-F2F1-44D1-A781-1DD9D5094566) docs. ## SM3 Using SM3 hash algorithm is the same as using other existing hash algorithm, like SHA-256. It only invokes JDK APIs to generate the message digest (hash). Create MessageDigest instance. ``` MessageDigest md = MessageDigest.getInstance("SM3"); ``` It can pass all the message in and generate the digest. ``` byte[] message = ; byte[] digest = md.digest(message); ``` It also can pass the message segments, and finally generate the digest. ``` byte[] messageSegment1 = ; byte[] messageSegment2 = ; // Pass the message segments in md.update(messageSegment1); md.update(messageSegment2); // Finally generate the digest byte[] digest = md.digest(); ``` For detailed information about MessageDigest APIs, please refer to the official [MessageDigest](https://docs.oracle.com/en/java/javase/21/security/java-cryptography-architecture-jca-reference-guide.html#GUID-FB0090CA-2BCC-4D2C-BD2F-6F0A97197BD7) docs. ## HmacSM3 Using HmacSM3 algorithm is the same as using other existing MAC algorithm, like HmacSHA256. It only invokes JDK APIs to generate the message authentication code. Prepare a 16-bytes key. ``` byte[] key = ; SecretKey secretKey = new SecretKeySpec(key, "SM4"); ``` Create Mac instance. ``` Mac hmac = Mac.getInstance("HmacSM3"); ``` Initialize the Mac instance with the key. ``` hmac.init(secretKey); ``` Pass all the message in and generate message authentication code. The code is 32-bytes length. ``` byte[] message = ; byte[] mac = hmac.doFinal(message); ``` It also can pass the message segments, and finally generate the message authentication code. ``` byte[] messageSegment1 = ; byte[] messageSegment2 = ; // Pass the message segments in hmac.update(messageSegment1); hmac.update(messageSegment2); // Finally generate the message authentication code byte[] mac = hmac.doFinal(); ``` For the detailed information about Mac APIs, please refer to the official [Mac](https://docs.oracle.com/en/java/javase/21/security/java-cryptography-architecture-jca-reference-guide.html#GUID-8E014689-EBBB-4DE1-B6E0-24CE59AD8B9A) docs. ## SM4 Using SM4 cipher algorithm is the same as using other existing block cipher algorithm, like AES. It only invokes JDK APIs to do encryption and decryption. Tencent Kona JDK supports four operation modes, including CBC, CTR, ECB and GCM. It also supports PKCS#7 padding specification. Prepare a 16-bytes key. ``` byte[] key = ; SecretKey secretKey = new SecretKeySpec(key, "SM4"); ``` Create Cipher instance. ``` Cipher cipher = Cipher.getInstance(transformation); ``` The transformation consists of algorithm name, operation mode and padding type. A symbol `/` is used as separator between the parts. The following transformations are supported: - SM4/CBC/NoPadding: The operation mode is CBC. No padding is needed. It requires the input must be 16x bytes. - SM4/CBC/PKCS7Padding: The operation mode is CBC. PKCS#7 padding is used. It doesn't require that the input must be 16x bytes. - SM4/CTR/NoPadding: The operation mode is CBC. No padding is needed. It doesn't require that the input must be 16x bytes. - SM4/ECB/NoPadding: The operation mode is ECB. No padding is needed. It requires the input must be 16x bytes. - SM4/ECB/PKCS7Padding: The operation mode is ECB. PKCS#7 padding is used. It doesn't require that the input must be 16x bytes. - SM4/GCM/NoPadding: The operation mode is GCM. No padding is needed. It doesn't require that the input must be 16x bytes. Create the algorithm parameters. ``` AlgorithmParameterSpec paramSpec = ; ``` Different operation modes may need different AlgorithmParameterSpec types, - CBC and CTR modes use [IvParameterSpec](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/spec/IvParameterSpec.html). This parameter type needs a 16-bytes as Initialization Vector (IV). - GCM mode uses [GCMParameterSpec](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/spec/GCMParameterSpec.html). This parameter type needs a 12-bytes as Initialization Vector (IV) and specifies the tag length to 12-bytes. Initialize the Cipher instance with the key and parameter type and set the mode to encryption. ``` cipher.init(Cipher.ENCRYPT_MODE, secretKey, paramSpec); ``` Pass all the message in and generate the ciphertext. ``` byte[] ciphertext = cipher.doFinal(message); ``` Initialize the Cipher instance with the key and parameter type and set the mode to decryption. ``` cipher.init(Cipher.DECRYPT_MODE, secretKey); ``` Pass all the ciphertext in and generate the plaintext. ``` byte[] cleartext = cipher.doFinal(ciphertext); ``` It also can receive the plaintext/ciphertext segments in, and then generate the ciphertext/plaintext segments. ``` byte[] input1 = ; byte[] input2 = ; // Pass the plaintext/ciphertext segments in byte[] output1 = cipher.update(input1); byte[] output2 = cipher.update(input2); // Generate the ciphertext/plaintext segments byte[] outputFinal = cipher.doFinal(); ``` For the detailed information about Cipher APIs, please refer to the official [Cipher] docs. ## Certificate The so-called ShangMi certificate also complies to X.509 specification, though the public key algorithm is EC with SM2 curve and the signature algorithm is SM3withSM2. ``` String certPEM = ; CertificateFactory cf = CertificateFactory.getInstance("X.509"); X509Certificate certificate = (X509Certificate) cf.generateCertificate( new ByteArrayInputStream(certPEM.getBytes(StandardCharsets.UTF_8)); ``` For more information on certificate parsing, please read the official reference on [CertificateFactory](https://docs.oracle.com/en/java/javase/21/security/java-pki-programmers-guide.html#GUID-BCABADD4-C0DC-4987-B187-F086B4BCE195). It can parse public key from the ShangMi certificate. ``` PublicKey publicKey = certificate.getPublicKey(); ``` publicKey can be cast to ECPublicKey. It can parse private key from PKCS#8 format. ``` String peyPEM = ; PKCS8EncodedKeySpec privateKeySpec = new PKCS8EncodedKeySpec( Base64.getMimeDecoder().decode(keyPem)); KeyFactory keyFactory = KeyFactory.getInstance("EC"); PrivateKey privateKey = keyFactory.generatePrivate(privateKeySpec); ``` privateKey can be cast to ECPrivateKey. It can sign data with PKCS#8 private key and verify the signature with X.509 certificate. Create Signature instance and use SM3withSM2 signature algorithm. ``` Signature signature = Signature.getInstance("SM3withSM2"); ``` Sign the message with the private key and generate the signature data. ``` signature.initSign(privateKey); signature.update(message); byte[] sign = signature.sign(); ``` Verify the signature data with the certificate and determine whether the verification passes or fails. ``` signature.initVerify(certificate); signature.update(message); boolean verified = signature.verify(sign); ``` The certificate has to contain digitalSignature key usage for verifying signature data. But it also can verify the signature with the public key directly. ``` signature.initVerify(publicKey); signature.update(message); boolean verified = signature.verify(sign); ``` ## TLCP 1.1 and TLS 1.3/RFC 8998 In order to take advantage of the implementations on TLCP 1.1 and TLS 1.3/RFC 8998, the most important point is taking SSLSocket or SSLEngine to apply the [SSLContext](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/net/ssl/SSLContext.html) implementation that supports the protocols. ``` KeyStore trustStore = ; TrustManagerFactory tmf = TrustManagerFactory.getInstance("PKIX"); tmf.init(trustStore); KeyStore keyStore = ; KeyManagerFactory kmf = KeyManagerFactory.getInstance("NewSunX509"); kmf.init(keyStore, keyStorePassword); SSLContext context = SSLContext.getInstance("TLCPv1.1"); context.init(kmf.getKeyManagers(), tmf.getTrustManagers(), new SecureRandom()); ``` When create SSLContext instances, it allows to specify the following context protocols: - TLCPv1.1, which indicates only TLCP 1.1 is supported. - TLSv1.3, which indicates only TLS 1.3 is supported. - TLCP, which indicates TLCP 1.1, TLS 1.3 and TLS 1.2 are supported. Please read the official [JSSE](https://docs.oracle.com/en/java/javase/21/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-93DEEE16-0B70-40E5-BBE7-55C3FD432345) reference for understanding it deeply. --- ## File: konajdk/README.md ## Tencent Kona Tencent Kona is a no-cost, production-ready distribution of the Open Java Development Kit (OpenJDK), Long-Term Support (LTS) with quarterly updates. Kona serves as the default JDK at Tencent internally, optimized for extreme-scale of Big Data, Machine Learning and Cloud Computing workloads. It is also used to build and maintain a Tencent supported version of OpenJDK for Tencent customers and partners who wish to use OpenJDK to run their applications. Kona also implements China's cryptographic algorithms, including SM2, SM3 and SM4, and secure communication protocol TLCP (or SMSSL). For more details on these features, please refer to [the reference guide](https://tencent.github.io/konajdk/sm/). ## Supported JDK Releases Tencent Kona currently supports the JDK Long-Term Support (LTS) releases 8, 11, 17, 21 and 25. For more details, please go through the individual repository for each of these releases: - Tencent Kona 8: [https://github.com/Tencent/TencentKona-8](https://github.com/Tencent/TencentKona-8) - Tencent Kona 11: [https://github.com/Tencent/TencentKona-11](https://github.com/Tencent/TencentKona-11) - Tencent Kona 17: [https://github.com/Tencent/TencentKona-17](https://github.com/Tencent/TencentKona-17) - Tencent Kona 21: [https://github.com/Tencent/TencentKona-21](https://github.com/Tencent/TencentKona-21) - Tencent Kona 25: [https://github.com/Tencent/TencentKona-25](https://github.com/Tencent/TencentKona-25) ## Supported System Platforms Tencent Kona currently supports Linux/x86_64, Linux/aarch64, Windows/x86_64, macOS/x86_64 and macOS/aarch64. ## License Tencent Kona is under the same licensing terms as the upstream OpenJDK project. It is clearly a "friendly fork". Please find the license [text](https://tencent.github.io/konajdk/LICENSE.txt) for more details.