GmSSL: a C toolkit for SM2, SM3, SM4, SM9 and TLCP

What GmSSL is for, and who ends up using it

GmSSL exists to give C projects the Chinese commercial cryptography algorithms and the protocols built on them. The README lists SM2 encryption and signing, SM3 hashing, SM4 in CBC, CTR, GCM, ECB, CFB, OFB, CCM and XTS modes, ZUC and ZUC-256 stream ciphers, SM9 identity-based encryption and signing, and the LMS/HSS post-quantum signature scheme. On top of the primitives it implements X.509 certificates, CRLs, PKCS #10 requests, PKCS #8 private keys encrypted with SM4 and SM3, and the SM2 digital envelope defined by GM/T 0010-2012.

The audience is narrower than a general TLS library's. If your server has to interoperate with a Chinese CA, a national-standard TLS endpoint, or a hardware security module that speaks SDF or SKF, this is the kind of library you reach for. The README also positions GmSSL 3 for embedded work: it says the library does not depend on dynamic memory and can run on MCUs and SOCs without an operating system. That is a different design centre from OpenSSL, and it explains several choices elsewhere in the project.

It is not a general-purpose replacement for OpenSSL, and the README says so plainly. GmSSL 3 rewrote all the code and changed the API, so existing OpenSSL code does not compile against it. The OpenSSL-Compatibility-Layer subproject exists to bridge that gap for applications such as Nginx, but it is a separate repository and a separate dependency to track.

SM2, SM3, SM4 and TLCP: what the library actually implements

The algorithm inventory is the part most readers will check first. SM4 is a block cipher with the full set of modes listed above, and the README notes that the gmssl command line tool exposes options for all of them, plus GHASH computation. SM3 is the hash, and the library also carries SHA-1 and the SHA-2 family. SM2 covers encryption and signing, and SM9 covers identity-based encryption and signing, which is a genuinely different key model: an SM9 user's private key is derived from a master secret rather than generated locally.

On the protocol side the README names three stacks. TLCP 1.1 with the cipher suite TLS_ECC_SM4_CBC_SM3 {0xE0,0x13}, per GB/T 38636-2020 and GM/T 0024-2014. TLS 1.2 with TLS_ECDHE_SM4_CBC_SM3 {0xE0,0x11}, under the same standards. TLS 1.3 with TLS_SM4_GCM_SM3 {0x00,0xC6}, which is the RFC 8998 suite. The v3.2.0 change log adds PSK-DHE and PSK-only handshake modes with 0-RTT, HelloRetryRequest, SNI, certificate transparency and OCSP stapling extensions, and a P-256 with AES-128 and SHA-256 suite. The TLS stack is described as a state machine supporting non-blocking mode, which matters if you are integrating it into an event loop rather than a blocking socket.

Two removals are worth noting. The change log says RC4 and MD5 were removed as broken algorithms. That is a deliberate break from older GmSSL releases and from OpenSSL's habit of keeping legacy ciphers behind flags. If some peer in your network still negotiates MD5, this library will not help you.

Building GmSSL from source and running make test

GmSSL 3 uses CMake and does not require Perl, which the README frames as a portability improvement over the previous build system. The README gives this sequence for a source build:

mkdir build
cd build
cmake ..
make
make test
sudo make install

After make install the README says the gmssl command line tool lands in the default install directory, a gmssl directory is created under the headers path, and libgmssl.so or libgmssl.dylib is installed in the library directory. For a static build, configure with -DBUILD_SHARED_LIBS=OFF to produce libgmssl.a. That flag is the one to remember if you are cross-compiling for an embedded target and do not want a shared object.

On Windows the README gives a Visual Studio command prompt variant:

mkdir build
cd build
cmake .. -G "NMake Makefiles" -DWIN32=ON
nmake

There is no make test step in the Windows sequence as written. The repository also ships INSTALL.md at the top level, which is the place to look for build details the README does not repeat.

For a first real use, the README documents a speed test build that exercises the primitives directly:

cmake .. -DENABLE_TEST_SPEED=ON
make
./bin/sm4_cltest; ./bin/sm4test; ./bin/sm3test; ./bin/sm2_signtest; ./bin/sm2_enctest; ./bin/sm9test; ./bin/zuctest

Running those binaries is the quickest way to confirm that SM4, SM3, SM2, SM9 and ZUC all execute on your machine before you wire the library into an application. The README reports measured throughput from these programs on several laptops, including SM4 CTR32 encryption and SM2 signing rates, but those numbers come from the project's own machines and are not a prediction for yours.

The OpenSSL compatibility question, answered by the README

The most common expectation people bring to a C crypto library is that it can stand in for OpenSSL. GmSSL cannot, at least not directly. The README states that GmSSL 3.0 rewrote all the code and changed the API, so the current version is incompatible with OpenSSL and cannot be used to replace it at compile time. That is not a temporary gap; it is the consequence of the rewrite.

