chrome.certificateProvider

Mô tả

Sử dụng API này để hiển thị các chứng chỉ cho nền tảng, nơi có thể sử dụng các chứng chỉ này để xác thực TLS.

Quyền

certificateProvider

Phạm vi cung cấp

Chrome 46 trở lên Chỉ ChromeOS

Khái niệm và cách sử dụng

Thông thường, cách sử dụng API này để hiển thị chứng chỉ máy khách cho ChromeOS tuân theo các bước sau:

  • Tiện ích này sẽ đăng ký các sự kiện onCertificatesUpdateRequested và onSignatureRequested.
  • Tiện ích này sẽ gọi setCertificates() để cung cấp danh sách chứng chỉ ban đầu sau khi khởi chạy.
  • Tiện ích này sẽ theo dõi các thay đổi trong danh sách chứng chỉ hiện có và gọi setCertificates() để thông báo cho trình duyệt về mọi thay đổi đó.
  • Trong quá trình bắt tay TLS, trình duyệt sẽ nhận được một yêu cầu chứng chỉ máy khách. Với sự kiện onCertificatesUpdateRequested, trình duyệt sẽ yêu cầu Tiện ích báo cáo mọi chứng chỉ mà trình duyệt hiện cung cấp.
  • Tiện ích này sẽ báo cáo lại các chứng chỉ hiện có bằng phương thức setCertificates().
  • Trình duyệt sẽ so khớp tất cả chứng chỉ hiện có với yêu cầu chứng chỉ máy khách từ máy chủ lưu trữ từ xa. Kết quả trùng khớp sẽ hiển thị cho người dùng trong hộp thoại lựa chọn.
  • Người dùng có thể chọn chứng chỉ và do đó phê duyệt việc xác thực hoặc huỷ việc xác thực.
Hộp thoại chọn chứng chỉ
Hộp thoại lựa chọn chứng chỉ.
  • Nếu người dùng huỷ quá trình xác thực hoặc không có chứng chỉ nào phù hợp với yêu cầu, thì quá trình xác thực ứng dụng TLS sẽ bị huỷ.
  • Ngược lại, nếu người dùng phê duyệt yêu cầu xác thực bằng chứng chỉ do Tiện ích này cung cấp, thì trình duyệt sẽ yêu cầu Tiện ích ký dữ liệu để tiếp tục cơ chế bắt tay TLS. Yêu cầu được gửi dưới dạng sự kiện onSignatureRequested.
  • Sự kiện này chứa dữ liệu đầu vào, khai báo thuật toán nào phải được dùng để tạo chữ ký và tham chiếu đến một trong các chứng chỉ mà Tiện ích này báo cáo. Tiện ích này phải tạo chữ ký cho dữ liệu đã cho bằng cách sử dụng khoá riêng tư được liên kết với chứng chỉ được tham chiếu. Việc tạo chữ ký có thể yêu cầu phải thêm một DigestInfo và đệm kết quả trước khi ký thực tế.
  • Tiện ích này sẽ gửi lại chữ ký cho trình duyệt bằng phương thức reportSignature(). Nếu không thể tính chữ ký, thì phương thức phải được gọi mà không có chữ ký.
  • Nếu chữ ký đã được cung cấp, trình duyệt sẽ hoàn tất quá trình bắt tay TLS.

Trình tự các bước thực tế có thể khác. Ví dụ: người dùng sẽ không được yêu cầu chọn chứng chỉ nếu đang sử dụng chính sách doanh nghiệp để tự động chọn một chứng chỉ (xem AutoSelectCertificateForUrls và Chính sách của Chrome dành cho người dùng).

Trong Tiện ích, đoạn mã này có thể tương tự như đoạn mã sau:

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);

Loại

Algorithm

Chrome 86 trở lên

Các loại thuật toán chữ ký mật mã được hỗ trợ.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Chỉ định thuật toán chữ ký RSASSA PKCS#1 v1.5 bằng hàm băm MD5-SHA-1. Tiện ích này không được thêm tiền tố DigestInfo mà chỉ được thêm khoảng đệm PKCS#1. Thuật toán này không còn được dùng nữa và sẽ không bao giờ được Chrome yêu cầu kể từ phiên bản 109.

