### Install GmSSL PHP Extension

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

This snippet outlines the bash commands required to compile and install the GmSSL PHP extension. It assumes the GmSSL library is already installed and accessible.

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

--------------------------------

### Verify GmSSL PHP Extension Installation

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

This PHP code snippet checks if the GmSSL extension is correctly installed by printing the GMSSL_PHP_VERSION constant. It's a simple verification step after enabling the extension.

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

--------------------------------

### Enable GmSSL Extension in php.ini

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

This snippet shows how to enable the GmSSL PHP extension by adding 'extension=gmssl' to the php.ini file. This is a necessary step after installation for the extension to be recognized by PHP.

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

--------------------------------

### Derive Key Material with PBKDF2-HMAC-SM3 in GmSSL-PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Derives cryptographic key material from a password using the PBKDF2 algorithm with HMAC-SM3. The gmssl_sm3_pbkdf2 function requires the password, salt, number of iterations, and desired key length as parameters. The example demonstrates deriving an encryption key.

```php
<?php
// Derive encryption key from password
$password = "MySecureP@ssw0rd!";
$salt = gmssl_rand_bytes(16);
$iterations = 10000;
$key_length = 32;

$derived_key = gmssl_sm3_pbkdf2($password, $salt, $iterations, $key_length);
echo "Derived key: " . bin2hex($derived_key) . "\n";
echo "Key length: " . strlen($derived_key) . " bytes\n";

// Use derived key for encryption
$encryption_key = gmssl_sm3_pbkdf2($password, $salt, 10000, GMSSL_SM4_KEY_SIZE);
$plaintext = "Secret data";
$iv = gmssl_rand_bytes(GMSSL_SM4_GCM_DEFAULT_IV_SIZE);
$ciphertext = gmssl_sm4_gcm_encrypt($encryption_key, $iv, "", GMSSL_SM4_GCM_MAX_TAG_SIZE, $plaintext);
?>
```

--------------------------------

### Get Certificate Subject and Issuer Details (PHP)

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Extracts and displays the subject and issuer information from an X.509 certificate loaded via PEM format. It shows how to access common fields like CN, O, OU, and C, and includes a check for self-signed certificates. Requires the gmssl extension.

```php
<?php
// Load certificate
$cert = gmssl_cert_from_pem("certificate.pem");

// Get subject information
$subject = gmssl_cert_get_subject($cert);
echo "Subject:\n";
echo "  CN: " . ($subject['CN'] ?? 'N/A') . "\n";
echo "  O: " . ($subject['O'] ?? 'N/A') . "\n";
echo "  OU: " . ($subject['OU'] ?? 'N/A') . "\n";
echo "  C: " . ($subject['C'] ?? 'N/A') . "\n";

// Get issuer information
$issuer = gmssl_cert_get_issuer($cert);
echo "Issuer:\n";
echo "  CN: " . ($issuer['CN'] ?? 'N/A') . "\n";
echo "  O: " . ($issuer['O'] ?? 'N/A') . "\n";

// Check if self-signed
if ($subject['raw_data'] === $issuer['raw_data']) {
    echo "Certificate is self-signed\n";
}
?>

```

--------------------------------

### SM4 Block Cipher Encryption/Decryption with GmSSL-PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Performs low-level encryption and decryption using the SM4 block cipher. The gmssl_sm4_encrypt and gmssl_sm4_decrypt functions operate on 16-byte blocks and require a key and plaintext/ciphertext block. The example demonstrates a round-trip encryption and decryption verification.

```php
<?php
// Low-level SM4 block encryption
$key = gmssl_rand_bytes(GMSSL_SM4_KEY_SIZE);
$plaintext_block = gmssl_rand_bytes(GMSSL_SM4_BLOCK_SIZE);

$ciphertext_block = gmssl_sm4_encrypt($key, $plaintext_block);
$decrypted_block = gmssl_sm4_decrypt($key, $ciphertext_block);

echo "Key: " . bin2hex($key) . "\n";
echo "Plaintext: " . bin2hex($plaintext_block) . "\n";
echo "Ciphertext: " . bin2hex($ciphertext_block) . "\n";
echo "Decrypted: " . bin2hex($decrypted_block) . "\n";

// Verify round-trip
if ($plaintext_block === $decrypted_block) {
    echo "Encryption/decryption successful\n";
}
?>
```

--------------------------------

### Compute SM3 Hash Digest with GmSSL-PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Computes the SM3 cryptographic hash of a given message. The function gmssl_sm3 takes a string as input and returns a 256-bit (32-byte) hash digest. Examples show hashing a simple string and arbitrary data.

