GmSSL-PHP

Introduction

The PHP GmSSL extension is the binding to the GmSSL C library, which provides functions of Chinese SM2, SM3, SM4, SM9, ZUC crypto algorithms.

Download

Installation

To compile and install the GmSSL PHP extension, you need to install the GmSSL library (version >= 3.1.0). See the GmSSL INSTALL.md for more details.

$ cd GmSSL-PHP-master
$ phpize
$ ./configure
$ make
$ sudo make install

The GmSSL PHP extension need to be enabled in the php.ini.

$ sudo vim `php-config --ini-path`/php.ini

Search “Dynamic Extensions” and dd a new line extension=gmssl at the end of this section.

You can print the constant value GMSSL_PHP_VERSION to see if the GmSSL extension is correctly installed.

<?php
print(GMSSL_PHP_VERSION."\n");
?>

php gmssl.php

Quick Start

You can start GmSSL extension with the following simple examples of SM3, SM4 and SM2 crypto algorithms.

SM3 Examples

SM3 is a cryptographic hash function with 256-bit output hash value. Compute the SM3 digest of the string “abc”.

<?php
	$hash = gmssl_sm3("abc");
	print(bin2hex($hash)."\n");
?>

SM4 Examples

SM4 is a block cipher with 128-bit key length and 128-bit block size. Use SM4 to encrypt a block of message (16 bytes).

<?php
	$key = gmssl_rand_bytes(GMSSL_SM4_KEY_SIZE);
	$block = gmssl_rand_bytes(GMSSL_SM4_BLOCK_SIZE);
	$ciphertext = gmssl_sm4_encrypt($key, $block);
	$plaintext = gmssl_sm4_decrypt($key, $ciphertext);

	print(bin2hex($block)."\n");
	print(bin2hex($plaintext)."\n");
?>

The gmssl_sm4_encrypt and gmssl_sm4_decrypt functions export low-level API of SM4 block cipher. For the encryption of typical message, You can use SM4 with some encryption modes, such as CBC, CTR and GCM mode. The GCM mode is the recommended mode for non-expert users.

<?php
	$key = gmssl_rand_bytes(GMSSL_SM4_KEY_SIZE);
	$iv = gmssl_rand_bytes(GMSSL_SM4_GCM_DEFAULT_ID_SIZE);
	$aad = "Encoding: Text";
	$message = "This is the secret text message.";

	$ciphertext = gmssl_sm4_gcm_encrypt($key, $iv, $aad, $message, GMSSL_SM4_GCM_MAX_TAG_SIZE);
	$plaintext = gmssl_sm4_gcm_decrypt($key, $iv, $aad, $ciphertext, GMSSL_SM4_GCM_MAX_TAG_SIZE);

	print(bin2hex($message)."\n");
	print(bin2hex($plaintext)."\n");
?>

SM2 Examples

SM2 is the ellptic curve cryptogrphy standard of China. The standard includes the SM2 signature algorithm, the SM2 public key encryption algorithm and the recommended 256-bit SM2 domain parameters. Here is the example of SM2 key generation, signature generation/verification, and the SM2 public key encryption/decryption.

<?php
	$sm2_key = gmssl_sm2_key_generate();
	$pass = "123456";
	gmssl_sm2_private_key_info_encrypt_to_pem($sm2_key, $pass, "sm2.pem");
	gmssl_sm2_public_key_info_to_pem($sm2_key, "sm2pub.pem");
	$sm2_pub = gmssl_sm2_public_key_info_from_pem("sm2pub.pem");

	$sig = gmssl_sm2_sign($sign_key, GMSSL_SM2_DEFAULT_ID, "To be signed message");
	print(gmssl_sm2_verify($sm2_pub, GMSSL_SM2_DEFAULT_ID, "To be signed message", $sig)."\n");

	$ciphertext = gmssl_sm2_encrypt($sm2_pub, "Secret key materials");
	$plaintext = gmssl_sm2_decrypt($sm2_key, $ciphertext);
	print($plaintext."\n");
?>

GmSSL PHP API

Predefined Constants

Functions

gmssl_rand_bytes

Generate cryptographic secure random bytes.

gmssl_rand_bytes(int $length): string

gmssl_sm3

Calculate the SM3 digest of a message.

gmssl_sm3(string $message): string

gmssl_sm3_hmac

Calculate the HMAC-SM3 MAC tag of a messag.

gmssl_sm3_hmac(
	string $key,
	string $message
): string

gmssl_sm3_pbkdf2

