chrome.certificateProvider

Açıklama

Bu API'yi, sertifikaları platforma sunmak için kullanın. Platform, bu sertifikaları TLS kimlik doğrulamaları için kullanabilir.

İzinler

certificateProvider

Kullanılabilirlik

Chrome 46 veya daha yeni bir sürüm 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ı içerir:

  • Uzantı, onCertificatesUpdateRequested ve onSignatureRequested etkinliklerine kaydolur.
  • Uzantı, başlatma işleminden sonra ilk sertifika listesini sağlamak için setCertificates() işlevini çağırır.
  • Uzantı, kullanılabilir sertifikaların listesindeki değişiklikleri izler ve tarayıcıyı bu tür değişiklikler hakkında bilgilendirmek için setCertificates() işlevini çağırır.
  • TLS el sıkışması sırasında tarayıcı, istemci sertifikası isteği alır. onCertificatesUpdateRequested etkinliğiyle tarayıcı, uzantıdan şu anda sağladığı tüm sertifikaları bildirmesini ister.
  • Uzantı, setCertificates() yöntemini kullanarak şu anda kullanılabilen sertifikaları bildirir.
  • Tarayıcı, kullanılabilir tüm sertifikaları uzak ana makineden gelen istemci sertifikası isteğiyle eşleştirir. Eşleşmeler, seçim iletişim kutusunda kullanıcıya sunulur.
  • Kullanıcı bir sertifika seçerek kimlik doğrulamayı onaylayabilir veya 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 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, onSignatureRequested etkinliği olarak gönderilir.
  • Bu etkinlik, giriş verilerini içerir, imzayı oluşturmak için hangi algoritmanın kullanılması gerektiğini belirtir ve bu uzantı tarafından bildirilen sertifikalardan birine atıfta bulunur. Uzantı, referans verilen sertifikayla ilişkili özel anahtarı kullanarak verilen veriler için bir imza oluşturmalıdır. İmza oluşturmak için gerçek imzalamadan önce 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ımlar farklı olabilir. Örneğin, sertifikayı otomatik olarak seçme kurumsal politikası kullanılıyorsa kullanıcıdan sertifika seçmesi istenmez (AutoSelectCertificateForUrls ve Kullanıcılar için Chrome politikaları bölümüne bakın).

Uzantıda bu durum aşağıdaki snippet'e benzer 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 ş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ı boyutta tuz ile 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 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ğerlerine ayarlanmalıdır. Bu uzantı yalnızca bu karma algoritmalarından biriyle hesaplanan özetlerin imzalarını ister. Bu, karma tercihi azalan sırada olmalıdır.

CertificatesUpdateRequest

Chrome 86 ve sonraki sürümler

Özellikler

  • certificatesRequestId

    sayı

    İstek tanımlayıcısının setCertificates'a iletilmesini isteyin.

ClientCertificateInfo

Chrome 86 ve sonraki sürümler

Özellikler

  • certificateChain

    ArrayBuffer[]

    Dizi, ilk öğe 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 tüm algoritmalar desteklenir. Uzantıdan yalnızca bu algoritmalardan birini kullanarak imza oluşturması 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 veya sonraki bir sürüm

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"
Hatayı yukarıdaki türlerle temsil edilemediğini belirtir.

PinRequestType

Chrome 57 veya sonraki bir sürüm

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 veya sonraki bir sürüm

Ö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ş olur.

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ıdır.

    Başarıyla oluşturulduysa imza.

RequestPinDetails

Chrome 57 veya sonraki bir sürüm

Ö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 isteklerinin sayısı aşıldığında uzantı tarafından stopPinRequest, 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ıyı başarısızlık nedeni hakkında bilgilendirmek için bu ayar yapılmalıdır.

  • requestType

    PinRequestType isteğe bağlı

    İstenen kod 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 ayarlanmamalıdır.

  • clientCertificates

    ClientCertificateInfo[]

    Ş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

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. Verilerin karma oluşturma işlemi uygulanmadığını unutmayın.

  • signRequestId

    sayı

    İstek tanımlayıcısının reportSignature'a iletilmesini isteyin.

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 veya sonraki bir sürüm

    Uzantının, kimlik gerektiren bir yöntemi (ör. requestPin) çağırması gerektiğinde kullanacağı benzersiz kimlik.

StopPinRequestDetails

Chrome 57 veya sonraki bir sürüm

Özellikler

  • errorType

    PinRequestErrorType isteğe bağlı

    Hata şablonu. Varsa kullanıcıya gösterilir. Akışın durdurulmasının nedenini içermesi amaçlanmıştır (ör. MAX_ATTEMPTS_EXCEEDED).

  • signRequestId

    sayı

    SignRequest'te Chrome tarafından verilen kimlik.

Yöntemler

reportSignature()

Chrome 86 ve sonraki sürümler 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

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

Uzantı, her onSignatureRequested etkinliği için sonunda bu işlevi çağırmalıdır. 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

İadeler

  • Promise<void>

    Chrome 96 veya daha yeni bir sürüm

requestPin()

Chrome 57 veya sonraki bir sürüm 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

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. Başka bir akış devam ediyorsa 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.

İadeler

setCertificates()

Chrome 86 ve sonraki sürümler 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

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

Uzantı, bu işlevi başlatma işleminden sonra ve şu anda kullanılabilen sertifikalar kümesindeki her değişiklikte çağırmalıdır. Uzantı, bu etkinlik her alındığında onCertificatesUpdateRequested yanıtı olarak bu işlevi de çağırmalıdır.

Parametreler

İadeler

  • Promise<void>

    Chrome 96 veya daha yeni bir sürüm

stopPinRequest()

Chrome 57 veya sonraki bir sürüm 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

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

Parametreler

  • ayrıntılar

    StopPinRequestDetails

    İstek akışının durdurulma nedenine ilişkin ayrıntıları içerir.

İadeler

  • Promise<void>

    Chrome 96 veya daha yeni bir sürüm

Etkinlikler

onCertificatesUpdateRequested

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

Bu etkinlik, setCertificates aracılığıyla ayarlanan sertifikalar yetersizse veya tarayıcı güncellenmiş bilgiler isterse tetiklenir. Uzantı, güncellenmiş sertifika listesi ve alınan setCertificates ile certificatesRequestId'ü ç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 bir mesajı imzalaması gerektiğinde her seferinde tetiklenir.

Uzantı, request kaynağından gelen giriş verilerini uygun algoritma ve özel anahtarla imzalamalı, alınan signRequestId ile reportSignature çağrısı yaparak döndürmelidir.

Parametreler