```php
<?php
// Hash a simple message
$message = "abc";
$digest = gmssl_sm3($message);
echo "SM3('abc'): " . bin2hex($digest) . "\n";
// Output: 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0

// Hash arbitrary data
$data = "The quick brown fox jumps over the lazy dog";
$hash = gmssl_sm3($data);
echo "Digest length: " . strlen($hash) . " bytes\n";
echo "Hash: " . bin2hex($hash) . "\n";
?>
```

--------------------------------

### Generate SM2 key pair in PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Generates an SM2 elliptic curve key pair using the GMSSL extension. This key pair can be used for digital signatures and public-key encryption. The example shows how to generate the keys, save them to PEM files (private key with password protection), and then load them back.

```php
<?php
// Generate SM2 key pair
$sm2_key = gmssl_sm2_key_generate();

// Save private key with password protection
$password = "SecurePassword123!";
$private_key_file = "sm2_private.pem";
$public_key_file = "sm2_public.pem";

gmssl_sm2_private_key_info_encrypt_to_pem($sm2_key, $private_key_file, $password);
gmssl_sm2_public_key_info_to_pem($sm2_key, $public_key_file);

echo "Private key saved to: " . $private_key_file . "\n";
echo "Public key saved to: " . $public_key_file . "\n";

// Load keys from files
$loaded_private = gmssl_sm2_private_key_info_decrypt_from_pem($private_key_file, $password);
$loaded_public = gmssl_sm2_public_key_info_from_pem($public_key_file);

echo "Keys generated and loaded successfully\n";
?>

```

--------------------------------

### Get Subject's Public Key from X.509 Certificate (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Retrieves the SM2 public key from the SubjectPublicKeyInfo field of an X.509 certificate. The function takes the certificate string and returns the public key as a string, formatted identically to the output of `sm2_public_key_info_from_pem`. Exceptions are thrown for invalid inputs or library errors.

```php
gmssl_cert_get_subject_public_key(string $cert): string
```

--------------------------------

### Get Issuer Field of X.509 Certificate (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Retrieves the Issuer field from an SM2 X.509 certificate. The input is a string representing the certificate, typically obtained from `gmssl_cert_from_pem`. The function returns an array containing certificate details, including a 'raw_data' field with the DER-encoding of the Issuer's Distinguished Name.

```php
gmssl_cert_get_issuer(string $cert): array
```

--------------------------------

### Get Validity Field of X.509 Certificate (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Extracts the Validity period from an SM2 X.509 certificate. This function takes the certificate string as input and returns an array with 'notBefore' and 'notAfter' keys, each containing an integer timestamp representing the certificate's validity range. Invalid parameters or GmSSL library errors will result in exceptions.

```php
gmssl_cert_get_validity(string $cert): array
```

--------------------------------

### gmssl_sm9_sign_master_public_key_from_pem

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports the SM9 signing master public key from a PEM file.

```APIDOC
## gmssl_sm9_sign_master_public_key_from_pem

### Description
Imports the SM9 signing master public key from a file.

### Method
`gmssl_sm9_sign_master_public_key_from_pem`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php
// Example usage:
gmssl_sm9_sign_master_public_key_from_pem('/path/to/master_public_key.pem');
?>
```

### Response
#### Success Response (string)
- **master_public_key** (string) - The imported SM9 signing master public key.

#### Response Example
```json
{
    "master_public_key": "-----BEGIN SM9 MASTER PUBLIC KEY-----\n...\n-----END SM9 MASTER PUBLIC KEY-----"
}
```

#### Errors/Exceptions
- Throws exceptions on invalid parameters and GmSSL library inner errors.
```

--------------------------------

### Get SM2 Certificate Serial Number - PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Retrieves the SerialNumber field from an SM2 X.509 certificate. The function requires the certificate data. It returns the raw bytes of the SerialNumber or throws exceptions on errors.

```php
gmssl_cert_get_serial_number(string $cert): string
```

--------------------------------

### Extract Public Key and Verify/Encrypt with SM2 (PHP)

Source: https://context7.com/gmssl/gmssl-php/llms.txt

This snippet demonstrates how to load an X.509 certificate, extract its SM2 public key, and then use that public key to verify a digital signature and encrypt data. It relies on the gmssl_cert_from_pem, gmssl_cert_get_subject_public_key, gmssl_sm2_verify, and gmssl_sm2_encrypt functions.

```php
<?php
// Load certificate
$cert = gmssl_cert_from_pem("user_cert.pem");

// Extract public key
$public_key = gmssl_cert_get_subject_public_key($cert);
echo "Public key extracted successfully\n";

// Use public key to verify a signature
$message = "Signed document content";
$signature_file = "document.sig";
$signature = file_get_contents($signature_file);

try {
    $is_valid = gmssl_sm2_verify($public_key, GMSSL_SM2_DEFAULT_ID, $message, $signature);
    echo "Signature verification: " . ($is_valid ? "Valid" : "Invalid") . "\n";
} catch (Exception $e) {
    echo "Verification error: " . $e->getMessage() . "\n";
}

