Chuyển tới nội dung chính

Tài liệu tham khảo 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 bản tóm tắt hàm băm đang chờ ký để nhận kết quả 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 NICSRShttps://ssl.face.nicsrs.com

Nếu cần địa chỉ môi trường khác, vui lòng sử dụng đị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​

Giao diện sử dụng HTTP Basic Auth:

  • Tên người dùng: Access Key
  • Mật khẩu: Access Secret

Tạo tiêu đề Authorization:

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

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

{
  "code": 0,
  "message": "ok",
  "data": {}
}
TrườngKiểuÝ nghĩa
codeintegerMã trạng thái nghiệp vụ. 0 nghĩa là thành công, khác 0 nghĩa là nghiệp vụ thất bại.
messagestringMô tả trạng thái nghiệp vụ, là mô tả lỗi khi thất bại.
dataobjectDữ liệu nghiệp vụ của giao diện.

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

  • HTTP không phải 2xx → xử lý như lỗi HTTP.
  • HTTP 2xx và code != 0 → xử lý như 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 byte thô của hash cần ký (mã hóa Base64), dịch vụ từ xa sử dụng chứng chỉ được chỉ định để hoàn tất ký RSA PKCS#1 và trả về kết quả.

Lưu ý

/v1/codesign/sign Trả về nội dung chữ ký thành công đượ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 tính 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ườngKiểuBắt buộcÝ nghĩa
codestringCóSố chứng chỉ, dùng để chọn chứng chỉ ký từ xa.
digeststringCóMã hóa Base64 của các byte thô của giá trị băm cần ký. Bên gọi cần tính toán giá trị băm cục bộ theo tệp đích và yêu cầu của công cụ ký.
algorithmstringCóThuật toán băm, hỗ trợ SHA1, SHA256, SHA384, SHA512.
paddingstringCóChế độ đệm RSA, hiện cố định là PKCS1.
extraobjectKhôngThông tin ngữ cảnh phía máy khách, dùng cho ghi nhật ký ký, kiểm toán và khắc phục sự cố.

extra Mô tả trường:

TrườngKiểuÝ nghĩa
platformstringNền tảng máy khách, ví dụ windows/amd64, linux/amd64.
versionstringPhiên bản máy khách.
revisionstringBản build/revision của máy khách.
timestringThời gian build máy khách hoặc thời gian yêu cầu.
hostnamestringTên máy chủ khởi tạo chữ ký.
signing_filenamestringTên tệp hoặc đường dẫn được ký, khuyến nghị làm mờ theo chính sách bảo mật.
signing_filesizeintegerKí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ườngKiểuÝ nghĩa
idstringID bản ghi ký, dùng khi gọi report-sign.
signaturestringMã 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 nhận được kết quả ký từ xa, máy khách có thể gặp lỗi khi 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 sử dụng để truyền trạng thái xử lý cuối cùng của máy khách về máy chủ, thuận tiện cho việc hiển thị hồ sơ ký và điều tra kiểm toán.

Ghi chú

Giao diện này chỉ ghi lại kết quả xử lý từ phía máy khách, không thay đổi kết quả đếm 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ườngKiểuBắt buộcÝ nghĩa
idstringCódata.id do /v1/codesign/sign trả về.
statusintegerCó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ể sẽ dựa trên 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 văn bản lỗi cố định để đưa ra các 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 byte thô của giá trị băm, không phải chuỗi hex, cũng không phải nội dung tệp đầy đủ.
  • 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ả đã khử nhạy cảm tiền tố/hậu tố.
  • Khuyến nghị sau khi client hoàn tất xử lý cuối cùng, 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 về sau.
  • Xử lý riêng lỗi mạng, lỗi HTTP và lỗi nghiệp vụ, đồng thời thiết lập chiến lược timeout và retry hợp lý cho yêu cầu ký.
Cập nhật lần cuối vào