chrome.certificateProvider

.

Descripción

Usa esta API para exponer certificados a la plataforma que puede usarlos para las autenticaciones TLS.

Permisos

certificateProvider

Disponibilidad

Chrome 46 y versiones posteriores Solo en ChromeOS .

Conceptos y uso

El uso típico de esta API para exponer certificados de cliente a ChromeOS sigue estos pasos:

  • La extensión registra los eventos onCertificatesUpdateRequested y onSignatureRequested.
  • La extensión llama a setCertificates() para proporcionar la lista inicial de certificados después de la inicialización.
  • La extensión supervisa los cambios en la lista de certificados disponibles y llama a setCertificates() para notificar al navegador sobre cada uno de esos cambios.
  • Durante un protocolo de enlace TLS, el navegador recibe una solicitud de certificado de cliente. Con un evento onCertificatesUpdateRequested, el navegador le solicita a la extensión que informe todos los certificados que proporciona actualmente.
  • La extensión informa los certificados disponibles actualmente con el método setCertificates().
  • El navegador hace coincidir todos los certificados disponibles con la solicitud de certificado de cliente del host remoto. Las coincidencias se presentan al usuario en un diálogo de selección.
  • El usuario puede seleccionar un certificado y, así, aprobar la autenticación o anular la autenticación.
Diálogo de selección de certificados
Diálogo de selección de certificados.
  • Si el usuario anula la autenticación o ningún certificado coincidió con la solicitud, se anula la autenticación del cliente TLS.
  • De lo contrario, si el usuario aprueba la autenticación con un certificado proporcionado por esta extensión, el navegador solicita a la extensión que firme los datos para continuar con el protocolo de enlace TLS. La solicitud se envía como un evento onSignatureRequested.
  • Este evento contiene datos de entrada, declara qué algoritmo debe usarse para generar la firma y hace referencia a uno de los certificados que informó esta extensión. La Extensión debe crear una firma para los datos proporcionados usando la clave privada asociada con el certificado al que se hace referencia. Para crear la firma, es posible que se requiera anteponer un DigestInfo y rellenar el resultado antes de la firma real.
  • La extensión devuelve la firma al navegador usando el método reportSignature(). Si no se pudo calcular la firma, se debe llamar al método sin firma.
  • Si se proporcionó la firma, el navegador completa el protocolo de enlace TLS.

La secuencia real de pasos puede ser diferente. Por ejemplo, no se le pedirá al usuario que seleccione un certificado si se usa la política empresarial para seleccionar un certificado automáticamente (consulta AutoSelectCertificateForUrls y Políticas de Chrome para usuarios).

En la extensión, puede ser similar al siguiente fragmento:

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);

Tipos

Algorithm

Chrome 86 y versiones posteriores

Tipos de algoritmos de firma criptográfica compatibles.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Especifica el algoritmo de firma RSASSA PKCS#1 v1.5 con el hash MD5-SHA-1. La extensión no debe anteponer un prefijo DigestInfo, solo debe agregar relleno PKCS#1. Este algoritmo dejó de estar disponible y Chrome nunca lo solicitará a partir de la versión 109.

"RSASSA_PKCS1_v1_5_SHA1"
Especifica el algoritmo de firma RSASSA PKCS#1 v1.5 con la función de hash SHA-1.

"RSASSA_PKCS1_v1_5_SHA256"
Especifica el algoritmo de firma RSASSA PKCS#1 v1.5 con la función de hash SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
Especifica el algoritmo de firma RSASSA PKCS#1 v1.5 con la función de hash SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
Especifica el algoritmo de firma RSASSA PKCS#1 v1.5 con la función de hash SHA-512.

"RSASSA_PSS_SHA256"
Especifica el algoritmo de firma RSASSA PSS con la función de hash SHA-256, la función de generación de máscaras MGF1 y la sal del mismo tamaño que el hash.

"RSASSA_PSS_SHA384"
Especifica el algoritmo de firma RSASSA PSS con la función de hash SHA-384, la función de generación de enmascaramiento de MGF1 y la sal del mismo tamaño que el hash.

"RSASSA_PSS_SHA512"
Especifica el algoritmo de firma RSASSA PSS con la función de hash SHA-512, la función de generación de máscaras MGF1 y la sal del mismo tamaño que el hash.

CertificateInfo

Propiedades

  • certificado

    ArrayBuffer

    Debe ser la codificación DER de un certificado X.509. Actualmente, solo se admiten certificados de claves RSA.

  • supportedHashes

    Hash

    Debe configurarse con todos los hash compatibles con este certificado. A esta extensión solo se le pedirán las firmas de los resúmenes calculados con uno de estos algoritmos de hash. Esto debe estar en orden decreciente de la preferencia de hash.

