คำแนะนำการใช้งาน CSP

ภาพรวม

คำแนะนำนี้ใช้สำหรับการกำหนดค่า sslTrus Cryptographic Service Provider (CSP) บน Windows และใช้ Microsoft signtool.exe จาก Windows SDK เพื่อทำการลงนามโค้ดด้วย Cloud HSM

signtool csp ของโปรเจกต์นี้รับผิดชอบการติดตั้ง กำหนดค่า และบำรุงรักษา Provider ส่วนการลงนามจริงจะใช้ signtool.exe จาก Windows SDK ซึ่งทั้งสองไม่ใช่โปรแกรมเดียวกัน

sslTrus Cryptographic Service Provider เป็น CSP แบบ CryptoAPI ดั้งเดิม เหมาะสำหรับกระบวนการลงนามบน Windows ที่ต้องการเชื่อมต่อผ่าน /csp และ /kc คีย์ส่วนตัวสำหรับการลงนามจะถูกเก็บไว้ใน Cloud HSM เสมอ ส่วนเครื่อง local จะเก็บเฉพาะ CSP DLL, ใบรับรองการลงนาม และการกำหนดค่าการเข้าถึงที่ป้องกันด้วย Windows DPAPI

การเตรียมตัวก่อนใช้งาน

• ระบบ Windows x64
• เทอร์มินัลที่รันในฐานะผู้ดูแลระบบ สำหรับติดตั้งหรือถอนการติดตั้ง Provider
• CLI ของ signtool ของโปรเจกต์นี้ และมีคำสั่งย่อย csp อยู่ภายใน
• ติดตั้ง Windows SDK แล้ว และสามารถใช้ signtool.exe ของ Microsoft ได้
• มี Access Key, Access Secret และหมายเลขใบรับรอง (CERT_CODE) ที่ถูกต้อง
• เครือข่ายสามารถเข้าถึงบริการลงนามโค้ดและบริการ timestamp ที่เลือกได้

ยืนยันว่าเครื่องมือทั้งสองใช้งานได้แยกกัน:

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

หากมีโปรแกรมชื่อเดียวกันสองตัวอยู่ในไดเรกทอรีปัจจุบันหรือ PATH พร้อมกัน อย่าลืมยืนยันเป้าหมายที่เรียกใช้งานจริงผ่านพาธแบบเต็มหรือ where

เริ่มต้นอย่างรวดเร็ว

ในเทอร์มินัลผู้ดูแลระบบ ให้ดำเนินการตามลำดับ:

signtool csp install
signtool csp add
signtool csp list

csp add จะโต้ตอบเพื่อขอให้ป้อนข้อมูล:

Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE

หลังจากกำหนดค่าเสร็จเรียบร้อยแล้ว ใช้ Microsoft signtool.exe จาก Windows SDK ในการลงนาม:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

แทนที่ CERT_CODE และ app.exe ในตัวอย่างด้วยหมายเลขใบรับรองจริงและไฟล์ที่รอการลงนาม

ติดตั้ง Provider

ดำเนินการ:

signtool csp install

该คำสั่งจะ:

• เขียน sslTrusCSP.dll ลงใน %ProgramData%\sslTrusKSP และคัดลอกไปยังไดเรกทอรีระบบ
• ลงทะเบียน sslTrus Cryptographic Service Provider (ประเภท Provider เป็น PROV_RSA_AES)
• ติดตั้ง KSP DLL ที่เกี่ยวข้อง และลงทะเบียน sslTrus Key Storage Provider เป็น CNG Provider alias ที่มีชื่อเดียวกับ CSP
• สร้างหรือบันทึก %ProgramData%\sslTrusKSP\config.dat; ไฟล์ใช้การเข้ารหัส Windows DPAPI ของเครื่องนั้น

การติดตั้งจะแก้ไขการลงทะเบียน Provider ระดับระบบ โดยปกติต้องรันในเทอร์มินัลผู้ดูแลระบบ หากเวอร์ชัน CSP DLL ในไดเรกทอรีระบบตรงกับเวอร์ชันที่ฝังอยู่ CLI จะข้ามการคัดลอก CSP DLL แต่ยังคงดำเนินการลงทะเบียน Provider

เพิ่มการกำหนดค่าใบรับรอง

ดำเนินการ:

signtool csp add

如需ใช้ที่อยู่บริการ NICSRS:

signtool csp add --address nicsrs

