เอกสารอ้างอิง API การลงนามโค้ดระยะไกล

เอกสารนี้จัดทำขึ้นสำหรับนักพัฒนาที่ต้องการเชื่อมต่อความสามารถในการลงนามระยะไกลโดยตรง โดยอธิบายอินเทอร์เฟซสองรายการต่อไปนี้:

• POST /v1/codesign/sign: ส่งแฮชไดเจสต์ที่รอการลงนาม รับผลลัพธ์ลายเซ็น RSA PKCS#1
• POST /v1/codesign/report-sign: รายงานผลการประมวลผลขั้นสุดท้ายของไคลเอนต์ (ไม่มีผลต่อการนับจำนวนการลงนาม)

---

ที่อยู่สำหรับเชื่อมต่อ

สภาพแวดล้อม	ที่อยู่
สภาพแวดล้อมการใช้งานจริง (ค่าเริ่มต้น)	https://ssl.face.racent.com
สภาพแวดล้อม NICSRS	https://ssl.face.nicsrs.com

หากต้องการที่อยู่สภาพแวดล้อมอื่น ให้ยึดตามที่อยู่ที่ทีมส่งมอบหรือฝ่ายปฏิบัติการให้ไว้

---

ข้อตกลงทั่วไป

รูปแบบคำขอ

• โปรโตคอล: HTTPS
• Method: POST
• Body: JSON
• Headers:

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

การตรวจสอบสิทธิ์

อินเทอร์เฟซใช้ HTTP Basic Auth:

• Username: Access Key
• Password: Access Secret

สร้างส่วนหัว Authorization:

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

โครงสร้างการตอบกลับทั่วไป

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

ฟิลด์	ประเภท	ความหมาย
code	integer	รหัสสถานะทางธุรกิจ 0 หมายถึงสำเร็จ ส่วนค่าที่ไม่ใช่ 0 หมายถึงธุรกิจล้มเหลว
message	string	คำอธิบายสถานะทางธุรกิจ หากล้มเหลวจะเป็นข้อความแสดงข้อผิดพลาด
data	object	ข้อมูลทางธุรกิจของอินเทอร์เฟซ

ผู้เรียกใช้ควรจัดการทั้งรหัสสถานะ HTTP และรหัสสถานะทางธุรกิจพร้อมกัน:

• HTTP ไม่ใช่ 2xx → จัดการตามข้อผิดพลาด HTTP
• HTTP 2xx และ code != 0 → จัดการตามข้อผิดพลาดทางธุรกิจ
• HTTP 2xx และ code == 0 → อ่าน data ที่เกี่ยวข้อง

---

อินเทอร์เฟซการลงนาม

คำอธิบายอินเทอร์เฟซ

POST /v1/codesign/sign

ส่งไบต์ดิบของแฮชที่รอการลงนาม (เข้ารหัส Base64) โดยบริการระยะไกลจะใช้ใบรับรองที่ระบุเพื่อดำเนินการลงนาม RSA PKCS#1 และส่งคืนผลลัพธ์

หมายเหตุ

/v1/codesign/sign หากส่งคืนเนื้อหาการลงนามสำเร็จจะถือว่าการลงนามสำเร็จ และจำนวนครั้งการลงนามจะเพิ่มขึ้น 1 คำขอที่ล้มเหลวจะไม่นับจำนวนครั้งการลงนาม การเรียก report-sign หรือไม่ไม่มีผลต่อการนับครั้ง

พารามิเตอร์คำขอ

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

ฟิลด์	ประเภท	จำเป็น	ความหมาย
code	string	ใช่	หมายเลขใบรับรอง ใช้เลือกใบรับรองสำหรับการลงนามระยะไกล
digest	string	ใช่	การเข้ารหัส Base64 ของไบต์ดิบของแฮชที่รอการลงนาม ผู้เรียกใช้ต้องคำนวณแฮชในเครื่องตามไฟล์เป้าหมายและข้อกำหนดของเครื่องมือลงนาม
algorithm	string	ใช่	อัลกอริทึมแฮช รองรับ SHA1, SHA256, SHA384, SHA512
padding	string	ใช่	โหมด Padding ของ RSA ปัจจุบันคงที่คือ PKCS1
extra	object	ไม่ใช่	ข้อมูลบริบทฝั่งไคลเอ็นต์ ใช้สำหรับบันทึกลายเซ็น การตรวจสอบ และการแก้ไขปัญหา