CertificatesUpdateRequest

Chrome 86 y versiones posteriores

Propiedades

  • certificatesRequestId

    número

    Es el identificador de solicitud que se pasará a setCertificates.

ClientCertificateInfo

Chrome 86 y versiones posteriores

Propiedades

  • certificateChain

    ArrayBuffer[]

    La matriz debe contener la codificación DER del certificado de cliente X.509 como primer elemento.

    Esto debe incluir exactamente un certificado.

  • supportedAlgorithms

    Algoritmo

    Todos los algoritmos compatibles con este certificado. Solo se solicitarán firmas a la extensión con uno de estos algoritmos.

Error

Chrome 86 y versiones posteriores

Son los tipos de errores que la extensión puede informar.

Valor

"GENERAL_ERROR"

Hash

Obsoleta. Se reemplazó por Algorithm.

Enum

"MD5_SHA1"
Especifica los algoritmos de hash MD5 y SHA1.

"SHA1"
Especifica el algoritmo de hash SHA1.

"SHA256"
Especifica el algoritmo de hash SHA256.

"SHA384"
Especifica el algoritmo de hash SHA384.

"SHA512"
Especifica el algoritmo de hash SHA512.

PinRequestErrorType

Chrome 57 y versiones posteriores

Los tipos de errores que se pueden presentar al usuario a través de la función requestPin.

Enum

"INVALID_PIN"
Especifica que el PIN no es válido.

"INVALID_PUK"
Especifica que la PUK no es válida.

"MAX_ATTEMPTS_EXCEEDED"
Especifica que se superó la cantidad máxima de intentos.

"UNKNOWN_ERROR"
Especifica que los tipos anteriores no pueden representar el error.

PinRequestType

Chrome 57 y versiones posteriores

El tipo de código que solicita la extensión con la función requestPin.

Enum

"PIN"
Especifica que el código solicitado es un PIN.

"PUK"
Especifica que el código solicitado es PUK.

PinResponseDetails

Chrome 57 y versiones posteriores

Propiedades

  • userInput

    string opcional

    Es el código que proporcionó el usuario. Estará vacío si el usuario cerró el diálogo o se produjo otro error.

ReportSignatureDetails

Chrome 86 y versiones posteriores

Propiedades

  • error

    "GENERAL_ERROR"
     opcional

    Error que se produjo al generar la firma, si lo hubo.

  • signRequestId

    número

    Es el identificador de solicitud que se recibió a través del evento onSignatureRequested.

  • firma

    ArrayBuffer opcional

    La firma, si se generó correctamente.

RequestPinDetails

Chrome 57 y versiones posteriores

Propiedades

  • attemptsLeft

    número opcional

    La cantidad de intentos restantes. Esto se proporciona para que cualquier IU pueda presentar esta información al usuario. No se espera que Chrome aplique esto; en su lugar, la extensión debe llamar a stopPinRequest con errorType = MAX_ATTEMPTS_EXCEEDED cuando se excede la cantidad de solicitudes de fijación.

  • errorType

    PinRequestErrorType optional

    La plantilla de error que se muestra al usuario Esto se debe establecer si la solicitud anterior falló, para notificar al usuario sobre el motivo de la falla.

  • requestType

    PinRequestType opcional

    Es el tipo de código solicitado. El valor predeterminado es PIN.

  • signRequestId

    número

    Es el ID que proporciona Chrome en SignRequest.

SetCertificatesDetails

Chrome 86 y versiones posteriores

Propiedades

  • certificatesRequestId

    número opcional

    Cuando se llama en respuesta a onCertificatesUpdateRequested, debe contener el valor certificatesRequestId recibido. De lo contrario, debe desactivarse.

  • clientCertificates

    ClientCertificateInfo[]

    Lista de certificados de cliente disponibles actualmente.

  • error

    "GENERAL_ERROR"
     opcional

    Error que se produjo durante la extracción de certificados, si hubiera alguno. El usuario verá este error cuando corresponda.

SignatureRequest

Chrome 86 y versiones posteriores

Propiedades

  • algoritmo

    Algorithm

    Algoritmo de firma que se usará.

  • certificado

    ArrayBuffer

    Codificación DER de un certificado X.509. La extensión debe firmar input con la clave privada asociada.

  • entrada

    ArrayBuffer

    Datos que se firmarán. Ten en cuenta que los datos no tienen codificación hash.

  • signRequestId

    número

    Es el identificador de solicitud que se pasará a reportSignature.