"RSASSA_PKCS1_v1_5_SHA1"
Chỉ định thuật toán chữ ký RSASSA PKCS#1 v1.5 bằng hàm băm SHA-1.

"RSASSA_PKCS1_v1_5_SHA256"
Chỉ định thuật toán chữ ký RSASSA PKCS#1 v1.5 bằng hàm băm SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
Chỉ định thuật toán chữ ký RSASSA PKCS#1 v1.5 bằng hàm băm SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
Chỉ định thuật toán chữ ký RSASSA PKCS#1 v1.5 bằng hàm băm SHA-512.

"RSASSA_PSS_SHA256"
Chỉ định thuật toán chữ ký RSASSA PSS với hàm băm SHA-256, hàm tạo mặt nạ MGF1 và dữ liệu ngẫu nhiên có cùng kích thước với hàm băm.

"RSASSA_PSS_SHA384"
Chỉ định thuật toán chữ ký RSASSA PSS có hàm băm SHA-384, hàm tạo mặt nạ MGF1 và dữ liệu ngẫu nhiên có cùng kích thước với hàm băm.

"RSASSA_PSS_SHA512"
Chỉ định thuật toán chữ ký RSASSA PSS có hàm băm SHA-512, hàm tạo mặt nạ MGF1 và dữ liệu ngẫu nhiên có cùng kích thước với hàm băm.

CertificateInfo

Thuộc tính

  • chứng nhận

    ArrayBuffer

    Phải là định dạng mã hoá DER của chứng chỉ X.509. Hiện tại, chỉ có chứng chỉ của khoá RSA được hỗ trợ.

  • supportedHashes

    Hàm băm[]

    Bạn phải đặt thành tất cả hàm băm được hỗ trợ cho chứng chỉ này. Tiện ích này sẽ chỉ được yêu cầu cung cấp chữ ký của các chuỗi đại diện được tính toán bằng một trong các thuật toán băm này. Việc này phải được sắp xếp theo thứ tự giảm dần lựa chọn ưu tiên về hàm băm.

CertificatesUpdateRequest

Chrome 86 trở lên

Thuộc tính

  • certificatesRequestId

    số

    Giá trị nhận dạng yêu cầu cần được truyền đến setCertificates.

ClientCertificateInfo

Chrome 86 trở lên

Thuộc tính

  • certificateChain

    ArrayBuffer[]

    Mảng phải chứa mã hoá DER của chứng chỉ máy khách X.509 dưới dạng phần tử đầu tiên.

    Mã này phải bao gồm chính xác một chứng chỉ.

  • supportedAlgorithms

    Thuật toán[]

    Tất cả thuật toán được hỗ trợ cho chứng chỉ này. Tiện ích này sẽ chỉ được yêu cầu cung cấp chữ ký bằng một trong các thuật toán này.

Error

Chrome 86 trở lên

Các loại lỗi mà tiện ích có thể báo cáo.

Giá trị

"General_ERROR"

Hash

Không dùng nữa. Được thay thế bằng Algorithm.

Enum

"MD5_SHA1"
Chỉ định thuật toán băm MD5 và SHA1.

"SHA1"
Chỉ định thuật toán băm SHA1.

"SHA256"
Chỉ định thuật toán băm SHA256.

"SHA384"
Chỉ định thuật toán băm SHA384.

"SHA512"
Chỉ định thuật toán băm SHA512.

PinRequestErrorType

Chrome 57 trở lên

Các loại lỗi có thể hiển thị cho người dùng thông qua hàm requestPin.

Enum

"INVALID_PIN"
Chỉ định mã PIN không hợp lệ.

"INVALID_PUK"
Chỉ định mã PUK là không hợp lệ.

"MAX_Errors_EXCEEDED"
Chỉ định số lần thử tối đa đã bị vượt quá.

"UNKNOWN_ERROR"
Chỉ định rằng các loại trên không thể biểu thị lỗi.

PinRequestType

Chrome 57 trở lên

Loại mã mà tiện ích yêu cầu có hàm requestPin.

Enum

"Mã PIN"
Chỉ định mã được yêu cầu là mã PIN.

"PUK"
Chỉ định mã được yêu cầu là mã PUK.

PinResponseDetails

Chrome 57 trở lên