// Use public key to encrypt data
$plaintext = "Encrypted message for certificate holder";
$ciphertext = gmssl_sm2_encrypt($public_key, $plaintext);
echo "Message encrypted with certificate's public key\n";
?>
```

--------------------------------

### gmssl_sm9_sign_master_public_key_to_pem

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports the SM9 signing master public key to a PEM file.

```APIDOC
## gmssl_sm9_sign_master_public_key_to_pem

### Description
Exports the SM9 signing master public key to a file.

### Method
`gmssl_sm9_sign_master_public_key_to_pem`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php
// Example usage:
gmssl_sm9_sign_master_public_key_to_pem($master_key, '/path/to/master_public_key.pem');
?>
```

### Response
#### Success Response (bool)
- **success** (bool) - **true** on success.

#### Response Example
```json
{
    "success": true
}
```

#### Errors/Exceptions
- Throws exceptions on invalid parameters and GmSSL library inner errors.
```

--------------------------------

### gmssl_sm9_sign_master_key_info_decrypt_from_pem

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports an SM9 signing master key from an encrypted PEM file.

```APIDOC
## gmssl_sm9_sign_master_key_info_decrypt_from_pem

### Description
Imports SM9 signing master key from encrypted PEM file.

### Method
`gmssl_sm9_sign_master_key_info_decrypt_from_pem`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php
// Example usage:
gmssl_sm9_sign_master_key_info_decrypt_from_pem('/path/to/encrypted_master_key.pem', 'your_passphrase');
?>
```

### Response
#### Success Response (string)
- **master_key** (string) - The decrypted SM9 signing master key.

#### Response Example
```json
{
    "master_key": "-----BEGIN SM9 MASTER PRIVATE KEY-----\n...\n-----END SM9 MASTER PRIVATE KEY-----"
}
```

#### Errors/Exceptions
- Throws exceptions on invalid parameters and GmSSL library inner errors.
```

--------------------------------

### gmssl_sm9_sign_key_info_encrypt_to_pem

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports a user's SM9 signing key to an encrypted PEM file.

```APIDOC
## gmssl_sm9_sign_key_info_encrypt_to_pem

### Description
Exports a user's SM9 signing key to an encrypted PEM file.

### Method
`gmssl_sm9_sign_key_info_encrypt_to_pem`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php
// Example usage:
gmssl_sm9_sign_key_info_encrypt_to_pem($sign_key, '/path/to/encrypted_sign_key.pem', 'your_passphrase');
?>
```

### Response
#### Success Response (bool)
- **success** (bool) - **true** on success.

#### Response Example
```json
{
    "success": true
}
```

#### Errors/Exceptions
- Throws exceptions on invalid parameters and GmSSL library inner errors.
```

--------------------------------

### Get Subject Field of X.509 Certificate (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Obtains the Subject field from an SM2 X.509 certificate. The function expects the certificate as a string and returns an array representing the Subject. Similar to the issuer retrieval, a 'raw_data' key provides the DER-encoded Subject's Distinguished Name.

```php
gmssl_cert_get_subject(string $cert): array
```

--------------------------------

### gmssl_sm9_sign_key_info_decrypt_from_pem

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports a user's SM9 signing key from an encrypted PEM file.

```APIDOC
## gmssl_sm9_sign_key_info_decrypt_from_pem

### Description
Imports a user's SM9 signing key from an encrypted PEM file.

### Method
`gmssl_sm9_sign_key_info_decrypt_from_pem`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php
// Example usage:
gmssl_sm9_sign_key_info_decrypt_from_pem('/path/to/encrypted_sign_key.pem', 'your_passphrase');
?>
```

### Response
#### Success Response (string)
- **sign_key** (string) - The decrypted SM9 signing private key.

#### Response Example
```json
{
    "sign_key": "-----BEGIN SM9 PRIVATE KEY-----\n...\n-----END SM9 PRIVATE KEY-----"
}
```

#### Errors/Exceptions
- Throws exceptions on invalid parameters and GmSSL library inner errors.
```

--------------------------------

### Sign and Verify Messages with SM2 in PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Demonstrates how to sign a message using an SM2 private key and verify the signature with the corresponding public key. It also shows how tampering with the message invalidates the signature. Requires gmssl extension.

```php
<?php
// Generate key pair
$sm2_key = gmssl_sm2_key_generate();
$password = "P@ssw0rd";

// Save and load keys
gmssl_sm2_private_key_info_encrypt_to_pem($sm2_key, "sm2.pem", $password);
gmssl_sm2_public_key_info_to_pem($sm2_key, "sm2pub.pem");

$private_key = gmssl_sm2_private_key_info_decrypt_from_pem("sm2.pem", $password);
$public_key = gmssl_sm2_public_key_info_from_pem("sm2pub.pem");

