Bug 879861 - Part 1: SecureElement APIs WebIDL. r=ehsan, r=smaug

dom/webidl/SecureElement.webidl

@@ -0,0 +1,156 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+ /* Copyright © 2014 Deutsche Telekom, Inc. */
+
+enum SEType {
+  "uicc",
+  "eSE"
+};
+
+enum SEError {
+  "SESecurityError",            // Requested operation does not match the access control rules of the application.
+  "SEIoError",                  // I/O Error while communicating with the secure element.
+  "SEBadStateError",            // Error occuring as a result of bad state.
+  "SEInvalidChannelError",      // Opening a channel failed because no channel is available.
+  "SEInvalidApplicationError",  // The requested application was not found on the secure element.
+  "SEGenericError"              // Generic failures.
+};
+
+enum SEChannelType {
+  "basic",
+  "logical"
+};
+
+// Dictionary that represents an APDU command to be sent to a secure element.
+dictionary SECommand {
+  required octet cla;            // Class Byte
+  required octet ins;            // Instruction Byte
+  required octet p1;             // First Octet of Parameters Byte
+  required octet p2;             // Second Octet of Parameters Byte
+  sequence<octet>? data = null;  // Sequence of octets
+  short le = -1;                 // The length of the expected
+                                 // response data or -1 if none is expected
+};
+
+[CheckPermissions="secureelement-manage",
+ AvailableIn="CertifiedApps",
+ JSImplementation="@mozilla.org/secureelement/reader;1"]
+interface SEReader {
+
+  // 'true' if a secure element is present
+  readonly attribute boolean isSEPresent;
+
+  // Type of SecureElement
+  readonly attribute SEType type;
+
+  /**
+   * Opens a session with the Secure Element.
+   * Note that a reader may have several opened sessions.
+   *
+   * @return If the operation is successful the promise is resolved with an instance of SESession.
+   */
+  [Throws]
+  Promise<SESession> openSession();
+
+  /**
+   * Closes all sessions associated with this Reader and its associated channels.
+   *
+   */
+  [Throws]
+  Promise<void> closeAll();
+};
+
+[CheckPermissions="secureelement-manage",
+ AvailableIn="CertifiedApps",
+ JSImplementation="@mozilla.org/secureelement/session;1"]
+interface SESession {
+
+  // 'reader' that provides this session
+  readonly attribute SEReader reader;
+
+  // Status of current session
+  readonly attribute boolean isClosed;
+
+  /**
+   * Opens a communication logical channel to an application on Secure Element identified by the AID.
+   * The 'aid' can be null for some secure elements.
+   *
+   * @param aid
+   *     Application Identifier of the Card Applet on the secure element.
+   *     If the 'aid' is null :
+   *       For secure element type 'eSE', the default applet is selected.
+   *       For secure element type 'uicc', the request will be immediately rejected.
+   *     Note that the length of 'aid should be between 5 and 16.
+   *
+   * @return If the operation is successful the promise is resolved with an instance of SEChannel.
+   */
+  [Throws]
+  Promise<SEChannel> openLogicalChannel(Uint8Array? aid);
+
+  /**
+   * Close all active channels associated with this session.
+   *
+   */
+  [Throws]
+  Promise<void> closeAll();
+};
+
+[CheckPermissions="secureelement-manage",
+ AvailableIn="CertifiedApps",
+ JSImplementation="@mozilla.org/secureelement/channel;1"]
+interface SEChannel {
+
+  // 'session' obj this channel is bound to
+  readonly attribute SESession session;
+
+  // response to openBasicChannel / openLogicalChannel operation
+  [Constant, Cached] readonly  attribute Uint8Array? openResponse;
+
+  // Status of channel
+  readonly attribute boolean isClosed;
+
+  // Type of channel
+  readonly attribute SEChannelType type;
+
+  /**
+   * Transmits the APDU command to the secure element. This is an atomic operation that transmits
+   * an APDU command (as per ISO7816-4) to the secure element (UICC / eSE). Upon receiving response
+   * to the transmit apdu command, it is propogated to the applications using SEResponse object.
+   *
+   * @param command
+   *     SECommand to be sent to secure element
+   *
+   * @return If success, the promise is resolved with the new created
+   * SEResponse object. Otherwise, rejected with the error of type 'SEError'.
+   */
+  [Throws]
+  Promise<SEResponse> transmit(optional SECommand command);
+
+  /**
+   * Closes the active channel.
+   *
+   */
+  [Throws]
+  Promise<void> close();
+};
+
+[CheckPermissions="secureelement-manage",
+ AvailableIn="CertifiedApps",
+ JSImplementation="@mozilla.org/secureelement/response;1"]
+interface SEResponse {
+  // Response received on this 'channel' object.
+  [Constant] readonly attribute SEChannel channel;
+
+  // First octet of response's status word
+  [Constant] readonly attribute octet        sw1;
+
+  // Second octet of response's status word
+  [Constant] readonly attribute octet        sw2;
+
+  // The response's data field bytes
+  [Cached, Pure] readonly attribute sequence<octet>?  data;
+
+};
+

dom/webidl/SecureElementManager.webidl

@@ -0,0 +1,22 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+ /* Copyright © 2014 Deutsche Telekom, Inc. */
+
+[CheckPermissions="secureelement-manage",
+ AvailableIn="CertifiedApps",
+ JSImplementation="@mozilla.org/secureelement/manager;1",
+ NavigatorProperty="seManager",
+ NoInterfaceObject]
+interface SEManager {
+
+  /**
+   * Retrieves all the readers available on the device.
+   *
+   * @return If success, the promise is resolved to  a sequence
+   *        of SEReaders Otherwise, rejected with an error.
+   */
+  [Throws]
+  Promise<sequence<SEReader>> getSEReaders();
+};