Thuộc tính

  • userInput

    chuỗi không bắt buộc

    Mã do người dùng cung cấp. Trống nếu người dùng đóng hộp thoại hoặc xảy ra một số lỗi khác.

ReportSignatureDetails

Chrome 86 trở lên

Thuộc tính

  • error

    "General_ERROR"
     không bắt buộc

    Đã xảy ra lỗi khi tạo chữ ký (nếu có).

  • signRequestId

    số

    Giá trị nhận dạng yêu cầu đã nhận được thông qua sự kiện onSignatureRequested.

  • Chữ ký

    ArrayBuffer không bắt buộc

    Chữ ký, nếu được tạo thành công.

RequestPinDetails

Chrome 57 trở lên

Thuộc tính

  • attemptsLeft

    số không bắt buộc

    Số lần thử còn lại. Mã này được cung cấp để bất kỳ giao diện người dùng nào cũng có thể hiển thị thông tin này cho người dùng. Chrome dự kiến sẽ không thực thi việc này, thay vào đó, stopPinRequest sẽ được gọi bằng tiện ích có errorType = MAX_Errors_EXCEEDED khi vượt quá số lượng yêu cầu ghim.

  • errorType

    PinRequestErrorType optional

    Mẫu lỗi hiển thị cho người dùng. Bạn nên đặt thuộc tính này nếu yêu cầu trước đó không thành công để thông báo cho người dùng về lý do không thực hiện được.

  • requestType

    PinRequestType không bắt buộc

    Loại mã được yêu cầu. Mặc định là mã PIN.

  • signRequestId

    số

    Mã nhận dạng do Chrome cung cấp trong signRequest.

SetCertificatesDetails

Chrome 86 trở lên

Thuộc tính

  • certificatesRequestId

    số không bắt buộc

    Khi được gọi để phản hồi onCertificatesUpdateRequested, phải chứa giá trị certificatesRequestId đã nhận. Nếu không thì bạn không nên đặt.

  • clientCertificates

    ClientCertificateInfo[]

    Danh sách các chứng chỉ ứng dụng hiện có.

  • error

    "General_ERROR"
     không bắt buộc

    Đã xảy ra lỗi khi trích xuất chứng chỉ, nếu có. Lỗi này sẽ hiển thị cho người dùng khi thích hợp.

SignatureRequest

Chrome 86 trở lên

Thuộc tính

  • thuật toán

    Thuật toán

    Thuật toán chữ ký sẽ được sử dụng.

  • chứng nhận

    ArrayBuffer

    Mã hoá DER của chứng chỉ X.509. Tiện ích phải ký input bằng khoá riêng tư liên kết.

  • input

    ArrayBuffer

    Dữ liệu cần ký. Xin lưu ý rằng dữ liệu này không được băm.

  • signRequestId

    số

    Giá trị nhận dạng yêu cầu cần được truyền đến reportSignature.

SignRequest

Thuộc tính

  • chứng nhận

    ArrayBuffer

    Mã hoá DER của chứng chỉ X.509. Tiện ích phải ký digest bằng khoá riêng tư liên kết.

  • chuỗi đại diện

    ArrayBuffer

    Thông báo này phải được ký.

  • hàm băm

    Hàm băm

    Đề cập đến thuật toán băm dùng để tạo digest.

  • signRequestId

    số

    Chrome 57 trở lên

    Mã nhận dạng duy nhất mà tiện ích sử dụng nếu cần gọi một phương thức yêu cầu mã đó, ví dụ: requestPin.

StopPinRequestDetails

Chrome 57 trở lên

Thuộc tính

  • errorType

    PinRequestErrorType optional

    Mẫu lỗi. Nếu có, thông tin này sẽ hiển thị cho người dùng. Nhằm đưa ra lý do dừng luồng nếu xảy ra lỗi, ví dụ: MAX_Permission_EXCEEDED.

  • signRequestId

    số

    Mã nhận dạng do Chrome cung cấp trong signRequest.

Phương thức

reportSignature()

Lời hứa Chrome 86 trở lên 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

Phải được gọi để phản hồi onSignatureRequested.

Cuối cùng, tiện ích phải gọi hàm này cho mọi sự kiện onSignatureRequested; việc triển khai API sẽ ngừng chờ lệnh gọi này sau một khoảng thời gian và phản hồi bằng lỗi hết thời gian chờ khi hàm này được gọi.

