ncnn Documentation

1. Project Overview & Quickstart (Tencent/ncnn) Copy Chapter

File: README.md Copy Chapter

ncnn

ncnn is a high-performance neural network inference framework optimized for mobile, embedded, and desktop deployment.
It has no third-party runtime dependencies, runs across CPU and Vulkan GPU backends, and provides tools such as pnnx for converting PyTorch and ONNX models to ncnn.
Developers can deploy deep learning models efficiently on phones, PCs, browsers, and edge devices.
ncnn is currently being used in many Tencent applications, such as QQ, Qzone, WeChat, Pitu, and so on.

ncnn 是一个面向移动端、嵌入式和桌面端部署优化的高性能神经网络推理框架。
ncnn 无第三方运行时依赖，支持 CPU 和 Vulkan GPU 后端，并提供 pnnx 等工具将 PyTorch 和 ONNX 模型转换为 ncnn 模型。
基于 ncnn，开发者可以将深度学习模型高效部署到手机、PC、浏览器和边缘设备上。
ncnn 目前已在腾讯多款应用中使用，如：QQ，Qzone，微信，天天 P 图等。

Quick Start Copy Chapter

The recommended beginner path is PyTorch -> pnnx -> ncnn.

| Install pnnx in a PyTorch environment

pip3 install pnnx

Export a PyTorch model to ncnn

import torch
import torch.nn as nn
import pnnx

class Model(nn.Module):
    def __init__(self):
        super().__init__()
        self.conv = nn.Conv2d(3, 8, 1)
        self.relu = nn.ReLU()
        self.fc = nn.Linear(8, 4)

    def forward(self, x):
        x = self.conv(x)
        x = self.relu(x)
        x = x.mean((2, 3))
        return self.fc(x)

model = Model().eval()

x = torch.rand(1, 3, 224, 224)
pnnx.export(model, "model.pt", (x,))

This generates model.ncnn.param and model.ncnn.bin. | Run with ncnn C++ API

#include "net.h"

ncnn::Net net;
net.load_param("model.ncnn.param");
net.load_model("model.ncnn.bin");

ncnn::Mat in(224, 224, 3);

auto ex = net.create_extractor();
ex.input("in0", in);

ncnn::Mat out;
ex.extract("out0", out);

Or use Python

import numpy as np
import ncnn

net = ncnn.Net()
net.load_param("model.ncnn.param")
net.load_model("model.ncnn.bin")

x = np.zeros((3, 224, 224), np.float32)
mat = ncnn.Mat(x)

ex = net.create_extractor()
ex.input("in0", mat)

ret, out = ex.extract("out0")
print(np.array(out).shape)
``` |
| --- | --- |



See [pnnx](tools/pnnx), [use ncnn with PyTorch or ONNX](https://github.com/Tencent/ncnn/wiki/use-ncnn-with-pytorch-or-onnx), [Python API](python), and [examples](examples) for complete workflows.

---

## Community



| **技术交流 QQ 群**
637093648 (超多大佬)
答案：卷卷卷卷卷（已满） | **Telegram Group** | **Discord Channel** |
| --- | --- | --- |
| **Pocky QQ 群（MLIR YES!）**
677104663 (超多大佬)
答案：multi-level intermediate representation |  |  |
| **他们都不知道 pnnx 有多好用群**
818998520 (新群！) |  |  |



---

## Download & Build status

https://github.com/Tencent/ncnn/releases/latest




|  | **[how to build ncnn library](https://github.com/Tencent/ncnn/wiki/how-to-build) on Linux / Windows / macOS / Raspberry Pi3, Pi4 / POWER / Android / NVIDIA Jetson / iOS / WebAssembly / AllWinner D1 / Loongson 2K1000** |  |
| --- | --- | --- |
| Source | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-full-source.zip) |  |
|  | - [Build for Android](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-android)
- [Build for Termux on Android](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-termux-on-android) |  |
| Android | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-android-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-android.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Aandroid) |
| Android shared | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-android-vulkan-shared.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-android-shared.zip) |  |
|  | - [Build for HarmonyOS with cross-compiling](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-harmonyos-with-cross-compiling) |  |
| HarmonyOS | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-harmonyos-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-harmonyos.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Aharmonyos) |
| HarmonyOS shared | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-harmonyos-vulkan-shared.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-harmonyos-shared.zip) |  |
|  | - [Build for iOS on macOS with xcode](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-ios-on-macos-with-xcode) |  |
| iOS | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-ios-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-ios.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Aios) |
| iOS-Simulator | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-ios-simulator-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-ios-simulator.zip) |  |
|  | - [Build for macOS](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-macos) |  |
| macOS | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-macos-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-macos.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Amacos) |
| Mac-Catalyst | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-mac-catalyst-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-mac-catalyst.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Amac-catalyst) |
| watchOS | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-watchos.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Awatchos) |
| watchOS-Simulator | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-watchos-simulator.zip) |  |
| tvOS | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-tvos-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-tvos.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Atvos) |
| tvOS-Simulator | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-tvos-simulator-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-tvos-simulator.zip) |  |
| visionOS | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-visionos-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-visionos.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Avisionos) |
| visionOS-Simulator | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-visionos-simulator-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-visionos-simulator.zip) |  |
| Apple xcframework | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-apple-vulkan.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-apple.zip) |  |
|  | - [Build for Linux / NVIDIA Jetson / Raspberry Pi3, Pi4 / POWER](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-linux) |  |
| Ubuntu 22.04 | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-ubuntu-2204.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-ubuntu-2204-shared.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Alinux-x64-gpu-gcc) |
| Ubuntu 24.04 | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-ubuntu-2404.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-ubuntu-2404-shared.zip) |  |
|  | - [Build for Windows x64 using VS2017](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-windows-x64-using-visual-studio-community-2017)
- [Build for Windows x64 using MinGW-w64](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-windows-x64-using-mingw-w64) |  |
| VS2015 | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-windows-vs2015.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-windows-vs2015-shared.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Awindows) |
| VS2017 | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-windows-vs2017.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-windows-vs2017-shared.zip) |  |
| VS2019 | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-windows-vs2019.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-windows-vs2019-shared.zip) |  |
| VS2022 | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-windows-vs2022.zip)
  [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-windows-vs2022-shared.zip) |  |
|  | - [Build for WebAssembly](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-webassembly) |  |
| WebAssembly | [](https://github.com/Tencent/ncnn/releases/latest/download/ncnn-20260526-webassembly.zip) | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Aweb-assembly) |
|  | - [Build for ARM Cortex-A family with cross-compiling](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-arm-cortex-a-family-with-cross-compiling)
- [Build for Hisilicon platform with cross-compiling](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-hisilicon-platform-with-cross-compiling)
- [Build for AllWinner D1](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-allwinner-d1)
- [Build for Loongson 2K1000](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-loongson-2k1000)
- [Build for QNX](https://github.com/Tencent/ncnn/wiki/how-to-build#build-for-qnx) |  |
| Linux (arm) |  | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Alinux-arm) |
| Linux (aarch64) |  | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Alinux-aarch64) |
| Linux (mips) |  | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Alinux-mips) |
| Linux (mips64) |  | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Alinux-mips64) |
| Linux (ppc64) |  | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Alinux-ppc64) |
| Linux (riscv64) |  | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Alinux-riscv64) |
| Linux (loongarch64) |  | [](https://github.com/Tencent/ncnn/actions?query=workflow%3Alinux-loongarch64) |



---

## Build

Use the prebuilt packages above when possible. To build from source, see the full [how to build ncnn library](https://github.com/Tencent/ncnn/wiki/how-to-build) guide for Linux, Windows, macOS, Android, iOS, WebAssembly, HarmonyOS, Raspberry Pi, Jetson, and embedded targets.

Common Linux build:

```bash
git clone --recursive https://github.com/Tencent/ncnn.git
cd ncnn
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DNCNN_VULKAN=ON -DNCNN_BUILD_EXAMPLES=ON ..
cmake --build . -j$(nproc)

Model Conversion Copy Chapter