// Sign a message
$message = "Contract: Transfer $10000 to Account #12345";
$signature = gmssl_sm2_sign($private_key, GMSSL_SM2_DEFAULT_ID, $message);

echo "Message: " . $message . "\n";
echo "Signature: " . bin2hex($signature) . "\n";
echo "Signature length: " . strlen($signature) . " bytes\n";

// Verify signature
$is_valid = gmssl_sm2_verify($public_key, GMSSL_SM2_DEFAULT_ID, $message, $signature);
echo "Signature valid: " . ($is_valid ? "Yes" : "No") . "\n";

// Verify with tampered message
$tampered_message = "Contract: Transfer $99999 to Account #12345";
$is_valid_tampered = gmssl_sm2_verify($public_key, GMSSL_SM2_DEFAULT_ID, $tampered_message, $signature);
echo "Tampered message valid: " . ($is_valid_tampered ? "Yes" : "No") . "\n";
?>

```

--------------------------------

### gmssl_sm9_enc_master_key_info_encrypt_to_pem

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports the SM9 encryption master key to an encrypted PEM file.

```APIDOC
## gmssl_sm9_enc_master_key_info_encrypt_to_pem

### Description
Exports the SM9 encryption master key to an encrypted PEM file.

### Method
`gmssl_sm9_enc_master_key_info_encrypt_to_pem`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php
// Example usage:
gmssl_sm9_enc_master_key_info_encrypt_to_pem($master_key, '/path/to/encrypted_master_key.pem', 'your_passphrase');
?>
```

### Response
#### Success Response (bool)
- **success** (bool) - **true** on success.

#### Response Example
```json
{
    "success": true
}
```

#### Errors/Exceptions
- Throws exceptions on invalid parameters and GmSSL library inner errors.
```

--------------------------------

### Derive Key Material with gmssl_sm3_pbkdf2

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Extracts key material from a password using the KBKDF2-HMAC-SM3 algorithm. It requires a password, salt (at least 8 bytes), iteration count, and desired output length. Recommended iterations are over 8000. Returns raw binary string or NULL on failure.

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

--------------------------------

### Import Decrypted SM2 Private Key from PEM using PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports an SM2 private key from a password-encrypted PEM file. It requires the path to the PEM file and the correct passphrase used for encryption. The function returns the SM2 private key in its inner format, equivalent to the output of `gmssl_sm2_key_generate`. Errors are thrown for invalid parameters or library issues.

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

--------------------------------

### Load X.509 Certificate from PEM (PHP)

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Loads and parses an X.509 certificate from a PEM file using the gmssl extension. It demonstrates how to print certificate details, extract the serial number, and retrieve the validity period (notBefore and notAfter dates).

```php
<?php
// Load certificate from file
$cert_file = "certificate.pem";
$cert = gmssl_cert_from_pem($cert_file);

// Print certificate details
gmssl_cert_print($cert, "Certificate Information");

// Extract serial number
$serial = gmssl_cert_get_serial_number($cert);
echo "Serial Number: " . bin2hex($serial) . "\n";

// Get validity period
$validity = gmssl_cert_get_validity($cert);
echo "Not Before: " . date('Y-m-d H:i:s', $validity['notBefore']) . "\n";
echo "Not After: " . date('Y-m-d H:i:s', $validity['notAfter']) . "\n";

// Check if certificate is currently valid
$now = time();
if ($now >= $validity['notBefore'] && $now <= $validity['notAfter']) {
    echo "Certificate is currently valid\n";
} else {
    echo "Certificate is expired or not yet valid\n";
}
?>

```

--------------------------------

### gmssl_sm9_enc_master_key_generate

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Generates an SM9 encryption master key.

```APIDOC
## gmssl_sm9_enc_master_key_generate

### Description
Generates an SM9 encryption master key.

### Method
`gmssl_sm9_enc_master_key_generate`

### Parameters
None

### Request Example
```php
<?php
// Example usage:
gmssl_sm9_enc_master_key_generate();
?>
```

### Response
#### Success Response (string)
- **master_key** (string) - The generated SM9 encryption master key.

#### Response Example
```json
{
    "master_key": "-----BEGIN SM9 ENCRYPTION MASTER KEY-----\n...\n-----END SM9 ENCRYPTION MASTER KEY-----"
}
```

#### Errors/Exceptions
- Throws exceptions on GmSSL library inner errors.
```

--------------------------------

### Import SM9 Encryption Master Public Key from PEM - PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports an SM9 encryption master public key from a PEM file. The function requires the path to the PEM file. It returns the master public key as a string and will throw exceptions for invalid parameters or library errors.

```php
gmssl_sm9_enc_master_public_key_from_pem(
	string $file
): string
```

--------------------------------