Tham số

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 96 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

requestPin()

Lời hứa Chrome 57 trở lên 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

Yêu cầu người dùng gửi mã PIN. Mỗi lần, bạn chỉ được phép gửi một yêu cầu liên tục. Các yêu cầu được đưa ra trong khi đang diễn ra một quy trình khác sẽ bị từ chối. Tiện ích có trách nhiệm thử lại sau nếu một quy trình khác đang diễn ra.

Tham số

  • chi tiết

    RequestPinDetails

    Chứa thông tin chi tiết về hộp thoại được yêu cầu.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (details?: PinResponseDetails) => void

Giá trị trả về

  • Promise&lt;PinResponseDetails | không xác định>

    Chrome 96 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

setCertificates()

Lời hứa Chrome 86 trở lên 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

Đặt một danh sách chứng chỉ để sử dụng trong trình duyệt.

Tiện ích sẽ gọi hàm này sau khi khởi chạy và trên mọi thay đổi trong tập hợp chứng chỉ hiện có. Tiện ích cũng sẽ gọi hàm này để phản hồi onCertificatesUpdateRequested mỗi khi nhận được sự kiện này.

Tham số

  • Các chứng chỉ cần đặt. Các chứng chỉ không hợp lệ sẽ bị bỏ qua.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 96 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

stopPinRequest()

Lời hứa Chrome 57 trở lên 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Dừng yêu cầu ghim do hàm requestPin bắt đầu.

Tham số

  • Chứa thông tin chi tiết về lý do dừng luồng yêu cầu.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 96 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

Sự kiện

onCertificatesRequested

Chrome 47 trở lên &amp;leq; MV2 Không dùng nữa kể từ Chrome 86
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Thay vào đó, hãy sử dụng onCertificatesUpdateRequested.

Sự kiện này sẽ kích hoạt mỗi khi trình duyệt yêu cầu danh sách chứng chỉ hiện tại do tiện ích này cung cấp. Tiện ích này phải gọi reportCallback chính xác một lần với danh sách chứng chỉ hiện tại.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (reportCallback: function) => void

    • reportCallback

      hàm

      Tham số reportCallback sẽ có dạng như sau: 

      (certificates: CertificateInfo[], callback: function) => void

      • chứng chỉ

        CertificateInfo[]

      • số gọi lại

        hàm

        Tham số callback sẽ có dạng như sau: 

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 trở lên 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Sự kiện này sẽ kích hoạt nếu các chứng chỉ được đặt qua setCertificates không đủ hoặc trình duyệt yêu cầu thông tin cập nhật. Tiện ích này phải gọi hàm setCertificates với danh sách chứng chỉ đã cập nhật và certificatesRequestId đã nhận.

Tham số

onSignatureRequested

Chrome 86 trở lên 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Sự kiện này sẽ kích hoạt mỗi khi trình duyệt cần ký thư bằng cách sử dụng chứng chỉ do tiện ích này cung cấp qua setCertificates.

Tiện ích này phải ký dữ liệu đầu vào từ request bằng thuật toán và khoá riêng tư thích hợp, rồi trả về dữ liệu đó bằng cách gọi reportSignature với signRequestId đã nhận.

Tham số

onSignDigestRequested

&amp;leq; MV2 Không dùng nữa kể từ Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Thay vào đó, hãy sử dụng onSignatureRequested.

Sự kiện này sẽ kích hoạt mỗi khi trình duyệt cần ký thư bằng cách sử dụng chứng chỉ do tiện ích này cung cấp để trả lời một sự kiện onCertificatesRequested. Tiện ích phải ký dữ liệu trong request bằng thuật toán và khoá riêng tư thích hợp, đồng thời trả về dữ liệu đó bằng cách gọi reportCallback. reportCallback phải được gọi chính xác một lần.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (request: SignRequest, reportCallback: function) => void

    • request

      SignRequest

    • reportCallback

      hàm

      Chrome 47 trở lên

      Tham số reportCallback sẽ có dạng như sau: 

      (signature?: ArrayBuffer) => void

      • Chữ ký

        ArrayBuffer không bắt buộc