Descripción
Usa esta API para exponer certificados a la plataforma que puede usarlos para las autenticaciones TLS.
Permisos
certificateProvider
Disponibilidad
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 acerca de 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 con los certificados disponibles actualmente a través del 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.
- 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
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
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
Propiedades
-
certificatesRequestId
número
Es el identificador de solicitud que se pasará a
setCertificates
.
ClientCertificateInfo
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
Todos los algoritmos compatibles con este certificado. Solo se solicitarán firmas a la extensión con uno de estos algoritmos.
Error
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
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
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
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
Propiedades
-
error
"GENERAL_ERROR"
opcionalError 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
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
Propiedades
-
certificatesRequestId
número opcional
Cuando se llama en respuesta a
onCertificatesUpdateRequested
, debe contener el valorcertificatesRequestId
recibido. De lo contrario, debe desactivarse. -
clientCertificates
Lista de certificados de cliente disponibles actualmente.
-
error
"GENERAL_ERROR"
opcionalError que se produjo durante la extracción de certificados, si hubiera alguno. El usuario verá este error cuando corresponda.
SignatureRequest
Propiedades
-
algoritmo
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
Se refiere al algoritmo de hash que se usó para crear
digest
. -
signRequestId
número
Chrome 57 y versiones posterioresEl ID único que usará la extensión en caso de que necesite llamar a un método que lo requiera, p.ej., requestPin.
StopPinRequestDetails
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()
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
-
detalles
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Muestra
-
Promesa<void>
Chrome 96 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
requestPin()
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
-
detalles
Contiene los detalles sobre el diálogo solicitado.
-
callback
función opcional
El parámetro
callback
se ve de la siguiente manera:(details?: PinResponseDetails) => void
-
detalles
PinResponseDetails opcional
-
Muestra
-
Promise<PinResponseDetails | indefinido>
Chrome 96 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
setCertificates()
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
-
detalles
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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
Detiene la solicitud de fijación que inicia la función requestPin
.
Parámetros
-
detalles
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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
Eventos
onCertificatesRequested
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
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
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
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(request: CertificatesUpdateRequest) => void
-
request
-
onSignatureRequested
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
-
callback
función
El parámetro
callback
se ve de la siguiente manera:(request: SignatureRequest) => void
-
request
-
onSignDigestRequested
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
-
reportCallback
función
Chrome 47 y versiones posterioresEl parámetro
reportCallback
se ve de la siguiente manera:(signature?: ArrayBuffer) => void
-
firma
ArrayBuffer opcional
-
-