PHPackages yangweijie/sm4-gcm - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Security](/categories/security) 4. / 5. yangweijie/sm4-gcm ActiveLibrary[Security](/categories/security) yangweijie/sm4-gcm ================== PHP implementation of SM4-GCM authenticated encryption 09[1 issues](https://github.com/yangweijie/sm4-gcm/issues)Java Since Oct 23Pushed 8mo agoCompare [ Source](https://github.com/yangweijie/sm4-gcm)[ Packagist](https://packagist.org/packages/yangweijie/sm4-gcm)[ RSS](/packages/yangweijie-sm4-gcm/feed)WikiDiscussions main Synced today READMEChangelogDependenciesVersions (1)Used By (0) SM4-GCM PHP Library =================== [](#sm4-gcm-php-library) A PHP implementation of the SM4 block cipher in Galois/Counter Mode (GCM) for authenticated encryption. Overview -------- [](#overview) This library provides a PHP implementation of the SM4-GCM authenticated encryption algorithm, which is a Chinese national standard. SM4 is a block cipher with a block size of 128 bits and a key size of 128 bits. GCM mode provides both confidentiality and authenticity. Features -------- [](#features) - SM4 block cipher implementation - GCM mode for authenticated encryption - Support for Additional Authenticated Data (AAD) - Secure parameter generation - Multiple adapters (OpenSSL, built-in) - Comprehensive exception handling - PSR-4 autoloading compliant Requirements ------------ [](#requirements) - PHP 7.4 or higher - OpenSSL extension (recommended for better performance) Note: While the OpenSSL extension is recommended for better performance, some PHP installations may not fully support SM4-GCM even if it appears in the available cipher methods list. In such cases, the library will automatically fall back to the built-in implementation. Installation ------------ [](#installation) ### Using Composer [](#using-composer) ``` composer require your-vendor/sm4-gcm ``` ### Manual Installation [](#manual-installation) 1. Clone or download the repository 2. Include the autoloader in your PHP script: ``` require_once 'vendor/autoload.php'; ``` Usage ----- [](#usage) ### Basic Encryption/Decryption [](#basic-encryptiondecryption) ``` use SM4GCM\SM4GCM; use SM4GCM\SM4GCMParameterGenerator; use SM4GCM\CryptoUtils; // Generate a random key $key = CryptoUtils::secureRandom(16); // 128 bits // Generate parameters $paramGenerator = new SM4GCMParameterGenerator(); $params = $paramGenerator->generateParameters(); $iv = $params->getIV(); // Create SM4GCM instance $sm4gcm = new SM4GCM($key, $iv); // Encrypt data $plaintext = "Hello, SM4-GCM!"; $ciphertext = $sm4gcm->encrypt($plaintext); // Decrypt data $decrypted = $sm4gcm->decrypt($ciphertext); echo $decrypted; // Outputs: Hello, SM4-GCM! ``` ### Using Additional Authenticated Data (AAD) [](#using-additional-authenticated-data-aad) ``` use SM4GCM\SM4GCM; // Create SM4GCM instance $sm4gcm = new SM4GCM($key, $iv); $aad = "Additional authenticated data"; // Encrypt with AAD $ciphertext = $sm4gcm->encrypt($plaintext, $aad); // Decrypt with AAD $decrypted = $sm4gcm->decrypt($ciphertext, $aad); ``` ### Custom Parameters [](#custom-parameters) ``` use SM4GCM\SM4GCM; use SM4GCM\SM4GCMParameters; // Create custom parameters $iv = CryptoUtils::secureRandom(12); // 96 bits IV $tagLength = 128; // 128 bits tag // Create SM4GCM instance with custom parameters $sm4gcm = new SM4GCM($key, $iv, $tagLength); ``` API Reference ------------- [](#api-reference) ### SM4GCM Class [](#sm4gcm-class) #### Constructor [](#constructor) ``` new SM4GCM(string $key, string $iv, int $tagLength = 128) ``` - `$key`: The 128-bit encryption key - `$iv`: The initialization vector (nonce) - `$tagLength`: The authentication tag length in bits (32-128, multiple of 8) #### Methods [](#methods) ##### encrypt [](#encrypt) ``` encrypt(string $plaintext, string $aad = ''): string ``` Encrypts plaintext using SM4-GCM. - `$plaintext`: The data to encrypt - `$aad`: Additional authenticated data (optional) - Returns: The ciphertext with authentication tag appended ##### decrypt [](#decrypt) ``` decrypt(string $ciphertext, string $aad = ''): string ``` Decrypts ciphertext using SM4-GCM. - `$ciphertext`: The data to decrypt (including authentication tag) - `$aad`: Additional authenticated data (optional) - Returns: The decrypted plaintext ##### updateAAD [](#updateaad) ``` updateAAD(string $aad): void ``` Sets additional authenticated data for subsequent operations. - `$aad`: The additional authenticated data ##### reset [](#reset) ``` reset(): void ``` Resets the SM4GCM instance to its initial state. ### Helper Classes [](#helper-classes) #### SM4GCMParameterGenerator [](#sm4gcmparametergenerator) Generates cryptographically secure parameters for SM4-GCM. ##### Methods [](#methods-1) ###### generateIV [](#generateiv) ``` generateIV(int $length = 12): string ``` Generates a random initialization vector. - `$length`: The IV length in bytes (default: 12) - Returns: The generated IV ###### generateParameters [](#generateparameters) ``` generateParameters(int $tagLength = 128, int $ivLength = null): SM4GCMParameters ``` Generates SM4GCMParameters with random values. - `$tagLength`: The authentication tag length in bits (default: 128) - `$ivLength`: The IV length in bytes (default: 12) - Returns: The generated SM4GCMParameters #### CryptoUtils [](#cryptoutils) Provides utility functions for cryptographic operations. ##### Methods [](#methods-2) ###### toHex [](#tohex) ``` toHex(string $bytes): string ``` Converts bytes to hexadecimal string. - `$bytes`: The bytes to convert - Returns: The hexadecimal representation ###### toBytes [](#tobytes) ``` toBytes(string $hex): string ``` Converts hexadecimal string to bytes. - `$hex`: The hexadecimal string to convert - Returns: The byte representation ###### secureRandom [](#securerandom) ``` secureRandom(int $length): string ``` Generates cryptographically secure random bytes. - `$length`: The number of bytes to generate - Returns: The random bytes ###### constantTimeEquals [](#constanttimeequals) ``` constantTimeEquals(string $a, string $b): bool ``` Compares two strings in constant time to prevent timing attacks. - `$a`: First string to compare - `$b`: Second string to compare - Returns: True if strings are equal, false otherwise Security Considerations ----------------------- [](#security-considerations) 1. **Key Management**: Keep your encryption keys secure. Never hardcode them in your source code. 2. **IV Uniqueness**: Never reuse an IV with the same key. Generate a new random IV for each encryption operation. 3. **Tag Verification**: Always verify the authentication tag before using decrypted data. 4. **Side-Channel Attacks**: This implementation attempts to mitigate timing attacks through constant-time comparisons. OpenSSL Support --------------- [](#openssl-support) This library includes an OpenSSL adapter for better performance. However, some PHP installations may not fully support SM4-GCM even if it appears in the available cipher methods list. The library automatically detects whether SM4-GCM is properly supported and will fall back to the built-in implementation if needed. You can check if OpenSSL SM4-GCM is supported in your environment: ``` use yangweijie\SM4GCM\Adapter\AdapterFactory; if (AdapterFactory::isOpenSSLSM4GCMsupported()) { echo "OpenSSL SM4-GCM is supported"; } else { echo "Using built-in implementation"; } ``` Testing ------- [](#testing) To run the test suite: ``` composer test ``` ### Comparison Testing [](#comparison-testing) This library includes a comparison testing framework that can validate the built-in implementation against an OpenSSL-based implementation. This is useful for verifying the correctness of the implementation. To run the comparison tests: ``` # Using the provided scripts cd tests/Comparison ./run_comparison_tests.sh # On Unix-like systems run_comparison_tests.bat # On Windows systems ``` Note: The comparison tests require a PHP installation with OpenSSL SM4-GCM support. The specific PHP version mentioned in the project documentation should be used for accurate testing. If the required PHP version is not available, the tests will be skipped with an appropriate message. License ------- [](#license) This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. Contributing ------------ [](#contributing) Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. Acknowledgments --------------- [](#acknowledgments) - This implementation is based on the Chinese National Standard for SM4 block cipher - Thanks to the PHP community for their valuable contributions and feedback ### Health Score 17 ↑ LowBetter than 6% of packages Maintenance43 Moderate activity, may be stable Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity13 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/c0b5f090a9bb92727e9c2e8281d05c2da5f2f9bf66cf1811714a9ffc0e383325?d=identicon)[yangweijie](/maintainers/yangweijie) --- Top Contributors [![yangweijie](https://avatars.githubusercontent.com/u/1614114?v=4)](https://github.com/yangweijie "yangweijie (4 commits)") ### Embed Badge ![Health badge](/badges/yangweijie-sm4-gcm/health.svg) ``` [![Health](https://phpackages.com/badges/yangweijie-sm4-gcm/health.svg)](https://phpackages.com/packages/yangweijie-sm4-gcm) ``` ### Alternatives [mews/purifier Laravel 5/6/7/8/9/10 HtmlPurifier Package 2.0k18.7M143](/packages/mews-purifier)[paragonie/ecc PHP Elliptic Curve Cryptography library 24820.0k38](/packages/paragonie-ecc)[laravelgems/blade-escape Custom blade directives to figth against XSS 1212.5k](/packages/laravelgems-blade-escape) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)