--address ไม่ใช่พารามิเตอร์ที่ส่งผ่าน URL โดยตรง ปัจจุบัน nicsrs จะใช้บริการ NICSRS ส่วนค่าว่าง racent หรือค่าอื่น ๆ จะใช้บริการเริ่มต้น

เมื่อเพิ่มแล้ว CLI จะดึงใบรับรองจากบริการระยะไกล และบันทึกลงใน:

%ProgramData%\sslTrusKSP\CERT_CODE.crt

พร้อมกันนี้ให้เขียนที่อยู่บริการ ข้อมูลประจำตัว หมายเลขใบรับรอง และพาธของใบรับรองลงในไฟล์คอนฟิกที่เข้ารหัส CERT_CODE เป็นทั้งตัวระบุใบรับรองระยะไกล และเป็นค่าของ /kc ใน signtool.exe ของ Microsoft ในภายหลัง

หากเพิ่มหมายเลขใบรับรองที่มีอยู่แล้ว CLI จะถามว่าจะเขียนทับหรือไม่: ป้อน y เพื่อแทนที่คอนฟิกเดิม; กด Enter โดยตรงหรือป้อนค่าอื่นจะคงคอนฟิกเดิมไว้

ดูและลบคอนฟิก

ดูคอนฟิกปัจจุบัน:

signtool csp list

ผลลัพธ์ประกอบด้วยหมายเลขใบรับรอง ประเภทบริการ Access Key และ Access Secret ที่ถูกปกปิดบางส่วน โปรดอย่าอัปโหลดผลลัพธ์จากคำสั่ง ไฟล์คอนฟิก หรือบันทึกล็อกไปยังพื้นที่สาธารณะ

ลบการกำหนดค่าบางรายการ:

signtool csp del

ป้อนหมายเลขใบรับรองตามคำแนะนำได้เลย การดำเนินการนี้จะลบเฉพาะรายการที่เกี่ยวข้องในการกำหนดค่าการเข้ารหัสเท่านั้น ไม่ลบไฟล์ใบรับรอง .crt ที่มีชื่อเดียวกัน หากไม่ใช้งานแล้ว กรุณาลบไฟล์ดังกล่าวด้วยตนเอง

ใช้ลายเซ็น Microsoft signtool.exe

ลายเซ็น SHA-256

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

คำอธิบายพารามิเตอร์:

พารามิเตอร์	คำอธิบาย
/csp "sslTrus Cryptographic Service Provider"	ระบุผู้ให้บริการ CSP
/kc CERT_CODE	ระบุคีย์คอนเทนเนอร์ที่สอดคล้องกับหมายเลขใบรับรอง
/f <证书路径>	ระบุไฟล์ใบรับรองที่ดาวน์โหลดโดย csp add
/fd SHA256	ระบุอัลกอริทึมการย่อไฟล์
/tr <URL>	ระบุบริการ timestamp ตามมาตรฐาน RFC 3161
/td SHA256	ระบุอัลกอริทึมการย่อของ timestamp

CSP ปัจจุบันรองรับอัลกอริทึมการย่อไฟล์ SHA1, SHA256, SHA384 และ SHA512; สำหรับลายเซ็นใหม่ โดยทั่วไปแนะนำให้ใช้ SHA-256 หรือเวอร์ชันที่สูงกว่า ที่อยู่ timestamp ควรพิจารณาจากนโยบายใบรับรองของคุณและความเข้ากันได้ของแพลตฟอร์มเป้าหมาย

เพิ่มลายเซ็น SHA-1

เมื่อมีความจำเป็นต้องรองรับระบบเก่าจริงๆ จึงสามารถเพิ่ม SHA-1 ทับลงบนลายเซ็นที่มีอยู่ได้:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA1 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  /as ^
  ".\app.exe"

/as หมายถึงการเพิ่มลายเซ็น เพื่อหลีกเลี่ยงการเขียนทับลายเซ็นที่มีอยู่ ควรปฏิบัติตามนโยบายของระบบเป้าหมายและใบรับรองว่าจำเป็นต้องใช้ SHA-1 หรือไม่ ไม่ควรใช้เป็นตัวเลือกเริ่มต้นสำหรับโปรเจกต์ใหม่

ตรวจสอบลายเซ็น

หลังลงนามแล้วสามารถใช้ Microsoft signtool.exe เพื่อตรวจสอบได้：

signtool.exe verify /pa /v ".\app.exe"

