chrome.certificateProvider

Descripción

Usa esta API para exponer certificados a la plataforma que puede usar estos certificados para autenticaciones de TLS.

Permisos

certificateProvider

Disponibilidad

Chrome 46 y versiones posteriores Solo para ChromeOS

Conceptos y uso

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

  • La extensión se registra para 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 pide 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, de esta manera, aprobar o abortar la autenticación.
Diálogo de selección de certificados
Diálogo de selección de certificados.
  • Si el usuario cancela la autenticación o no hay ningún certificado que coincida con la solicitud, se cancela 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 le 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 se debe usar 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 determinados con la clave privada asociada con el certificado al que se hace referencia. Para crear la firma, es posible que debas anteponer un DigestInfo y rellenar el resultado antes de la firma real.
  • La extensión envía la firma al navegador con 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 los usuarios).

En la extensión, esto puede verse 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 agregar un prefijo DigestInfo, sino solo el padding 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 hash SHA-1.

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

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

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

"RSASSA_PSS_SHA256"
Especifica el algoritmo de firma PSS de RSASSA 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 PSS de RSASSA con la función hash SHA-384, la función de generación de máscara 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 hash SHA-512, la función de generación de máscara 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[]

    Se debe establecer en todos los valores hash compatibles con este certificado. A esta extensión solo se le solicitarán firmas de resúmenes calculados con uno de estos algoritmos de hash. Esto debe estar en orden de preferencia de hash decreciente.

CertificatesUpdateRequest

Chrome 86 y versiones posteriores

Propiedades

  • certificatesRequestId

    número

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

ClientCertificateInfo

Chrome 86 y versiones posteriores

Propiedades

  • certificateChain

    ArrayBuffer[]

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

    Debe incluir exactamente un certificado.

  • supportedAlgorithms

    Algoritmo[]

    Todos los algoritmos compatibles con este certificado A la extensión solo se le pedirá que firme con uno de estos algoritmos.

Error

Chrome 86 y versiones posteriores

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

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 el error no se puede representar con los tipos anteriores.

PinRequestType

Chrome 57 y versiones posteriores

Es 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 un PUK.

PinResponseDetails

Chrome 57 y versiones posteriores

Propiedades

  • userInput

    cadena opcional

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

ReportSignatureDetails

Chrome 86 y versiones posteriores

Propiedades

  • error

    "GENERAL_ERROR"
     opcional

    Es el error que se produjo cuando se generaba la firma, si la 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 genera correctamente

RequestPinDetails

Chrome 57 y versiones posteriores

Propiedades

  • attemptsLeft

    número opcional

    Es la cantidad de intentos restantes. Esto se proporciona para que cualquier IU pueda presentarle 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 supere la cantidad de solicitudes de pines.

  • errorType

    PinRequestErrorType opcional

    Es la plantilla de error que se muestra al usuario. Se debe establecer si la solicitud anterior falló para notificarle al usuario el motivo de la falla.

  • requestType

    PinRequestType: Opcional

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

  • signRequestId

    número

    El ID que proporciona Chrome en SignRequest.

SetCertificatesDetails

Chrome 86 y versiones posteriores

Propiedades

  • certificatesRequestId

    número opcional

    Cuando se llame en respuesta a onCertificatesUpdateRequested, debe contener el valor certificatesRequestId recibido. De lo contrario, no se debe establecer.

  • clientCertificates

    ClientCertificateInfo[]

    Es la lista de certificados de cliente disponibles actualmente.

  • error

    "GENERAL_ERROR"
     opcional

    Error que se produjo durante la extracción de los certificados, si los hay. Este error se mostrará al usuario cuando corresponda.

SignatureRequest

Chrome 86 y versiones posteriores

Propiedades

  • algoritmo

    Algorithm

    Es el algoritmo de firma que se usará.

  • certificado

    ArrayBuffer

    La 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 la solicitud que se pasará a reportSignature.

SignRequest

Propiedades

  • certificado

    ArrayBuffer

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

  • resumen

    ArrayBuffer

    Es el resumen que se debe firmar.

  • hash

    Hash

    Hace referencia al algoritmo de hash que se usó para crear digest.

  • signRequestId

    número

    Chrome 57 y versiones posteriores

    Es el ID único que usará la extensión si necesita llamar a un método que lo requiera, p.ej., requestPin.

StopPinRequestDetails

Chrome 57 y versiones posteriores

Propiedades

  • errorType

    PinRequestErrorType opcional

    La plantilla de error Si está presente, se le muestra al usuario. Se diseñó para contener el motivo por el que se detuvo el flujo si se debió a un error, p.ej., MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    número

    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. La implementación de la API dejará de esperar esta llamada después de un tiempo y responderá con 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

  • Promise<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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,
)

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

Parámetros

Muestra

  • Promise<PinResponseDetails | undefined>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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

  • Promise<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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 pin que inició la función requestPin.

Parámetros

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

  • callback

    función opcional

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

    () => void

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

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

Eventos

onCertificatesUpdateRequested

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

Este evento se activa si los certificados establecidos a través de setCertificates no son suficientes o si 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 necesita firmar un mensaje con un certificado que proporciona 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