chrome.certificateProvider

Açıklama

Bu API'yi kullanarak sertifikalarınızı platforma gösterin. Platform, bu sertifikaları TLS kimlik doğrulamaları için kullanabilir.

İzinler

certificateProvider

Kullanılabilirlik

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

Kavramlar ve kullanım

İstemci sertifikalarını ChromeOS'e göstermek için bu API'nin tipik kullanımı aşağıdaki adımları izler:

  • Uzantı, onCertificatesUpdateRequested ve onSignatureRequested etkinliklerine kaydolur.
  • Uzantı, ilk başlatma işleminden sonra ilk sertifika listesini sağlamak için setCertificates() çağrısını yapar.
  • 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ır.
  • TLS el sıkışma sırasında tarayıcı bir istemci sertifikası isteği alır. Tarayıcı, onCertificatesUpdateRequested etkinliğiyle uzantıda şu anda sağladığı tüm sertifikaların raporlanmasını 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ğrulamayı onaylayabilir veya iptal edebilir.
Sertifika seçme iletişim kutusu
Sertifika seçim 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ı bu uzantı tarafından sağlanan bir sertifikayla kimlik doğrulamayı onaylarsa tarayıcı, TLS el sıkışma işlemine devam etmek için uzantıda verileri imzalamasını ister. İstek, onSignatureRequested etkinliği olarak gönderilir.
  • Bu etkinlik giriş verileri içerir, imzayı oluşturmak için hangi algoritmanın kullanılması gerektiğini belirtir ve bu uzantı tarafından raporlanan sertifikalardan birini ifade eder. Uzantı, referans verilen sertifikayla ilişkili özel anahtarı kullanarak belirli veriler için bir imza oluşturmalıdır. İmzayı oluşturmak için gerçek imzalamadan önce bir DigestInfo ön eklenmesi 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.

Gerçek adım sırası farklı olabilir. Örneğin, otomatik sertifika seçme kurumsal politikası kullanılıyorsa kullanıcıdan sertifika seçmesi istenmez (AutoSelectCertificateForUrls ve Kullanıcılar için Chrome politikaları başlıklı makalelere bakın).

Uzantıdaki bu kod, 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

Desteklenen kriptografik imza 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 ön ekini eklememelidir ancak yalnızca PKCS#1 dolgu eklemelidir. Bu algoritmanın desteği sonlandırılmıştır ve 109 sürümü itibarıyla 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şlevi, MGF1 maske oluşturma işlevi ve karma ile aynı boyutta tuz 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ı boyutta tuz 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ı boyutta tuz içeren 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 oluşturma işlemlerine ayarlanmalıdır. Bu uzantıdan yalnızca bu karma oluşturma algoritmalarından biriyle hesaplanan özetlerin imzaları istenir. Bu, karma oluşturma tercihinin azalan sırasına göre olmalıdır.

CertificatesUpdateRequest

Chrome 86 ve sonraki sürümler

Özellikler

  • certificatesRequestId

    sayı

    setCertificates adresine 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 dosya tam olarak bir sertifika içermelidir.

  • supportedAlgorithms

    Algoritma[]

    Bu sertifika için desteklenen tüm algoritmalar. Uzantıdan yalnızca bu algoritmalardan biri kullanılarak imza 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

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'nın 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 edilemediğini belirtir.

PinRequestType

Chrome 57 ve sonraki sürümler

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

Chrome 57 ve sonraki sürümler

Ö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

Özellikler

  • hata

    "GENERAL_ERROR"
     isteğe bağlı

    İmza oluşturulurken oluşan hata (varsa).

  • signRequestId

    sayı

    onSignatureRequested etkinliği aracılığıyla alınan istek tanımlayıcısı.

  • signature

    ArrayBuffer isteğe bağlı

    Başarıyla oluşturulduysa imza.

RequestPinDetails

Chrome 57 ve sonraki sürümler

Ö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 bunu zorunlu kılması beklenmez. Bunun yerine, PIN isteği sayısı aşıldığında uzantı tarafından stopPinRequest işlevi errorType = MAX_ATTEMPTS_EXCEEDED ile ç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ız olma nedenini bildirmek için bu ayar yapılmalı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

Chrome 86 ve sonraki sürümler

Özellikler

  • certificatesRequestId

    number isteğe bağlı

    onCertificatesUpdateRequested yanıtı olarak çağrıldığında, alınan certificatesRequestId değerini içermelidir. Aksi takdirde ayarlanmamış olmalıdır.

  • clientCertificates

    ClientCertificateInfo[]

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

  • hata

    "GENERAL_ERROR"
     isteğe bağlı

    Varsa sertifikalar ayıklanırken oluşan hata. 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

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

  • giriş

    ArrayBuffer

    İmzalanacak veriler. Verilere karma oluşturma işlemi uygulanmaz.

  • signRequestId

    sayı

    reportSignature adresine iletilecek istek tanımlayıcısı.

SignRequest

Özellikler

  • sertifika

    ArrayBuffer

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

  • özet

    ArrayBuffer

    İ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

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

StopPinRequestDetails

Chrome 57 ve sonraki sürümler

Özellikler

  • errorType

    PinRequestErrorType isteğe bağlı

    Hata şablonu. Varsa kullanıcıya gösterilir. Akış, bir hatadan (ör. MAX_ATTEMPTS_EXCEEDED) kaynaklanarak durdurulduysa hatanın nedenini içerir.

  • signRequestId

    sayı

    SignRequest'te Chrome tarafından verilen kimlik.

Yöntemler

reportSignature()

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

onSignatureRequested işlevine 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ı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

  • Promise<void>

    Chrome 96 ve üzeri sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

requestPin()

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

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

    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<PinResponseDetails | undefined>

    Chrome 96 ve üzeri sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

setCertificates()

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

Tarayıcıda kullanılacak sertifika listesini ayarlar.

Uzantı, ilk kullanıma hazırlama işleminden sonra ve mevcut sertifika grubunda her değişiklikte bu işlevi çağırmalıdır. Uzatma, bu etkinlik her alındığında onCertificatesUpdateRequested 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

  • Promise<void>

    Chrome 96 ve üzeri sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

stopPinRequest()

Promise 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

    işlev isteğe bağlı

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

    () => void

İadeler

  • Promise<void>

    Chrome 96 ve üzeri sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

Etkinlikler

onCertificatesUpdateRequested

Chrome 86 ve sonraki sürümler 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

setCertificates aracılığıyla ayarlanan sertifikalar yetersizse veya tarayıcı güncellenmiş bilgiler isterse bu etkinlik tetiklenir. Uzatma, güncellenmiş sertifika listesini ve alınan certificatesRequestId değerini içeren setCertificates çağrısı yapmalı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 sertifika kullanarak bir mesajı imzalaması gerektiğinde her zaman tetiklenir.

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

Parametreler