Sm Remote API Reference

Operations

POST /decrypt

Decrypts base64-encoded SM4 ciphertext in the requested mode (SM4-CBC default, or SM4-GCM; SM4-ECB only under SMREMOTE_SM4_MODE=ECB-Interop) with the supplied 128-bit (16-byte) base64-encoded key. CBC requires ivBase64; GCM requires ivBase64 and tagBase64. Returns the plaintext as base64. Returns 400 if the key, ciphertext, IV/tag, or algorithm is invalid, the requested SM4 mode is disabled, or GCM authentication fails.

Responses:

POST /encrypt

Encrypts the provided base64-encoded payload with SM4 in the requested mode (SM4-CBC default, or SM4-GCM; SM4-ECB only under SMREMOTE_SM4_MODE=ECB-Interop) and the supplied 128-bit (16-byte) base64-encoded key. Returns the ciphertext as base64, plus ivBase64 (CBC/GCM) and tagBase64 (GCM). Returns 400 if the key, payload, or algorithm is missing/invalid, the key length is not 16 bytes, or the requested SM4 mode is disabled.

Responses:

POST /hash

Computes an SM3 hash of the provided base64-encoded payload. Returns the hash as both base64 and lowercase hex. Defaults to SM3 if algorithmId is omitted. Returns 400 if the payload is missing, invalid base64, or an unsupported algorithm is requested.

Responses:

GET /health

Returns the liveness status of the SM Remote crypto service. Always returns 200 OK with status ‘ok’ when the service is running. Used by infrastructure health probes.

Responses:

POST /sign

Signs the provided base64-encoded payload using the SM2 algorithm and the specified key ID. Seeds the key from an ephemeral EC key pair if not already present. Returns the base64-encoded SM2 signature. Returns 400 if the key ID, algorithm, or payload is missing or invalid.

Responses:

GET /status

Returns the availability status and supported algorithms of the SM Remote crypto provider. Reports the active provider name (cn.sm.soft or cn.sm.remote.http) and the list of supported signature algorithms.

Responses:

POST /verify

Verifies an SM2 signature against the provided base64-encoded payload using the specified key ID. Returns a boolean valid field indicating whether the signature matches. Returns 400 if the key ID, algorithm, payload, or signature is missing or invalid base64.

Responses: