Açıklama
Bu API'yi kullanarak sertifikaları platforma gösterebilirsiniz. Platform, bu sertifikaları TLS kimlik doğrulamaları için kullanabilir.
İzinler
certificateProviderKullanılabilirlik
Kavramlar ve kullanım
İstemci sertifikalarını ChromeOS'e göstermek için bu API'nin tipik kullanımı aşağıdaki adımları içerir:
- Uzantı,
onCertificatesUpdateRequestedveonSignatureRequestedetkinlikleri için kaydolur. - 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 her değişiklik hakkında tarayıcıyı bilgilendirmek için
setCertificates()yöntemini çağırır. - TLS el sıkışması sırasında tarayıcı bir istemci sertifikası isteği alır.
onCertificatesUpdateRequestedetkinliğiyle tarayıcı, uzantıdan o anda sağladığı tüm sertifikaları bildirmesini ister. - Uzantı,
setCertificates()yöntemini kullanarak mevcut sertifikaları bildirir. - Tarayıcı, mevcut 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 iptal edebilir.
- Kullanıcı kimlik doğrulama işlemini iptal ederse veya istekle eşleşen sertifika yoksa TLS istemci 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,
onSignatureRequestedetkinliği olarak gönderilir. - Bu etkinlik, giriş verilerini içerir, imza oluşturmak için hangi algoritmanın kullanılması gerektiğini bildirir ve bu uzantı tarafından bildirilen sertifikalardan birini belirtir. Uzantı, referans verilen sertifikayla ilişkili özel anahtarı kullanarak belirli veriler için bir imza oluşturmalıdır. İmza oluşturmak için asıl imzalamadan önce bir DigestInfo eklenmesi ve sonucun doldurulması gerekebilir.
- Uzantı,
reportSignature()yöntemini kullanarak imzayı tarayıcıya geri gönderir. İmza hesaplanamadıysa 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 (AutoSelectCertificateForUrls ve Kullanıcılar için Chrome politikaları başlıklı makaleleri inceleyin).
Uzantıda bu, aşağıdaki snippet'e benzer şekilde görünebilir:
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() {
browser.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.
browser.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.
browser.certificateProvider.reportSignature({
signRequestId: request.signRequestId,
error: 'GENERAL_ERROR'
});
return;
}
const signature = signUnhashedData(key, request.input, request.algorithm);
browser.certificateProvider.reportSignature({
signRequestId: request.signRequestId,
signature: signature
});
}
browser.certificateProvider.onCertificatesUpdateRequested.addListener(
handleCertificatesUpdateRequest);
browser.certificateProvider.onSignatureRequested.addListener(
handleSignatureRequest);
Türler
Algorithm
Desteklenen şifreleme imzası algoritmalarının türleri.
Enum
"RSASSA_PKCS1_v1_5_MD5_SHA1"
MD5-SHA-1 karma oluşturma ile RSASSA PKCS#1 v1.5 imza algoritmasını belirtir. Uzantı, 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 işleviyle RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.
"RSASSA_PKCS1_v1_5_SHA384"
SHA-384 karma işleviyle RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.
"RSASSA_PKCS1_v1_5_SHA512"
SHA-512 karma işleviyle RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.
"RSASSA_PSS_SHA256"
SHA-256 karma işlevi, MGF1 maske oluşturma işlevi ve karma ile aynı boyuttaki salt ile RSASSA PSS imza algoritmasını belirtir.
"RSASSA_PSS_SHA384"
SHA-384 karma işlevi, MGF1 maske oluşturma işlevi ve karma ile aynı boyutta salt içeren RSASSA PSS imza algoritmasını belirtir.
"RSASSA_PSS_SHA512"
SHA-512 karma işlevi, MGF1 maske oluşturma işlevi ve karma ile aynı boyuttaki salt ile RSASSA PSS imza algoritmasını 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 karma değerlere ayarlanmalıdır. Bu uzantıdan yalnızca bu karma algoritmalarından biriyle hesaplanan özetlerin imzaları istenir. Bu, azalan karma tercihi sırasına göre olmalıdır.
CertificatesUpdateRequest
Özellikler
-
certificatesRequestId
sayı
setCertificates'e iletilecek istek tanımlayıcısı.
ClientCertificateInfo
Özellikler
-
certificateChain
ArrayBuffer[]
Dizinin ilk öğesi, X.509 istemci sertifikasının DER kodlaması olmalıdır.
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 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
requestPin işlevi aracılığıyla kullanıcıya gösterilebilecek 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
requestPin işleviyle uzantı tarafından istenen kodun türü.
Enum
"PIN"
İstenen kodun PIN olduğunu belirtir.
"PUK"
İstenen kodun 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ş bırakılır.
ReportSignatureDetails
Özellikler
-
hata
"GENERAL_ERROR"
isteğe bağlıİmza oluşturulurken meydana gelen hata (varsa).
-
signRequestId
sayı
onSignatureRequestedetkinliği aracılığıyla alınan istek tanımlayıcısı. -
signature
ArrayBuffer isteğe bağlı
Başarıyla oluşturulmuşsa imza.
RequestPinDetails
Özellikler
-
attemptsLeft
number isteğe bağlı
Kalan deneme sayısı. Bu, herhangi bir kullanıcı arayüzünün bu bilgileri kullanıcıya sunabilmesi için sağlanır. Chrome'un bu kısıtlamayı uygulaması beklenmez. Bunun yerine, PIN isteklerinin sayısı aşıldığında uzantı tarafından errorType = MAX_ATTEMPTS_EXCEEDED ile stopPinRequest çağrılmalıdır.
-
errorType
PinRequestErrorType isteğe bağlı
Kullanıcıya gösterilen hata şablonu. Önceki istek başarısız olduysa kullanıcıya başarısızlık nedenini bildirmek için bu değer ayarlanmalıdır.
-
requestType
PinRequestType isteğe bağlı
İstenen kodun türü. Varsayılan değer PIN'dir.
-
signRequestId
sayı
SignRequest'te Chrome tarafından verilen kimlik.
SetCertificatesDetails
Özellikler
-
certificatesRequestId
number isteğe bağlı
onCertificatesUpdateRequestedyanıtı olarak çağrıldığında, alınancertificatesRequestIddeğerini içermelidir. Aksi takdirde ayarlanmamalıdır. -
clientCertificates
Şu anda kullanılabilen istemci sertifikalarının listesi.
-
hata
"GENERAL_ERROR"
isteğe bağlıSertifikalar ayıklanırken oluşan hata (varsa). Bu hata, uygun olduğunda kullanıcıya gösterilir.
SignatureRequest
Özellikler
-
algoritma
Kullanılacak imza algoritması.
-
sertifika
ArrayBuffer
X.509 sertifikasının DER kodlaması. Uzantı, ilişkili özel anahtarı kullanarak
inputöğesini imzalamalıdır. -
giriş
ArrayBuffer
İmzalanacak veriler. Verilere karma oluşturma işlemi uygulanmadığını unutmayın.
-
signRequestId
sayı
reportSignature'e iletilecek istek tanımlayıcısı.
SignRequest
Özellikler
-
sertifika
ArrayBuffer
X.509 sertifikasının DER kodlaması. Uzantı, ilişkili özel anahtarı kullanarak
digestöğesini imzalamalıdır. -
özet
ArrayBuffer
İmzalanması gereken özet.
-
hash
digestoluşturmak için kullanılan karma algoritmasını ifade eder. -
signRequestId
sayı
Chrome 57 ve sonraki sürümler Chrome 148'den itibaren browser.*Uzantının, benzersiz kimlik gerektiren bir yöntemi (ör. requestPin) çağırması gerektiğinde kullanacağı benzersiz kimlik.
StopPinRequestDetails
Özellikler
-
errorType
PinRequestErrorType isteğe bağlı
Hata şablonu. Varsa kullanıcıya gösterilir. Akışın durdurulma nedenini (ör. MAX_ATTEMPTS_EXCEEDED) içerir.
-
signRequestId
sayı
SignRequest'te Chrome tarafından verilen kimlik.
Yöntemler
reportSignature()
browser.certificateProvider.reportSignature(
details: ReportSignatureDetails,
): Promise<void>
onSignatureRequested için yanıt olarak çağrılmalıdır.
Uzantı, her onSignatureRequested etkinliği için bu işlevi çağırmalıdır. API uygulaması, bir süre sonra bu çağrıyı beklemeyi durdurur ve bu işlev çağrıldığında zaman aşımı hatası verir.
Parametreler
-
ayrıntılar
İadeler
-
Promise<void>
Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*
requestPin()
browser.certificateProvider.requestPin(
details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>
Kullanıcıdan PIN ister. Aynı anda yalnızca bir devam eden isteğe izin verilir. Başka bir akış devam ederken gönderilen istekler reddedilir. Devam eden başka bir akış varsa daha sonra tekrar denemek uzantının sorumluluğundadır.
Parametreler
-
ayrıntılar
İstenen iletişim kutusuyla ilgili ayrıntıları içerir.
İadeler
-
Promise<PinResponseDetails | undefined>
Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*Kullanıcı PIN'i girdiğinde çözümlenen bir Promise döndürür. İletişim kutusu isteği başarısız bir şekilde tamamlanırsa (ör. iletişim kutusu kullanıcı tarafından iptal edildiyse veya gösterilmesine izin verilmediyse) hata vererek reddeder.
setCertificates()
browser.certificateProvider.setCertificates(
details: SetCertificatesDetails,
): Promise<void>
Tarayıcıda kullanılacak sertifikaların listesini ayarlar.
Uzantı, başlatma işleminden sonra ve mevcut sertifika grubundaki her değişiklikte bu işlevi çağırmalıdır. Uzantı, bu etkinlik her alındığında onCertificatesUpdateRequested yanıtı olarak da bu işlevi çağırmalıdır.
Parametreler
-
ayrıntılar
Ayarlanacak sertifikalar. Geçersiz sertifikalar yoksayılır.
İadeler
-
Promise<void>
Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*Tamamlandığında çözümlenen bir Promise döndürür.
stopPinRequest()
browser.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
): Promise<void>
requestPin işlevi tarafından başlatılan PIN isteğini durdurur.
Parametreler
-
ayrıntılar
İstek akışının durdurulma nedeni hakkında ayrıntıları içerir.
İadeler
-
Promise<void>
Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*PIN iletişim kutusunu kapatma isteği tamamlandığında çözümlenen bir Promise döndürür.
Etkinlikler
onCertificatesUpdateRequested
browser.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
Bu etkinlik, setCertificates aracılığıyla ayarlanan sertifikalar yetersizse veya tarayıcı güncel bilgi isterse tetiklenir. Uzantı, güncellenmiş sertifika listesi ve alınan certificatesRequestId ile setCertificates yöntemini çağırmalıdır.
Parametreler
-
callback
işlev
callbackparametresi şu şekilde görünür:(request: CertificatesUpdateRequest) => void
onSignatureRequested
browser.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
Bu etkinlik, tarayıcının setCertificates aracılığıyla bu uzantı tarafından sağlanan bir sertifikayı kullanarak bir mesajı imzalaması gerektiğinde tetiklenir.
Uzantı, uygun algoritmayı ve özel anahtarı kullanarak request adresinden gelen giriş verilerini imzalamalı ve alınan signRequestId ile reportSignature işlevini çağırarak döndürmelidir.
Parametreler
-
callback
işlev
callbackparametresi şu şekilde görünür:(request: SignatureRequest) => void
-
istek
-