DOCSEARCHbyAlgolia
Submit Docs

GmSSL Documentation

repository·master·Indexed 27 days ago

https://github.com/guanzhi/gmssl

An open-source commercial cryptography library developed by Peking University. GmSSL provides comprehensive support for Chinese national cryptographic algorithms (SM series), standards, and secure communication protocols including TLCP 1.1, TLS 1.2, and TLS 1.3. It targets embedded, mobile, and server environments and includes language bindings for Java, PHP, Go, Python, Rust, and Node.js. The library also features an OpenSSL-Compatibility-Layer for integration with applications like Nginx.

Tokens
2.9K
Snippets
12
Records
19
Agent score
41%

What's inside GmSSL

  1. Install GmSSL on Windows using Visual Studio

    master

    On Windows, it is recommended to use Visual Studio 2022 or newer. Use the "Developer Command Prompt for VS 2022" to run the build commands. Note that nmake install typically requires Administrator privileges to write to C:\Program Files\GmSSL.

    mkdir build
cd build
cmake .. -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release
nmake
ctest --output-on-failure
nmake install

  2. Compile GmSSL in Visual Studio environment

    master

    To compile GmSSL using the Visual Studio command prompt (NMake), use the following commands:

    1. Create a build directory.
    2. Run cmake with the NMake Makefiles generator and the WIN32=ON flag.
    3. Run nmake to build.
    mkdir build
cd build
cmake .. -G "NMake Makefiles" -DWIN32=ON
nmake

  3. Cross-compile GmSSL for Android

    master

    Use the Android NDK's CMake toolchain to cross-compile for Android. You must specify the NDK path, the target ABI, and the minimum Android platform version.

    mkdir build; cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-23
cmake --build .

  4. Build installation packages (DEB, RPM, .sh)

    master

    Use the cpack tool included with CMake to generate distributable installation packages. Ensure you have performed a release build first.

    # Build DEB (Debian/Ubuntu)
mkdir build; cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
cpack -G DEB

# Build RPM (RedHat/CentOS)
cpack -G RPM

# Build .sh installer script
cpack -G STGZ

  5. Cross-compile GmSSL for iOS/iPhoneOS

    master

    To cross-compile for iOS, you must use the ios-cmake toolchain.

    1. Download ios.toolchain.cmake from https://github.com/leetal/ios-cmake.
    2. Place the ios.toolchain.cmake file in your build directory.
    3. Run CMake using the Xcode generator and the toolchain file.

    If you encounter a signing error (error: Signing for "gmssl" requires a development team.), open the generated project in Xcode and configure the Signing & Capabilities section with your Development Team.

    mkdir build; cd build
cmake .. -G Xcode -DCMAKE_TOOLCHAIN_FILE=../ios.toolchain.cmake -DPLATFORM=OS64
cmake --build . --config Release

  6. Install GmSSL via CMake

    master

    GmSSL 3 uses the CMake build system. To build and install from source on Linux/macOS, follow these steps:

    1. Uncompress the source code.
    2. Enter the source directory.
    3. Create a build directory and run the build commands.

    To generate static libraries (libgmssl.a) instead of shared libraries, pass the -DBUILD_SHARED_LIBS=OFF flag during the cmake configuration step.

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

  7. Generate binary distribution packages

    master

    To create a distribution package that includes both static and dynamic libraries, follow this workflow. This ensures the gmssl CLI tool is linked against the static library while the lib directory contains both .a and shared library files (.so, .dylib, or .dll).

    Workflow:

    1. Build and install the shared library version to a prefix.
    2. Build and install the static library version to the same prefix (this overwrites the CLI binary to link statically).
    3. Compress the resulting directory.
    #!/bin/bash -x
VERSION=3.2.0
OS=macos
ARCH=arm64

PREFIX="$PWD/gmssl-$VERSION"
rm -rf "$PREFIX" build-shared build-static

# 1. Build Shared Libraries
cmake -S . -B build-shared -DCMAKE_BUILD_TYPE=Release \
	-DBUILD_SHARED_LIBS=ON \
	-DCMAKE_INSTALL_PREFIX="$PREFIX"
cmake --build build-shared
ctest --test-dir build-shared --output-on-failure
cmake --install build-shared

# 2. Build Static Libraries (overwrites bin/gmssl to link statically)
cmake -S . -B build-static -DCMAKE_BUILD_TYPE=Release \
	-DBUILD_SHARED_LIBS=OFF \
	-DCMAKE_INSTALL_PREFIX="$PREFIX"
cmake --build build-static
ctest --test-dir build-static --output-on-failure
cmake --install build-static

# 3. Package
tar czvf gmssl-$VERSION-$OS-$ARCH.tar.gz gmssl-$VERSION

  8. Install GmSSL on Linux or macOS from source

    master

    To install GmSSL on Linux or macOS, download and extract the source code, then follow the standard CMake build process. It is highly recommended to run ctest after building to ensure the cryptographic tools are functioning correctly before installation.

    Default Installation Paths:

    • Headers: /usr/local/include/gmssl
    • Libraries: /usr/local/lib (Linux: libgmssl.so, macOS: libgmssl.dylib)

    Custom Installation Path: If you do not want to install to system directories, use the -DCMAKE_INSTALL_PREFIX flag.

    # Standard installation
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
ctest --output-on-failure
sudo cmake --install .

# Installation to a custom directory
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/local/gmssl
cmake --build .
ctest --output-on-failure
cmake --install .

  9. Use OpenSSL-Compatibility-Layer with GmSSL

    master
    GmSSL 3.0+ is not binary-compatible with OpenSSL due to API changes. To use GmSSL with applications like Nginx, use the OpenSSL-Compatibility-Layer sub-project. This layer allows applications to call GmSSL functions using the OpenSSL API. It has been tested to be compatible with Nginx versions 1.16 through 1.25.

  10. Compile GmSSL in a Cygwin environment

    master

    Cygwin provides a POSIX interface layer and a Linux-like toolchain (GCC, CMake) for Windows. This is useful for testing GmSSL's command-line features or using Linux shell tools on Windows.

    Note: Programs compiled in Cygwin are native Windows programs but require cygwin1.dll to run. They may have slightly higher overhead due to the POSIX translation layer.

    Steps:

    1. Download and install setup-x86_64.exe from cygwin.com.
    2. Copy your source code from the Windows filesystem to the Cygwin home directory (e.g., using /cygdrive/c/... mapping).
    3. Run the standard CMake build process.
    # Example: Copying source from Windows Downloads to Cygwin home
cp "/cygdrive/c/Users/Guan Zhi/Downloads/GmSSL-master.zip" ~~

# Build process
unzip GmSSL-master.zip
cd GmSSL-master
mkdir build
cd build
cmake ..
cmake --build .
ctest --output-on-failure
cmake --install .

  11. Trim GmSSL modules and algorithms

    master

    To reduce the binary size or meet specific deployment requirements, you can disable certain algorithms or modules during configuration. Note that disabling low-level algorithms may impact dependent protocols and tools.

    # Example: Disabling SHA1, AES, SKF, and SDF
cmake .. -DENABLE_SHA1=OFF -DENABLE_AES=OFF -DENABLE_SKF=OFF -DENABLE_SDF=OFF
cmake --build .

  12. Configure GmSSL build options (Shared vs Static)

    master

    By default, GmSSL builds shared libraries. You can control this behavior using the BUILD_SHARED_LIBS CMake variable.

    • ON: Build shared libraries (default).
    • OFF: Build static libraries.