Implementation for chrome.certificateProvider.requestPin/stopPinRequest

chrome/common/extensions/api/certificate_provider.idl

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // 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 {
   enum Hash {
     MD5_SHA1,
     SHA1,
     SHA256,
     SHA384,
     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.
     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;
   };
 
   [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;
 
     // 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, PIN or PUK. Default is PIN.

[Devlin, 2016/09/21 17:31:20]

remove ', PIN or PUK' - this is implied by the enum values.

[igorcov, 2016/10/17 14:42:20]

Done.

+    PinRequestType? requestType;
+
+    // The error template displayed for user. This should be set if the previous

[Devlin, 2016/09/21 17:31:20]

display for -> displayed to the

Also, what is an error template?

[igorcov, 2016/10/17 14:42:20]

The error template is the text displayed in the dialog as an error
with some possible variables to be filled like attempts_left.

We defined the templates because don't want to allow the extensions
to show any text they want as an error (for security reasons).

+    // 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 will be called with

[Devlin, 2016/09/21 17:31:20]

what will call stopPinRequest?

[igorcov, 2016/10/17 14:42:20]

Extension is expected to make that call. Included this info in the comment.

+    // 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. If some error occurred, it will be provided using

[Devlin, 2016/09/21 17:31:20]

We typically don't explicitly document that runtime.lastError will be set, since
that's the assumption.  Also, this seems like a list that's doomed to get out of
date with the rest of the code.  I'd probably just remove this.

[igorcov, 2016/10/17 14:42:20]

Done.

+    // chrome.runtime.lastError variable. The error can be:
+    // OTHER_FLOW_IN_PROGRESS - A request PIN flow is ongoing already.
+    // 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

[Devlin, 2016/09/21 17:31:20]

Callback types don't need documentation; their use in the function is
documentation itself.

[igorcov, 2016/10/17 14:42:20]

Done.

+  // 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);
 
   // 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 is to be signed, the extension
   // must not prepend a DigestInfo prefix but only add PKCS#1 padding.
@@ skipping 20 matching lines @@
     // 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.
     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.

[Devlin, 2016/09/21 17:31:20]

while other -> while another

[igorcov, 2016/10/17 14:42:20]

Done.

+    // It's extension's responsibility to try again later if other flow is in

[Devlin, 2016/09/21 17:31:20]

It's extension's -> It is the extension's

if other -> if another

[igorcov, 2016/10/17 14:42:20]

Done.

+    // progress.
+    static void requestPin(RequestPinDetails details,
+                           RequestPinCallback callback);
+
+    // Stops the pin request started by $(ref:requestPin) function.

[Devlin, 2016/09/21 17:31:20]

by $ -> by the $

[igorcov, 2016/10/17 14:42:20]

Done.

+    static void stopPinRequest(StopPinRequestDetails details,
+                               StopPinRequestCallback callback);
+  };
 };