Tích hợp API

sslTrus cung cấp API ký mã từ xa, phù hợp với các nhà phát triển cần tự xây dựng client ký, hệ thống build hoặc các chương trình tích hợp ký khác.

API nhận tóm tắt tệp do client tính toán, dịch vụ ký mã từ xa sử dụng chứng chỉ ký mã được chỉ định để hoàn tất việc ký bằng khóa riêng và trả về kết quả ký.

Client chịu trách nhiệm:

Tính toán tóm tắt của dữ liệu cần ký.
Tạo cấu trúc chữ ký mà tệp đích yêu cầu.
Gọi giao diện ký từ xa.
Ghi kết quả ký trả về vào tệp đích hoặc cấu trúc chữ ký.
Báo cáo kết quả xử lý cuối cùng của client khi cần.

Khóa riêng ký mã luôn được lưu trong HSM trên đám mây và sẽ không được trả về cho client qua API.

Địa chỉ truy cập

Địa chỉ mặc định của môi trường production:

https://ssl.face.racent.com

Môi trường NICSRS:

https://ssl.face.nicsrs.com

API ký đầy đủ:

POST https://ssl.face.racent.com/v1/codesign/sign

Giao diện báo cáo kết quả:

POST https://ssl.face.racent.com/v1/codesign/report-sign

Nếu môi trường triển khai thực tế sử dụng địa chỉ dịch vụ khác, vui lòng tham khảo địa chỉ do bộ phận bàn giao hoặc vận hành cung cấp.

Xác thực danh tính

API sử dụng HTTP Basic Auth.

Mối quan hệ tương ứng:

Username = Access Key
Password = Access Secret

Tiêu đề yêu cầu:

Authorization: Basic <base64(accessKey:accessSecret)>

Ví dụ:

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

Khi sử dụng thực tế curl, bạn có thể cung cấp trực tiếp qua tham số -u:

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret là thông tin xác thực nhạy cảm, không được ghi vào mã nguồn, tệp cấu hình công khai, nhật ký hoặc trang front-end.

Định dạng yêu cầu chung

API sử dụng:

HTTPS
POST
JSON

Tiêu đề yêu cầu:

Content-Type: application/json
Accept: application/json
Authorization: Basic <credentials>

Định dạng phản hồi chung

API trả về cấu trúc JSON thống nhất:

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

Mô tả các trường:

Trường	Kiểu	Mô tả
`code`	integer	Mã trạng thái nghiệp vụ, `0` nghĩa là thành công
`message`	string	Trạng thái hoặc thông báo lỗi
`data`	object	Dữ liệu nghiệp vụ của giao diện

Máy khách cần đồng thời kiểm tra mã trạng thái HTTP và mã trạng thái nghiệp vụ.

Khuyến nghị xử lý theo cách sau:

HTTP 非 2xx
    ↓
HTTP 请求失败

HTTP 2xx + code != 0
    ↓
业务失败

HTTP 2xx + code == 0
    ↓
读取 data

Đừng chỉ dựa vào HTTP 200 để đánh giá yêu cầu ký đã thành công.

Giao diện ký

Giao diện:

POST /v1/codesign/sign

Giao diện này dùng để gửi tóm tắt cần ký và nhận kết quả ký bằng khóa riêng từ xa.

Tham số yêu cầu

Ví dụ yêu cầu:

{
  "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
  }
}

Các tham số chính:

Tham số	Loại	Bắt buộc	Mô tả
`code`	string	Có	Số chứng chỉ ký mã
`digest`	string	Có	Mã hóa Base64 của byte thô digest cần ký
`algorithm`	string	Có	Thuật toán digest
`padding`	string	Có	Phương thức đệm RSA, hiện cố định là `PKCS1`
`extra`	object	Không	Thông tin ngữ cảnh và kiểm toán phía máy khách

Thuật toán digest

Hiện hỗ trợ:

SHA1
SHA256
SHA384
SHA512

Ví dụ khi sử dụng SHA-256:

{
  "algorithm": "SHA256"
}

algorithm phải nhất quán với thuật toán tóm tắt thực tế được digest sử dụng.

Định dạng digest

digest phải là:

Byte băm gốc → Base64

Không phải:

文件内容 Base64

Cũng không phải:

十六进制哈希字符串

Ví dụ: nếu bản tóm tắt SHA-256 có kích thước 32 byte, thì cần mã hóa Base64 32 byte gốc này trước khi truyền vào giao diện.

padding

Hiện tại cố định sử dụng:

PKCS1

Tức là:

{
  "padding": "PKCS1"
}

Không truyền các phương thức padding khác.

extra

extra được dùng để ghi lại ngữ cảnh máy khách, thông tin kiểm toán và hỗ trợ khắc phục sự cố.

Hỗ trợ:

Trường	Kiểu	Mô tả
`platform`	string	Nền tảng máy khách
`version`	string	Phiên bản máy khách
`revision`	string	Bản sửa đổi bản dựng máy khách
`time`	string	Thời gian bản dựng hoặc thời gian ghi nhận phía yêu cầu
`hostname`	string	Tên máy chủ khởi tạo yêu cầu
`signing_filename`	string	Tên tệp được ký hoặc đường dẫn cục bộ
`signing_filesize`	integer	Kích thước tệp, đơn vị là byte

