Remote Code Signing API Reference

This document is intended for developers who need to directly integrate remote signing capabilities, and describes the following two interfaces:

• POST /v1/codesign/sign: Submit the hash digest to be signed and obtain the RSA PKCS#1 signature result.
• POST /v1/codesign/report-sign: Report the final processing result of the client (this does not affect signature billing counts).

---

Endpoint

Environment	Address
Production environment (default)	https://ssl.face.racent.com
NICSRS environment	https://ssl.face.nicsrs.com

If you need addresses for other environments, use the address provided by the delivery or operations team as the standard.

---

General Conventions

Request Format

• Protocol: HTTPS
• Method: POST
• Body: JSON
• Headers:

Content-Type: application/json
Accept: application/json
Authorization: Basic <base64(accessKey:accessSecret)>

Authentication

This API uses HTTP Basic Auth:

• Username: Access Key
• Password: Access Secret

Generate the Authorization header:

printf "%s:%s" "$ACCESS_KEY" "$ACCESS_SECRET" | base64

General Response Structure

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Field	Type	Description
code	integer	Business status code. 0 indicates success, a value other than 0 indicates a business failure.
message	string	Business status description, which is the error description when a failure occurs.
data	object	Interface business data.

The caller should handle both HTTP status codes and business status codes:

• HTTP non-2xx → Handle as an HTTP error.
• HTTP 2xx and code != 0 → Handle as a business error.
• HTTP 2xx and code == 0 → Read the corresponding data.

---

Signature Interface

Interface Description

POST /v1/codesign/sign

Submit the raw bytes of the hash to be signed (Base64-encoded). The remote service will complete the RSA PKCS#1 signature using the specified certificate and return the result.

Note

/v1/codesign/sign A successfully returned signature content is considered a successful signature, and the signature count will be incremented by 1. Failed requests do not consume signature counts. Whether report-sign is called does not affect the count.

Request parameters

{
  "code": "CERT_CODE",
  "digest": "BASE64_ENCODED_HASH",
  "algorithm": "SHA256",
  "padding": "PKCS1",
  "extra": {
    "platform": "windows/amd64",
    "version": "1.0.0",
    "revision": "abcdef0",
    "time": "2026-06-12T10:00:00+08:00",
    "hostname": "build-host-01",
    "signing_filename": "Example.exe",
    "signing_filesize": 1048576
  }
}

Field	Type	Required	Description
code	string	Yes	Certificate number, used to select the remote signing certificate.
digest	string	Yes	Base64 encoding of the raw bytes of the hash to be signed. The caller must compute the hash locally according to the requirements of the target file and signing tool.
algorithm	string	Yes	Hash algorithm, supports SHA1, SHA256, SHA384, SHA512.
padding	string	Yes	RSA padding mode, currently fixed as PKCS1.
extra	object	No	Client context information, used for signature records, auditing and troubleshooting.

Description of the extra field:

Field	Type	Description
platform	string	Client platform, such as windows/amd64, linux/amd64.
version	string	Client version.
revision	string	Client build revision.
time	string	Client build time or request time.
hostname	string	Hostname that initiates the signature.
signing_filename	string	Signed file name or path, desensitization is recommended according to security policies.
signing_filesize	integer	Size of the signed file (in bytes).

Request Example

curl -u "$ACCESS_KEY:$ACCESS_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "code": "CERT_CODE",
    "digest": "BASE64_ENCODED_HASH",
    "algorithm": "SHA256",
    "padding": "PKCS1",
    "extra": {
      "platform": "windows/amd64",
      "version": "1.0.0",
      "hostname": "build-host-01",
      "signing_filename": "Example.exe",
      "signing_filesize": 1048576
    }
  }' \
  https://ssl.face.racent.com/v1/codesign/sign

Successful Response

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "735985894427246592",
    "signature": "BASE64_ENCODED_SIGNATURE"
  }
}

Field	Type	Description
id	string	Signature record ID, used when calling report-sign.
signature	string	Base64 encoding of the RSA signature result.

---

Report Signature Result

API Description

POST /v1/codesign/report-sign

After the client obtains the remote signature result, failures may occur during local processing, writing, or returning the result to the caller. This interface is used to report the client's final processing status back to the server, to facilitate signature record display and audit troubleshooting.

Note

This interface only records the client processing result, and does not change the count result for /v1/codesign/sign. Not calling this interface will not affect the number of successful signatures.

Request Parameters

{
  "id": "735985894427246592",
  "status": 1
}

Field	Type	Required	Description
id	string	Yes	The data.id returned by /v1/codesign/sign.
status	integer	Yes	Final processing status of the client: 1 for success, 2 for failure.

Request Example

curl -u "$ACCESS_KEY:$ACCESS_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "735985894427246592",
    "status": 1
  }' \
  https://ssl.face.racent.com/v1/codesign/report-sign

Success Response

{
  "code": 0,
  "message": "ok",
  "data": null
}

Error Response Example

Authentication failed:

{
  "code": 401,
  "message": "unauthorized",
  "data": null
}

Parameter error:

{
  "code": 400,
  "message": "invalid request",
  "data": null
}

Notice

Specific error codes and error messages are subject to the actual response returned by the server. Integrators should not rely on fixed error text for business branch logic judgments.

---

Integration Recommendations

• Properly protect Access Secret and do not write it to logs, crash reports, or front-end pages.
• digest must be the Base64 encoding of the raw hash bytes, not a hexadecimal string, nor the complete file content.
• algorithm must use the same actual hash algorithm as digest.
• The current padding mode is fixed to PKCS1, do not pass other values.
• The digest and signature fields may be long; it is recommended to only record their length or prefix/suffix desensitized results in logs.
• It is recommended to call report-sign to report the result after the client completes the final processing, which facilitates subsequent audit and troubleshooting.
• Handle network errors, HTTP errors, and business errors separately, and set reasonable timeout and retry policies for signed requests.