The project's answer is the OpenSSL-Compatibility-Layer subproject, a separate repository that presents an OpenSSL-shaped interface over GmSSL. The README says applications such as Nginx can call GmSSL through it, and that the layer has been tested with Nginx versions 1.16 through 1.25. Read that range carefully. It is a tested range, not a guarantee, and the README does not describe what happens outside it. If you run a newer Nginx, or a different application that links OpenSSL, you are outside the documented envelope and should expect to do your own integration work.

There is a second practical consequence. If you adopt the compatibility layer, you now depend on two repositories moving together: the layer and the library. The README does not describe the layer's release cadence or how it tracks GmSSL versions, so treat that as an open question to resolve before you commit to it in a long-lived product.

Hardware keys, SDF and SKF, and the SoftSDF substitute

GmSSL has built-in support for two classes of Chinese cryptographic hardware: SDF devices, which the README describes as typically PCI-E cryptographic cards or server cryptographic machines, and SKF devices, which are usually small USB cryptographic keys. This is a real differentiator against libraries that only implement the algorithms in software, because the private key never has to leave the hardware.

The README is candid about the weak spot here. The list of tested cryptographic product models reads "to be added." There is no published compatibility matrix. If your deployment depends on a specific vendor's card, you cannot confirm from the README that it has been exercised.

The project's workaround is SoftSDF, a subproject that provides a software implementation of the SDF interface. The README is explicit that it is functionally equivalent but does not provide the same security guarantees as hardware key protection, and that it is meant for development and testing before swapping in a real SDF device at deployment. That is a sensible split, but it means your test environment and your production environment differ in exactly the property you care about. The change log also mentions an sdftest command for correctness and compatibility testing, which is the tool to reach for when you first attach real hardware.

Where GmSSL is the wrong tool

If you need a general-purpose TLS stack for the public web, GmSSL is the wrong choice. Its protocol support is organised around Chinese standards and RFC 8998, and the README's cipher suite list is short by design. You will not find the broad suite coverage that a mainstream TLS library offers, and the README does not claim otherwise.

If you need post-quantum algorithms that are actually standardised and widely deployed, look carefully before adopting. The v3.2.0 change log adds CRYSTALS-Kyber key encapsulation and SM3-based SPHINCS+, XMSS and LMS/HSS signatures. The README's feature list names only LMS/HSS under post-quantum, while the change log names all four. That inconsistency between the two documents is worth resolving against the source before you build a design on it. Note also that XMSS and LMS/HSS are stateful schemes, which the change log flags explicitly; stateful signatures impose key-reuse hazards that stateless code does not.

If your team cannot build C from source, this is not a library you can adopt casually. There is no package manager install in the README, no signed binary distribution described, and the build instructions assume a working CMake toolchain. Language bindings exist as separate subprojects for Java, PHP, Go, Python, Rust and Node.js, but each is its own repository with its own build, and the README does not describe how they track library releases.

Finally, if you need to support a peer that still uses MD5 or RC4, GmSSL removed them. That is the right call, but it is a hard boundary.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-06-30. Release v3.2.0 is dated 2026-06-21, which follows v3.1.1 in December 2023. That gap of roughly two and a half years between the two releases is the number to plan around: the project does ship, but not on a frequent cadence, and the 3.2.0 change log is large, covering TLS 1.3 handshake modes, several post-quantum algorithms, new SM4 modes and a performance pass across the SM algorithms. A release that large after a long quiet period means an upgrade is not a drop-in patch.

The licence is Apache-2.0, per the LICENSE file at the repository root. That is a permissive licence with an explicit patent grant, which is usually the practical concern for cryptography code. This is a description of the licence identifier, not legal advice; if you ship a regulated product, have your own counsel review the notices and any third-party components in the tree.

Upgrade cost is the part the README does not cover. There is no documented rollback procedure, no migration guide from 3.1.1 to 3.2.0, and no statement about API or ABI stability between releases. The 3.0 rewrite that broke OpenSSL compatibility is the precedent here. Pin a version, keep the build reproducible, and read the change log before moving, because the project's own history shows it will break compatibility when the design requires it.

Editorial conclusion

Adopt GmSSL if your product must speak SM2, SM3, SM4, SM9 or TLCP and you are willing to build it yourself and pin the version you test. Do not adopt it expecting a drop-in OpenSSL replacement: the README states the current API is incompatible, and the compatibility layer is a separate subproject that the README only claims works with Nginx 1.16 to 1.25. Before committing, run make test after building, and check the CMake options in CMakeLists.txt for the algorithm set and shared/static choice you actually need, because the README does not document a rollback path or an upgrade procedure between releases.

Frequently asked questions

Official sources

1. guanzhi/GmSSL on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases