chrome.certificateProvider

คำอธิบาย

ใช้ API นี้เพื่อแสดงใบรับรองต่อแพลตฟอร์มที่สามารถใช้ใบรับรองเหล่านี้สําหรับการตรวจสอบสิทธิ์ TLS

สิทธิ์

certificateProvider

ความพร้อมใช้งาน

Chrome 46 ขึ้นไป ChromeOS เท่านั้น

แนวคิดและการใช้งาน

การใช้งานทั่วไปของ API นี้เพื่อแสดงใบรับรองไคลเอ็นต์ต่อ ChromeOS มีขั้นตอนดังนี้

  • ส่วนขยายจะลงทะเบียนสําหรับเหตุการณ์ onCertificatesUpdateRequested และ onSignatureRequested
  • ส่วนขยายจะเรียก setCertificates() เพื่อระบุรายการใบรับรองเริ่มต้นหลังจากการเริ่มต้น
  • ส่วนขยายจะตรวจสอบการเปลี่ยนแปลงในรายการใบรับรองที่ใช้ได้และเรียก setCertificates() เพื่อแจ้งให้เบราว์เซอร์ทราบเกี่ยวกับการเปลี่ยนแปลงดังกล่าวทุกครั้ง
  • ในระหว่างการจับมือ TLS เบราว์เซอร์จะได้รับคําขอใบรับรองไคลเอ็นต์ เมื่อเกิดเหตุการณ์ onCertificatesUpdateRequested ขึ้นเบราว์เซอร์จะขอให้ส่วนขยายรายงานใบรับรองทั้งหมดที่มีให้ในปัจจุบัน
  • ส่วนขยายจะรายงานกลับพร้อมใบรับรองที่ใช้ได้ในปัจจุบันโดยใช้เมธอด setCertificates()
  • เบราว์เซอร์จะจับคู่ใบรับรองที่มีอยู่ทั้งหมดกับคําขอใบรับรองไคลเอ็นต์จากโฮสต์ระยะไกล ระบบจะแสดงรายการที่ตรงกันให้ผู้ใช้เห็นในกล่องโต้ตอบการเลือก
  • ผู้ใช้สามารถเลือกใบรับรองเพื่ออนุมัติการตรวจสอบสิทธิ์หรือยกเลิกการตรวจสอบสิทธิ์ได้
กล่องโต้ตอบการเลือกใบรับรอง
กล่องโต้ตอบการเลือกใบรับรอง
  • หากผู้ใช้ยกเลิกการตรวจสอบสิทธิ์หรือไม่มีใบรับรองที่ตรงกับคำขอ ระบบจะยกเลิกการตรวจสอบสิทธิ์ไคลเอ็นต์ TLS
  • หรือหากผู้ใช้อนุมัติการตรวจสอบสิทธิ์ด้วยใบรับรองที่ส่วนขยายนี้ให้ไว้ เบราว์เซอร์จะขอให้ส่วนขยายลงนามในข้อมูลเพื่อดำเนินการแฮนด์เชค TLS ต่อ ระบบจะส่งคําขอเป็นเหตุการณ์ onSignatureRequested
  • เหตุการณ์นี้มีข้อมูลอินพุต ประกาศว่าต้องใช้อัลกอริทึมใดในการสร้างลายเซ็น และอ้างอิงถึงใบรับรองรายการใดรายการหนึ่งที่ส่วนขยายนี้รายงาน ส่วนขยายต้องสร้างลายเซ็นสําหรับข้อมูลที่ระบุโดยใช้คีย์ส่วนตัวที่เชื่อมโยงกับใบรับรองที่อ้างอิง การสร้างลายเซ็นอาจต้องใส่ DigestInfo ไว้ข้างหน้าและเพิ่มค่าให้กับผลลัพธ์ก่อนการเซ็นชื่อจริง
  • ส่วนขยายจะส่งลายเซ็นกลับไปยังเบราว์เซอร์โดยใช้เมธอด reportSignature() หากคำนวณลายเซ็นไม่ได้ จะต้องเรียกใช้เมธอดโดยไม่มีลายเซ็น
  • หากมีลายเซ็น เบราว์เซอร์จะดำเนินการแฮนด์เชค TLS ให้เสร็จสมบูรณ์