Extract key material from a password by using KBKDF2-HMAC-SM3

gmssl_sm3_pbkdf2(
	string $password,
	string $salt,
	int $iter,
	string $outlen
): string

gmssl_sm4_encrypt

Encrypt a block of message (16-bytes) using SM4 block cipher.

gmssl_sm4_encrypt(
	string $key,
	string $data_block
): string

gmssl_sm4_decrypt

Decrypt a block of message (16-bytes) using SM4 block cipher.

gmssl_sm4_decrypt(
	string $key,
	string $cipher_block
): string

gmssl_sm4_cbc_encrypt

Encrypt message using SM4-CBC mode (with padding)

gmssl_sm4_cbc_encrypt(
	string $key,
	string $iv,
	string $data
): string

gmssl_sm4_cbc_decrypt

Decrypt SM4-CBC (with padding) ciphertext

gmssl_sm4_cbc_decrypt(
	string $key,
	string $iv,
	string $ciphertext
): string

gmssl_sm4_ctr_encrypt

Encrypt/decrypt message with SM4-CTR mode. The encryption and decryption is the same in CTR mode. So there is no gmssl_sm4_ctr_decrypt.

gmssl_sm4_ctr_encrypt(
	string $key,
	string $iv,
	string $data
): string

gmssl_sm4_gcm_encrypt

Encrypt message using SM4-GCM mode

gmssl_sm4_gcm_encrypt(
	string $key,
	string $iv,
	string $aad,
	int $taglen,
	string $data
): string

gmssl_sm4_gcm_decrypt

Decrypt SM4-GCM ciphertext

gmssl_sm4_gcm_decrypt(
	string $key,
	string $iv,
	string $aad,
	int $taglen,
	string $ciphertext
): string

gmssl_zuc_encrypt

Encrypt/decrypt message using ZUC stream cipher

gmssl_zuc_encrypt(
	string $key,
	string $iv,
	string $data
): string

gmssl_sm2_key_generate

Generate SM2 Keypair

gmssl_sm2_key_generate(): string

gmssl_sm2_compute_z

Compute SM2 Z value from SM2 public key and user’s identity.

gmssl_sm2_compute_z(
	string $public_key,
	string $id
): string

gmssl_sm2_private_key_info_encrypt_to_pem

Export SM2 private key to password encrypted PEM file

gmssl_sm2_private_key_info_encrypt_to_pem(
	string $keypair,
	string $file,
	string $passphrase
): bool

gmssl_sm2_private_key_info_decrypt_from_pem

Import SM2 private key from password encrypted PEM file

gmssl_sm2_private_key_info_decrypt_from_pem(
	string $file,
	string $passphrase
): string

gmssl_sm2_public_key_info_to_pem

Export SM2 public key to PEM file.

gmssl_sm2_public_key_info_to_pem(
	string $public_key,
	string $file,
): bool

gmssl_sm2_public_key_info_from_pem

Import SM2 public key from PEM file.

gmssl_sm2_public_key_info_from_pem(
	string $file,
): string

gmssl_sm2_sign

Sign message (not digest) and generate SM2 signature

gmssl_sm2_sign(
	string $keypair,
	string $id,
	string $message
): string

gmssl_sm2_verify

gmssl_sm2_verify - Verify SM2 signature

gmssl_sm2_verify(
	string $public_key,
	string $id,
	string $message,
	string $signature
): bool

gmssl_sm2_encrypt

Encrypt short secret message with SM2 public key.

gmssl_sm2_encrypt(
	string $public_key,
	string $data
): string

gmssl_sm2_decrypt

Decrypt SM2 ciphertext with SM2 private key

gmssl_sm2_decrypt(
	string $keypair,
	string $ciphertext
): string

gmssl_sm9_sign_master_key_generate

Generate SM9 signing master key

gmssl_sm9_sign_master_key_generate(): string

gmssl_sm9_sign_master_key_extract_key

Extract the signing private key from SM9 master key with signer’s ID

gmssl_sm9_sign_master_key_extract_key(
	string $master_key,
	string $id
): string

gmssl_sm9_sign_master_key_info_encrypt_to_pem

Export SM9 signing master key to encrypted PEM file

gmssl_sm9_sign_master_key_info_encrypt_to_pem(
	string $master_key,
	string $file,
	string $passphrase
): bool

gmssl_sm9_sign_master_key_info_decrypt_from_pem

Import SM9 signing master key from encrypted PEM file

gmssl_sm9_sign_master_key_info_decrypt_from_pem(
	string $file,
	string $passphrase
): string

