chrome.certificateProvider

Açıklama

Sertifikaları, TLS kimlik doğrulamalarında kullanabilecekleri platforma göstermek için bu API'yi kullanın.

İzinler

certificateProvider

Kullanılabilirlik

Yalnızca Chrome 46 ve üstü ChromeOS

Kavramlar ve kullanım

İstemci sertifikalarını ChromeOS'e sunmak için bu API genellikle aşağıdaki adımları uygular:

  • Uzantı, onCertificatesUpdateRequested ve onSignatureRequested 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
Sertifika seçimi iletişim kutusu.
  • 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

Chrome 86 ve sonraki sürümler

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

Chrome 86 ve sonraki sürümler

Özellikler

  • certificatesRequestId

    sayı

    setCertificates'e iletilecek istek tanımlayıcısı.

ClientCertificateInfo

Chrome 86 ve sonraki sürümler

Ö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

    Algoritma[]

    Bu sertifika için desteklenen tüm algoritmalar. Uzantıdan yalnızca bu algoritmalardan birini kullanan imzalar istenir.

Error

Chrome 86 ve sonraki sürümler

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

Chrome 57 ve sonraki sürümler

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

Chrome 57 ve sonraki sürümler

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

Chrome 57 ve sonraki sürümler

Ö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

Chrome 86 ve sonraki sürümler

Ö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

Chrome 57 ve sonraki sürümler

Ö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

Chrome 86 ve sonraki sürümler

Özellikler

  • certificatesRequestId

    numara isteğe bağlı

    onCertificatesUpdateRequested yanıtı olarak çağrıldığında alınan certificatesRequestId değerini içermelidir. Aksi takdirde ayarlama yapılmamalıdır.

  • clientCertificates

    ClientCertificateInfo[]

    Ş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

Chrome 86 ve sonraki sürümler

Özellikler

  • algoritma

    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.

  • digest oluşturmak için kullanılan karma algoritmasını ifade eder.

  • signRequestId

    sayı

    Chrome 57 ve sonraki sürümler

    Uzantının bunu gerektiren bir yöntemi (ör. requestPin) çağırması gerektiğinde uzantı tarafından kullanılacak benzersiz kimlik.

StopPinRequestDetails

Chrome 57 ve sonraki sürümler

Ö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()

Söz Chrome 86 ve üstü sürümler 
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

    ReportSignatureDetails

  • 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ümler

    Vaatler, 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()

Söz Chrome 57 ve sonraki sürümler 
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

    RequestPinDetails

    İ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

İlerlemeler

  • Söz<PinResponseDetails|undefined>

    Chrome 96 ve sonraki sürümler

    Vaatler, 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()

Söz Chrome 86 ve üstü sürümler 
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

    SetCertificatesDetails

    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ümler

    Vaatler, 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()

Söz Chrome 57 ve sonraki sürümler 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

requestPin işlevi tarafından başlatılan sabitleme isteğini durdurur.

Parametreler

  • ayrıntılar

    StopPinRequestDetails

    İ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ümler

    Vaatler, 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 47 ve sonraki sürümler &leq; MV2 Chrome 86'dan itibaren kullanımdan kaldırıldı
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

        CertificateInfo[]

      • geri çağırma

        işlev

        callback parametresi şu şekilde görünür: 

        (rejectedCertificates: ArrayBuffer[])=>void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 ve sonraki sürümler 
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

onSignatureRequested

Chrome 86 ve sonraki sürümler 
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

onSignDigestRequested

&leq; MV2 Chrome 86'dan itibaren kullanımdan kaldırıldı
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

      SignRequest

    • reportCallback

      işlev

      Chrome 47 ve sonraki sürümler

      reportCallback parametresi şu şekilde görünür: 

      (signature?: ArrayBuffer)=>void

      • signature

        ArrayBuffer isteğe bağlı