// Copyright 2015 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Use this API to expose certificates to the platform which can use these
// certificates for TLS authentications.
namespace certificateProvider {
// Types of supported cryptographic signature algorithms.
enum Algorithm {
// Specifies the RSASSA PKCS#1 v1.5 signature algorithm with the MD5-SHA-1
// hashing. The extension must not prepend a DigestInfo prefix but only
// add PKCS#1 padding. This algorithm is deprecated and will never be requested
// by Chrome as of version 109.
RSASSA_PKCS1_v1_5_MD5_SHA1,
// Specifies the RSASSA PKCS#1 v1.5 signature algorithm
// with the SHA-1 hash function.
RSASSA_PKCS1_v1_5_SHA1,
// Specifies the RSASSA PKCS#1 v1.5 signature algorithm
// with the SHA-256 hashing function.
RSASSA_PKCS1_v1_5_SHA256,
// Specifies the RSASSA PKCS#1 v1.5 signature algorithm
// with the SHA-384 hashing function.
RSASSA_PKCS1_v1_5_SHA384,
// Specifies the RSASSA PKCS#1 v1.5 signature algorithm
// with the SHA-512 hashing function.
RSASSA_PKCS1_v1_5_SHA512,
// Specifies the RSASSA PSS signature algorithm with the SHA-256 hashing
// function, MGF1 mask generation function and the salt of the same size as
// the hash.
RSASSA_PSS_SHA256,
// Specifies the RSASSA PSS signature algorithm with the SHA-384 hashing
// function, MGF1 mask generation function and the salt of the same size as
// the hash.
RSASSA_PSS_SHA384,
// Specifies the RSASSA PSS signature algorithm with the SHA-512 hashing
// function, MGF1 mask generation function and the salt of the same size as
// the hash.
RSASSA_PSS_SHA512
};
// Types of errors that the extension can report.
enum Error {
// General error that cannot be represented by other more specific
// error codes.
GENERAL_ERROR
};
// Information about a client certificate.
[noinline_doc] dictionary ClientCertificateInfo {
// The array must contain the DER encoding of the X.509 client certificate
// as its first element.
// <p>This must include exactly one certificate.</p>
ArrayBuffer[] certificateChain;
// All algorithms supported for this certificate. The extension will only be
// asked for signatures using one of these algorithms.
Algorithm[] supportedAlgorithms;
};
dictionary SetCertificatesDetails {
// When called in response to $(ref:onCertificatesUpdateRequested), should
// contain the received <code>certificatesRequestId</code> value. Otherwise,
// should be unset.
long? certificatesRequestId;
// Error that occurred while extracting the certificates, if any. This error
// will be surfaced to the user when appropriate.
Error? error;
// List of currently available client certificates.
ClientCertificateInfo[] clientCertificates;
};
dictionary CertificatesUpdateRequest {
// Request identifier to be passed to $(ref:setCertificates).
long certificatesRequestId;
};
dictionary SignatureRequest {
// Request identifier to be passed to $(ref:reportSignature).
long signRequestId;
// Data to be signed. Note that the data is not hashed.
ArrayBuffer input;
// Signature algorithm to be used.
Algorithm algorithm;
// The DER encoding of a X.509 certificate. The extension must sign
// <code>input</code> using the associated private key.
ArrayBuffer certificate;
};
dictionary ReportSignatureDetails {
// Request identifier that was received via the $(ref:onSignatureRequested)
// event.
long signRequestId;
// Error that occurred while generating the signature, if any.
Error? error;
// The signature, if successfully generated.
ArrayBuffer? signature;
};
// Deprecated. Replaced by $(ref:Algorithm).
enum Hash {
// Specifies the MD5 and SHA1 hashing algorithms.
MD5_SHA1,
// Specifies the SHA1 hashing algorithm.
SHA1,
// Specifies the SHA256 hashing algorithm.
SHA256,
// Specifies the SHA384 hashing algorithm.
SHA384,
// Specifies the SHA512 hashing algorithm.
SHA512
};
// The type of code being requested by the extension with requestPin function.
enum PinRequestType {
// Specifies the requested code is a PIN.
PIN,
// Specifies the requested code is a PUK.
PUK
};
// The types of errors that can be presented to the user through the
// requestPin function.
enum PinRequestErrorType {
// Specifies the PIN is invalid.
INVALID_PIN,
// Specifies the PUK is invalid.
INVALID_PUK,
// Specifies the maximum attempt number has been exceeded.
MAX_ATTEMPTS_EXCEEDED,
// Specifies that the error cannot be represented by the above types.
UNKNOWN_ERROR
};
// Deprecated. Replaced by $(ref:ClientCertificateInfo).
dictionary CertificateInfo {
// Must be the DER encoding of a X.509 certificate. Currently, only
// certificates of RSA keys are supported.
ArrayBuffer certificate;
// Must be set to all hashes supported for this certificate. This extension
// will only be asked for signatures of digests calculated with one of these
// hash algorithms. This should be in order of decreasing hash preference.
Hash[] supportedHashes;
};
// Deprecated. Replaced by $(ref:SignatureRequest).
dictionary SignRequest {
// The unique ID to be used by the extension should it need to call a method
// that requires it, e.g. requestPin.
long signRequestId;
// The digest that must be signed.
ArrayBuffer digest;
// Refers to the hash algorithm that was used to create <code>digest</code>.
Hash hash;
// The DER encoding of a X.509 certificate. The extension must sign
// <code>digest</code> using the associated private key.
ArrayBuffer certificate;
};
dictionary RequestPinDetails {
// The ID given by Chrome in SignRequest.
long signRequestId;
// The type of code requested. Default is PIN.
PinRequestType? requestType;
// The error template displayed to the user. This should be set if the
// previous request failed, to notify the user of the failure reason.
PinRequestErrorType? errorType;
// The number of attempts left. This is provided so that any UI can present
// this information to the user. Chrome is not expected to enforce this,
// instead stopPinRequest should be called by the extension with
// errorType = MAX_ATTEMPTS_EXCEEDED when the number of pin requests is
// exceeded.
long? attemptsLeft;
};
dictionary StopPinRequestDetails {
// The ID given by Chrome in SignRequest.
long signRequestId;
// The error template. If present it is displayed to user. Intended to
// contain the reason for stopping the flow if it was caused by an error,
// e.g. MAX_ATTEMPTS_EXCEEDED.
PinRequestErrorType? errorType;
};
dictionary PinResponseDetails {
// The code provided by the user. Empty if user closed the dialog or some
// other error occurred.
DOMString? userInput;
};
callback RequestPinCallback = void (optional PinResponseDetails details);
callback StopPinRequestCallback = void ();
callback SetCertificatesCallback = void ();
callback ReportSignatureCallback = void ();
// The callback provided by the extension that Chrome uses to report back
// rejected certificates. See <code>CertificatesCallback</code>.
callback ResultCallback = void (ArrayBuffer[] rejectedCertificates);
// If no error occurred, this function must be called with the signature of
// the digest using the private key of the requested certificate.
// For an RSA key, the signature must be a PKCS#1 signature. The extension
// is responsible for prepending the DigestInfo prefix and adding PKCS#1
// padding. If an error occurred, this callback should be called without
// signature.
callback SignCallback = void (optional ArrayBuffer signature);
// Call this exactly once with the list of certificates that this extension is
// providing. The list must only contain certificates for which the extension
// can sign data using the associated private key. If the list contains
// invalid certificates, these will be ignored. All valid certificates are
// still registered for the extension. Chrome will call back with the list of
// rejected certificates, which might be empty.
callback CertificatesCallback =
void (CertificateInfo[] certificates, ResultCallback callback);
interface Events {
// This event fires if the certificates set via $(ref:setCertificates)
// are insufficient or the browser requests updated information. The
// extension must call $(ref:setCertificates) with the updated list of
// certificates and the received <code>certificatesRequestId</code>.
static void onCertificatesUpdateRequested(
CertificatesUpdateRequest request);
// This event fires every time the browser needs to sign a message using a
// certificate provided by this extension via $(ref:setCertificates).
// <p>The extension must sign the input data from <code>request</code> using
// the appropriate algorithm and private key and return it by calling
// $(ref:reportSignature) with the received <code>signRequestId</code>.</p>
static void onSignatureRequested(SignatureRequest request);
// <p>This event fires every time the browser requests the current list of
// certificates provided by this extension. The extension must call
// <code>reportCallback</code> exactly once with the current list of
// certificates.</p>
[deprecated="Use $(ref:onCertificatesUpdateRequested) instead."]
static void onCertificatesRequested(CertificatesCallback reportCallback);
// This event fires every time the browser needs to sign a message using
// a certificate provided by this extension in reply to an
// $(ref:onCertificatesRequested) event.
// The extension must sign the data in <code>request</code> using the
// appropriate algorithm and private key and return it by calling
// <code>reportCallback</code>. <code>reportCallback</code> must be called
// exactly once.
// |request|: Contains the details about the sign request.
[deprecated="Use $(ref:onSignatureRequested) instead."]
static void onSignDigestRequested(SignRequest request,
SignCallback reportCallback);
};
interface Functions {
// Requests the PIN from the user. Only one ongoing request at a time is
// allowed. The requests issued while another flow is ongoing are rejected.
// It's the extension's responsibility to try again later if another flow is
// in progress.
// |details|: Contains the details about the requested dialog.
// |callback|: Is called when the dialog is resolved with the user input, or
// when the dialog request finishes unsuccessfully (e.g. the dialog was
// canceled by the user or was not allowed to be shown).
static void requestPin(
RequestPinDetails details,
RequestPinCallback callback);
// Stops the pin request started by the $(ref:requestPin) function.
// |details|: Contains the details about the reason for stopping the
// request flow.
// |callback|: To be used by Chrome to send to the extension the status from
// their request to close PIN dialog for user.
static void stopPinRequest(
StopPinRequestDetails details,
StopPinRequestCallback callback);
// Sets a list of certificates to use in the browser.
// <p>The extension should call this function after initialization and on
// every change in the set of currently available certificates. The
// extension should also call this function in response to
// $(ref:onCertificatesUpdateRequested) every time this event is
// received.</p>
// |details|: The certificates to set. Invalid certificates will be ignored.
// |callback|: Called upon completion.
static void setCertificates(
SetCertificatesDetails details,
optional SetCertificatesCallback callback);
// Should be called as a response to $(ref:onSignatureRequested).
// <p>The extension must eventually call this function for every
// $(ref:onSignatureRequested) event; the API implementation will stop
// waiting for this call after some time and respond with a timeout
// error when this function is called.</p>
static void reportSignature(
ReportSignatureDetails details,
optional ReportSignatureCallback callback);
};
};
Codebase Browser
chromium