{"id":9776,"library":"gmssl","title":"GMSSL: China's National Cryptographic Algorithms","description":"GMSSL is a pure-Python library providing implementations of China's national cryptographic algorithms: SM2 (elliptic curve cryptography), SM3 (hash function), and SM4 (block cipher). It is currently at version 3.2.2 and is actively maintained, with releases typically following bug fixes or minor enhancements.","status":"active","version":"3.2.2","language":"en","source_language":"en","source_url":"https://github.com/duanhongyi/gmssl","tags":["cryptography","sm2","sm3","sm4","china-cryptography","pure-python"],"install":[{"cmd":"pip install gmssl","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"sm2","correct":"from gmssl import sm2"},{"symbol":"sm3","correct":"from gmssl import sm3"},{"symbol":"sm4","correct":"from gmssl import sm4"}],"quickstart":{"code":"from gmssl import sm4\n\n# SM4 operates on 16-byte blocks with a 16-byte key.\nkey = b'this is a 16-byt' # Must be 16 bytes\niv = b'this is a 16-byt'  # Must be 16 bytes for CBC mode\n\n# Example for ECB mode (no IV needed, but data must be padded/block aligned)\n# gmssl.sm4.encrypt/decrypt handles PKCS7 padding automatically if not block-aligned.\noriginal_data_ecb = b'Hello world! This is a test message for SM4 ECB mode.'\nencrypted_ecb = sm4.encrypt(key, original_data_ecb)\ndecrypted_ecb = sm4.decrypt(key, encrypted_ecb)\nassert original_data_ecb == decrypted_ecb\nprint(f\"SM4 ECB: Original: {original_data_ecb}, Decrypted: {decrypted_ecb}\")\n\n# Example for CBC mode (IV required)\noriginal_data_cbc = b'Another test message for SM4 CBC mode, with an IV.'\nencrypted_cbc = sm4.encrypt(key, original_data_cbc, iv)\ndecrypted_cbc = sm4.decrypt(key, encrypted_cbc, iv)\nassert original_data_cbc == decrypted_cbc\nprint(f\"SM4 CBC: Original: {original_data_cbc}, Decrypted: {decrypted_cbc}\")\n\nprint(\"SM4 encryption/decryption examples completed successfully.\")","lang":"python","description":"Encrypts and decrypts data using SM4 in both ECB and CBC modes, demonstrating the required `bytes` input for keys, IVs, and data. The library automatically handles PKCS7 padding for `encrypt` and removes it for `decrypt`."},"warnings":[{"fix":"Ensure all string literals are prefixed with `b` (e.g., `b'mydata'`) or explicitly encoded (e.g., `mystring.encode('utf-8')`).","message":"All cryptographic inputs (keys, IVs, data) and outputs must be `bytes`. Passing `str` will result in a `TypeError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the key and IV variables are `bytes` objects exactly 16 bytes long. For example, `key = b'mysecretkey12345'`.","message":"SM4 keys and IVs must be exactly 16 bytes long. Providing an incorrect length will raise a `ValueError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For performance-critical applications, consider benchmarking `gmssl` against alternatives or optimizing application design to minimize cryptographic overhead.","message":"As a pure-Python implementation, `gmssl` might exhibit lower performance for high-throughput cryptographic operations compared to C-accelerated libraries.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install gmssl` to install the library.","cause":"The `gmssl` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'gmssl'"},{"fix":"Ensure the key variable is a `bytes` object exactly 16 bytes long. For example, `key = b'mysecretkey12345'`.","cause":"The SM4 key provided for encryption/decryption does not have the required length of 16 bytes.","error":"ValueError: key is not 16 bytes"},{"fix":"Convert the string to bytes using `.encode('utf-8')` or ensure string literals are byte literals (e.g., `b'data'`).","cause":"A string (`str`) was passed to a cryptographic function that expects byte-like objects (`bytes`).","error":"TypeError: argument should be bytes or other byte-like object, not str"}]}