Bug 879861 - Part 1: SecureElement APIs WebIDL. r=ehsan, r=smaug
authorSiddartha Pothapragada <Siddartha.Pothapragada@telekom.com>
Wed, 04 Feb 2015 06:56:00 -0500
changeset 256097 e014c9f1d2fb798941a57000a08cd23d0c12dfc2
parent 256096 bd459caf1f9a0458aa42c010c313d3e3a2aa0771
child 256098 7b877b26ddee6783c94825231243b9ba025bf58d
push id4610
push userjlund@mozilla.com
push dateMon, 30 Mar 2015 18:32:55 +0000
treeherdermozilla-beta@4df54044d9ef [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersehsan, smaug
bugs879861
milestone38.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 879861 - Part 1: SecureElement APIs WebIDL. r=ehsan, r=smaug
dom/webidl/SecureElement.webidl
dom/webidl/SecureElementManager.webidl
new file mode 100644
--- /dev/null
+++ b/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;
+
+};
+
new file mode 100644
--- /dev/null
+++ b/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();
+};