// 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.
  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);
  };
};