### Export Encrypted SM9 Signing Master Key to PEM (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports an SM9 signing master key to an encrypted PEM file. Requires the master key, the output file path, and a passphrase for encryption. Returns true on success and false on failure, throwing exceptions for invalid inputs or library errors.

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

--------------------------------

### Generate SM2 Keypair using PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Generates an SM2 keypair, returning a 96-byte string. The first 64 bytes represent the raw public key, and the last 32 bytes represent the raw private key. Exceptions are thrown for GmSSL library errors.

```php
gmssl_sm2_key_generate(): string
```

--------------------------------

### Export SM9 Signing Master Public Key to PEM - gmssl-php

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports the SM9 signing master public key to a specified PEM file. This function takes the master key or master public key and the output file path as parameters. It returns true on success and false on failure. Errors can occur due to invalid parameters or GmSSL library issues.

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

--------------------------------

### Generate SM9 Signing Master Key (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Generates a new SM9 signing master key. This function takes no parameters and returns the master key as a string. It will throw exceptions if there are issues within the GmSSL library during generation.

```php
gmssl_sm9_sign_master_key_generate(): string
```

--------------------------------

### Import SM2 Public Key from PEM (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports an SM2 public key from a PEM file. The function returns the SM2 public key as a 96-byte string, with the last 32 bytes set to zero if a private key was provided. It throws exceptions for invalid parameters or GmSSL library errors.

```php
gmssl_sm2_public_key_info_from_pem(
	string $file,
): string
```

--------------------------------

### Export Encrypted SM2 Private Key to PEM using PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports an SM2 private key to a password-encrypted PEM file. It takes the 96-byte keypair string generated by `gmssl_sm2_key_generate`, the desired output file path, and a passphrase for encryption. Returns true on success, false on failure, and throws exceptions for invalid parameters or library errors.

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

--------------------------------

### Derive key material using PBKDF2-HMAC-SM3

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Derives cryptographic key material from a password using PBKDF2 with HMAC-SM3 via the `gmssl_sm3_pbkdf2` function.

```APIDOC
## gmssl_sm3_pbkdf2

### Description
Derives cryptographic key material from a password using PBKDF2 with HMAC-SM3.

### Method
`gmssl_sm3_pbkdf2(string $password, string $salt, int $iterations, int $key_length): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php
// Derive encryption key from password
$password = "MySecureP@ssw0rd!";
$salt = gmssl_rand_bytes(16);
$iterations = 10000;
$key_length = 32;

$derived_key = gmssl_sm3_pbkdf2($password, $salt, $iterations, $key_length);
echo "Derived key: " . bin2hex($derived_key) . "\n";
echo "Key length: " . strlen($derived_key) . " bytes\n";

// Use derived key for encryption
$encryption_key = gmssl_sm3_pbkdf2($password, $salt, 10000, GMSSL_SM4_KEY_SIZE);
$plaintext = "Secret data";
$iv = gmssl_rand_bytes(GMSSL_SM4_GCM_DEFAULT_IV_SIZE);
$ciphertext = gmssl_sm4_gcm_encrypt($encryption_key, $iv, "", GMSSL_SM4_GCM_MAX_TAG_SIZE, $plaintext);
?>
```

### Response
#### Success Response (200)
- **derived_key** (string) - The derived cryptographic key material.
```

--------------------------------

### SM2 Key Generation, Signing, Verification, Encryption, Decryption

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

This PHP snippet showcases the SM2 elliptic curve cryptography functions. It includes key generation, saving keys to PEM format, signing and verifying messages, and encrypting/decrypting data.

```php
<?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");
?>
```

--------------------------------

### SM4 Block Encryption and Decryption

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

This PHP snippet shows the basic usage of SM4 for encrypting and decrypting a single block of data using a randomly generated key and block. It highlights the low-level API for SM4.

```php
<?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");
?>
```

--------------------------------

### Import SM9 Signing Master Public Key from PEM - gmssl-php

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports an SM9 signing master public key from a PEM file. The function requires the path to the PEM file and returns the SM9 signing master public key as a string. It may throw exceptions for invalid inputs or internal GmSSL errors.

```php
gmssl_sm9_sign_master_public_key_from_pem(
	string $file
): string
```

--------------------------------

### Import SM2 Certificate from PEM - PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports an SM2 X.509 certificate from a PEM-encoded file. The function requires the file path and returns the certificate in DER-encoded bytes. It will throw exceptions for invalid parameters or library issues.

```php
gmssl_cert_from_pem(string $path): string
```

--------------------------------

### Encrypt and Decrypt Messages with SM2 in PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Demonstrates SM2 public key encryption of a message using a public key and subsequent decryption with the corresponding private key. It highlights the maximum plaintext size limit. Requires gmssl extension.

