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..1a28971d826d2e6e1d5863848112673582473f3a 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 PinRequestType {
+    PIN,
+    PUK
+  };
+
+  enum PinRequestErrorType {
+    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,10 @@ namespace certificateProvider {
   };
 
   [noinline_doc] 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;
 
@@ -36,6 +52,54 @@ 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.
+    PinRequestType? requestType;
+
+    // The error template displayed for 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 StopPinRequestDetails will be called with
+    // errorType = MAX_ATTEMPTS_EXCEEDED when the number of pin requests is
+    // exceeded.
+    long? attemptsLeft;
+  };
+
+  dictionary StopPinRequestDetails {
+    // The ID given by Chrome when 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. If some error occurred, it will be provided using
+    // chrome.runtime.lastError variable. The error can be:
+    // OTHER_FLOW_IN_PROGRESS - A request PIN flow is ongoing already.

[emaxx, 2016/08/02 17:51:02]

You have to check with the other existing APIs, but I thing
chrome.runtime.lastError.message usually contains a human-readable error. So
it's better not to list here any exact string values.

+    // INVALID_ID - The value of signRequestId is invalid.
+    // UNEXPECTED_ERROR - Some unexpected error occurred in the code.
+    DOMString? userInput;
+  };
+
+  // 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 the extension the status from
+  // their request to close PIN dialog for user.
+  callback StopPinRequestCallback = void ();
+
   // 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 +140,17 @@ namespace certificateProvider {
     static void onSignDigestRequested(SignRequest request,
                                       SignCallback reportCallback);
   };
+
+  interface Functions {
+    // Requests the PIN from user. Only one ongoing request at a time is
+    // allowed. The requests issued while other flow is ongoing are rejected.
+    // It's extension's responsibility to try again later if other flow is in
+    // progress.
+    static void requestPin(RequestPinDetails details,
+                           RequestPinCallback callback);
+
+    // Stops the pin request started by $(ref:requestPin) function.
+    static void stopPinRequest(StopPinRequestDetails details,
+                               StopPinRequestCallback callback);
+  };
 };