IDL implementation of requestPin API in certificateProvider.

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 4062d0445b3a48d68be9c5f97b3a383d372e9416..9d776847fe92c7b94f31922a91e6e54d171d3d9c 100644
--- a/chrome/common/extensions/api/certificate_provider.idl
+++ b/chrome/common/extensions/api/certificate_provider.idl
@@ -13,6 +13,18 @@ namespace certificateProvider {
     SHA512
   };
 
+  enum RequestType {
+    PIN,
+    PUK
+  };
+
+  enum ErrorType {
+    INVALID_PIN,
+    INVALID_PUK,
+    MAX_ATTEMPTS_EXCEEDED,
+    UNKNOWN_ERROR
+  };
+
   [noinline_doc] dictionary CertificateInfo {
     // Must be the DER encoding of a X.509 certificate. Currently, only
     // certificates of RSA keys are supported.
@@ -25,6 +37,9 @@ namespace certificateProvider {
   };
 
   [noinline_doc] dictionary SignRequest {
+    // The unique ID to be used if extension will require a PIN.
+    long signRequestId;

[stevenjb, 2016/07/25 18:57:57]

Nice solution, thanks. This needs to be optional though, right?

[igorcov1, 2016/07/26 10:21:11]

I think Chrome should always include this parameter as it doesn't know at this
point if PIN will be required or not. Don't see any scenario when this could be
skipped.

[stevenjb, 2016/07/26 16:10:15]

Making this required would break any existing usage.

[igorcov1, 2016/07/26 17:45:29]

I don't see how it would break anything existent. It's an event, so the
extension just receives additional parameter in request. The old implementations
should ignore it. There are often changes in Chrome that add mandatory
parameters in events, for example this CL: http://crrev.com/1857033002

[stevenjb, 2016/07/28 00:41:56]

I guess that JS being JS it won't break the code. It might break Closure
compilation, but probably mostly not.

+
     // The digest that must be signed.
     ArrayBuffer digest;
 
@@ -36,6 +51,37 @@ namespace certificateProvider {
     ArrayBuffer certificate;
   };
 
+  dictionary RequestPinDetails {
+    // The ID given by Chrome when in SignRequest.
+    long signRequestId;
+
+    // The type of code requested, PIN or PUK. Default is PIN.
+    RequestType? requestType;
+
+    // The error message to display for user. Default - no error.

[stevenjb, 2016/07/25 18:57:57]

The error request would be set if a previous failed, correct? We should document
that.

[igorcov1, 2016/07/26 10:21:11]

Done.

+    ErrorType? errorType;
+
+    // The number of attempts left.

[stevenjb, 2016/07/25 18:57:57]

We should expand this comment, e.g.:
// 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
StopPinRequestDetails will be called with errorType = MAX_ATTEMPTS_EXCEEDED when
the number of pin requests is exceeded.

[igorcov1, 2016/07/26 10:21:11]

Updated, thanks.

+    long? attemptsLeft;
+  };
+
+  dictionary StopPinRequestDetails {

[stevenjb, 2016/07/25 18:57:57]

We should probably pass signRequestId here.

[igorcov1, 2016/07/26 10:21:11]

At this point we can use the active extension_id (the one that initiated the
flow) to check that it matches the extension that asked to stop the request.
This allows us to validate the request without the ID.

[stevenjb, 2016/07/26 16:10:15]

Conceivably couldn't the extension issue more than one request? (Chrome would
presumably handle one at a time). If we intend to disallow that we should
document that and add an error code.

[emaxx, 2016/07/26 17:36:21]

+1 for passing request id here.

Even though our current plan is to disallow simultaneous requests, requiring to
pass the id here leaves us with more choices for the future changes. Also this
would make the API a bit more symmetric.

[igorcov1, 2016/07/26 17:45:29]

Yes, we don't plan to keep a queue of requests. If active request is on going,
all the new requests are rejected immediately. Added this in comments to
PinResponseDetails and to requestPin to clarify this.

[igorcov1, 2016/07/27 11:58:20]

Added the ID here and made the details parameter in stopPinRequest mandatory.

+    ErrorType? errorType;
+  };
+
+  dictionary PinResponseDetails {
+    DOMString? userInput;

[stevenjb, 2016/07/25 18:57:57]

This should also provide an error value, e.g. 'REQUEST_ID_NOT_FOUND',
'USER_CANCELED', 'UNAVAILABLE' (in case we have scenarios where we can't
actually show a dialog, even though we currently don't expect that to be the
case), 'BUSY' (in case the UI is already showing a different system modal
dialog).

[igorcov1, 2016/07/26 10:21:11]

Good point, but this is intended to be achieved using chrome.runtime.lastError
variable. As that seems to be the standard way to notify about the errors in
Chrome API.

[stevenjb, 2016/07/26 16:10:15]

Fair point. We should document that, and define what the response looks like on
failure (empty?).

[igorcov1, 2016/07/26 17:45:29]

Done.

+  };
+
+  // A callback called when the dialog gets 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).
+  callback RequestPinCallback = void (optional PinResponseDetails details);
+
+  // The callback to be used by Chrome to send to middleware application the
+  // status from their request to close PIN dialog for user.
+  callback StopPinRequestCallback = void ();

[stevenjb, 2016/07/25 18:57:57]

Do we actually need this?

[igorcov1, 2016/07/26 10:21:11]

It might be useful in case the user closes the dialog while the
extension is processing previous input. Using this callback and
chrome.runtime.lastError the extension will be notified that user stopped the
flow manually.

Other case is when extension asks to stop the flow that wasn't initiated at all.
It would provide a way to have more information and better debug abilities when
writing the extension code.

[stevenjb, 2016/07/26 16:10:15]

Acknowledged.

+
   // The callback provided by the extension that Chrome uses to report back
   // rejected certificates. See <code>CertificatesCallback</code>.
   callback ResultCallback = void (ArrayBuffer[] rejectedCertificates);
@@ -76,4 +122,14 @@ namespace certificateProvider {
     static void onSignDigestRequested(SignRequest request,
                                       SignCallback reportCallback);
   };
+
+  interface Functions {
+    // Requests the PIN from user.
+    static void requestPin(RequestPinDetails details,
+                           RequestPinCallback callback);
+
+    // Stops the pin request started by $(ref:requestPin) function.
+    static void stopPinRequest(optional StopPinRequestDetails details,
+                               StopPinRequestCallback callback);
+  };
 };