gmssl_sm9_sign_master_public_key_to_pem

Export SM9 signing master public key to file

gmssl_sm9_sign_master_public_key_to_pem(
	string $master_key,
	string $file,
): bool

gmssl_sm9_sign_master_public_key_from_pem

Import SM9 signing master public key from file

gmssl_sm9_sign_master_public_key_from_pem(
	string $file
): string

gmssl_sm9_sign_key_info_encrypt_to_pem

Export user’s SM9 signing key to encrypted PEM file

gmssl_sm9_sign_key_info_encrypt_to_pem(
	string $sign_key,
	string $file,
	string $passphrase
): bool

gmssl_sm9_sign_key_info_decrypt_from_pem

Import user’s SM9 signing key from encrypted PEM file

gmssl_sm9_sign_key_info_decrypt_from_pem(
	string $file,
	string $passphrase
): string

gmssl_sm9_sign

Sign message with user’s SM9 signing key

gmssl_sm9_sign(
	string $sign_key,
	string $message
): string

gmssl_sm9_verify

Verify SM9 signature of message with signer’s ID

gmssl_sm9_verify(
	string $master_public_key,
	string $id,
	string $message,
	string $signature
): bool

gmssl_sm9_enc_master_key_generate

Generate SM9 encryption master key

gmssl_sm9_enc_master_key_generate(): string

gmssl_sm9_enc_master_key_extract_key

Extract the encryption private key from SM9 master key with user’s ID

gmssl_sm9_enc_master_key_extract_key(
	string $master_key,
	string $id
): string

###gmssl_sm9_enc_master_key_info_encrypt_to_pem

Export SM9 encryption master key to encrypted PEM file

gmssl_sm9_enc_master_key_info_encrypt_to_pem(
	string $master_key,
	string $file,
	string $passphrase
): bool

gmssl_sm9_enc_master_key_info_decrypt_from_pem

Import SM9 encryption master key from encrypted PEM file

gmssl_sm9_enc_master_key_info_decrypt_from_pem(
	string $file,
	string $passphrase
): string

gmssl_sm9_enc_master_public_key_to_pem

Export SM9 encryption master public key to file

gmssl_sm9_enc_master_public_key_to_pem(
	string $master_key,
	string $file,
): bool

gmssl_sm9_enc_master_public_key_from_pem

Import SM9 encryption master public key from file

gmssl_sm9_enc_master_public_key_from_pem(
	string $file
): string

gmssl_sm9_enc_key_info_encrypt_to_pem

Export user’s SM9 encryption key to encrypted PEM file

gmssl_sm9_enc_key_info_encrypt_to_pem(
	string $enc_key,
	string $file,
	string $passphrase
): bool

gmssl_sm9_enc_key_info_decrypt_from_pem

Import user’s SM9 encryption key from encrypted PEM file

gmssl_sm9_enc_key_info_decrypt_from_pem(
	string $file,
	string $passphrase
): string

gmssl_sm9_encrypt

Encrypt short message with recipient’s ID

gmssl_sm9_encrypt(
	string $master_public_key,
	string $id,
	string $data
): string

gmssl_sm9_decrypt

Decrypt SM9 ciphertext with user’s SM9 private key

gmssl_sm9_decrypt(
	string $enc_key,
	string $id,
	string $ciphertext
): string

gmssl_cert_from_pem

Import X.509 certificate from PEM file.

gmssl_cert_from_pem(string $path): string

gmssl_cert_print

Print details of a X.509 certificate.

gmssl_cert_print(
	string $cert,
	string $label
): bool

gmssl_cert_get_serial_number

Get the SerialNumber field of a X.509 certificate.

gmssl_cert_get_serial_number(string $cert): string

gmssl_cert_get_issuer

Get the Issuer field of a X.509 certificate.

gmssl_cert_get_issuer(string $cert): array

gmssl_cert_get_validity

Get the Validity field of a X.509 certificate.

gmssl_cert_get_validity(string $cert): array

gmssl_cert_get_subject

Get the Subject field of a X.509 certificate.

gmssl_cert_get_subject(string $cert): array

gmssl_cert_get_subject_public_key

Get the SM2 public key from the SubjectPublicKeyInfo field of a X.509 certificate.

gmssl_cert_get_subject_public_key(string $cert): string

gmssl_cert_verify_by_ca_cert

Verify a X.509 certificate by a CA certificate.

gmssl_cert_verify_by_ca_cert(
	string $cert,
	string $cacert,
	string $sm2_id
): bool
This site is open source. Improve this page.