Remote Code Signing API Reference

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

• 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 client's final processing result (does not affect signing count).

---

Access Endpoints

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

For other environment endpoints, refer to the addresses provided during delivery or operations.

---

General Conventions

Request Format

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

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

Authentication

The API uses HTTP Basic Auth:

• Username: Access Key
• Password: Access Secret

To 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, while a non-0 value indicates business failure.
message	string	Business status description; provides the error details on failure.
data	object	Interface business data.

The caller should handle both the HTTP status code and the business status code:

• Non-2xx HTTP → Handle according to the HTTP error.
• HTTP 2xx with code != 0 → Handle according to the business error.
• HTTP 2xx with code == 0 → Read the corresponding data.

---

Signed Interface

Interface Description

POST /v1/codesign/sign

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

Note

/v1/codesign/sign A successful return of the signature content is considered a successful signature, and the signature count increases by 1. Failed requests do not consume the signature count. Whether to call report-sign 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 as required by the target file and signing tool.
algorithm	string	Yes	Hash algorithm, supports SHA1, SHA256, SHA384, SHA512.
padding	string	Yes	RSA padding mode, currently fixed to PKCS1.
extra	object	No	Client context information, used for signature records, auditing, and troubleshooting.

Fields of extra:

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 of the signing machine.
signing_filename	string	Signed file name or path; it is recommended to redact it according to security policies.
signing_filesize	integer	Signed file size (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 signing result, it may fail when processing locally, writing, or returning it to the caller. This interface is used to send the client's final processing status back to the server, facilitating the display of signing records and audit troubleshooting.

Note

This interface only records the client's processing result and does not change the count result of /v1/codesign/sign. Not calling this interface does not affect the number of successful signing attempts.

Request Parameters

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

Field	Type	Required	Description
id	string	Yes	The /v1/codesign/sign returned by data.id.
status	integer	Yes	Client final processing status: 1 indicates success, 2 indicates 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

Successful Response

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

---

Error Response Examples

Authentication failure:

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

Parameter error:

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

Note

The specific error code and error message are subject to the actual server response. The integrating party should not rely on fixed error text for business branch decisions.

---

Integration Recommendations

• Properly protect the Access Secret, and do not write it into logs, crash reports, or frontend pages.
• digest must be the Base64 encoding of the raw hash bytes, not a hexadecimal string, and not the full file content.
• algorithm must be consistent with the actual hash algorithm used by digest.
• The current padding mode is fixed to PKCS1; do not pass other values.
• The digest and signature fields may be long; in logs, it is recommended to record only the length or the masking result of prefixes and suffixes.
• It is recommended to call report-sign on the client side after final processing to report the result, facilitating subsequent audit and troubleshooting.
• Handle network errors, HTTP errors, and business errors separately, and set reasonable timeout and retry policies for signed requests.