```php
<?php
// Generate key pair
$sm2_key = gmssl_sm2_key_generate();
gmssl_sm2_public_key_info_to_pem($sm2_key, "sm2pub.pem");
$public_key = gmssl_sm2_public_key_info_from_pem("sm2pub.pem");

// Encrypt a session key or other small secret
$session_key = gmssl_rand_bytes(32);
$plaintext = "Session Key: " . bin2hex($session_key);

echo "Max plaintext size: " . GMSSL_SM2_MAX_PLAINTEXT_SIZE . " bytes\n";
echo "Plaintext: " . $plaintext . "\n";

$ciphertext = gmssl_sm2_encrypt($public_key, $plaintext);
echo "Ciphertext: " . bin2hex($ciphertext) . "\n";

// Decrypt with private key
$decrypted = gmssl_sm2_decrypt($sm2_key, $ciphertext);
echo "Decrypted: " . $decrypted . "\n";

if ($plaintext === $decrypted) {
    echo "SM2 encryption successful\n";
}
?>

```

--------------------------------

### Print SM2 Certificate Details - PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Prints the details of an SM2 X.509 certificate. It takes the certificate (typically obtained from gmssl_cert_from_pem) and a label string for output. The function returns true on success or false on failure.

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

--------------------------------

### Encrypt with SM4-CBC in PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Encrypts data using SM4 in CBC mode with PKCS#7 padding. This mode requires a key and an initialization vector (IV). The function automatically handles padding for messages of any length. Decryption verifies the integrity of the message.

```php
<?php
// CBC mode encryption with padding
$key = gmssl_rand_bytes(GMSSL_SM4_KEY_SIZE);
$iv = gmssl_rand_bytes(GMSSL_SM4_CBC_IV_SIZE);
$plaintext = "This message can be any length and will be padded automatically";

$ciphertext = gmssl_sm4_cbc_encrypt($key, $iv, $plaintext);
echo "Plaintext length: " . strlen($plaintext) . " bytes\n";
echo "Ciphertext length: " . strlen($ciphertext) . " bytes\n";

$decrypted = gmssl_sm4_cbc_decrypt($key, $iv, $ciphertext);
echo "Decrypted: " . $decrypted . "\n";

// Verify
if ($plaintext === $decrypted) {
    echo "CBC encryption/decryption successful\n";
}
?>

```

--------------------------------

### Encrypt SM9 Signing Key to PEM - gmssl-php

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports a user's SM9 signing private key to an encrypted PEM file. It requires the signing key, the output file path, and a passphrase for encryption. The function returns a boolean indicating success or failure. Errors can be raised for invalid parameters or GmSSL library problems.

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

--------------------------------

### Encrypt/Decrypt with SM4-CTR Mode using PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Encrypts or decrypts data using the SM4-CTR mode. This function handles both encryption and decryption as they are identical in CTR mode. It requires a 16-byte key, a 16-byte Initialization Vector (IV), and the data to be processed. Errors are thrown for invalid inputs or library issues.

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

--------------------------------

### Export SM9 Encryption Master Public Key to PEM - PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports an SM9 encryption master public key to a PEM-encoded file. This function takes the master key (or public key) and the desired output file path. It returns true on success and false on failure, or throws exceptions for errors.

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

--------------------------------

### Verify X.509 Certificate using CA Certificate (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Verifies an SM2 X.509 certificate against a provided CA certificate. This function requires the certificate to verify (`$cert`), the CA certificate (`$cacert`), and the CA's signing SM2 ID (`$sm2_id`). It returns a boolean value indicating whether the verification was successful. The Issuer of `$cert` must match the Subject of `$cacert`.

```php
gmssl_cert_verify_by_ca_cert(
	string $cert,
	string $cacert,
	string $sm2_id
): bool
```

--------------------------------

### Sign with SM9 Identity-Based Signature (PHP)

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Signs a message using SM9 identity-based cryptography without requiring a certificate. It covers key generation, extraction, signing, and verification. Dependencies include the gmssl extension.

```php
<?php
// Setup: Generate master key and extract user key
$master_key = gmssl_sm9_sign_master_key_generate();
$master_pub_file = "sm9_master_pub.pem";
gmssl_sm9_sign_master_public_key_to_pem($master_key, $master_pub_file);

$user_id = "alice@company.com";
$sign_key = gmssl_sm9_sign_master_key_extract_key($master_key, $user_id);

// Sign a message
$message = "Important business contract";
$signature = gmssl_sm9_sign($sign_key, $message);

echo "Signer ID: " . $user_id . "\n";
echo "Message: " . $message . "\n";
echo "Signature: " . bin2hex($signature) . "\n";

// Anyone can verify using master public key and signer's ID
$master_pub = gmssl_sm9_sign_master_public_key_from_pem($master_pub_file);
$is_valid = gmssl_sm9_verify($master_pub, $user_id, $message, $signature);

echo "Signature valid: " . ($is_valid ? "Yes" : "No") . "\n";

// Verification fails with wrong ID
$is_valid_wrong = gmssl_sm9_verify($master_pub, "bob@company.com", $message, $signature);
echo "Signature valid (wrong ID): " . ($is_valid_wrong ? "Yes" : "No") . "\n";
?>

```

