chrome/common/extensions/api/certificate_provider.idl

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use this API to expose certificates to the platform which can use these
   6 // certificates for TLS authentications.
   7 namespace certificateProvider {
   8   enum Hash {
   9     MD5_SHA1,
  10     SHA1,
  11     SHA256,
  12     SHA384,
  13     SHA512
  14   };
  15
  16   [noinline_doc] dictionary CertificateInfo {
  17     // Must be the DER encoding of a X.509 certificate. Currently, only
  18     // certificates of RSA keys are supported.
  19     ArrayBuffer certificate;
  20
  21     // Must be set to all hashes supported for this certificate. This extension
  22     // will only be asked for signatures of digests calculated with one of these
  23     // hash algorithms.
  24     Hash[] supportedHashes;
  25   };
  26
  27   [noinline_doc] dictionary SignRequest {
  28     // The digest that must be signed.
  29     ArrayBuffer digest;
  30
  31     // Refers to the hash algorithm that was used to create <code>digest</code>.
  32     Hash hash;
  33
  34     // The DER encoding of a X.509 certificate. The extension must sign
  35     // <code>digest</code> using the associated private key.
  36     ArrayBuffer certificate;
  37   };
  38
  39   // The callback provided by the extension that Chrome uses to report back
  40   // rejected certificates. See <code>CertificatesCallback</code>.
  41   callback ResultCallback = void (ArrayBuffer[] rejectedCertificates);
  42
  43   // If no error occurred, this function must be called with the signature of
  44   // the digest using the private key of the requested certificate.
  45   // For an RSA key, the signature must be a PKCS#1 signature. The extension
  46   // is responsible for prepending the DigestInfo prefix and adding PKCS#1
  47   // padding. If an <code>MD5_SHA1</code> hash is to be signed, the extension
  48   // must not prepend a DigestInfo prefix but only add PKCS#1 padding.
  49   // If an error occurred, this callback should be called without signature.
  50   callback SignCallback = void (optional ArrayBuffer signature);
  51
  52   // Call this exactly once with the list of certificates that this extension is
  53   // providing. The list must only contain certificates for which the extension
  54   // can sign data using the associated private key. If the list contains
  55   // invalid certificates, these will be ignored. All valid certificates are
  56   // still registered for the extension. Chrome will call back with the list of
  57   // rejected certificates, which might be empty.
  58   callback CertificatesCallback =
  59       void (CertificateInfo[] certificates, ResultCallback callback);
  60
  61   interface Events {
  62     // This event fires every time the browser requests the current list of
  63     // certificates provided by this extension. The extension must call
  64     // <code>reportCallback</code> exactly once with the current list of
  65     // certificates.
  66     static void onCertificatesRequested(CertificatesCallback reportCallback);
  67
  68     // This event fires every time the browser needs to sign a message using a
  69     // certificate provided by this extension in reply to an
  70     // $(ref:onCertificatesRequested) event.
  71     // The extension must sign the data in <code>request</code> using the
  72     // appropriate algorithm and private key and return it by calling
  73     // <code>reportCallback</code>. <code>reportCallback</code> must be called
  74     // exactly once.
  75     // |request|: Contains the details about the sign request.
  76     static void onSignDigestRequested(SignRequest request,
  77                                       SignCallback reportCallback);
  78   };
  79 };