Ví dụ:

{
  "extra": {
    "platform": "linux/amd64",
    "version": "1.2.0",
    "hostname": "github-runner-01",
    "signing_filename": "app.exe",
    "signing_filesize": 5242880
  }
}

Nếu signing_filename chứa thư mục nội bộ, tên người dùng hoặc thông tin nhạy cảm khác, bạn nên ẩn danh hóa theo chính sách bảo mật phía khách hàng.

Ví dụ về yêu cầu ký

Sử dụng curl:

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": "linux/amd64",
      "version": "1.0.0",
      "hostname": "build-host-01",
      "signing_filename": "Example.exe",
      "signing_filesize": 1048576
    }
  }' \
  https://ssl.face.racent.com/v1/codesign/sign

Phản hồi chữ ký

Phản hồi thành công:

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

Trường trả về:

Trường	Kiểu	Mô tả
`id`	string	ID bản ghi chữ ký
`signature`	string	Mã hóa Base64 của kết quả chữ ký RSA

Đối với khả năng ký thực tế, máy khách chủ yếu sử dụng:

data.signature

Nếu cần báo cáo trạng thái cuối cùng sau khi xử lý cục bộ hoàn tất, bạn cũng cần lưu:

data.id

Quy trình xử lý phía máy khách

Quy trình điển hình:

读取待签名文件
      ↓
按照目标格式生成待签名数据
      ↓
计算摘要
      ↓
Base64 编码摘要
      ↓
POST /v1/codesign/sign
      ↓
获得 signature
      ↓
构造最终签名结构
      ↓
写回目标文件
      ↓
POST /v1/codesign/report-sign

Cần lưu ý:

/v1/codesign/sign

Chỉ chịu trách nhiệm ký khóa riêng từ xa ở tầng dưới.

Cách tổ chức cấu trúc chữ ký cho PE Authenticode, JAR, PDF hoặc các định dạng tệp khác do máy khách tự xử lý theo định dạng mục tiêu.

Báo cáo kết quả ký

Giao diện:

POST /v1/codesign/report-sign

Sau khi client nhận được kết quả ký từ xa, vẫn có thể xảy ra lỗi trong các bước xử lý tiếp theo, ví dụ:

Không thể tạo cấu trúc chữ ký cuối cùng.
Không thể ghi vào tệp đích.
Lỗi quyền truy cập tệp cục bộ.
Xử lý phía client gặp sự cố sau đó.

Bạn có thể sử dụng API này để gửi trạng thái xử lý cuối cùng về máy chủ.

Tham số yêu cầu

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

Trường	Kiểu	Bắt buộc	Mô tả
`id`	string	Có	ID bản ghi chữ ký được trả về bởi `/v1/codesign/sign`
`status`	integer	Có	Trạng thái xử lý cuối cùng của máy khách

Giá trị trạng thái:

Trạng thái	Mô tả
`1`	Máy khách xử lý cuối cùng thành công
`2`	Máy khách xử lý cuối cùng thất bại

Ví dụ yêu cầu

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

Phản hồi thành công

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

Số lần ký

Số lần ký API được tính dựa trên việc thao tác ký từ xa có thành công hay không.

Khi:

HTTP 2xx
code == 0
data.signature 非空

Khi cả hai điều kiện được đáp ứng đồng thời, chữ ký được coi là hợp lệ:

签名次数 +1

Những trường hợp sau không tiêu tốn số lần ký:

Xác thực thất bại.
Tham số sai.
Yêu cầu mạng thất bại.
Yêu cầu nghiệp vụ thất bại.
Máy chủ không trả về thành công nội dung chữ ký.

Cần đặc biệt lưu ý:

/v1/codesign/report-sign

Chỉ là báo cáo trạng thái xử lý cuối cùng của client, không thuộc hoạt động ký mới và cũng không làm tăng hoặc giảm số lần ký.

Ngay cả khi client đã nhận thành công kết quả ký từ xa, nhưng sau đó ghi file cục bộ thất bại, thì chữ ký khóa riêng từ xa đã hoàn tất trước đó vẫn được tính là một lần ký.

Để biết thêm quy tắc tính lượt, vui lòng tham khảo tài liệu tham khảo.

Xử lý lỗi

Client cần xử lý riêng biệt:

Lỗi mạng.
Lỗi HTTP.
Lỗi nghiệp vụ API.
Lỗi xử lý cục bộ của client.

Xác thực thất bại

Ví dụ:

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

Cần kiểm tra:

Access Key có chính xác không.
Access Secret có chính xác không.
Yêu cầu có mang Authorization Header chính xác không.

Lỗi tham số

Ví dụ:

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

Cần tập trung kiểm tra:

code có chính xác không.
digest có phải là Base64 hợp lệ không.
algorithm có khớp với tóm tắt không.
padding có phải là PKCS1 không.