--------------------------------

### SM4 GCM Mode Encryption and Decryption

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

This PHP snippet demonstrates SM4 encryption and decryption using the GCM mode, which is recommended for general use. It includes an Initialization Vector (IV), Associated Authenticated Data (AAD), and an authentication tag.

```php
<?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");
?>
```

--------------------------------

### Generate SM9 Encryption Master Key - gmssl-php

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Generates a new SM9 encryption master key. This function takes no parameters. It returns the generated SM9 master key as a string. Exceptions are thrown in case of GmSSL library errors.

```php
gmssl_sm9_enc_master_key_generate(): string
```

--------------------------------

### Export SM2 Public Key to PEM (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports an SM2 public key to a PEM file. Accepts either a public key or a private key as input, extracting only the public key for export. The function returns a boolean indicating success or failure and throws exceptions on invalid parameters or internal library errors.

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

--------------------------------

### Export SM9 Encryption Key to Encrypted PEM - PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports a user's SM9 encryption private key to an encrypted PEM file. This function requires the encryption key, the output file path, and a passphrase for encryption. It returns true on success or false on failure, and handles errors via exceptions.

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

--------------------------------

### Compute SM2 Z Value in PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Shows how to compute the SM2 Z value, which is crucial for SM2 signature algorithms, using a private key and a user identifier. It illustrates that the Z value differs based on the provided user ID. Requires gmssl extension.

```php
<?php
// Generate key pair
$sm2_key = gmssl_sm2_key_generate();

// Compute Z value with default ID
$z_default = gmssl_sm2_compute_z($sm2_key, GMSSL_SM2_DEFAULT_ID);
echo "Z value (default ID): " . bin2hex($z_default) . "\n";
echo "Z value length: " . strlen($z_default) . " bytes\n";

// Compute Z value with custom ID
$custom_id = "user@example.com";
$z_custom = gmssl_sm2_compute_z($sm2_key, $custom_id);
echo "Z value (custom ID): " . bin2hex($z_custom) . "\n";

// Z values are different for different IDs
if ($z_default !== $z_custom) {
    echo "Z values differ based on user ID\n";
}
?>

```

--------------------------------

### Import SM9 Encryption Key from Encrypted PEM - PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Decrypts and imports a user's SM9 encryption private key from an encrypted PEM file. This function requires the file path and the decryption passphrase. It returns the private key as a string or throws exceptions on errors.

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

--------------------------------

### Import SM9 Encryption Master Key from PEM - PHP

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Decrypts and imports an SM9 encryption master key from an encrypted PEM file. It requires the file path and a passphrase for decryption. The function returns the master key as a string or throws exceptions on errors.

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

--------------------------------

### Decrypt SM9 Signing Key from PEM - gmssl-php

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports a user's SM9 signing private key from an encrypted PEM file. This function takes the file path and the decryption passphrase. It returns the SM9 signing private key as a string. Exceptions are thrown for invalid parameters or GmSSL library errors.

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

--------------------------------

### Encrypt Message with SM4-CBC using gmssl_sm4_cbc_encrypt

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Encrypts a plaintext message of any length using the SM4 cipher in CBC mode with padding. Requires a 16-byte key, a 16-byte Initialization Vector (IV), and the plaintext data. Returns raw binary ciphertext whose length is a multiple of GMSSL_SM4_BLOCK_SIZE.

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

--------------------------------

### Encrypt with SM4-CTR in PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Encrypts data using SM4 in CTR mode. This mode is efficient as encryption and decryption are the same operation. It requires a key and an initialization vector (IV) which serves as the initial counter. CTR mode allows for random access to encrypted data.

```php
<?php
// CTR mode - same function for encrypt and decrypt
$key = gmssl_rand_bytes(GMSSL_SM4_KEY_SIZE);
$iv = gmssl_rand_bytes(GMSSL_SM4_CTR_IV_SIZE);
$plaintext = "Counter mode allows random access to encrypted data";

$ciphertext = gmssl_sm4_ctr_encrypt($key, $iv, $plaintext);
echo "Ciphertext: " . bin2hex($ciphertext) . "\n";

// Decrypt using the same function
$decrypted = gmssl_sm4_ctr_encrypt($key, $iv, $ciphertext);
echo "Decrypted: " . $decrypted . "\n";

// Verify
if ($plaintext === $decrypted) {
    echo "CTR mode successful\n";
}
?>

```

--------------------------------

### Generate SM9 Signing Master Key in PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Details the process of generating an SM9 identity-based signing master key, typically performed by a trusted authority. It includes saving the master key and its public counterpart securely. Requires gmssl extension.

```php
<?php
// Generate master key (done by trusted authority)
$master_key = gmssl_sm9_sign_master_key_generate();

// Save master key with password protection
$password = "MasterKeyPassword123!";
$master_key_file = "sm9_sign_master.pem";
$master_pub_file = "sm9_sign_master_pub.pem";

gmssl_sm9_sign_master_key_info_encrypt_to_pem($master_key, $master_key_file, $password);
gmssl_sm9_sign_master_public_key_to_pem($master_key, $master_pub_file);

echo "Master key generated and saved\n";

// Load keys
$master = gmssl_sm9_sign_master_key_info_decrypt_from_pem($master_key_file, $password);
$master_pub = gmssl_sm9_sign_master_public_key_from_pem($master_pub_file);

echo "Master keys loaded successfully\n";
?>

```

--------------------------------

### Sign Message with SM2 (PHP)

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Signs a message using the SM2 algorithm and generates a signature. Requires the signer's private key, their identity string, and the message to be signed. Returns the signature in DER encoding. Throws exceptions for invalid inputs or internal errors.

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

--------------------------------

### Encrypt SM9 Encryption Master Key to PEM - gmssl-php

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Exports the SM9 encryption master key to an encrypted PEM file. This function requires the master key, the output file path, and a passphrase for encryption. It returns a boolean indicating success (true) or failure (false). Errors can be triggered by invalid parameters or GmSSL library problems.

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

--------------------------------

### Decrypt SM9 Signing Master Key from PEM - gmssl-php

Source: https://github.com/gmssl/gmssl-php/blob/main/README.md

Imports an SM9 signing master key from an encrypted PEM file. It requires the file path and the passphrase used for encryption. The function returns the decrypted SM9 signing master key as a string. Exceptions are thrown for invalid parameters or GmSSL library errors.

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

--------------------------------

### Generate SM9 Encryption Master Key (PHP)

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Generates an SM9 identity-based encryption master key, typically used by a trusted authority. This process includes key generation, saving to PEM files (encrypted and public), and loading them back. Requires the gmssl extension.

```php
<?php
// Generate encryption master key (trusted authority)
$master_key = gmssl_sm9_enc_master_key_generate();

// Save master keys
$password = "EncMasterPassword";
$master_key_file = "sm9_enc_master.pem";
$master_pub_file = "sm9_enc_master_pub.pem";

gmssl_sm9_enc_master_key_info_encrypt_to_pem($master_key, $master_key_file, $password);
gmssl_sm9_enc_master_public_key_to_pem($master_key, $master_pub_file);

echo "Encryption master key generated\n";

// Load keys
$master = gmssl_sm9_enc_master_key_info_decrypt_from_pem($master_key_file, $password);
$master_pub = gmssl_sm9_enc_master_public_key_from_pem($master_pub_file);

echo "Master keys loaded successfully\n";
?>

```

--------------------------------

### Generate cryptographic random bytes

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Generates cryptographically secure random bytes suitable for keys, initialization vectors, and nonces using the `gmssl_rand_bytes` function.

```APIDOC
## gmssl_rand_bytes

### Description
Generates cryptographically secure random bytes.

### Method
`gmssl_rand_bytes(int $length): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
<?php
// Generate a 16-byte random key for SM4
$key = gmssl_rand_bytes(GMSSL_SM4_KEY_SIZE);
echo "Random key: " . bin2hex($key) . "\n";

// Generate a random IV for GCM mode
$iv = gmssl_rand_bytes(GMSSL_SM4_GCM_DEFAULT_IV_SIZE);
echo "Random IV: " . bin2hex($iv) . "\n";

// Generate random salt for PBKDF2
$salt = gmssl_rand_bytes(16);
echo "Random salt: " . bin2hex($salt) . "\n";
?>
```

### Response
#### Success Response (200)
- **bytes** (string) - Cryptographically secure random bytes.
```

--------------------------------

### Generate Cryptographic Random Bytes with GmSSL-PHP

Source: https://context7.com/gmssl/gmssl-php/llms.txt

Generates cryptographically secure random bytes using gmssl_rand_bytes. This is suitable for creating keys, initialization vectors (IVs), and salts. The function takes the desired number of bytes as input.

```php
<?php
// Generate a 16-byte random key for SM4
$key = gmssl_rand_bytes(GMSSL_SM4_KEY_SIZE);
echo "Random key: " . bin2hex($key) . "\n";

// Generate a random IV for GCM mode
$iv = gmssl_rand_bytes(GMSSL_SM4_GCM_DEFAULT_IV_SIZE);
echo "Random IV: " . bin2hex($iv) . "\n";

// Generate random salt for PBKDF2
$salt = gmssl_rand_bytes(16);
echo "Random salt: " . bin2hex($salt) . "\n";
?>
```