ลำดับขั้นตอนจริงอาจแตกต่างออกไป ตัวอย่างเช่น ระบบจะไม่ขอให้ผู้ใช้เลือกใบรับรองหากใช้นโยบายขององค์กรเพื่อเลือกใบรับรองโดยอัตโนมัติ (ดู AutoSelectCertificateForUrls และนโยบาย Chrome สําหรับผู้ใช้)

ในส่วนขยาย ข้อมูลนี้อาจมีลักษณะคล้ายกับข้อมูลโค้ดต่อไปนี้

function collectAvailableCertificates() {
  // Return all certificates that this Extension can currently provide.
  // For example:
  return [{
    certificateChain: [new Uint8Array(...)],
    supportedAlgorithms: ['RSASSA_PKCS1_v1_5_SHA256']
  }];
}

// The Extension calls this function every time the currently available list of
// certificates changes, and also once after the Extension's initialization.
function onAvailableCertificatesChanged() {
  chrome.certificateProvider.setCertificates({
    clientCertificates: collectAvailableCertificates()
  });
}

function handleCertificatesUpdateRequest(request) {
  // Report the currently available certificates as a response to the request
  // event. This is important for supporting the case when the Extension is
  // unable to detect the changes proactively.
  chrome.certificateProvider.setCertificates({
    certificatesRequestId: request.certificatesRequestId,
    clientCertificates: collectAvailableCertificates()
  });
}

// Returns a private key handle for the given DER-encoded certificate.
// |certificate| is an ArrayBuffer.
function getPrivateKeyHandle(certificate) {...}

// Digests and signs |input| with the given private key. |input| is an
// ArrayBuffer. |algorithm| is an Algorithm.
// Returns the signature as ArrayBuffer.
function signUnhashedData(privateKey, input, algorithm) {...}

function handleSignatureRequest(request) {
  // Look up the handle to the private key of |request.certificate|.
  const key = getPrivateKeyHandle(request.certificate);
  if (!key) {
    // Handle if the key isn't available.
    console.error('Key for requested certificate no available.');

    // Abort the request by reporting the error to the API.
    chrome.certificateProvider.reportSignature({
      signRequestId: request.signRequestId,
      error: 'GENERAL_ERROR'
    });
    return;
  }

  const signature = signUnhashedData(key, request.input, request.algorithm);
  chrome.certificateProvider.reportSignature({
    signRequestId: request.signRequestId,
    signature: signature
  });
}

chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
    handleCertificatesUpdateRequest);
chrome.certificateProvider.onSignatureRequested.addListener(
    handleSignatureRequest);

ประเภท

Algorithm

Chrome 86 ขึ้นไป

ประเภทอัลกอริทึมลายเซ็นการเข้ารหัสที่รองรับ

ค่าแจกแจง

"RSASSA_PKCS1_v1_5_MD5_SHA1"
ระบุอัลกอริทึมลายเซ็น RSASSA PKCS#1 v1.5 ที่มีการแฮช MD5-SHA-1 ส่วนขยายต้องไม่ใส่คำนำหน้า DigestInfo แต่ให้เพิ่มการเติม PKCS#1 เท่านั้น อัลกอริทึมนี้เลิกใช้งานแล้วและ Chrome จะไม่ขอข้อมูลนี้อีกนับตั้งแต่เวอร์ชัน 109

"RSASSA_PKCS1_v1_5_SHA1"
ระบุอัลกอริทึมลายเซ็น RSASSA PKCS#1 v1.5 ที่มีฟังก์ชันแฮช SHA-1

"RSASSA_PKCS1_v1_5_SHA256"
ระบุอัลกอริทึมลายเซ็น RSASSA PKCS#1 v1.5 ที่มีฟังก์ชันการแฮช SHA-256

"RSASSA_PKCS1_v1_5_SHA384"
ระบุอัลกอริทึมการเซ็นชื่อ RSASSA PKCS#1 v1.5 ที่มีฟังก์ชันการแฮช SHA-384

"RSASSA_PKCS1_v1_5_SHA512"
ระบุอัลกอริทึมลายเซ็น RSASSA PKCS#1 v1.5 ที่มีฟังก์ชันการแฮช SHA-512

