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 และ Salt ที่มีขนาดเท่ากับแฮช

"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

    แฮช[]

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

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 ที่ได้รับ ไม่เช่นนั้นก็ควรยกเลิกการตั้งค่า

  • 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,
): Promise<void>

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

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

พารามิเตอร์

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

  • Promise<void>

    Chrome 96 ขึ้นไป

requestPin()

Chrome 57 ขึ้นไป 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

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

พารามิเตอร์

  • รายละเอียด

    RequestPinDetails

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

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

setCertificates()

Chrome 86 ขึ้นไป 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

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

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

พารามิเตอร์

  • รายละเอียด

    SetCertificatesDetails

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

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

  • Promise<void>

    Chrome 96 ขึ้นไป

stopPinRequest()

Chrome 57 ขึ้นไป 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

หยุดคำขอ PIN ที่ฟังก์ชัน requestPin เริ่มต้น

พารามิเตอร์

  • รายละเอียด

    StopPinRequestDetails

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

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

  • Promise<void>

    Chrome 96 ขึ้นไป

กิจกรรม

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