Skip to main content

คู่มือการใช้งาน CSP

ภาพรวม​

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

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

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

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

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

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

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 ของเครื่อง-local

การติดตั้งจะแก้ไขการลงทะเบียน 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 Provider
/kc CERT_CODEระบุ key container ที่สอดคล้องกับหมายเลขใบรับรอง
/f <证书路径>ระบุไฟล์ใบรับรองที่ดาวน์โหลดโดย csp add
/fd SHA256ระบุอัลกอริทึมการย่อยไฟล์
/tr <URL>ระบุบริการประทับเวลา RFC 3161
/td SHA256ระบุอัลกอริทึมการย่อยของการประทับเวลา

ปัจจุบัน 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 ตรงกับ CERT_CODE.crt ที่ดาวน์โหลดจาก csp add
การเรียกลงนามล้มเหลวตรวจสอบหมายเลขใบรับรอง ข้อมูลรับรองบริการ และการเชื่อมต่อเครือข่าย แล้วดู %ProgramData%\sslTrusKSP\sslTrusCSP.log
ใช้ที่อยู่บริการแบบกำหนดเองแต่คำร้องขอผิดปกติCSP เรียกใช้เส้นทาง /v1/codesign/sign แบบคงที่ของบริการคำร้องขอ ที่อยู่บริการที่กำหนดค่าไว้ควรให้เฉพาะ http(s)://host[:port] เท่านั้น

ข้อแนะนำด้านความปลอดภัย​

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

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

Last updated on