คำอธิบายฟิลด์ extra:

ฟิลด์	ประเภท	ความหมาย
platform	string	แพลตฟอร์มฝั่งไคลเอ็นต์ เช่น windows/amd64, linux/amd64
version	string	เวอร์ชันฝั่งไคลเอ็นต์
revision	string	revision การ build ของไคลเอนต์
time	string	เวลาที่ build ไคลเอนต์หรือเวลาที่ส่งคำขอ
hostname	string	ชื่อโฮสต์ที่เริ่มการลงนาม
signing_filename	string	ชื่อไฟล์หรือเส้นทางของไฟล์ที่ถูกลงนาม แนะนำให้ปกปิดข้อมูลตามนโยบายความปลอดภัย
signing_filesize	integer	ขนาดไฟล์ที่ถูกลงนาม (ไบต์)

ตัวอย่างคำขอ

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

การตอบสนองที่สำเร็จ

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

ฟิลด์	ประเภท	ความหมาย
id	string	รหัสบันทึกลายเซ็น ใช้เมื่อเรียก report-sign
signature	string	ผลลัพธ์ลายเซ็น RSA ที่เข้ารหัส Base64

---

รายงานผลลัพธ์ลายเซ็น

คำอธิบายอินเทอร์เฟซ

POST /v1/codesign/report-sign

After the client retrieves the remote signing result, it may fail during local processing, writing, or returning the result to the caller. This API is used to report the client's final processing status back to the server, facilitating signature record display and audit troubleshooting.

Note

This API only records the client processing result and does not change the counting result of /v1/codesign/sign. Not calling this API does not affect the successful signing count.

Request Parameters

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

ฟิลด์	ประเภท	จำเป็น	ความหมาย
id	string	ใช่	/v1/codesign/sign ที่ส่งกลับโดย data.id
status	integer	ใช่	สถานะการประมวลผลสุดท้ายของไคลเอนต์: 1 สำเร็จ 2 ล้มเหลว

ตัวอย่างคำขอ

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

การตอบกลับเมื่อสำเร็จ

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

---

ตัวอย่างการตอบกลับเมื่อเกิดข้อผิดพลาด

การตรวจสอบสิทธิ์ล้มเหลว:

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

ข้อผิดพลาดของพารามิเตอร์:

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

หมายเหตุ

โปรดยึดตามรหัสข้อผิดพลาดและข้อความแสดงข้อผิดพลาดที่เซิร์ฟเวอร์ส่งกลับมาจริงเป็นหลัก ฝั่งผู้เชื่อมต่อไม่ควรพึ่งพาข้อความข้อผิดพลาดตายตัวเพื่อใช้เป็นเงื่อนไขแยกสาขาทางธุรกิจ

---

คำแนะนำในการเชื่อมต่อ

• ปกป้อง Access Secret อย่างเหมาะสม อย่าเขียนลงในล็อก รายงานข้อขัดข้อง หรือหน้าเว็บฝั่งฟรอนต์เอนด์
• digest ต้องเป็นการเข้ารหัส Base64 ของไบต์ดิบของแฮช ไม่ใช่สตริงเลขฐานสิบหก และไม่ใช่เนื้อหาไฟล์แบบเต็ม
• algorithm ต้องสอดคล้องกับอัลกอริทึมแฮชจริงของ digest
• โหมดแพดดิงปัจจุบันใช้ PKCS1 แบบคงที่เท่านั้น อย่าส่งค่าอื่น
• ฟิลด์ digest และ signature อาจมีความยาวมาก แนะนำให้บันทึกเฉพาะความยาวหรือผลลัพธ์ที่ปกปิดส่วนหน้า/ส่วนท้ายในล็อก
• แนะนำให้เรียก report-sign เพื่อรายงานผลหลังการประมวลผลขั้นสุดท้ายฝั่งไคลเอ็นต์เสร็จสิ้น เพื่อสะดวกต่อการตรวจสอบและแก้ไขปัญหาในภายหลัง
• จัดการข้อผิดพลาดเครือข่าย ข้อผิดพลาด HTTP และข้อผิดพลาดทางธุรกิจแยกจากกัน และกำหนดกลยุทธ์การหมดเวลาและการลองใหม่ที่เหมาะสมสำหรับคำขอที่ลงนาม