Açıklama
Sertifikaları, TLS kimlik doğrulamalarında kullanabilecekleri platforma göstermek için bu API'yi kullanın.
İzinler
certificateProvider
Kullanılabilirlik
Kavramlar ve kullanım
İstemci sertifikalarını ChromeOS'e sunmak için bu API genellikle aşağıdaki adımları uygular:
- Uzantı,
onCertificatesUpdateRequested
veonSignatureRequested
etkinliklerine kaydedilir. - Uzantı, başlatma işleminden sonra ilk sertifika listesini sağlamak için
setCertificates()
yöntemini çağırır. - Uzantı, kullanılabilir sertifikalar listesindeki değişiklikleri izler ve tarayıcıyı bu tür her değişiklik hakkında bilgilendirmek için
setCertificates()
çağrısı yapar. - TLS el sıkışması sırasında tarayıcı bir istemci sertifikası isteği alır. Bir
onCertificatesUpdateRequested
etkinliğiyle tarayıcı, Uzantı'dan şu anda sağladığı tüm sertifikaları bildirmesini ister. - Uzantı,
setCertificates()
yöntemini kullanarak şu anda kullanılabilir olan sertifikaları raporlar. - Tarayıcı, kullanılabilir tüm sertifikaları uzak ana makineden gelen istemci sertifikası isteğiyle eşleştirir. Eşleşmeler, kullanıcıya bir seçim iletişim kutusunda sunulur.
- Kullanıcı bir sertifika seçerek kimlik doğrulamasını onaylayabilir veya kimlik doğrulamasını iptal edebilir.
![Sertifika seçimi iletişim kutusu](https://developer.chrome.google.cn/static/docs/extensions/reference/api/images/certificate_provider_selection_dialog.png?authuser=5&hl=tr)
- Kullanıcı kimlik doğrulamayı iptal ederse veya istekle eşleşen sertifika yoksa TLS istemcisi kimlik doğrulaması iptal edilir.
- Aksi takdirde, kullanıcı bu Uzantı tarafından sağlanan bir sertifikayla kimlik doğrulamayı onaylarsa tarayıcı, TLS el sıkışmasına devam etmek için Uzantı'dan verileri imzalamasını ister. İstek bir
onSignatureRequested
etkinliği olarak gönderilir. - Bu etkinlik giriş verilerini içerir, imzayı oluşturmak için hangi algoritmanın kullanılması gerektiğini tanımlar ve bu Uzantı tarafından bildirilen sertifikalardan birine başvurur. Uzantı, referans verilen sertifikayla ilişkili özel anahtarı kullanarak, belirtilen veriler için bir imza oluşturmalıdır. İmzanın oluşturulması için bir DigestInfo'nun önceden başlatılması ve gerçek imzadan önce sonucun doldurulması gerekebilir.
- Uzantı,
reportSignature()
yöntemini kullanarak imzayı tarayıcıya geri gönderir. İmza hesaplanamıyorsa yöntem imza olmadan çağrılmalıdır. - İmza sağlandıysa tarayıcı TLS el sıkışmasını tamamlar.
Gerçek adım sırası farklı olabilir. Örneğin, otomatik olarak sertifika seçmeye yönelik kurumsal politika kullanılıyorsa kullanıcıdan sertifika seçmesi istenmez (bkz. AutoSelectCertificateForUrls
ve Kullanıcılar için Chrome politikaları).
Bu, Uzantı'da aşağıdaki snippet'e benzeyebilir:
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);
Türler
Algorithm
Desteklenen kriptografik imza algoritması türleri.
Enum
"RSASSA_PKCS1_v1_5_MD5_SHA1"
MD5-SHA-1 karma oluşturma işlemiyle RSASSA PKCS#1 v1.5 imza algoritmasını belirtir. Uzantı, başa bir DigestInfo öneki eklememeli, yalnızca PKCS#1 dolgusu eklemelidir. Bu algoritma kullanımdan kaldırılmıştır ve 109 sürümünden itibaren Chrome tarafından hiçbir zaman istenmeyecektir.
"RSASSA_PKCS1_v1_5_SHA1"
SHA-1 karma işleviyle RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.
"RSASSA_PKCS1_v1_5_SHA256"
SHA-256 karma oluşturma işleviyle RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.
"RSASSA_PKCS1_v1_5_SHA384"
SHA-384 karma oluşturma işleviyle RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.
"RSASSA_PKCS1_v1_5_SHA512"
SHA-512 karma oluşturma işleviyle RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.
"RSASSA_PSS_SHA256"
SHA-256 karma oluşturma işleviyle RSASSA PSS imza algoritmasını, MGF1 maske oluşturma işlevi ve karma ile aynı boyuttaki takviye değeri belirtir.
"RSASSA_PSS_SHA384"
SHA-384 karma oluşturma işleviyle RSASSA PSS imza algoritmasını, MGF1 maske oluşturma işlevi ve karma ile aynı boyuttaki takviye değeri belirtir.
"RSASSA_PSS_SHA512"
SHA-512 karma oluşturma işleviyle RSASSA PSS imza algoritmasını, MGF1 maske oluşturma işlevi ve karma ile aynı boyuttaki takviye değeri belirtir.
CertificateInfo
Özellikler
-
sertifika
ArrayBuffer
X.509 sertifikasının DER kodlaması olmalıdır. Şu anda yalnızca RSA anahtarlarının sertifikaları desteklenmektedir.
-
supportedHashes
Karma[]
Bu sertifika için desteklenen tüm karmalar olarak ayarlanmalıdır. Bu uzantıdan yalnızca bu karma algoritmalarından biriyle hesaplanan özetlerin imzaları istenir. Bu, karma tercihinin azaltıldığı sırada olmalıdır.
CertificatesUpdateRequest
Özellikler
-
certificatesRequestId
sayı
setCertificates
'e iletilecek istek tanımlayıcısı.
ClientCertificateInfo
Özellikler
-
certificateChain
ArrayBuffer[]
Dizi, ilk öğesi olarak X.509 istemci sertifikasının DER kodlamasını içermelidir.
Bu, tam olarak bir sertifika içermelidir.
-
supportedAlgorithms
Bu sertifika için desteklenen tüm algoritmalar. Uzantıdan yalnızca bu algoritmalardan birini kullanan imzalar istenir.
Error
Uzantının bildirebileceği hata türleri.
Değer
"GENERAL_ERROR"
Hash
Kullanımdan kaldırıldı. Algorithm
ile değiştirildi.
Enum
"MD5_SHA1"
MD5 ve SHA1 karma oluşturma algoritmalarını belirtir.
"SHA1"
SHA1 karma oluşturma algoritmasını belirtir.
"SHA256"
SHA256 karma oluşturma algoritmasını belirtir.
"SHA384"
SHA384 karma oluşturma algoritmasını belirtir.
"SHA512"
SHA512 karma oluşturma algoritmasını belirtir.
PinRequestErrorType
Kullanıcıya requestPin işlevi aracılığıyla sunulabilecek hata türleri.
Enum
"INVALID_PIN"
PIN'in geçersiz olduğunu belirtir.
"INVALID_PUK"
PUK'un geçersiz olduğunu belirtir.
"MAX_ATTEMPTS_EXCEEDED"
Maksimum deneme sayısının aşıldığını belirtir.
"UNKNOWN_ERROR"
Hatanın yukarıdaki türlerle temsil edilemeyeceğini belirtir.
PinRequestType
Uzantı tarafından requestPin işleviyle istenen kodun türü.
Enum
"PIN"
İstenen kodun PIN olduğunu belirtir.
"PUK"
İstenen kodun bir PUK olduğunu belirtir.
PinResponseDetails
Özellikler
-
userInput
string isteğe bağlı
Kullanıcı tarafından sağlanan kod. Kullanıcı iletişim kutusunu kapattıysa veya başka bir hata oluştuysa boştur.
ReportSignatureDetails
Özellikler
-
hata
isteğe bağlı
İmza oluşturulurken oluşan hata (varsa).
-
signRequestId
sayı
onSignatureRequested
etkinliği aracılığıyla alınan istek kimliği. -
signature
ArrayBuffer isteğe bağlı
İmza (başarıyla oluşturulduysa).
RequestPinDetails
Özellikler
-
attemptsLeft
numara isteğe bağlı
Kalan deneme sayısı. Bu açıklama, tüm kullanıcı arayüzlerinin bu bilgileri kullanıcıya sunabilmesi için yapılır. Chrome'un bunu uygulaması beklenmez. PIN isteklerinin sayısı aşıldığında, errorType = MAX_ATTEMPTS_EXCEEDED olan uzantı stopPinRequest tarafından çağrılmalıdır.
-
errorType
PinRequestErrorType isteğe bağlı
Kullanıcıya gösterilen hata şablonu. Bu, önceki istek başarısız olduysa kullanıcıya hatanın nedenini bildirmek için ayarlanmalıdır.
-
requestType
PinRequestType isteğe bağlı
İstenen kodun türü. Varsayılan değer PIN'dir.
-
signRequestId
sayı
Chrome tarafından SignRequest'te verilen kimlik.
SetCertificatesDetails
Özellikler
-
certificatesRequestId
numara isteğe bağlı
onCertificatesUpdateRequested
yanıtı olarak çağrıldığında alınancertificatesRequestId
değerini içermelidir. Aksi takdirde ayarlama yapılmamalıdır. -
clientCertificates
Şu anda kullanılabilen istemci sertifikalarının listesi.
-
hata
isteğe bağlı
Sertifikalar ayıklanırken hata oluştu (varsa). Bu hata, uygun olduğunda kullanıcıya gösterilir.
SignatureRequest
Özellikler
-
algoritma
Kullanılacak imza algoritması.
-
sertifika
ArrayBuffer
Bir X.509 sertifikasının DER kodlaması. Uzantı, ilişkilendirilen özel anahtarı kullanarak
input
öğesini imzalamalıdır. -
giriş
ArrayBuffer
İmzalanacak veri. Verilere karma oluşturma işlemi uygulanmadığını unutmayın.
-
signRequestId
sayı
reportSignature
'e iletilecek istek tanımlayıcısı.
SignRequest
Özellikler
-
sertifika
ArrayBuffer
Bir X.509 sertifikasının DER kodlaması. Uzantı, ilişkilendirilen özel anahtarı kullanarak
digest
öğesini imzalamalıdır. -
özet
ArrayBuffer
İmzalanması gereken özet.
-
hash
digest
oluşturmak için kullanılan karma algoritmasını ifade eder. -
signRequestId
sayı
Chrome 57 ve sonraki sürümlerUzantının bunu gerektiren bir yöntemi (ör. requestPin) çağırması gerektiğinde uzantı tarafından kullanılacak benzersiz kimlik.
StopPinRequestDetails
Özellikler
-
errorType
PinRequestErrorType isteğe bağlı
Hata şablonu. Mevcutsa kullanıcıya gösterilir. Bir hata nedeniyle akışın durdurulma nedenini (ör. MAX_ATTEMPTS_EXCEEDED) içerir.
-
signRequestId
sayı
Chrome tarafından SignRequest'te verilen kimlik.
Yöntemler
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
onSignatureRequested
yanıtı olarak çağrılmalıdır.
Uzantının sonuç olarak her onSignatureRequested
etkinliği için bu işlevi çağırması gerekir. API uygulaması, bir süre sonra bu çağrıyı beklemeyi durdurur ve bu işlev çağrıldığında bir zaman aşımı hatasıyla yanıt verir.
Parametreler
-
ayrıntılar
-
geri çağırma
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:() => void
İlerlemeler
-
Promise<void>
Chrome 96 ve sonraki sürümlerVaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
Kullanıcıdan PIN'i ister. Tek seferde yalnızca bir devam eden isteğe izin verilir. Başka bir akış devam ederken gönderilen istekler reddedilir. Başka bir akış devam ederse daha sonra tekrar denemek uzantının sorumluluğundadır.
Parametreler
-
ayrıntılar
İstenen iletişim kutusuyla ilgili ayrıntıları içerir.
-
geri çağırma
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:(details?: PinResponseDetails) => void
-
ayrıntılar
PinResponseDetails isteğe bağlı
-
İlerlemeler
-
Promise<PinResponseDetails | undefined>
Chrome 96 ve sonraki sürümlerVaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
Tarayıcıda kullanılacak sertifikaların listesini ayarlar.
Uzantı, başlatma işleminden sonra ve şu anda kullanılabilir olan sertifika kümesindeki her değişiklikte bu işlevi çağırmalıdır. Uzantı, bu etkinlik her alındığında onCertificatesUpdateRequested
özelliğine yanıt olarak bu işlevi de çağırmalıdır.
Parametreler
-
ayrıntılar
Ayarlanacak sertifikalar. Geçersiz sertifikalar yoksayılır.
-
geri çağırma
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:() => void
İlerlemeler
-
Promise<void>
Chrome 96 ve sonraki sürümlerVaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
requestPin
işlevi tarafından başlatılan sabitleme isteğini durdurur.
Parametreler
-
ayrıntılar
İstek akışının durdurulma nedeniyle ilgili ayrıntıları içerir.
-
geri çağırma
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:() => void
İlerlemeler
-
Promise<void>
Chrome 96 ve sonraki sürümlerVaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.
Etkinlikler
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
Bunun yerine onCertificatesUpdateRequested
alanını kullanın.
Bu etkinlik, tarayıcı bu uzantı tarafından sağlanan mevcut sertifika listesini her istediğinde tetiklenir. Uzantı, reportCallback
'yi geçerli sertifika listesiyle tam olarak bir kez çağırmalıdır.
Parametreler
-
geri çağırma
işlev
callback
parametresi şu şekilde görünür:(reportCallback: function) => void
-
reportCallback
işlev
reportCallback
parametresi şu şekilde görünür:(certificates: CertificateInfo[], callback: function) => void
-
certificates
-
geri çağırma
işlev
callback
parametresi şu şekilde görünür:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
setCertificates
üzerinden ayarlanan sertifikalar yeterli değilse veya tarayıcı güncel bilgileri isterse bu etkinlik tetiklenir. Uzantı, güncellenen sertifikaların listesi ve alınan certificatesRequestId
ile setCertificates
yöntemini çağırmalıdır.
Parametreler
-
geri çağırma
işlev
callback
parametresi şu şekilde görünür:(request: CertificatesUpdateRequest) => void
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
Bu etkinlik, tarayıcının setCertificates
aracılığıyla bu uzantı tarafından sağlanan bir sertifikayı kullanarak mesajı imzalaması gerektiğinde tetiklenir.
Uzantı, giriş verilerini uygun algoritmayı ve gizli anahtarı kullanarak request
imzalamalı ve alınan signRequestId
ile reportSignature
yöntemini çağırarak döndürmelidir.
Parametreler
-
geri çağırma
işlev
callback
parametresi şu şekilde görünür:(request: SignatureRequest) => void
-
istek
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
Bunun yerine onSignatureRequested
alanını kullanın.
Bu etkinlik, tarayıcının bir onCertificatesRequested
etkinliğine yanıt olarak bu uzantı tarafından sağlanan sertifikayı kullanarak bir mesajı imzalaması gerektiğinde tetiklenir. Uzantının uygun algoritmayı ve özel anahtarı kullanarak request
içindeki verileri imzalaması ve reportCallback
yöntemini çağırarak döndürmesi gerekir. reportCallback
tam olarak bir kez çağrılmalıdır.
Parametreler
-
geri çağırma
işlev
callback
parametresi şu şekilde görünür:(request: SignRequest, reportCallback: function) => void
-
istek
-
reportCallback
işlev
Chrome 47 ve sonraki sürümlerreportCallback
parametresi şu şekilde görünür:(signature?: ArrayBuffer) => void
-
signature
ArrayBuffer isteğe bağlı
-
-