chrome.certificateProvider

Descripción

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

Permisos

certificateProvider

Disponibilidad

Chrome 46 y versiones posteriores Solo para ChromeOS

Conceptos y uso

El uso habitual de esta API para exponer certificados de cliente en 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 cambio.
  • 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 de los certificados disponibles actualmente mediante el método setCertificates().
  • El navegador asocia 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 anularla.
Diálogo de selección de certificados
Diálogo de selección de certificados
.
  • Si el usuario anula la autenticación o si ningún certificado coincide 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 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 proporcionados mediante 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 devuelve 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 utiliza la política empresarial para seleccionar automáticamente un certificado (consulta AutoSelectCertificateForUrls y las 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, sino solo agregar padding PKCS#1. Este algoritmo está obsoleto 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áscara 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 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 de 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

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

CertificatesUpdateRequest

Chrome 86 y versiones posteriores

Propiedades

  • certificatesRequestId

    número

    El identificador de la solicitud 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 su primer elemento.

    Esto debe incluir exactamente un certificado.

  • supportedAlgorithms

    Algoritmo

    Todos los algoritmos son compatibles con este certificado. A la extensión solo se le pedirán firmas mediante 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

Ya no está disponible. 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 un PUK.

PinResponseDetails

Chrome 57 y versiones posteriores

Propiedades

  • userInput

    cadena opcional

    El código proporcionado por el usuario. Estará vacío si el usuario cerró el diálogo o se produjo algún otro error.

ReportSignatureDetails

Chrome 86 y versiones posteriores

Propiedades

  • error

     opcional

    Error que se produjo al generar la firma, si corresponde.

  • 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

    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 supera la cantidad de solicitudes de PIN.

  • errorType

    PinRequestErrorType opcional

    La plantilla de error que se muestra al usuario. Se debe configurar 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 proporcionado por 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, no debe establecerse.

  • clientCertificates

    ClientCertificateInfo[]

    Lista de certificados de cliente disponibles actualmente.

  • error

     opcional

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

SignatureRequest

Chrome 86 y versiones posteriores

Propiedades

  • algoritmo

    Algorithm

    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

    El identificador de la solicitud 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

    El resumen que se debe firmar.

  • hash

    Hash

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

  • signRequestId

    número

    Chrome 57 y versiones posteriores

    El ID único que debe 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 opcional

    La plantilla de error. Si está presente, se muestra al usuario. Tiene el objetivo de contener el motivo para detener el flujo si se debe a un error, p.ej., MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    número

    Es el ID proporcionado por 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.

Eventualmente, la extensión debe llamar a esta función por 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

Devuelve

  • Promise<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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,
)

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

Devuelve

  • Promesa<PinResponseDetails|undefined>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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 cada vez que se modifica 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

Devuelve

  • Promise<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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 iniciada por la función requestPin.

Parámetros

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

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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

onCertificatesRequested

Chrome 47 y versiones posteriores &leq; MV2 Obsoleta a partir de 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 de certificados actual.

Parámetros

  • callback

    la función

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

    (reportCallback: function)=>void

    • reportCallback

      la función

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

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

      • certificates

        CertificateInfo.

      • callback

        la 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 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 los certificatesRequestId recibidos.

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 la 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 mostrarlos llamando a reportSignature con el signRequestId recibido.

Parámetros

onSignDigestRequested

&leq; MV2 Obsoleto a partir de Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

En su lugar, usa onSignatureRequested.

Este evento se activa cada vez que el navegador necesita firmar un mensaje con un certificado proporcionado por la 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 mostrarlos llamando a reportCallback. Se debe llamar a reportCallback exactamente una vez.

Parámetros

  • callback

    la función

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

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

    • request

      SignRequest

    • reportCallback

      la función

      Chrome 47 y versiones posteriores

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

      (signature?: ArrayBuffer)=>void

      • firma

        ArrayBuffer opcional