"RSASSA_PSS_SHA256"
ระบุอัลกอริทึมลายเซ็น RSASSA PSS ที่มีฟังก์ชันการแฮช SHA-256, ฟังก์ชันการสร้างหน้ากาก MGF1 และเกลือขนาดเดียวกับแฮช

"RSASSA_PSS_SHA384"
ระบุอัลกอริทึมลายเซ็น RSASSA PSS ที่มีฟังก์ชันการแฮช SHA-384, ฟังก์ชันการสร้างหน้ากาก MGF1 และ Salt ขนาดเดียวกับแฮช

"RSASSA_PSS_SHA512"
ระบุอัลกอริทึมลายเซ็น RSASSA PSS ที่มีฟังก์ชันการแฮช SHA-512, ฟังก์ชันการสร้างหน้ากาก MGF1 และ Salt ขนาดเดียวกับแฮช

CertificateInfo

พร็อพเพอร์ตี้

  • ใบรับรอง

    ArrayBuffer

    ต้องเป็นการเข้ารหัส DER ของใบรับรอง X.509 ปัจจุบันระบบรองรับเฉพาะใบรับรองของคีย์ RSA เท่านั้น

  • supportedHashes

    Hash[]

    ต้องตั้งค่าเป็นแฮชทั้งหมดที่รองรับสำหรับใบรับรองนี้ ระบบจะขอลายเซ็นของข้อมูลสรุปที่คำนวณด้วยอัลกอริทึมแฮชอย่างใดอย่างหนึ่งเหล่านี้เท่านั้น ซึ่งควรเรียงตามลำดับความชอบแฮชจากมากไปน้อย

CertificatesUpdateRequest

Chrome 86 ขึ้นไป

พร็อพเพอร์ตี้

  • certificatesRequestId

    ตัวเลข

    ส่งตัวระบุคำขอไปยัง setCertificates

ClientCertificateInfo

Chrome 86 ขึ้นไป

พร็อพเพอร์ตี้

  • certificateChain

    ArrayBuffer[]

    อาร์เรย์ต้องมีการเข้ารหัส DER ของใบรับรองไคลเอ็นต์ X.509 เป็นองค์ประกอบแรก

    โดยต้องมีใบรับรองเพียง 1 รายการ

  • supportedAlgorithms

    อัลกอริทึม[]

    อัลกอริทึมทั้งหมดที่รองรับสำหรับใบรับรองนี้ ระบบจะขอลายเซ็นจากส่วนขยายโดยใช้อัลกอริทึมอย่างใดอย่างหนึ่งเหล่านี้เท่านั้น

Error

Chrome 86 ขึ้นไป

ประเภทข้อผิดพลาดที่ส่วนขยายรายงานได้

ค่า

"GENERAL_ERROR"

Hash

เลิกใช้งานแล้ว แทนที่โดย Algorithm

ค่าแจกแจง

"MD5_SHA1"
ระบุอัลกอริทึมการแฮช MD5 และ SHA1

"SHA1"
ระบุอัลกอริทึมการแฮช SHA1

"SHA256"
ระบุอัลกอริทึมการแฮช SHA256

"SHA384"
ระบุอัลกอริทึมการแฮช SHA384

"SHA512"
ระบุอัลกอริทึมการแฮช SHA512

PinRequestErrorType

Chrome 57 ขึ้นไป

ประเภทข้อผิดพลาดที่แสดงต่อผู้ใช้ผ่านฟังก์ชัน requestPin

ค่าแจกแจง

"INVALID_PIN"
ระบุว่า PIN ไม่ถูกต้อง

"INVALID_PUK"
ระบุว่า PUK ไม่ถูกต้อง

"MAX_ATTEMPTS_EXCEEDED"
ระบุว่ามีการพยายามเกินจำนวนครั้งที่อนุญาตสูงสุด

"UNKNOWN_ERROR"
ระบุว่าข้อผิดพลาดไม่สามารถแสดงด้วยประเภทข้างต้น

PinRequestType

Chrome 57 ขึ้นไป

ประเภทโค้ดที่ส่วนขยายขอด้วยฟังก์ชัน requestPin

ค่าแจกแจง

