IDL implementation of requestPin API in certificateProvider.

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 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.
     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 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;
 
     // 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 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);
 
   // 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.
+    static void requestPin(RequestPinDetails details,
+                           RequestPinCallback callback);
+
+    // Stops the pin request started by $(ref:requestPin) function.
+    static void stopPinRequest(optional StopPinRequestDetails details,
+                               StopPinRequestCallback callback);
+  };
 };