Add new certificateProvider extension API.

chrome/common/extensions/api/certificate_provider.idl

Index: chrome/common/extensions/api/certificate_provider.idl
diff --git a/chrome/common/extensions/api/certificate_provider.idl b/chrome/common/extensions/api/certificate_provider.idl
index 631026e2206c85c10c13ba1e8de7dc3874246f1a..1cd69dc9f75af7a17c984719149642a8e9ba975d 100644
--- a/chrome/common/extensions/api/certificate_provider.idl
+++ b/chrome/common/extensions/api/certificate_provider.idl
@@ -13,8 +13,8 @@ namespace certificateProvider {
     SHA512
   };
 
-  dictionary CertificateInfo {
-    // Must be the DER encoding of a X.509 client certificate. Currently, only
+  [noinline_doc] dictionary CertificateInfo {
+    // Must be the DER encoding of a X.509 certificate. Currently, only
     // certificates of RSA keys are supported.
     ArrayBuffer certificate;
 
@@ -24,55 +24,56 @@ namespace certificateProvider {
     Hash[] supportedHashes;
   };
 
-  dictionary SignRequest {
+  [noinline_doc] dictionary SignRequest {
     // The digest that must be signed.
     ArrayBuffer digest;
 
-    // Refers to the hash algorithm that was used to create |digest|.
+    // Refers to the hash algorithm that was used to create <code>digest</code>.
     Hash hash;
 
-    // The DER encoding of a X.509 client certificate. The extension must sign
-    // |digest| using the associated private key.
+    // The DER encoding of a X.509 certificate. The extension must sign
+    // <code>digest</code> using the associated private key.
     ArrayBuffer certificate;
   };
 
-  // Either |error| or |signature| and not both must be set.
-  dictionary SignatureDetails {
-    // If the signature of the digest could not be calculated, this field must
-    // be set.
-    DOMString? error;
+  // The callback provided by the extension that Chrome uses to report back
+  // rejected certificates. See <code>CertficiatesCallbac</code>.

[emaxx, 2015/09/07 17:35:14]

Typos in "CertificatesCallback".

[bartfab (slow), 2015/09/08 14:55:17]

Can you use a $(ref:) here instead of <code></code>?

[pneubeck (no reviews), 2015/09/08 15:30:50]

Done.

[pneubeck (no reviews), 2015/09/08 15:30:51]

I don't know, as this comment currently does not appear in the generated
documentation.

+  callback ResultCallback = void (ArrayBuffer[] rejectedCertificates);
 
-    // If no error occurred, this field must be set to the signature of the
-    // digest using the private the of the requested client 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 MD5_SHA1 hash must be signed, the extension must not
-    // prepend a DigestInfo prefix but only add PKCS#1 padding.
-    ArrayBuffer? signature;
-  };
-
-  callback DoneCallback = void ();
-  callback SignCallback = void(SignatureDetails reply, DoneCallback callback);
+  // 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 <code>MD5_SHA1</code> hash must be signed, the extension

[bartfab (slow), 2015/09/08 14:55:17]

Nit: s/must/is to/ (to avoid double "must" in one sentence)

[pneubeck (no reviews), 2015/09/08 15:30:51]

Done.

+  // must not prepend a DigestInfo prefix but only add PKCS#1 padding.
+  // If an error occurred, this callback should be called without signature.
+  callback SignCallback = void (optional ArrayBuffer signature);
 
-  // Notifies Chrome that this extension is capable of responding to signing
-  // requests for the certificates listed in |certificates|. The list must
-  // only contain certificates for which the extension can sign data
-  // using the associated private key.
+  // 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, DoneCallback callback);
+      void (CertificateInfo[] certificates, ResultCallback callback);
 
   interface Events {
     // This event fires every time the browser requests the current list of
     // certificates provided by this extension. The extension must call
-    // |callback| exactly once with the current list of certificates.
-    static void onClientCertificatesRequested(CertificatesCallback callback);
+    // <code>reportCallback</code> exactly once with the current list of
+    // certificates.
+    static void onCertificatesRequested(CertificatesCallback reportCallback);
 
     // This event fires every time the browser needs to sign a message using a
-    // certificate provided by this extension using |publishClientCertificates|.
-    // The extension must sign the data in |request| using the appropriate
-    // algorithm and private key and return it by calling |callback|. |callback|
-    // must be called exactly once.
+    // 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.

[bartfab (slow), 2015/09/08 14:55:17]

Nit: s:|:<code>: s:|:</code>:

[pneubeck (no reviews), 2015/09/08 15:30:50]

Nope. the |argument_name| syntax is expected by the documentation generator.

     static void onSignDigestRequested(SignRequest request,
-                                      SignCallback callback);
+                                      SignCallback reportCallback);
   };
 };