"PIN"
ระบุว่ารหัสที่ขอคือ PIN

"PUK"
ระบุว่ารหัสที่ขอคือ PUK

PinResponseDetails

Chrome 57 ขึ้นไป

พร็อพเพอร์ตี้

  • userInput

    สตริง ไม่บังคับ

    รหัสที่ผู้ใช้ระบุ ว่างเปล่าหากผู้ใช้ปิดกล่องโต้ตอบหรือเกิดข้อผิดพลาดอื่นๆ

ReportSignatureDetails

Chrome 86 ขึ้นไป

พร็อพเพอร์ตี้

  • ข้อผิดพลาด

    "GENERAL_ERROR"
     ไม่บังคับ

    ข้อผิดพลาดที่เกิดขึ้นขณะสร้างลายเซ็น (หากมี)

  • signRequestId

    ตัวเลข

    ตัวระบุคําขอที่ได้รับผ่านเหตุการณ์ onSignatureRequested

  • ลายเซ็น

    ArrayBuffer ไม่บังคับ

    ลายเซ็น หากสร้างสำเร็จ

RequestPinDetails

Chrome 57 ขึ้นไป

พร็อพเพอร์ตี้

  • attemptsLeft

    ตัวเลข ไม่บังคับ

    จำนวนครั้งที่เหลือ ข้อมูลนี้ระบุไว้เพื่อให้ UI ใดก็ได้แสดงข้อมูลนี้ต่อผู้ใช้ Chrome ไม่ได้บังคับใช้ข้อกำหนดนี้ แต่ส่วนขยายควรเรียกใช้ stopPinRequest ด้วย errorType = MAX_ATTEMPTS_EXCEEDED เมื่อจำนวนคำขอ PIN เกิน

  • errorType

    PinRequestErrorType ไม่บังคับ

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

  • requestType

    PinRequestType ไม่บังคับ

    ประเภทรหัสที่ขอ ค่าเริ่มต้นคือ PIN

  • signRequestId

    ตัวเลข

    รหัสที่ Chrome ระบุใน SignRequest

SetCertificatesDetails

Chrome 86 ขึ้นไป

พร็อพเพอร์ตี้

  • certificatesRequestId

    ตัวเลข ไม่บังคับ

    เมื่อเรียกใช้เพื่อตอบสนองต่อ onCertificatesUpdateRequested ควรมีค่า certificatesRequestId ที่ได้รับ มิเช่นนั้น ควรตั้งค่าเป็น "unset"

  • clientCertificates

    ClientCertificateInfo[]

    รายการใบรับรองไคลเอ็นต์ที่ใช้ได้ในปัจจุบัน

  • ข้อผิดพลาด

    "GENERAL_ERROR"
     ไม่บังคับ

    ข้อผิดพลาดที่เกิดขึ้นขณะดึงข้อมูลใบรับรอง (หากมี) ระบบจะแสดงข้อผิดพลาดนี้ต่อผู้ใช้ตามความเหมาะสม

SignatureRequest

Chrome 86 ขึ้นไป

พร็อพเพอร์ตี้

  • อัลกอริทึม

    อัลกอริทึม

    อัลกอริทึมลายเซ็นที่จะใช้

  • ใบรับรอง

    ArrayBuffer

    การโค้ด DER ของใบรับรอง X.509 ส่วนขยายต้องลงนามใน input โดยใช้คีย์ส่วนตัวที่เชื่อมโยง

  • อินพุต

    ArrayBuffer

    ข้อมูลที่จะเซ็น โปรดทราบว่าระบบไม่ได้แฮชข้อมูล

  • signRequestId

    ตัวเลข

    ส่งตัวระบุคำขอไปยัง reportSignature

SignRequest

พร็อพเพอร์ตี้

  • ใบรับรอง

    ArrayBuffer

    การโค้ด DER ของใบรับรอง X.509 ส่วนขยายต้องลงนามใน digest โดยใช้คีย์ส่วนตัวที่เชื่อมโยง

  • ไดเจสต์

    ArrayBuffer

    ข้อมูลสรุปที่ต้องลงนาม

  • แฮช

    แฮช

    หมายถึงอัลกอริทึมแฮชที่ใช้สร้าง digest

  • signRequestId

    ตัวเลข

    Chrome 57 ขึ้นไป

    รหัสที่ไม่ซ้ำกันซึ่งส่วนขยายจะใช้ในกรณีที่ต้องเรียกใช้เมธอดที่ต้องใช้รหัส เช่น requestPin

