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ự phát triển 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 máy khách 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 ký bằng khóa riêng và trả về kết quả ký.

Khách hàng chịu trách nhiệm:

Tính toán tóm tắt của dữ liệu cần ký.
Xây dựng cấu trúc chữ ký cần thiết cho tệp đích.
Gọi giao diện ký từ xa.
Ghi kết quả chữ ký được 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 máy khách theo yêu cầu.

Khóa riêng ký mã luôn được lưu trữ trong HSM trên đám mây và sẽ không được trả về cho máy khách 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ý hoàn chỉnh:

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 bàn giao thực tế sử dụng địa chỉ dịch vụ khác, vui lòng tham chiếu theo đị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 thực tế sử dụng 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

Sử dụng API:

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ả trường:

Trường	Kiểu	Mô tả
`code`	integer	Mã trạng thái nghiệp vụ, `0` biểu thị 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 để xác định yêu cầu ký đã thành công.

Giao diện ký

API:

POST /v1/codesign/sign

API này dùng để gửi bản 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

Yêu cầu ví dụ:

{
  "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ố	Kiểu	Bắt buộc	Mô tả
`code`	string	Có	Số hiệu chứng chỉ ký mã
`digest`	string	Có	Mã hóa Base64 của byte thô bản tóm tắt cần ký
`algorithm`	string	Có	Thuật toán tóm tắt
`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 tóm tắt

Hiện đang hỗ trợ:

SHA1
SHA256

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 sử dụng bởi digest.

Đị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ó độ dài 32 byte, thì 32 byte thô này phải được mã hóa Base64 trước khi truyền vào API.

padding

Hiện đang cố định sử dụng:

PKCS1

Tức là:

{
  "padding": "PKCS1"
}

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

bổ sung

extra được sử 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 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 đã ký

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

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

Trường được 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ý xong tại local, 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 sẽ do máy khách tự xử lý dựa trên định dạng mục tiêu.

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

API:

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 tiếp theo, ví dụ:

Không tạo được cấu trúc chữ ký cuối cùng.
Không ghi được tệp đích.
Lỗi quyền truy cập tệp cục bộ.
Lỗi xử lý phía máy khách tiếp theo.

Có thể sử dụng giao diện 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
}

Tham số:

Trường	Kiểu	Bắt buộc	Mô tả
`id`	string	Có	ID bản ghi chữ ký do `/v1/codesign/sign` trả về
`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 thành lập đồng thời, được coi là một lần ký thành công:

签名次数 +1

Các trường hợp sau không tiêu hao số lần ký:

Xác thực thất bại.
Lỗi tham số.
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ỉ báo cáo trạng thái xử lý cuối cùng của máy khách, không thuộc thao tác ký mới và cũng không làm tăng hoặc giảm số lần ký.

Ngay cả khi máy khách đã nhận thành công kết quả ký từ xa, nhưng sau đó gặp lỗi khi ghi tệp cục bộ, thì lần ký bằng 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

Máy khách nê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ộ phía máy khách.

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 một cách chính xác không.

Lỗi tham số

Ví dụ:

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

Cần kiểm tra kỹ các điểm sau:

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.

Khách hàng không nên phụ thuộc vào cố định:

message

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

Quy 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.

Thời gian chờ và thử lại

Khi gọi giao diện ký từ xa, nên đặt thời gian chờ 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ế thử lại tự động, bạn nên tránh khởi tạo lại yêu cầu ký một cách vô hạn hoặc vô điều kiện.

Khuyến nghị ghi chép riêng:

Thời gian bắt đầu yêu cầu.
Số hiệu chứng chỉ mục tiêu.
Mã đị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 lại toàn bộ Access Secret trong nhật ký.

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

Khuyến nghị 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

Đối với:

digest
signature

Đối với loại dữ liệu có độ dài lớn như vậy, không khuyến nghị ghi toàn bộ vào nhật ký thông thường.

Có thể ghi lại:

Độ dài.
Băm.
Tiền tố và hậu tố sau khi che dữ liệ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ó nên ẩn thông tin nhạy cảm 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:

Không nên lưu Access Secret vào mã frontend.
Không nên commit Access Secret vào kho Git.
Không ghi lại toàn bộ Authorization Header trong nhật ký thông thường.
Không ghi lại toàn bộ Access Secret.
Thực hiện che dấu nhật ký cần thiết đối với digest và signature.
Gọi dịch vụ ký từ xa qua HTTPS.
Máy khách nê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 tư.

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

Khi nào nên sử dụng API

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

Tình huống	Phương thức khuyến nghị
Ký trực tiếp các tệp EXE, DLL, MSI, v.v.	Công cụ máy khách
Microsoft SignTool, Visual Studio và các phần mềm Windows khác	Windows Provider
Ký tệp JAR	Tích hợp Java
GitHub Actions, Electron Builder và các bản dựng tự động khác	CI/CD và công cụ xây dựng
Tự phát triển máy khách ký	API
Tự triển khai quy trình ký theo định dạng tệp	API
Cần kiểm soát trực tiếp phần tóm tắt 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ý ở cấp thấp.

Nếu chỉ cần ký mã cho các tệp thông thường, ưu tiên sử dụng client sẵn có hoặc Provider tiêu chuẩn có thể giảm bớt khối lượng công việc tự xử lý định dạng tệp chữ 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 tóm tắt​

Định dạng digest​

padding​

bổ sung​

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

Phản hồi đã 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ố​

Thời gian chờ và thử lại​

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

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

Khi nào nên 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 tóm tắt

Định dạng digest

padding

bổ sung

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

Phản hồi đã 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ố

Thời gian chờ và thử lại

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

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

Khi nào nên sử dụng API