chrome.certificateProvider

Açıklama

Sertifikaları, TLS kimlik doğrulamaları için bu sertifikaları kullanabilen platformda kullanıma sunmak için bu API'yi kullanın.

İzinler

certificateProvider

Kullanılabilirlik

Chrome 46 ve sonraki sürümler Yalnızca ChromeOS

Kullanım

Bu API, istemci sertifikalarını ChromeOS'e göstermek için genellikle aşağıdaki adımları izler:

  • Uzantı, onCertificatesUpdateRequested ve onSignatureRequested etkinliklerine katılır.
  • Uzantı, başlatma işleminden sonra sertifikaların ilk listesini sağlamak için setCertificates komutunu çağırır.
  • Uzantı, kullanılabilir sertifikalar listesindeki değişiklikleri izler ve tarayıcıya bu tür her değişikliği bildirmek için setCertificates komutunu çağırır.
  • 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 halihazırda sağladığı tüm sertifikaları raporlamasını ister.
  • Uzantı, setCertificates yöntemini kullanarak o anda kullanılabilir olan 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 seçim iletişim kutusunda sunulur.
  • Kullanıcı bir sertifika seçebilir ve kimlik doğrulamasını onaylayabilir veya kimlik doğrulamasını iptal edebilir.

Sertifika seçimi iletişim kutusu

  • Kullanıcı kimlik doğrulamayı iptal ederse veya istekle eşleşen sertifika yoksa TLS istemci kimlik doğrulaması iptal edilir.
  • Aksi takdirde, kullanıcı kimlik doğrulamasını bu Uzantı tarafından sağlanan bir sertifikayla onaylarsa tarayıcı, Uzantı'dan TLS el sıkışmasına devam etmek için verileri imzalamasını ister. İstek, onSignatureRequested etkinliği olarak gönderilir.
  • Bu etkinlik giriş verilerini içerir, imzayı oluşturmak için hangi algoritmanın kullanılması gerektiğini bildirir ve bu uzantı tarafından bildirilen sertifikalardan birine başvuruda bulunur. Uzantı, başvurulan sertifikayla ilişkili özel anahtarı kullanarak belirtilen veriler için bir imza oluşturmalıdır. İmza oluşturmak için gerçek imzalamadan önce bir DigestInfo'nun başına geçilmesi ve sonucun doldurulması gerekebilir.
  • Uzantı, reportSignature yöntemini kullanarak imzayı tarayıcıya geri gönderir. İmza hesaplanamadıysa yöntemin imza olmadan çağrılması gerekir.
  • İmza sağlandıysa tarayıcı TLS el sıkışmasını tamamlar.