StopPinRequestDetails

Chrome 57 ขึ้นไป

พร็อพเพอร์ตี้

  • errorType

    PinRequestErrorType ไม่บังคับ

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

  • signRequestId

    ตัวเลข

    รหัสที่ Chrome ระบุใน SignRequest

เมธอด

reportSignature()

สัญญา Chrome 86 ขึ้นไป 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

ควรเรียกใช้เพื่อตอบสนองต่อ onSignatureRequested

ในที่สุดส่วนขยายจะต้องเรียกใช้ฟังก์ชันนี้สําหรับเหตุการณ์ onSignatureRequested ทุกรายการ การติดตั้งใช้งาน API จะหยุดรอการเรียกนี้หลังจากผ่านไประยะหนึ่งและตอบสนองด้วยข้อผิดพลาดเกี่ยวกับเวลาหมดอายุเมื่อมีการเรียกใช้ฟังก์ชันนี้

พารามิเตอร์

  • รายละเอียด

    ReportSignatureDetails

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    () => void

การคืนสินค้า

  • Promise<void>

    Chrome 96 ขึ้นไป

    ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

requestPin()

สัญญา Chrome 57 ขึ้นไป 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

ขอ PIN จากผู้ใช้ อนุญาตคำขอที่ดำเนินการอยู่ได้ครั้งละ 1 รายการเท่านั้น ระบบจะปฏิเสธคำขอที่ออกขณะที่ขั้นตอนอื่นกำลังดำเนินอยู่ ส่วนส่วนขยายมีหน้าที่รับผิดชอบในการลองอีกครั้งในภายหลังหากมีการดำเนินการอื่นอยู่

พารามิเตอร์

  • รายละเอียด

    RequestPinDetails

    มีรายละเอียดเกี่ยวกับกล่องโต้ตอบที่ขอ

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    (details?: PinResponseDetails) => void

การคืนสินค้า

  • Promise<PinResponseDetails | undefined>

    Chrome 96 ขึ้นไป

    ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

setCertificates()

สัญญา Chrome 86 ขึ้นไป 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

ตั้งค่ารายการใบรับรองที่จะใช้ในเบราว์เซอร์

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

พารามิเตอร์

  • รายละเอียด

    SetCertificatesDetails

    ใบรับรองที่จะตั้งค่า ระบบจะไม่สนใจใบรับรองที่ไม่ถูกต้อง

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    () => void

การคืนสินค้า

  • Promise<void>

    Chrome 96 ขึ้นไป

    ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

stopPinRequest()

สัญญา Chrome 57 ขึ้นไป 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

หยุดคําขอปักหมุดที่เริ่มโดยฟังก์ชัน requestPin

พารามิเตอร์

  • รายละเอียด

    StopPinRequestDetails

    มีรายละเอียดเกี่ยวกับเหตุผลในการหยุดขั้นตอนการส่งคำขอ

  • Callback

    ฟังก์ชัน ไม่บังคับ

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    () => void

การคืนสินค้า

  • Promise<void>

    Chrome 96 ขึ้นไป

    ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่มี Callback ไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ

กิจกรรม

onCertificatesUpdateRequested

Chrome 86 ขึ้นไป 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

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

พารามิเตอร์

onSignatureRequested

Chrome 86 ขึ้นไป 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

เหตุการณ์นี้จะทริกเกอร์ทุกครั้งที่เบราว์เซอร์ต้องเซ็นชื่อข้อความโดยใช้ใบรับรองที่ส่วนขยายนี้ให้ผ่าน setCertificates

ส่วนขยายต้องลงนามในข้อมูลอินพุตจาก request โดยใช้อัลกอริทึมและคีย์ส่วนตัวที่เหมาะสม และแสดงผลโดยการเรียก reportSignature พร้อม signRequestId ที่ได้รับ

พารามิเตอร์

  • Callback

    ฟังก์ชัน

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    (request: SignatureRequest) => void