Máy khách không nên phụ thuộc vào giá trị cố định:

message

Chuỗi thực thi logic chương trình.

Xử lý nghiệp vụ nên ưu tiên dựa trên mã trạng thái và hợp đồng giao diện.

Timeout và thử lại

Khi gọi giao diện ký từ xa, nên thiết lập timeout mạng hợp lý.

Khi cần thử lại, cần đặc biệt lưu ý:

签名接口不是普通查询接口

Nếu máy khách không nhận được phản hồi do sự cố mạng, điều đó không nhất thiết có nghĩa là máy chủ chưa hoàn tất việc ký.

Do đó, khi thiết kế cơ chế tự động thử lại, hãy tránh gửi lại yêu cầu ký không giới hạn hoặc vô điều kiện.

Bạn nên ghi lại riêng biệt:

Thời gian bắt đầu yêu cầu.
Số chứng chỉ mục tiêu.
Định danh tóm tắt.
Trạng thái HTTP.
Mã trạng thái nghiệp vụ.
ID bản ghi chữ ký được trả về.
Trạng thái xử lý cuối cùng của máy khách.

Không ghi Access Secret đầy đủ vào nhật ký.

Nhật ký và kiểm toán

Bạn nên ghi lại ngữ cảnh chữ ký cần thiết, ví dụ:

certificate code
platform
client version
hostname
filename
filesize
sign record id
result

对于：

digest
signature

Với những dữ liệu có độ dài lớn như vậy, không nên ghi toàn bộ vào nhật ký thông thường.

Có thể ghi lại:

Độ dài.
Giá trị băm.
Tiền tố và hậu tố sau khi che dấu.

Đường dẫn tệp cũng có thể chứa tên người dùng, tên dự án hoặc thông tin thư mục nội bộ, cần quyết định có che dấu hay không dựa trên yêu cầu bảo mật thực tế.

Hướng dẫn bảo mật

Khi tích hợp API, nên tuân thủ các nguyên tắc sau:

Access Secret không được lưu trong mã frontend.
Không được commit Access Secret vào kho Git.
Không ghi Authorization Header đầy đủ vào nhật ký thông thường.
Không ghi Access Secret đầy đủ.
Thực hiện che dấu nhật ký cần thiết cho digest và signature.
Gọi dịch vụ ký từ xa qua HTTPS.
Client cần xác thực trạng thái HTTP và trạng thái nghiệp vụ.
Thiết lập chính sách timeout và retry hợp lý cho các yêu cầu mạng.

API ký mã từ xa trả về kết quả ký, không phải khóa riêng.

Khóa riêng ký mã luôn được lưu trong HSM từ xa.

Khi nào sử dụng API

Nếu phương thức tích hợp hiện có đã đáp ứng nhu cầu, thường có thể sử dụng trực tiếp công cụ tương ứng.

Tình huống	Cách được khuyến nghị
Ký trực tiếp các tệp EXE, DLL, MSI, v.v.	Công cụ client
Phần mềm Windows như Microsoft SignTool, Visual Studio, v.v.	Windows Provider
Ký tệp JAR	Tích hợp Java
Build tự động như GitHub Actions, Electron Builder, v.v.	CI/CD và công cụ build
Tự phát triển client ký	API
Tự triển khai quy trình ký định dạng tệp	API
Cần kiểm soát trực tiếp digest và kết quả ký	API

API phù hợp hơn với các nhà phát triển cần kiểm soát quy trình ký ở tầng thấp.

Nếu chỉ cần hoàn tất ký mã cho tệp thông thường, ưu tiên sử dụng client hiện có hoặc Provider chuẩn có thể giảm bớt khối lượng công việc tự xử lý định dạng tệp ký.

Địa chỉ truy cập​

Xác thực danh tính​

Định dạng yêu cầu chung​

Định dạng phản hồi chung​

Giao diện ký​

Tham số yêu cầu​

Thuật toán digest​

Định dạng digest​

padding​

extra​

Ví dụ về yêu cầu ký​

Phản hồi chữ ký​

Quy trình xử lý phía máy khách​

Báo cáo kết quả ký​

Tham số yêu cầu​

Ví dụ yêu cầu​

Phản hồi thành công​

Số lần ký​

Xử lý lỗi​

Xác thực thất bại​

Lỗi tham số​

Timeout và thử lại​

Nhật ký và kiểm toán​

Hướng dẫn bảo mật​

Khi nào sử dụng API​

Địa chỉ truy cập

Xác thực danh tính

Định dạng yêu cầu chung

Định dạng phản hồi chung

Giao diện ký

Tham số yêu cầu

Thuật toán digest

Định dạng digest

padding

extra

Ví dụ về yêu cầu ký

Phản hồi chữ ký

Quy trình xử lý phía máy khách

Báo cáo kết quả ký

Tham số yêu cầu

Ví dụ yêu cầu

Phản hồi thành công

Số lần ký

Xử lý lỗi

Xác thực thất bại

Lỗi tham số

Timeout và thử lại

Nhật ký và kiểm toán

Hướng dẫn bảo mật

Khi nào sử dụng API