Adımların gerçek sırası farklı olabilir. Örneğin, sertifikayı otomatik olarak seçen kurumsal politika kullanılıyorsa kullanıcıdan sertifika seçmesi istenmez (AutoSelectCertificateForUrls ve Kullanıcılar için Chrome politikaları başlıklı makaleye bakın).

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() {
  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 'nı inceleyin.

Desteklenen şifreli imza algoritmalarının türleri.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
MD5-SHA-1 karma oluşturma işlemi uygulanmış RSASSA PKCS#1 v1.5 imza algoritmasını belirtir. Uzantı, DigestInfo önekini başa eklememeli ancak yalnızca PKCS#1 dolgusunu 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şlevine sahip RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.

"RSASSA_PKCS1_v1_5_SHA256"
SHA-256 karma oluşturma işlevine sahip RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.

"RSASSA_PKCS1_v1_5_SHA384"
SHA-384 karma oluşturma işlevine sahip RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.

"RSASSA_PKCS1_v1_5_SHA512"
SHA-512 karma oluşturma işlevine sahip RSASSA PKCS#1 v1.5 imza algoritmasını belirtir.

"RSASSA_PSS_SHA256"
SHA-256 karma oluşturma işlevi, MGF1 maske oluşturma işlevi ve karma ile aynı boyutun takviye değeri içeren RSASSA PSS imza algoritmasını belirtir.

"RSASSA_PSS_SHA384"
SHA-384 karma oluşturma işlevi, MGF1 maske oluşturma işlevi ve karma ile aynı boyutun takviye değeri içeren RSASSA PSS imza algoritmasını belirtir.

"RSASSA_PSS_SHA512"
SHA-512 karma oluşturma işlevi, MGF1 maske oluşturma işlevi ve karma ile aynı boyutun takviye değeri içeren RSASSA PSS imza algoritmasını belirtir.

CertificateInfo

Özellikler

  • sertifika

    DiziArabelleği

    Bir 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 karmalara ayarlanmalıdır. Bu uzantıdan yalnızca bu karma algoritmalarından biriyle hesaplanan özet imzaları istenir. Bu, karma tercihini azaltacak şekilde olmalıdır.

CertificatesUpdateRequest

Chrome 86 ve sonraki sürümler 'nı inceleyin.

Özellikler

  • certificatesRequestId

    sayı

    Tanımlayıcının setCertificates öğesine iletilmesini isteyin.

ClientCertificateInfo

Chrome 86 ve sonraki sürümler 'nı inceleyin.

Ö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[]

    Tüm algoritmalar bu sertifika için desteklenir. Uzantıdan yalnızca bu algoritmalardan birini kullanan imzalar istenir.

Error

Chrome 86 ve sonraki sürümler 'nı inceleyin.

Uzantının bildirebileceği hata türleri.

Değer

"GENERAL_ERROR"

Hash

Kullanımdan kaldırıldı. Algorithm ile değiştirilecek.

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 'nı inceleyin.

requestPin işlevi aracılığıyla kullanıcıya 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 'nı inceleyin.

requestPin işlevine sahip uzantı tarafından istenen kodun türü.

Enum

"PIN"
İstenen kodun bir PIN olduğunu belirtir.

"PUK"
İstenen kodun bir PUK olduğunu belirtir.

PinResponseDetails

Chrome 57 ve sonraki sürümler 'nı inceleyin.

Özellikler

  • userInput

    dize 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 'nı inceleyin.

Özellikler

  • hata

    "GENERAL_ERROR"
     isteğe bağlı

    Varsa imza oluşturulurken hata oluştu.

  • signRequestId

    sayı

    onSignatureRequested etkinliği üzerinden alınan istek tanımlayıcısı.

  • signature

    ArrayBuffer isteğe bağlı

    İmza (başarıyla oluşturulduysa).

RequestPinDetails

Chrome 57 ve sonraki sürümler 'nı inceleyin.

Özellikler

  • attemptsLeft

    sayı isteğe bağlı

    Kalan deneme sayısı. Bu sayede herhangi bir kullanıcı arayüzü, söz konusu bilgiyi kullanıcıya sunabilir. Chrome'un bunu zorunlu kılması beklenmemektedir. Bunun yerine, pin isteği sayısı aşıldığında stopPinRequest hatası = MAX_ATTEMPTS_EXCEEDED olan uzantı tarafından çağrılmalıdır.

  • errorType

    PinRequestErrorType optional

    Kullanıcıya gösterilen hata şablonu. Önceki istek başarısız olduysa kullanıcıya hatanın 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ı

    Chrome'un SignRequest tarafından sağlanan kimlik.

SetCertificatesDetails

Chrome 86 ve sonraki sürümler 'nı inceleyin.

Özellikler

  • certificatesRequestId

    sayı isteğe bağlı

    onCertificatesUpdateRequested komutuna yanıt olarak çağrıldığında, alınan certificatesRequestId değerini içermelidir. Aksi takdirde ayarlanmadan bırakılmalıdır.

  • clientCertificates

    ClientCertificateInfo[]

    Şu anda kullanılabilen istemci sertifikalarının listesi.

  • hata

    "GENERAL_ERROR"
     isteğe bağlı

    Sertifikalar ayıklanırken hata oluştu (varsa). Bu hata, uygun olduğunda kullanıcıya gösterilecektir.

SignatureRequest

Chrome 86 ve sonraki sürümler 'nı inceleyin.

Özellikler

  • algoritma

    Algoritma

    Kullanılacak imza algoritması.

  • sertifika

    DiziArabelleği

    X.509 sertifikasının DER kodlaması. Uzantı, ilişkili özel anahtarı kullanarak input öğesini imzalamalıdır.

  • giriş

    DiziArabelleği

    İmzalanacak veriler. Verilere karma oluşturma işlemi uygulanmadığını unutmayın.

  • signRequestId

    sayı

    Tanımlayıcının reportSignature öğesine iletilmesini isteyin.

SignRequest

Özellikler

  • sertifika

    DiziArabelleği

    X.509 sertifikasının DER kodlaması. Uzantı, ilişkili özel anahtarı kullanarak digest öğesini imzalamalıdır.

  • özet

    DiziArabelleği

    İmzalanması gereken özet.

  • hash

    Karma

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

  • signRequestId

    sayı

    Chrome 57 ve sonraki sürümler 'nı inceleyin.

    Uzantının gerekli olan bir yöntemi (ör. requestPin'dir.

StopPinRequestDetails

Chrome 57 ve sonraki sürümler 'nı inceleyin.

Özellikler

  • errorType

    PinRequestErrorType optional

    Hata şablonu. Varsa kullanıcıya gösterilir. Amacı, ör. bir hatadan kaynaklanan akışı durdurma nedenini içerir MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    sayı

    Chrome'un SignRequest tarafından sağlanan kimlik.

Yöntemler

reportSignature()

Söz Chrome 86 ve sonraki sürümler 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

onSignatureRequested yanıtı olarak çağrılmalıdır.

Uzantının sonuçta her onSignatureRequested etkinliği için bu işlevi çağırması gerekir. API uygulaması bir süre sonra bu çağrıyı beklemeyi bırakır ve bu işlev çağrıldığında zaman aşımı hatasıyla yanıt verir.

Parametreler

  • ayrıntılar

    ReportSignatureDetails

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Chrome 96 ve sonraki sürümler 'nı inceleyin.

    Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.

requestPin()

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

Kullanıcıdan PIN 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

    işlev isteğe bağlı

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

    (details?: PinResponseDetails) => void

İadeler

  • Promise&lt;PinResponseDetails | tanımlanmadı>

    Chrome 96 ve sonraki sürümler 'nı inceleyin.

    Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.

setCertificates()

Söz Chrome 86 ve sonraki sürümler 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

Tarayıcıda kullanılacak sertifikaların listesini ayarlar.

Uzantı, başlatmadan sonra ve o anda kullanılabilir olan sertifikalar grubundaki her değişiklikte bu işlevi çağırmalıdır. Uzantı, bu etkinlik her alındığında onCertificatesUpdateRequested komutuna 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

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Chrome 96 ve sonraki sürümler 'nı inceleyin.

    Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.

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 PIN isteğini durdurur.

Parametreler

  • ayrıntılar

    StopPinRequestDetails

    İstek akışının durdurulma nedeniyle ilgili ayrıntıları içerir.

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Chrome 96 ve sonraki sürümler 'nı inceleyin.

    Vaatler yalnızca Manifest V3 ve sonraki sürümler için desteklenir. Diğer platformların geri çağırma yapması gerekir.

Etkinlikler

onCertificatesRequested

Chrome 47 ve sonraki sürümler &amp;leq; MV2 Chrome 86'dan bu yana desteği sonlandırıldı
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Bunun yerine onCertificatesUpdateRequested alanını kullanın.

Tarayıcı bu uzantı tarafından sağlanan mevcut sertifikaların listesini her istediğinde bu etkinlik tetiklenir. Uzantı, mevcut sertifika listesiyle reportCallback öğesini 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 'nı inceleyin.
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

setCertificates aracılığıyla ayarlanan sertifikalar yetersizse veya tarayıcı güncellenmiş bilgiler isterse bu etkinlik tetiklenir. Uzantı, güncellenmiş sertifikaların listesini ve alınan certificatesRequestId ile setCertificates'ı çağırmalıdır.

Parametreler

onSignatureRequested

Chrome 86 ve sonraki sürümler 'nı inceleyin.
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 bir mesajı imzalaması gerektiğinde tetiklenir.

Uzantı, uygun algoritmayı ve özel anahtarı kullanarak request giriş verilerini imzalamalı ve alınan signRequestId ile reportSignature çağrısı yaparak bu verileri döndürmelidir.

Parametreler

onSignDigestRequested

&amp;leq; MV2 Chrome 86'dan bu yana desteği sonlandı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 bir sertifikayı kullanarak mesajı her imzalaması gerektiğinde tetiklenir. Uzantı, uygun algoritmayı ve özel anahtarı kullanarak request cihazındaki verileri imzalamalı ve reportCallback yöntemini çağırarak verileri döndürmelidir. 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 'nı inceleyin.

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

      (signature?: ArrayBuffer) => void

      • signature

        ArrayBuffer isteğe bağlı