Use Netron to inspect .param, .onnx, and .pnnx.param graphs.

Features Copy Chapter

• No third-party runtime dependencies and no BLAS / NNPACK requirement.
• Pure C++ implementation with C API and Python binding.
• Optimized CPU inference for mobile and embedded processors, including ARM NEON and multi-core scheduling.
• Vulkan GPU acceleration for supported platforms.
• Low memory footprint with explicit blob/workspace allocator design.
• Supports multi-input, multi-output, and multi-branch graphs.
• PyTorch and ONNX conversion through pnnx, plus legacy converter support for older model formats.
• Supports fp16 storage/arithmetic paths, int8 quantized inference, model optimization, and custom layers.
• Direct memory reference loading for .param and .bin models.

Model and Workload Coverage Copy Chapter

ncnn is still strong for classic and mobile CNN workloads, but current usage is broader than CNN-only deployment.

• Classification and backbones: VGG, AlexNet, GoogleNet, Inception, ResNet, DenseNet, SENet, SqueezeNet, MobileNet, ShuffleNet, MNasNet.
• Detection and face: SSD, Faster R-CNN, R-FCN, MTCNN, RetinaFace, scrfd, YOLOv2, YOLOv3, YOLOv4, YOLOv5, YOLOv7, YOLOv8, YOLOX, NanoDet.
• Segmentation, pose, and OCR: FCN, PSPNet, UNet, YOLACT, SimplePose, PP-OCR examples.
• Audio, generation, and language workloads are represented by community projects and examples where the model operators are supported.

For operator-level detail, see supported PyTorch operator status, supported ONNX operator status, and operation param weight table.

Project Examples Copy Chapter

Documentation And FAQ Copy Chapter

License Copy Chapter

BSD 3 Clause

File: benchmark/RankCards/README.md Copy Chapter

Rank the boards. Copy Section

The table below is generated by RankCards, using the timings found in the /ncnn/benchmark/README.md file.
First, the best set of timings is selected from each board.
The set is then compared to a reference set by calculating the ratio of each model one by one and averaging all results.
Finally, the boards are ranked from fast to slow.

2. Official Technical Reference & Guides (Tencent/Tencent.github.io) Copy Chapter

File: konajdk/sm/README.md Copy Chapter

Tencent Kona JDK ShangMi Reference Guide

Overview of ShangMi Copy Chapter

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 Copy Section

• 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 Copy Section

• 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 Copy Chapter

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 Copy Chapter

Key pair Copy Section

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 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 Copy Section

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 = <custom ID>;
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 docs.

Encryption Copy Section

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 docs.

SM3 Copy Chapter

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 docs.

HmacSM3 Copy Chapter

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 docs.

SM4 Copy Chapter

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. This parameter type needs a 16-bytes as Initialization Vector (IV).
• GCM mode uses GCMParameterSpec. 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 = <segment1>;
byte[] input2 = <segment2>;

// 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 Copy Chapter

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 = <certificate in PEM format>;
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.

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 Copy Chapter

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 implementation that supports the protocols.

KeyStore trustStore = <a trust store carring the CAs>;
TrustManagerFactory tmf = TrustManagerFactory.getInstance("PKIX");
tmf.init(trustStore);

KeyStore keyStore = <a key store carring the end entity certificates>;
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 reference for understanding it deeply.

File: konajdk/README.md Copy Chapter

Tencent Kona Copy Chapter

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.

Supported JDK Releases Copy Chapter

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
• Tencent Kona 11: https://github.com/Tencent/TencentKona-11
• Tencent Kona 17: https://github.com/Tencent/TencentKona-17
• Tencent Kona 21: https://github.com/Tencent/TencentKona-21
• Tencent Kona 25: https://github.com/Tencent/TencentKona-25

Supported System Platforms Copy Chapter

Tencent Kona currently supports Linux/x86_64, Linux/aarch64, Windows/x86_64, macOS/x86_64 and macOS/aarch64.

License Copy Chapter

Tencent Kona is under the same licensing terms as the upstream OpenJDK project. It is clearly a "friendly fork". Please find the license text for more details.