หากต้องการตรวจสอบลายเซ็นทั้งหมด สามารถเลือกตัวเลือกการตรวจสอบที่เกี่ยวข้องได้ตามเวอร์ชันและคำอธิบายพารามิเตอร์ของ Windows SDK signtool.exe

ถอนการติดตั้ง Provider

ให้รันคำสั่งในเทอร์มินัลของผู้ดูแลระบบ:

signtool csp uninstall

คำสั่งนี้จะลบการลงทะเบียน CSP และ CNG Provider alias ที่มีชื่อเดียวกับ CSP และลบสำเนา CSP DLL ออกจาก ProgramData และไดเรกทอรีระบบ โดยจะไม่ลบไดเรกทอรี %ProgramData%\sslTrusKSP ทั้งหมด และไม่ลบการลงทะเบียนและ DLL ของ sslTrus Key Storage Provider ที่เกี่ยวข้องโดยอัตโนมัติ หาก KSP นี้ถูกใช้เฉพาะในขั้นตอนการติดตั้ง CSP โปรดพิจารณาลบอย่างระมัดระวังตามสถานะการปรับใช้จริง

หลังถอนการติดตั้ง หากต้องการลบข้อมูลละเอียดอ่อนในเครื่อง ให้ลบการกำหนดค่า ใบรับรอง และบันทึกใน %ProgramData%\sslTrusKSP ด้วยตนเอง หลังจากยืนยันแล้วว่าไม่มีการใช้งานโดย KSP หรือกระบวนการลงนามอื่นอีก

คำถามที่พบบ่อย

อาการ	ข้อแนะนำในการแก้ไข
cryptographic service provider is only supported on windows	รันคำสั่งจัดการ CSP บน Windows
การติดตั้งแจ้งข้อผิดพลาดสิทธิ์หรือการเขียนลงไดเรกทอรีระบบล้มเหลว	ใช้เทอร์มินัลผู้ดูแลระบบและรัน signtool csp install
no csp configuration	รัน signtool csp install ก่อน จากนั้นรัน signtool csp add
no such certificate code	ใช้ signtool csp list เพื่อตรวจสอบหมายเลขใบรับรองก่อน
Microsoft signtool.exe ไม่พบ Provider	ยืนยันว่าคำสั่งติดตั้งสำเร็จ เครื่องมือปัจจุบันและ Provider เป็น x64 และเปิดเทอร์มินัลใหม่แล้วลองอีกครั้ง
ไม่พบไฟล์ใบรับรองขณะลงนาม	ยืนยันว่าเส้นทาง /f และ csp add ที่ดาวน์โหลด CERT_CODE.crt ตรงกัน
การเรียกลงนามล้มเหลว	ตรวจสอบหมายเลขใบรับรอง ข้อมูลรับรองบริการ และการเชื่อมต่อเครือข่าย จากนั้นดู %ProgramData%\sslTrusKSP\sslTrusCSP.log
ใช้ที่อยู่บริการแบบกำหนดเองแต่คำขอผิดปกติ	CSP เรียกใช้เส้นทาง /v1/codesign/sign แบบคงที่ของบริการคำขอ ที่อยู่บริการที่กำหนดค่าควรระบุเฉพาะ http(s)://host[:port]

คำอธิบายด้านความปลอดภัย

• Access Secret, config.dat, ไฟล์ใบรับรอง และบันทึก CSP ควรจัดการเป็นข้อมูลละเอียดอ่อน
• config.dat ได้รับการป้องกันโดย DPAPI ของโปรไฟล์ผู้ใช้ Windows ปัจจุบันที่สร้างการกำหนดค่า และไม่ควรคัดลอกไปยังผู้ใช้หรือเครื่องอื่นเพื่อใช้ซ้ำโดยตรง
• CSP ไม่บันทึกคีย์ส่วนตัว อย่าพยายามนำเข้าคีย์ส่วนตัวไปยัง %ProgramData%\sslTrusKSP
• การลงนาม CSP ต้องเข้าถึงบริการระยะไกล การหมดเวลาเครือข่าย การถูกปฏิเสธจากเซิร์ฟเวอร์ หรือบริการประทับเวลาไม่พร้อมใช้งาน อาจทำให้การลงนามล้มเหลว

สำหรับพารามิเตอร์ CLI และคำสั่งการลงนามเพิ่มเติม โปรดดู ข้อมูลอ้างอิงคำสั่ง SignTool sign