summaryrefslogtreecommitdiff
path: root/dom/webidl/SecureElement.webidl
blob: 1f247aac0afc59ac62c1d20083a5dfacdf93b99d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
/* 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.
  "SENotPresentError",          // Secure Element is not present
  "SEIllegalParameterError",    // Request operation does not have valid parameters.
  "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
};

[Pref="dom.secureelement.enabled",
 ChromeOnly,
 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();
};

[Pref="dom.secureelement.enabled",
 ChromeOnly,
 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();
};

[Pref="dom.secureelement.enabled",
 ChromeOnly,
 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();
};

[Pref="dom.secureelement.enabled",
 ChromeOnly,
 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;

};