Tham chiếu API ký mã từ xa

Bài viết này dành cho các nhà phát triển cần tích hợp trực tiếp khả năng ký từ xa, mô tả hai giao diện sau:

• POST /v1/codesign/sign：Gửi tóm tắt băm cần ký, nhận kết quả chữ ký RSA PKCS#1.
• POST /v1/codesign/report-sign：Báo cáo kết quả xử lý cuối cùng của máy khách (không ảnh hưởng đến số lần ký).

---

Địa chỉ truy cập

Môi trường	Địa chỉ
Môi trường sản xuất (mặc định)	https://ssl.face.racent.com
Môi trường NICSRS	https://ssl.face.nicsrs.com

Nếu cần địa chỉ môi trường 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.

---

Quy ước chung

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

• Giao thức: HTTPS
• Method: POST
• Body: JSON
• Headers:

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

Xác thực

API sử dụng HTTP Basic Auth:

• Username: Access Key
• Password: Access Secret

Tạo header Authorization:

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

Cấu trúc phản hồi chung

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

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

Bên gọi cần đồng thời xử lý mã trạng thái HTTP và mã trạng thái nghiệp vụ:

• HTTP không phải 2xx → xử lý theo lỗi HTTP.
• HTTP 2xx và code != 0 → xử lý theo lỗi nghiệp vụ.
• HTTP 2xx và code == 0 → đọc data tương ứng.

---

Giao diện ký

Mô tả giao diện

POST /v1/codesign/sign

Gửi các byte thô của hàm băm cần ký (mã hóa Base64), dịch vụ từ xa sẽ sử dụng chứng chỉ được chỉ định để hoàn tất chữ ký RSA PKCS#1 và trả về kết quả.

Lưu ý

/v1/codesign/sign trả về thành công nội dung chữ ký tức được coi là ký thành công, số lần ký tăng thêm 1. Yêu cầu thất bại không tiêu tốn số lần ký. Việc có gọi report-sign hay không không ảnh hưởng đến việc đếm số lần.

Tham số 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
  }
}

Trường	Kiểu	Bắt buộc	Ý nghĩa
code	string	Có	Số chứng chỉ, dùng để chọn chứng chỉ ký từ xa.
digest	string	Có	Mã hóa Base64 của các byte gốc của hàm băm cần ký. Bên gọi cần tính toán hàm băm cục bộ theo tệp đích và yêu cầu của công cụ ký.
algorithm	string	Có	Thuật toán băm, hỗ trợ SHA1, SHA256, SHA384, SHA512.
padding	string	có	Chế độ đệm RSA, hiện được cố định là PKCS1.
extra	object	không	Thông tin ngữ cảnh máy khách, dùng cho ghi nhật ký chữ ký, kiểm toán và khắc phục sự cố.

Mô tả trường extra:

Trường	Loại	Ý nghĩa
platform	string	Nền tảng máy khách, ví dụ windows/amd64, linux/amd64.
version	string	Phiên bản máy khách.
revision	string	Bản sửa đổi (revision) bản dựng máy khách.
time	string	Thời gian bản dựng máy khách hoặc thời gian yêu cầu.
hostname	string	Tên máy chủ khởi tạo chữ ký.
signing_filename	string	Tên tệp hoặc đường dẫn tệp được ký, khuyến nghị khử nhận dạng theo chính sách bảo mật.
signing_filesize	integer	Kích thước tệp được ký (byte).

Ví dụ yêu cầu

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

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

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

Trường	Kiểu	Ý nghĩa
id	string	ID bản ghi ký, dùng khi gọi report-sign.
signature	string	Mã hóa Base64 của kết quả ký RSA.

---

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

Mô tả giao diện

POST /v1/codesign/report-sign

Sau khi máy khách nhận được kết quả ký từ xa, có thể xảy ra lỗi trong quá trình xử lý cục bộ, ghi dữ liệu hoặc trả lại cho bên gọi. Giao diện này được dùng để gửi lại trạng thái xử lý cuối cùng của máy khách cho máy chủ, nhằm thuận tiện cho việc hiển thị hồ sơ ký và điều tra kiểm toán.

Giải thích

Giao diện này chỉ ghi lại kết quả xử lý của máy khách, không làm thay đổi kết quả đếm số lần của /v1/codesign/sign. Việc không gọi giao diện này không ảnh hưởng đến số lần ký thành công.

Tham số yêu cầu

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

Trường	Kiểu	Bắt buộc	Ý nghĩa
id	string	Có	/v1/codesign/sign trả về data.id.
status	integer	Có	Trạng thái xử lý cuối cùng của máy khách: 1 thành công, 2 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
}

---

Ví dụ phản hồi lỗi

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

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

Lỗi tham số:

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

Lưu ý

Mã lỗi và thông báo lỗi cụ thể được xác định theo phản hồi thực tế từ máy chủ. Bên tích hợp không nên dựa vào nội dung lỗi cố định để phân nhánh logic nghiệp vụ.

---

Khuyến nghị tích hợp

• Bảo vệ cẩn thận Access Secret, không ghi vào nhật ký, báo cáo sự cố hoặc trang frontend.
• digest phải là mã hóa Base64 của các byte gốc sau khi băm, không phải chuỗi hex cũng không phải toàn bộ nội dung tệp.
• algorithm phải nhất quán với thuật toán băm thực tế của digest.
• Chế độ đệm hiện tại cố định sử dụng PKCS1, không truyền giá trị khác.
• Các trường digest và signature có thể khá dài, trong nhật ký chỉ nên ghi lại độ dài hoặc kết quả che tiền tố/hậu tố.
• Khuyến nghị sau khi hoàn tất xử lý cuối cùng ở phía máy khách, gọi report-sign để báo cáo kết quả, thuận tiện cho việc kiểm tra và truy vết sau này.
• Xử lý riêng lỗi mạng, lỗi HTTP và lỗi nghiệp vụ, đồng thời thiết lập thời gian chờ và chiến lược thử lại hợp lý cho các yêu cầu ký.