Nội dung mô tả
Hãy sử dụng API này để hiển thị các chứng chỉ cho nền tảng có thể sử dụng các chứng chỉ này cho việc xác thực TLS.
Quyền
certificateProvider
Phạm vi cung cấp
Khái niệm và cách sử dụng
Cách sử dụng API này thông thường để hiển thị chứng chỉ ứng dụng cho ChromeOS theo các bước sau:
- Tiện ích này sẽ đăng ký cho các sự kiện
onCertificatesUpdateRequested
vàonSignatureRequested
. - Tiện ích này 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 theo dõi các thay đổi trong danh sách các chứng chỉ hiện có và lệnh 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ỉ ứng dụng. Thông qua sự kiện
onCertificatesUpdateRequested
, trình duyệt sẽ yêu cầu Tiện ích báo cáo tất cả chứng chỉ mà trình duyệt hiện đang cung cấp. - Tiện ích này báo cáo lại bằng các chứng chỉ hiện có bằng phương thức
setCertificates()
. - Trình duyệt 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ủ 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 một chứng chỉ và do đó phê duyệt việc xác thực hoặc huỷ quá trình xác thực.
- Nếu người dùng huỷ quá trình xác thực hoặc không có chứng chỉ nào khớ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 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 quá trình 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 dùng để tạo chữ ký và đề cập đến một trong các chứng chỉ mà Tiện ích này báo cáo. Tiện ích phải tạo chữ ký cho dữ liệu đã cung cấp bằng cách sử dụng khoá riêng tư 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 đặt trước một DigestInfo và đệm kết quả trước khi ký thực tế.
- Tiện ích này 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 được chữ ký, phương thức này phải được gọi mà không có chữ ký. - Nếu chữ ký được cung cấp thì 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 đã sử dụng chính sách doanh nghiệp tự động chọn 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
Các loại thuật toán chữ ký mã hoá được hỗ trợ.
Liệt kê
"RSASSA_PKCS1_v1_5_MD5_SHA1"
Chỉ định thuật toán chữ ký RSASSA PKCS#1 phiên bản 1.5 bằng hàm băm MD5-SHA-1. Tiện ích này không được thêm vào trước tiền tố DigestInfo mà chỉ được thêm khoảng đệm PKCS#1. Thuật toán này không đượ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 phiên bản 1.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 phiên bản 1.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 phiên bản 1.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 phiên bản 1.5 bằng hàm băm SHA-512.
"RSASSA_PSS_SHA256"
Chỉ định thuật toán chữ ký RSASSA PSS bằng 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 bằng 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 bằng 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à mã hóa DER của chứng chỉ X.509. Hiện tại, chúng tôi chỉ hỗ trợ chứng chỉ của khoá RSA.
-
supportedHashes
Hàm băm[]
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 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. Thao tác này phải theo thứ tự giảm dần lựa chọn ưu tiên về hàm băm.
CertificatesUpdateRequest
Thuộc tính
-
certificatesRequestId
number
Cần truyền giá trị nhận dạng yêu cầu đến
setCertificates
.
ClientCertificateInfo
Thuộc tính
-
certificateChain
ArrayBuffer[]
Mảng này phải chứa phần tử mã hoá DER của chứng chỉ ứng dụng khách X.509 làm phần tử đầu tiên.
Số này phải bao gồm đúng một chứng chỉ.
-
supportedAlgorithms
Tất cả thuật toán được hỗ trợ cho chứng chỉ này. Tiện ích sẽ chỉ được yêu cầu chữ ký bằng một trong những thuật toán này.
Error
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. Thay thế bằng Algorithm
.
Liệt kê
"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
Các loại lỗi có thể hiển thị cho người dùng thông qua hàm requestPin.
Liệt kê
"INVALID_PIN"
Chỉ định mã PIN không hợp lệ.
"INVALID_PUK"
Chỉ định mã PUK không hợp lệ.
"MAX_ATTEMPTS_EXCEEDED"
Chỉ định số lần thử tối đa đã vượt quá.
"UNKNOWN_ERROR"
Chỉ định rằng không thể biểu thị lỗi bằng các loại trên.
PinRequestType
Loại mã mà tiện ích có yêu cầu bằng hàm requestPin.
Liệt kê
"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
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
Thuộc tính
-
error
không bắt buộc
Lỗi đã xảy ra khi tạo chữ ký, nếu có.
-
signRequestId
number
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
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 để mọi giao diện người dùng đều có thể hiển thị thông tin này cho người dùng. Theo dự kiến, Chrome sẽ không thực thi việc này. Thay vào đó, tiện ích có errorType = MAX__EXCEEDED sẽ gọi StopPinRequest khi vượt quá số lượng yêu cầu mã PIN.
-
errorType
PinRequestErrorType không bắt buộc
Mẫu lỗi mà người dùng nhìn thấy. Bạn phải thiết lập thuộc tính này nếu yêu cầu trước đó không thực hiện được, để 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
number
Mã do Chrome cung cấp trong signRequest.
SetCertificatesDetails
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 được. Nếu không, bạn không nên đặt chính sách này. -
clientCertificates
Danh sách các chứng chỉ máy khách hiện có.
-
error
không bắt buộc
Đã xảy ra lỗi khi trích xuất các 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
Thuộc tính
-
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ư được liên kết. -
input
ArrayBuffer
Dữ liệu cần ký. Xin lưu ý rằng dữ liệu này chưa được băm.
-
signRequestId
number
Cần truyền giá trị nhận dạng yêu cầu đế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ư được liên kết. -
chuỗi đại diện
ArrayBuffer
Thông báo phải được ký.
-
hàm băm
Tham chiếu đến thuật toán băm được dùng để tạo
digest
. -
signRequestId
number
Chrome 57 trở lênMã nhận dạng duy nhất mà tiện ích sử dụng khi cần gọi một phương thức yêu cầu, chẳng hạn như requestPin.
StopPinRequestDetails
Thuộc tính
-
errorType
PinRequestErrorType không bắt buộc
Mẫu lỗi. Nếu có, người dùng sẽ thấy tên này. Dành cho mục đích chứa lý do dừng luồng nếu quy trình này là do lỗi gây ra, ví dụ: MAX_ đào_EXCEEDED.
-
signRequestId
number
Mã do Chrome cung cấp trong signRequest.
Phương thức
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
Sẽ được gọi dưới dạng phản hồi cho onSignatureRequested
.
Cuối cùng, tiện ích phải gọi hàm này cho mọi sự kiện onSignatureRequested
; quá trình 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 kèm theo lỗi hết thời gian chờ khi hàm này được gọi.
Tham số
-
chi tiết
-
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ề
-
Promise<void>
Chrome 96 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
Yêu cầu người dùng gửi mã PIN. Chỉ cho phép một yêu cầu đang diễn ra tại một thời điểm. Các yêu cầu đã được đưa ra trong khi một quy trình khác đang diễn ra 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
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
-
chi tiết
PinResponseDetails không bắt buộc
-
Giá trị trả về
-
Promise<PinResponseDetails | undefined>
Chrome 96 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
Đặt danh sách các 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 các chứng chỉ hiện có. Tiện ích cũng phải gọi hàm này để phản hồi onCertificatesUpdateRequested
mỗi khi nhận được sự kiện này.
Tham số
-
chi tiết
Các chứng chỉ cần đặt. 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ề
-
Promise<void>
Chrome 96 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
Dừng yêu cầu ghim do hàm requestPin
bắt đầu.
Tham số
-
chi tiết
Chứa thông tin chi tiết về lý do dừng quy trình 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ề
-
Promise<void>
Chrome 96 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
Sự kiện
onCertificatesRequested
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 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ỉ
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
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 đầy đủ hoặc trình duyệt yêu cầu cập nhật thông tin. Tiện ích phải gọi setCertificates
kèm theo danh sách chứng chỉ đã cập nhật và certificatesRequestId
đã nhận.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(request: CertificatesUpdateRequest) => void
-
request
-
onSignatureRequested
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 chứng chỉ do tiện ích này cung cấp qua setCertificates
.
Tiện ích 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, sau đó trả về dữ liệu đó bằng cách gọi reportSignature
với signRequestId
đã nhận.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(request: SignatureRequest) => void
-
request
-
onSignDigestRequested
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 chứng chỉ mà tiện ích này cung cấp để trả lời 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, rồ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
-
reportCallback
hàm
Chrome 47 trở lênTham số
reportCallback
sẽ có dạng như sau:(signature?: ArrayBuffer) => void
-
Chữ ký
ArrayBuffer không bắt buộc
-
-