เอกสารอ้างอิง 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:

• ชื่อผู้ใช้: Access Key
• รหัสผ่าน: 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	ใช่	โหมดการเติม RSA ปัจจุบันคงที่เป็น PKCS1
extra	object	ไม่ใช่	ข้อมูลบริบทของไคลเอ็นต์ ใช้สำหรับบันทึกลายเซ็น การตรวจสอบ และการแก้ไขปัญหา

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

ฟิลด์	ประเภท	ความหมาย
platform	string	แพลตฟอร์มของไคลเอ็นต์ เช่น windows/amd64, linux/amd64
version	string	เวอร์ชันของไคลเอ็นต์
revision	string	รีวิชันการ 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

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

คำอธิบาย

อินเทอร์เฟซนี้เพียงบันทึกผลการประมวลผลของไคลเอนต์เท่านั้น และไม่เปลี่ยนแปลงผลการนับจำนวนของ /v1/codesign/sign การไม่เรียกอินเทอร์เฟซนี้จะไม่ส่งผลต่อจำนวนครั้งที่ลงนามสำเร็จ

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

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

ฟิลด์	ประเภท	จำเป็น	ความหมาย
id	string	ใช่	data.id ที่ส่งกลับโดย /v1/codesign/sign
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 อย่างเหมาะสม อย่าเขียนลงในบันทึก รายงานข้อขัดข้อง หรือหน้าเว็บฝั่ง frontend
• digest ต้องเป็นการเข้ารหัส Base64 ของไบต์ดิบของแฮช ไม่ใช่สตริงเลขฐานสิบหก และไม่ใช่เนื้อหาไฟล์ทั้งหมด
• algorithm ต้องสอดคล้องกับอัลกอริทึมแฮชจริงของ digest
• โหมด padding ปัจจุบันใช้แบบคงที่เป็น PKCS1 อย่าส่งค่าอื่น
• ฟิลด์ digest และ signature อาจมีความยาวมาก แนะนำให้บันทึกเฉพาะความยาวหรือผลลัพธ์ที่ปกปิดอักขระส่วนหน้าและส่วนท้ายในบันทึก
• แนะนำให้เรียก report-sign เพื่อรายงานผลลัพธ์หลังจากที่ฝั่ง client ประมวลผลเสร็จสิ้นแล้ว เพื่อความสะดวกในการตรวจสอบและแก้ไขปัญหาภายหลัง
• จัดการข้อผิดพลาดด้านเครือข่าย ข้อผิดพลาด HTTP และข้อผิดพลาดทางธุรกิจแยกจากกัน และกำหนดระยะเวลาหมดเวลาและกลยุทธ์การลองใหม่ที่เหมาะสมสำหรับคำขอที่มีการลงนาม