SignRequest

Propiedades

  • certificado

    ArrayBuffer

    Codificación DER de un certificado X.509. La extensión debe firmar digest con la clave privada asociada.

  • resumen

    ArrayBuffer

    El resumen que se debe firmar.

  • hash

    Hash

    Se refiere al algoritmo de hash que se usó para crear digest.

  • signRequestId

    número

    Chrome 57 y versiones posteriores

    El ID único que usará la extensión en caso de que necesite llamar a un método que lo requiera, p.ej., requestPin.

StopPinRequestDetails

Chrome 57 y versiones posteriores

Propiedades

  • errorType

    PinRequestErrorType optional

    La plantilla de errores Si está presente, se muestra al usuario. Tienen la intención de contener el motivo de la detención del flujo si se debe a un error, p.ej., MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    número

    Es el ID que proporciona Chrome en SignRequest.

Métodos

reportSignature()

Promesa Chrome 86 y versiones posteriores .
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

Se debe llamar como respuesta a onSignatureRequested.

En algún momento, la extensión debe llamar a esta función para cada evento onSignatureRequested. Después de un tiempo, la implementación de la API dejará de esperar la llamada y mostrará un error de tiempo de espera cuando se llame a esta función.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

requestPin()

Promesa Chrome 57 y versiones posteriores .
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

Solicita el PIN al usuario. Solo se permite una solicitud en curso a la vez. Las solicitudes emitidas mientras otro flujo está en curso se rechazan. Es responsabilidad de la extensión volver a intentarlo más tarde si hay otro flujo en curso.

Parámetros

Muestra

  • Promise&lt;PinResponseDetails | indefinido>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

setCertificates()

Promesa Chrome 86 y versiones posteriores .
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

Establece una lista de certificados para usar en el navegador.

La extensión debe llamar a esta función después de la inicialización y en cada cambio en el conjunto de certificados disponibles actualmente. La extensión también debe llamar a esta función en respuesta a onCertificatesUpdateRequested cada vez que se recibe este evento.

Parámetros

  • Los certificados que se configurarán. Se ignorarán los certificados no válidos.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

stopPinRequest()

Promesa Chrome 57 y versiones posteriores .
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Detiene la solicitud de fijación que inicia la función requestPin.

Parámetros

  • Contiene los detalles sobre el motivo por el que se detuvo el flujo de la solicitud.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Eventos

onCertificatesRequested

Chrome 47 y versiones posteriores &amp;leq; MV2 Obsoleto desde Chrome 86
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

En su lugar, usa onCertificatesUpdateRequested.

Este evento se activa cada vez que el navegador solicita la lista actual de certificados proporcionados por esta extensión. La extensión debe llamar a reportCallback exactamente una vez con la lista actual de certificados.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (reportCallback: function) => void

    • reportCallback

      función

      El parámetro reportCallback se ve de la siguiente manera: 

      (certificates: CertificateInfo[], callback: function) => void

      • certificates

        CertificateInfo[]

      • callback

        función

        El parámetro callback se ve de la siguiente manera: 

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 y versiones posteriores 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Este evento se activa si los certificados configurados a través de setCertificates no son suficientes o el navegador solicita información actualizada. La extensión debe llamar a setCertificates con la lista actualizada de certificados y el certificatesRequestId recibido.

Parámetros

onSignatureRequested

Chrome 86 y versiones posteriores 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Este evento se activa cada vez que el navegador debe firmar un mensaje con un certificado proporcionado por esta extensión a través de setCertificates.

La extensión debe firmar los datos de entrada de request con el algoritmo y la clave privada adecuados, y devolverlos llamando a reportSignature con el signRequestId recibido.

Parámetros

onSignDigestRequested

&amp;leq; MV2 Obsoleto desde Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

En su lugar, usa onSignatureRequested.

Este evento se activa cada vez que el navegador debe firmar un mensaje con un certificado proporcionado por esta extensión en respuesta a un evento onCertificatesRequested. La extensión debe firmar los datos en request con el algoritmo y la clave privada adecuados, y llamar a reportCallback para mostrarlos. Se debe llamar a reportCallback exactamente una vez.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (request: SignRequest, reportCallback: function) => void

    • request

      SignRequest

    • reportCallback

      función

      Chrome 47 y versiones posteriores

      El parámetro reportCallback se ve de la siguiente manera: 

      (signature?: ArrayBuffer) => void

      • firma

        ArrayBuffer opcional