001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.jcrmi;
028:
029: import javax.microedition.io.*;
030:
031: /**
032: * This interface defines the Java Card RMI connection which can be used
033: * by J2ME applications to communicate with applications on a smart card
034: * using Java Card RMI protocol.
035: * <h4>
036: * Creating a Java Card RMI Connection
037: * </h4> <p>
038: * Java Card RMI connection is created by passing a generic connection URI
039: * string with a card
040: * application identifier (AID) and optionally the slot in which the
041: * card is inserted,
042: * to the {@link javax.microedition.io.Connector#open Connector.open} method.
043: * For example, the
044: * connection string:
045: * <pre>
046: * jcrmi:0;AID=A0.0.0.67.4.7.1F.3.2C.3
047: * </pre>
048: * indicates that the connection is to be established with
049: * an application having the
050: * AID A0.0.0.67.4.7.1F.3.2C.3 and which resides in
051: * the smart card
052: * inserted in the default slot; that is, slot number 0. If the slot number
053: * is not specified, then the
054: * default slot is assumed.
055: * </p>
056: * <p>
057: * Each Java Card RMI connection has a logical channel reserved
058: * exclusively for it. That is, the channel
059: * is dedicated to the J2ME application and the selected smart card
060: * application until the
061: * connection is closed.
062: * A smart card supporting logical channels allows the host device
063: * to open multiple logical channels to communicate with on-card applications.
064: * Logical channel other than the basic channel must be closed when
065: * corresponding connection is closed. Basic channel or channel 0 must remain
066: * open while the card is powered on.
067: * <p>
068: * Since the basic channel or channel 0 cannot be closed, the
069: * implementation should maintain its availability status.
070: * When a J2ME application asks for a new connection, the implementation
071: * would find out if channel 0 is in use by any application
072: * (native or J2ME application). If channel 0 is not in use, the
073: * implementation would acquire the channel 0 for communicating with the
074: * card application by setting the state of channel 0 to "IN USE". It would
075: * then select the desired application on channel 0. If the selection is
076: * successful, the newly created connection object would be returned to the
077: * J2ME application which can then use it to communicate with the card
078: * application.
079: * If the card application selection fails or the J2ME application calls
080: * <code>close</code> on the connection object, the availability state of
081: * the basic channel will be set back to "AVAILABLE" meaning that the basic
082: * channel is available for use.
083: * </p>
084: * <p>
085: * When a J2ME application requests a connection to the card and channel 0
086: * is in use by some other application (native or J2ME application), the
087: * implementation sends a <code>MANAGE CHANNEL</code> command to the
088: * card requesting a logical channel for the
089: * new connection. If there is a logical channel available, the card
090: * returns with the logical channel number which will be used by the new
091: * connection. The implementation would select the desired application on
092: * the newly allocated logical channel. If the selection is successful,
093: * the implementation returns the newly created connection object to
094: * the J2ME application which can then use it for communicating with the card
095: * application. If application selection fails or the J2ME application calls
096: * <code>close()</code> method to close the connection with
097: * the card application, the implementation will send a
098: * <code>MANAGE CHANNEL</code> command to
099: * the card to close the channel. The channel will then be available for use by
100: * other applications.
101: * </p>
102: * <p>
103: * In the case when there are no logical channels available or the
104: * card does not
105: * support logical channels, the card will return an error. An
106: * <code>IOException</code> will be thrown and no connection object will be
107: * returned to the J2ME application.
108: * </p>
109: * <h4>
110: * Invoking Methods on Remote Objects in Java Card
111: * </h4>
112: * <p>Once the Java Card RMI connection is created, the J2ME application
113: * can obtain an initial remote reference object using
114: * {@link #getInitialReference() getInitialReference}. Using this reference,
115: * the application can invoke
116: * methods of an initial remote object on the card and obtain other
117: * references to remote objects.</p>
118: *
119: * <h4>
120: * Communicating With Multiple Smart Card Applications
121: * </h4>
122: * <p>
123: * A J2ME application may connect and communicate with multiple smart card
124: * applications interchangeably. To achieve this the
125: * J2ME application can repeat the procedure mentioned above to create
126: * corresponding connection objects.
127: * </p>
128: * <h4>
129: * Closing a JavaCardRMIConnection
130: * </h4>
131: * <p>A J2ME application can call
132: * <code>javax.microedition.io.Connection.close()</code> on the
133: * connection object to terminate the connection and release the
134: * logical channel. The logical channel is free to be
135: * used by other applications. If an application terminates without
136: * closing an open connection, the implementation SHOULD perform the
137: * close operation automatically.</p>
138: *
139: * <h4>
140: * Exceptions that can be Thrown During Connection Establishment
141: * </h4>
142: * <p>If the card slot does not exist, or if the card
143: * is not inserted or powered on, or if application selection is failed
144: * a <code>ConnectionNotFoundException</code>
145: * must be thrown.</p>
146: * <p>If the J2ME application is not allowed to access the application
147: * with the specified application identifier a
148: * <code>SecurityException</code> is thrown.</p>
149: * <p>If there is no logical channel available to
150: * establish a connection, an <code>IOException</code>
151: * must be thrown.</p>
152: * <p>If initial remote reference object can not be created
153: * a <code>RemoteException</code> must be thrown.</p>
154: * <p>If a card is removed after the connection is established and then
155: * re-inserted,
156: * the J2ME application must re-establish the connection and get a new
157: * connection object. Any attempts to invoke remote method using the
158: * connection object created before removal of the card will result in
159: * <code>RemoteException</code> being thrown.
160: * </p>
161: * <h3>
162: * BNF Format for Connector.open() string
163: * </h3>
164: * <p>
165: * The URI MUST conform to the BNF syntax specified below. If the URI
166: * does not conform to this syntax, an <code>IllegalArgumentException</code>
167: * is thrown.
168: * </p>
169: * <table BORDER="1">
170: * <tr>
171: * <td><<em>JCRMI_connection_string</em>> </td>
172: * <td>::= "<strong>jcrmi:</strong>"<
173: * <em>cardApplicationAddress</em>> </td>
174: * </tr>
175: *
176: * <tr>
177: * <td><<em>cardApplicationAddress</em>> </td>
178: * <td>::= <i>[slot];<<em>AID_string</em>> </i> </td>
179: * </tr>
180: *
181: * <tr>
182: * <td><<em>slot</em>> </td>
183: * <td>::= <i>smart card slot.</i> (optional. Hexadecimal number
184: * identifying the smart card slot. Default slot assumed if left empty)
185: * </td>
186: * </tr>
187: *
188: * <tr>
189: * <td><<em>AID_string</em>> </td>
190: * <td>::= "AID="<i><AID></i> </td>
191: * </tr>
192: *
193: * <tr>
194: * <td><<em>AID</em>> </td>
195: * <td>::= <i><5 - 16 bytes> </i>
196: * <br> An AID (Application Identifier) uniquely identifies a smart card
197: * application. It is represented by 5 to 16 hexadecimal bytes where each
198: * byte value is seperated by a ".".</td>
199: * </tr>
200: * </table>
201: *
202: * <h3>Smart Card Slot Discovery Mechanism</h3>
203: * <p> J2ME devices may support a variable number of security elements
204: * (usually smart card slots). Some security elements are permanently
205: * attached to the device (e.g. a soldered chip), others are removable.
206: * The removable security elements may be cold-swappable, requiring
207: * the battery to be removed before the security element can be exchanged
208: * (e.g. a MiniSIM slot hidden behind the battery). Other removable
209: * security elements can be inserted and removed while the system is
210: * running. (e.g. a hot-swappable smart card reader). </p>
211: * <p>
212: * A system property is defined to indicate the names of the
213: * smart card slots. The property can be queried through the
214: * <code>System.getProperty()</code> method using the key
215: * <em>microedition.smartcardslots</em>. The value returned
216: * is a comma-separated list of the smart card slots which can
217: * be used in the <code>Connector.open()</code> string to identify the
218: * specific smart card slot.
219: * </p>
220: * <p>
221: * If the platform includes a (U)SIM card, it MUST be in slot 0.
222: * </p>
223: * <p>
224: * The logical slot names include the slot number and a descriptor
225: * indicating the type of the slot. For cold-swappable slots the
226: * letter 'C' is appended to the slot number. For hot-swappable slots
227: * the letter 'H' is appended to the slot number. The slot descriptors (the
228: * letter 'C' and 'H' appended to the slot number) cannot be passed as part
229: * of the URI to open a connection to the smart card application. The J2ME
230: * application MUST remove the descriptor from the logical slot name and
231: * only use the slot number in URI to identify the specific smart card
232: * slot.
233: * </p>
234: * <p> A typical configuration for a cold-swappable SIM card and
235: * a hot-swappable removable card would be: </p>
236: * <pre><code> <br> microedition.smartcardslots: 0C,1H<br></code></pre>
237: *
238: *
239: *
240: * <h3>
241: * Example
242: * </h3>
243: *
244: * <p>
245: * The following example shows how a <code>JavaCardRMIConnection</code>
246: * can be used to access a smart card application.
247: * </p>
248: * <pre>
249: * try {
250: * JavaCardRMIConnection connection = (JavaCardRMIConnection)
251: * Connector.open("jcrmi:0;AID=A0.0.0.67.4.7.1F.3.2C.3");
252: *
253: * Counter counter = (Counter) connection.getInitialReference();
254: * ...
255: * currentValue = counter.add(50);
256: * ...
257: * connection.close();
258: * } catch (Exception e) {
259: * ...
260: * }
261: * </pre>
262: * <h3>
263: * Note regarding PIN-related methods
264: * </h3>
265: * <p>
266: * A platform should implement the PIN entry UI in such a way that:
267: * <ul>
268: * <li>
269: * the UI is distinguishable from a UI generated by external sources
270: * (for example J2ME applications)
271: * </li>
272: * <li>
273: * external sources are not able to retrieve or insert PIN data
274: * </li>
275: * <li>
276: * If the static access control mechanism is implemented, the PIN
277: * related methods MUST be implemented as specified in the static access
278: * control mechanism. For further details see Appendix A (Recommended
279: * Security Element Access Control).
280: * </li>
281: * </ul>
282: * </p>
283: */
284:
285: public interface JavaCardRMIConnection extends Connection {
286: /**
287: * This status is returned to the calling J2ME application
288: * if the operation for PIN verification/change/disable/
289: * enable/unblock was not successful because the user
290: * cancelled the PIN entry request.
291: */
292: public static final short PINENTRY_CANCELLED = -1;
293:
294: /**
295: * Returns the stub object for an initial remote reference.
296: * @return the initial remote reference
297: */
298: java.rmi.Remote getInitialReference();
299:
300: /**
301: * A call to <code>enterPin</code> method pops up a UI that requests
302: * the PIN
303: * from the user. The pinID field indicates which PIN must be
304: * requested from the user. The user can either cancel the request
305: * or continue. If the user enters the PIN and chooses to continue,
306: * The implementation is responsible for
307: * presenting the PIN entered by the user to the card for verification.
308: * If padding is required for the PIN, the implementation is responsible
309: * for providing appropriate padding.
310: * @param pinID the type of PIN the implementation is suppose to prompt
311: * the user to enter.
312: * @return PINENTRY_CANCELLED if the user cancelled the PIN entry
313: * request or the value returned by the remote method.
314: * @exception java.rmi.RemoteException is thrown if the PIN could
315: * not be communicated to the card or an exception is thrown
316: * by the card in response to the PIN entry.
317: * @exception SecurityException is thrown if the J2ME application does
318: * not have appropriate rights to ask for PIN verification.
319: * @exception UnsupportedOperationException is thrown if the
320: * implementation does not support this method.
321: */
322: short enterPin(int pinID) throws java.rmi.RemoteException;
323:
324: /**
325: * A call to <code>changePin</code> method pops up a UI that requests
326: * the user for an old or existing PIN value and the new PIN value to
327: * change the value of the PIN. The pinID field indicates which PIN is
328: * to be changed. The user can either cancel the request
329: * or continue. If the user enters the PIN values and chooses to continue
330: * the implementation is responsible for presenting
331: * the old and new values of the PIN to the card.
332: * If padding is required for the PIN, the implementation is responsible
333: * for providing appropriate padding.
334: * @param pinID the type of PIN the implementation is suppose to prompt
335: * the user to change.
336: * @return PINENTRY_CANCELLED if the user cancelled the PIN entry
337: * request or the value returned by the remote method.
338: * @exception java.rmi.RemoteException is thrown if the PIN could
339: * not be communicated to the card or an exception is thrown
340: * by the card in response to the PIN entry.
341: * @exception SecurityException is thrown if the J2ME application does
342: * not have appropriate rights to ask for changing the PIN value.
343: * @exception UnsupportedOperationException is thrown if the
344: * implementation does not support this method.
345: */
346: short changePin(int pinID) throws java.rmi.RemoteException;
347:
348: /**
349: * A call to <code>disablePin</code> method pops up a UI that requests
350: * the user to enter the value for the PIN that is to be disabled.
351: * The pinID field
352: * indicates which PIN is to be disabled. The user can
353: * either cancel the request
354: * or continue. If the user enters the PIN and chooses to continue the
355: * implementation is responsible
356: * for presenting the PIN value to the card to disable PIN.
357: * If padding is required for the PIN, the implementation is responsible
358: * for providing appropriate padding.
359: * @param pinID the type of PIN the implementation is required to prompt
360: * the user to enter.
361: * @return PINENTRY_CANCELLED if the user cancelled the PIN entry
362: * request or the value returned by the remote method.
363: * @exception java.rmi.RemoteException is thrown if the PIN could
364: * not be communicated to the card or an exception is thrown
365: * by the card in response to the PIN entry.
366: * @exception SecurityException is thrown if the J2ME application does
367: * not have appropriate rights to ask for disabling the PIN.
368: * @exception UnsupportedOperationException is thrown if the
369: * implementation does not support this method.
370: */
371: short disablePin(int pinID) throws java.rmi.RemoteException;
372:
373: /**
374: * A call to <code>enablePin</code> method pops up a UI that requests
375: * the user to enter the value for the PIN that is to be enabled.
376: * The pinID field
377: * indicates which PIN is to be enabled. The user can
378: * either cancel the request
379: * or continue. If the user enters the PIN and chooses to continue the
380: * implementation is responsible
381: * for presenting the PIN value to the card for enabling the PIN.
382: * If padding is required for the PIN, the implementation is responsible
383: * for providing appropriate padding.
384: * @param pinID the type of PIN the implementation is required to prompt
385: * the user to enter.
386: * @return PINENTRY_CANCELLED if the user cancelled the PIN entry
387: * request or the value returned by the remote method.
388: * @exception java.rmi.RemoteException is thrown if the PIN could
389: * not be communicated to the card or an exception is thrown
390: * by the card in response to the PIN entry.
391: * @exception SecurityException is thrown if the J2ME application does
392: * not have appropriate rights to ask for enabling the PIN.
393: * @exception UnsupportedOperationException is thrown if the
394: * implementation does not support this method.
395: */
396: short enablePin(int pinID) throws java.rmi.RemoteException;
397:
398: /**
399: * This is a high-level method that lets the J2ME application
400: * ask the user to enter the value for an unblocking PIN,
401: * and the new value for the blocked PIN and send
402: * these to the card.
403: * A call to <code>unblockPin</code> method pops up a UI that requests
404: * the user to enter the value for the unblocking PIN and the
405: * new value for the blocked PIN.
406: * The <code>unblockingPinID</code> field indicates which unblocking
407: * PIN is to be
408: * used to unblock the blocked PIN which is indicated by the field
409: * <code>blockedPinID</code>.
410: * The user can either cancel the request
411: * or continue. If the user enters the PIN values and chooses to continue,
412: * the implementation is responsible
413: * for presenting the PIN values to the card for unblocking the
414: * blocked PIN.
415: * If padding is required for either of the PIN values, the
416: * implementation is responsible for providing appropriate padding.
417: * @param blockedPinID the ID of PIN that is to be unblocked.
418: * @param unblockingPinID the ID of unblocking PIN.
419: * @return PINENTRY_CANCELLED if the user cancelled the PIN entry
420: * request or the value returned by the remote method.
421: * @exception java.rmi.RemoteException is thrown if the PIN could
422: * not be communicated to the card or an exception is thrown
423: * by the card in response to the PIN entry.
424: * @exception SecurityException is thrown if the J2ME application does
425: * not have appropriate rights to ask for unblocking the PIN.
426: * @exception UnsupportedOperationException is thrown if the
427: * implementation does not support this method.
428: */
429: short unblockPin(int blockedPinID, int unblockingPinID)
430: throws java.rmi.RemoteException;
431:
432: }
|