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.apdu;
028:
029: import java.io.*;
030: import javax.microedition.io.*;
031:
032: /**
033: * <p>
034: * This interface defines the APDU (Application Protocol Data Unit)
035: * connection. J2ME applications can use this connection
036: * to communicate with applications on a smart card using APDU protocol.
037: * ISO 7816-4 defines the APDU protocol as an application-level
038: * protocol between
039: * a smart card and an application on the device. There are two types
040: * of APDU messages:
041: * command APDUs and response APDUs. Command APDUs are sent to the
042: * smart card by J2ME applications.
043: * Response APDUs are the messages received from the smart cards. For
044: * more information
045: * on APDU protocol see the ISO 7816-4 specifications.
046: * </p>
047: * <p>
048: * Also J2ME applications can use {@link #getATR() getATR} method in this
049: * interface
050: * to obtain information regarding an Answer To Reset (ATR) returned
051: * by the smart card on card reset and use the
052: * {@link #enterPin(int pinID) enterPin}
053: * method to
054: * ask the user to enter PIN which is sent to the smart card for
055: * verification.
056: * </p>
057: * <p>
058: * The methods of APDUConnection are not synchronized. The only method
059: * that can be called safely in another thread is close. When close is
060: * invoked on a connection that is executing in another thread, any
061: * pending I/O method MUST throw an InterruptedIOException. If an
062: * application terminates without calling close on the open connection,
063: * the implementation SHOULD perform the close operation automatically in
064: * order to recover resources, such as the logical channel.
065: * </p>
066: * <h4>
067: * Creating an APDU Connection
068: * </h4>
069: * <p>
070: * An APDU connection is created by passing a generic connection URI
071: * string with a card
072: * application identifier (AID) and optionally the slot in which the
073: * card is inserted,
074: * to the {@link javax.microedition.io.Connector#open Connector.open} method.
075: * For example, the
076: * connection string:</p>
077: * <pre>
078: * apdu:0;target=A0.0.0.67.4.7.1F.3.2C.3
079: * </pre>
080: * <p>indicates that the connection is to be established with a target
081: * application having
082: * AID A0.0.0.67.4.7.1F.3.2C.3, which resides in
083: * the smart card
084: * inserted in the default slot; that is, slot number 0. If the slot number
085: * is not specified, then the
086: * default slot is assumed.
087: * </p>
088: *
089: * <p>
090: * Each APDU connection has a logical channel reserved exclusively
091: * for it. That is, the channel
092: * is dedicated to the J2ME application and the selected smart card
093: * application until the
094: * connection is closed.
095: * A smart card supporting logical channels allows the host device
096: * to open multiple logical channels to communicate with on-card applications.
097: * Logical channels other than the basic channel may be closed when
098: * the connection is closed. Basic channel or channel 0 has to remain
099: * open while the card is powered on.
100: * <p>
101: * Since the basic channel or channel 0 cannot be closed, the
102: * terminal should maintain its availability status.
103: * When a J2ME application asks for a new connection, the implementation
104: * would find out if channel 0 is in use by any application
105: * (native or J2ME application). If channel 0 is not in use, the
106: * implementation would acquire the channel 0 for communicating with the
107: * card application by setting the state of channel 0 to "IN USE". It would
108: * then select the desired application on channel 0. If the selection is
109: * successful, the newly created connection object would be returned to the
110: * J2ME application which can then use it to communicate with the card
111: * application.
112: * If the card application selection fails or the J2ME application calls
113: * <code>close</code> on the connection object, the availability state of
114: * the basic channel will be set back to "AVAILABLE" meaning that the basic
115: * channel is available for use.
116: * </p>
117: * <p>
118: * When a J2ME application requests a connection to the card and channel 0
119: * is in use by some other application (native or J2ME application), the
120: * implementation sends a <code>MANAGE CHANNEL</code> command to the
121: * card requesting a logical channel for the
122: * new connection. If there is a logical channel available, the card
123: * returns with the logical channel number which will be used by the new
124: * connection. The implementation would select the desired application on
125: * the newly allocated logical channel. If the selection is successful,
126: * the implementation returns the newly created connection object to
127: * the J2ME application which can then use it for communicating with the card
128: * application. If application selection fails or the J2ME application calls
129: * <code>close()</code> method to close the connection with
130: * the card application, the implementation will send a
131: * <code>MANAGE CHANNEL</code> command to
132: * the card to close the channel. The channel will then be available for use by
133: * other applications.
134: * </p>
135: * <p>
136: * In the case when there are no logical channels available or the
137: * card does not
138: * support logical channels, the card will return an error. An
139: * <code>IOException</code> will be thrown and no connection object will be
140: * returned to the J2ME application.
141: * </p>
142: * <h4>
143: * Communicating With Smart Card Applications
144: * </h4>
145: * <p>
146: * Once an APDU connection is created, the J2ME application can use the
147: * {@link #exchangeAPDU(byte[]) exchangeAPDU}
148: * method to send command APDUs and receive response APDUs to and from
149: * the card.
150: * J2ME applications cannot use <code>exchangeAPDU</code>
151: * to send card
152: * application selection APDUs or channel management APDUs. Card
153: * application selection is allowed only by calling <code>Connector.open</code>
154: * method with the URI
155: * string described above and logical channels management is defined by
156: * API functionality.
157: * </p>
158: *
159: * <p>
160: * There may be several APDU connections open at the same time using
161: * different logical channels with the same card. However, since APDU
162: * protocol is synchronous, there can be no interleaving of command and
163: * their response APDUs across logical channels. Between the receipt of
164: * the command APDU and the sending of the response APDU to that command,
165: * only one logical channel is active.
166: * For T=0 protocol, for case 4 and case 2 command APDUs the card may
167: * respond with '61 XX' or '6C XX'. These special cases MUST be handled by
168: * the implementation in the following manner:
169: * <ul>
170: * <li>
171: * '61 XX': The implementation MUST send GET RESPONSE to
172: * the card to get the response data before any other command is sent.
173: * </li>
174: * <li>
175: * '6C XX': The implementation MUST resend the command after setting Le equal
176: * to XX received from the card before any other command is sent.
177: * </li>
178: * </ul>
179: * In both the cases discussed above, the implementation MUST make sure that
180: * between sending the command APDU, receiving status word '61 XX' or
181: * '6C XX', and sending GET RESPONSE or resending the command APDU with Le
182: * set to XX respectively, there MUST not be any other APDU exchange on any
183: * logical channel with the card. In case the status word '61 XX' is
184: * received multiple times successively from the card, the implementation
185: * must accumulate
186: * all the response data received from the card before returning it to the
187: * J2ME application. J2ME applications MUST remain oblivious of
188: * the exchanges mentioned above and should only get the response received
189: * as a result of the above operations.
190: * </p>
191: * <h4>
192: * Communicating With Multiple Smart Card Applications
193: * </h4>
194: * <p>
195: * A J2ME application may connect and communicate with multiple smart card
196: * applications interchangeably or have multiple connections with the
197: * same card application, if the card application is multi-selectable. To
198: * achieve this the
199: * J2ME application can repeat the procedure mentioned above to create
200: * corresponding connection objects.
201: * </p>
202: * <h4>
203: * Closing an APDUConnection
204: * </h4>
205: * <p>
206: * J2ME application can call
207: * <code>javax.microedition.io.Connection.close()</code> on an APDU
208: * connection to close the
209: * connection. If the connection was established on channel other than
210: * channel 0, this action closes the channel consequently deselecting
211: * the card application and making the channel available for use
212: * by other applications. In case of channel 0, the channel is marked
213: * as available for use by other applications. The application selected
214: * on channel 0 is not deselected at the time the connection is closed
215: * but remains selected until a new connection is established on
216: * channel 0.
217: * </p>
218: * <h3>Exceptions that can be Thrown During Connection Establishment</h3>
219: * A <code>ConnectionNotFoundException</code> is thrown in any of the following
220: * situations:
221: * <p>
222: * <ul>
223: * <li>if the card slot does not exist</li>
224: * <li>if the card is not inserted or powered on</li>
225: * <li>if the card application selection fails because
226: * the card application with the specified application
227: * identifier does not exist or because the card application
228: * refused selection</li>
229: * </ul>
230: * </p>
231: * <p>If the card application selection fails because the J2ME application
232: * is not allowed to access the application with the specified application
233: * identifier a <code>SecurityException</code> is thrown.</p>
234: *
235: * <p>In cases such as when there is no logical channel available to
236: * establish a connection, an <code>IOException</code>
237: * will be thrown and a connection object will not be returned to the
238: * J2ME application.</p>
239: * <p>
240: * If a card is removed after the connection is established and then
241: * re-inserted,
242: * the J2ME application will have to re-establish the connection and get a new
243: * connection object. Any attempts to exchange APDUs using the connection
244: * object created before removal of the card will result in
245: * <code>InterruptedIOException</code> being thrown.
246: * </p>
247: *
248: * <h3>
249: * BNF Format for Connector.open() string
250: * </h3>
251: * <p>
252: *
253: * The URI MUST conform to the BNF syntax specified below. If the URI
254: * does not conform to this syntax, an <code>IllegalArgumentException</code>
255: * is thrown.
256: * </p>
257: * <table BORDER="1">
258: * <tr>
259: * <td><<em>APDU_connection_string</em>> </td>
260: * <td>::= "<strong>apdu:</strong>"<<em>targetAddress</em>></td>
261: * </tr>
262: *
263: * <tr>
264: * <td><<em>targetAddress</em>> </td>
265: * <td>::= <i>[slot];target </i> </td>
266: * </tr>
267: *
268: * <tr>
269: * <td><<em>slot</em>> </td>
270: * <td>::= <i>smart card slot number.</i> (optional. Hexadecimal number
271: * identifying the smart card slot. Default slot assumed if left empty)
272: * </td>
273: * </tr>
274: * <tr>
275: * <td><<em>target</em>> </td>
276: * <td>::= "target="<i><<em>AID</em>>|"SAT"</i> </td>
277: * </tr>
278: * <tr>
279: * <td><<em>AID</em>> </td>
280: * <td>::= <i>< 5 - 16 bytes > </i>
281: * <br> An AID (Application Identifier) uniquely identifies a smart card
282: * application. It is represented by 5 to 16 hexadecimal bytes where each
283: * byte value is seperated by a ".".</td>
284: * </tr>
285: *
286: * </table>
287: * <h3>Smart Card Slot Discovery Mechanism</h3>
288: * <p> J2ME devices may support a variable number of security elements
289: * (usually smart card slots). Some security elements are permanently
290: * attached to the device (e.g. a soldered chip), others are removable.
291: * The removable security elements may be cold-swappable, requiring
292: * the battery to be removed before the security element can be exchanged
293: * (e.g. a MiniSIM slot hidden behind the battery). Other removable
294: * security elements can be inserted and removed while the system is
295: * running. (e.g. a hot-swappable smart card reader). </p>
296: * <p>
297: * A system property is defined to indicate the names of the
298: * smart card slots. The property can be queried through the
299: * <code>System.getProperty()</code> method using the key
300: * <em>microedition.smartcardslots</em>. The value returned
301: * is a comma-separated list of the smart card slots which can
302: * be used in the <code>Connector.open()</code> string to identify the
303: * specific smart card slot.
304: * </p>
305: * <p>
306: * If the platform includes a (U)SIM card, it MUST be in slot 0.
307: * </p>
308: * <p>
309: * The logical slot names include the slot number and a descriptor
310: * indicating the type of the slot. For cold-swappable slots the
311: * letter 'C' is appended to the slot number. For hot-swappable slots
312: * the letter 'H' is appended to the slot number. The slot descriptors (the
313: * letter 'C' and 'H' appended to the slot number) cannot be passed as part
314: * of the URI to open a connection to the smart card application. The J2ME
315: * application MUST remove the descriptor from the logical slot name and
316: * only use the slot number in URI to identify the specific smart card
317: * slot.
318: * </p>
319: * <p> A typical configuration for a cold-swappable SIM card and
320: * a hot-swappable removable card would be: </p>
321: * <pre><code> <br> microedition.smartcardslots: 0C,1H<br></code></pre>
322: *
323: * <h3>
324: * Support for (U)SIM Application Toolkit
325: * </h3>
326: * <p>
327: * If an implementation allows J2ME applications to communicate with (U)SAT,
328: * support for communication with (U)SAT should be implemented as specified
329: * below.</p>
330: * <p>
331: * The APDUConnection can be used to communicate with (U)SAT applications on
332: * channel 0.
333: * The following sections describe the constraints and methods
334: * in supporting communicating with (U)SAT applications.
335: * </p>
336: * <h4>
337: * Technical Constraints
338: * </h4>
339: * <ul>
340: * <li>The operator domain has full and exclusive access to this connection.
341: * </li>
342: * <li>Only ENVELOPE APDUs may be sent. For all other APDUs
343: * <code>IllegalArgumentException</code> is thrown.</li>
344: * <li>The class byte MUST be set by the implementation which will be either
345: * A0 or 80 depending on whether the phone is running GSM or UMTS. The class
346: * byte supplied by the J2ME application will be ignored.</li>
347: * <li>In the case when (U)SIM responds with status word '9E XX' or '9F XX',
348: * the behavior of APDUConnection would be the same as when
349: * status word '61 XX' is received from the card.</li>
350: * <li>In the case when (U)SIM responds with status word '62 XX' or '63 XX'
351: * the implementation MUST send GET RESPONSE to the card with Le set to '00'
352: * before any other command is sent. The implementation MUST make
353: * sure that between sending the ENVELOPE APDU, receiving status word '62 XX'
354: * or '63 XX', and sending GET RESPONSE APDU with Le set to '00', there MUST
355: * not be any other APDU exchange on any logical channel with the card.</li>
356: * <li> When the J2ME application sends an ENVELOPE APDU to the (U)SIM, the
357: * native application may be performing a proactive session. In this case the
358: * (U)SIM MUST manage the synchronization issue. The (U)SIM may respond
359: * with status word '93 00' (SIM Application Toolkit is busy) when the
360: * (U)SIM is performing another proactive session.</li>
361: * </ul>
362: * <h4>
363: * Open Connection with (U)SIM, invoke, Close Connection
364: * </h4>
365: * To communicate using (U)SAT commands, a J2ME application performs these
366: * steps:
367: * <ul>
368: * <li>The J2ME application establishes a connection by using the
369: * <code>Connector.open</code> method. To open a connection with a
370: * smart card using (U)SAT commands, the URI string passed to the
371: * <code>Connector.open</code> method MUST be the following:<br>
372: * <br>
373: * "apdu:<slot>;target=SAT"<br>
374: * <br>
375: * Where "apdu" is the protocol and slot is the card slot having
376: * the (U)SIM. The value "SAT" for parameter "target" indicates
377: * that the connection is to be established with (U)SAT.<br>
378: * <br>
379: * The implementation MUST use logical channel 0 even if this channel is
380: * occupied by other applications, and MUST not send a
381: * <code>MANAGE CHANNEL</code> or a <code>SELECT</code> by DF NAME command
382: * to the (U)SIM.</li>
383: * <li>The J2ME application invokes the <code>exchangeAPDU</code> method on
384: * <code>javax.microedition.apdu.APDUConnection</code> interface to send the
385: * ENVELOPE commands. The J2ME application MUST not initiate a proactive
386: * session since if a proactive session is started, it could cause
387: * synchronization problems with other entities talking to the (U)SAT, such as
388: * other J2ME applications or native applications.
389: * If a proactive session is started by the (U)SAT application in
390: * response to an envelope sent by the J2ME application, it is the
391: * responsibility of the J2ME application to deal with it accordingly.<br>
392: * The implementation MUST check the INS byte of the APDU
393: * sent by the J2ME application. If the APDU is not an ENVELOPE
394: * command, the implementation throws an
395: * <code>IllegalArgumentException</code>. The
396: * implementation MUST set the CLA byte corresponding to whether the phone
397: * is running GSM or UMTS.</li>
398: * <li>To close the connection, the J2ME application invokes the close method
399: * on javax.microedition.apdu.APDUConnection. The implementation MUST not send
400: * a CLOSE CHANNEL to the (U)SIM.</li>
401: * </ul>
402: * <h3>
403: * APDUConnection Example
404: * </h3>
405: *
406: * <p>
407: * The following example shows how an <code>APDUConnection</code>
408: * can be used to access a smart card application.
409: * </p>
410: * <pre>
411: * APDUConnection acn = null;
412: * try{
413: * // Create an APDUConnection object
414: * acn = (APDUConnection)
415: * Connector.open("apdu:0;target=A0.0.0.67.4.7.1F.3.2C.3");
416: *
417: * // Send a command APDU and receive response APDU
418: * responseAPDU = acn.exchangeAPDU(commandAPDU);
419: * ...
420: * } catch (IOException e) {
421: * ...
422: * } finally {
423: * ...
424: * if(acn != null) {
425: * // Close connection
426: * acn.close();
427: * }
428: * ...
429: * }
430: * ...
431: *</pre>
432: * <h3>
433: * Note regarding PIN-related methods
434: * </h3>
435: * <p>
436: * A platform should implement the PIN entry UI in such a way that:
437: * <ul>
438: * <li>
439: * the UI is distinguishable from a UI generated by external sources
440: * (for example J2ME applications)
441: * </li>
442: * <li>
443: * external sources are not able to retrieve or insert PIN data
444: * </li>
445: * <li>
446: * If the static access control mechanism is implemented, the PIN
447: * related methods MUST be implemented as specified in the static access
448: * control mechanism. For further details see Appendix A (Recommended
449: * Security Element Access Control).
450: * </li>
451: * </ul>
452: * </p>
453: */
454:
455: public interface APDUConnection extends Connection {
456: /**
457: * Exchanges an APDU command with a smart card application.
458: * This method will put the channel number of the associated channel
459: * in the CLA byte of the command APDU.
460: *
461: * Communication with a smart card device is synchronous.
462: * This method blocks until the response has been received
463: * from the smart card application, or is interrupted.
464: * The interruption could be due to the card being removed from
465: * the slot or operation timeout.
466: *
467: * @param commandAPDU a byte encoded command for the smart card
468: * application
469: * @return a byte encoded response to the requested operation
470: * @throws IllegalArgumentException if:
471: * <ul>
472: * <li><code>commandAPDU</code> parameter is null</li>
473: * <li><code>commandAPDU</code> contains a card application
474: * selection APDU</li>
475: * <li><code>commandAPDU</code> contains a MANAGE CHANNEL</code>
476: * command APDU</li>
477: * <li>if the channel associated with the connection object is
478: * non-zero and the CLA byte has a value other than 0x0X, 0x8X,
479: * 0x9X or 0xAX</li>
480: * <li><code>commandAPDU</code> parameter contains a
481: * malformed APDU</li>
482: * </ul>
483: * @throws InterruptedIOException can be thrown in any of these situations:
484: * <ul>
485: * <li>if this <code>Connection</code>
486: * object is closed during the exchange
487: * operation</li>
488: * <li>if the card is removed after connection is established and
489: * then reinserted, and an APDU exchange is attempted
490: * without re-establishing the connection</li>
491: * </ul>
492: * @exception IOException is thrown if the operation was not
493: * successful because of problems communicating with the card,
494: * or if the connection was already closed
495: * @throws SecurityException if <code>commandAPDU</code> byte array
496: * contains an APDU that the J2ME application is not allowed to send to
497: * the card application.
498:
499: */
500: byte[] exchangeAPDU(byte[] commandAPDU) throws IOException;
501:
502: /**
503: * Returns the <code>Answer To Reset</code> (ATR) message sent
504: * by the smart card in response to the reset operation. ATR is
505: * received from the card when the card is powered up or when it
506: * is reset. The implementation MUST detect the presence of the
507: * card when this method is called and return the value of ATR
508: * if the card is present and <code>null</code> if the card has
509: * been removed.
510: * @return the ATR message if the card is inserted, or <code>null</code>
511: * if the card has been removed or the connection has been closed.
512: */
513: byte[] getATR();
514:
515: /**
516: * This is a high-level method that lets the J2ME application
517: * ask for the user PIN value for PIN verification purposes and
518: * send it to the card.
519: * A call to <code>enterPin</code> method pops up a UI that requests
520: * the PIN from the user. The pinID field indicates which PIN must be
521: * requested from the user. The user can either cancel the request
522: * or continue. If the user enters the PIN and chooses to continue the
523: * implementation is responsible
524: * for presenting the PIN value to the card for verification.
525: * If padding is required for the PIN, the implementation is responsible
526: * for providing appropriate padding.
527: * @param pinID the type of PIN the implementation is supposed to prompt
528: * the user to enter.
529: * @return result of PIN verification which is the status word
530: * received from the smart card in the form of a byte array. This method
531: * would return null if the user cancels the request.
532: * @exception IOException is thrown if the PIN could not be communicated
533: * with the card because the connection was
534: * closed before this method was called or because
535: * of communication problems.
536: * @throws InterruptedIOException can be thrown in any of these situations:
537: * <ul>
538: * <li>if this <code>Connection</code>
539: * object is closed during the exchange
540: * operation</li>
541: * <li>if the card is removed after connection is established and
542: * then reinserted, and PIN entry is attempted
543: * without re-establishing the connection</li>
544: * </ul>
545: * @exception SecurityException is thrown if the J2ME application does
546: * not have appropriate rights to ask for PIN verification.
547: * @exception UnsupportedOperationException is thrown if the
548: * implementation does not support this method.
549: */
550: byte[] enterPin(int pinID) throws IOException;
551:
552: /**
553: * This is a high-level method that lets the J2ME application
554: * ask the user for PIN values for changing the PIN and sending these
555: * values to the card.
556: * A call to <code>changePin</code> method pops up a UI that requests
557: * the user for an old or existing PIN value and the new PIN value
558: * to change the value of the PIN. The pinID field indicates which PIN is
559: * to be changed. The user can
560: * either cancel the request
561: * or continue. If the user enters the PIN values and chooses to
562: * continue the
563: * implementation is responsible
564: * for presenting the PIN value to the card.
565: * If padding is required for the PIN, the implementation is responsible
566: * for providing appropriate padding.
567: * @param pinID the type of PIN the implementation is supposed to prompt
568: * the user to change.
569: * @return result of changing the PIN value which is the status word
570: * received from the smart card in the form of a byte array. This method
571: * would return null if the user cancels the request.
572: * @exception IOException is thrown if the PIN could not be communicated
573: * with the card because the connection was
574: * closed before this method was called or because
575: * of communication problems.
576: * @throws InterruptedIOException can be thrown in any of these situations:
577: * <ul>
578: * <li>if this <code>Connection</code>
579: * object is closed during the exchange
580: * operation</li>
581: * <li>if the card is removed after connection is established and
582: * then reinserted, and attempt is made to change PIN
583: * without re-establishing the connection</li>
584: * </ul>
585: * @exception SecurityException is thrown if the J2ME application does
586: * not have appropriate rights to ask for changing the PIN value.
587: * @exception UnsupportedOperationException is thrown if the
588: * implementation does not support this method.
589: */
590: byte[] changePin(int pinID) throws IOException;
591:
592: /**
593: * This is a high-level method that lets the J2ME application
594: * ask for the user PIN value for the PIN that is to be
595: * disabled and send it to the card.
596: * A call to <code>disablePin</code> method pops up a UI that requests
597: * the user to enter the value for the PIN that is to be disabled.
598: * The pinID field
599: * indicates which PIN is to be disabled. The user can
600: * either cancel the request
601: * or continue. If the user enters the PIN and chooses to continue the
602: * implementation is responsible
603: * for presenting the PIN value to the card to disable PIN.
604: * If padding is required for the PIN, the implementation is responsible
605: * for providing appropriate padding.
606: * @param pinID the type of PIN the implementation is required to prompt
607: * the user to enter.
608: * @return result of disabling the PIN value which is the status word
609: * received from the smart card in the form of a byte array. This method
610: * would return null if the user cancels the request.
611: * @exception IOException is thrown if the PIN could not be communicated
612: * with the card because the connection was
613: * closed before this method was called or because
614: * of communication problems.
615: * @throws InterruptedIOException can be thrown in any of these situations:
616: * <ul>
617: * <li>if this <code>Connection</code>
618: * object is closed during the exchange
619: * operation</li>
620: * <li>if the card is removed after connection is established and
621: * then reinserted, and attempt is made to disable PIN
622: * without re-establishing the connection</li>
623: * </ul>
624: * @exception SecurityException is thrown if the J2ME application does
625: * not have appropriate rights to ask for disabling the PIN.
626: * @exception UnsupportedOperationException is thrown if the
627: * implementation does not support this method.
628: */
629: byte[] disablePin(int pinID) throws IOException;
630:
631: /**
632: * This is a high-level method that lets the J2ME application
633: * ask for the user to enter the value for the PIN that is to
634: * be enabled and send it to the card.
635: * A call to <code>enablePin</code> method pops up a UI that requests
636: * the user to enter the value for the PIN that is to be enabled.
637: * The pinID field
638: * indicates which PIN is to be enabled. The user can
639: * either cancel the request
640: * or continue. If the user enters the PIN and chooses to continue the
641: * implementation is responsible
642: * for presenting the PIN value to the card for enabling the PIN.
643: * If padding is required for the PIN, the implementation is responsible
644: * for providing appropriate padding.
645: * @param pinID the type of PIN the implementation is required to prompt
646: * the user to enter.
647: * @return result of enabling the PIN value which is the status word
648: * received from the smart card in the form of a byte array. This method
649: * would return null if the user cancels the request.
650: * @exception IOException is thrown if the PIN could not be communicated
651: * with the card because the connection was
652: * closed before this method was called or because
653: * of communication problems.
654: * @throws InterruptedIOException can be thrown in any of these situations:
655: * <ul>
656: * <li>if this <code>Connection</code>
657: * object is closed during the exchange
658: * operation</li>
659: * <li>if the card is removed after connection is established and
660: * then reinserted, and attempt is made to enable PIN
661: * without re-establishing the connection</li>
662: * </ul>
663: * @exception SecurityException is thrown if the J2ME application does
664: * not have appropriate rights to ask for enabling the PIN.
665: * @exception UnsupportedOperationException is thrown if the
666: * implementation does not support this method.
667: */
668: byte[] enablePin(int pinID) throws IOException;
669:
670: /**
671: * This is a high-level method that lets the J2ME application
672: * ask the user to enter the value for an unblocking PIN,
673: * and the new value for the blocked PIN and send
674: * these to the card.
675: * A call to <code>unblockPin</code> method pops up a UI that requests
676: * the user to enter the value for the unblocking PIN and the
677: * new value for the blocked PIN.
678: * The <code>unblockingPinID</code> field indicates which unblocking
679: * PIN is to be
680: * used to unblock the blocked PIN which is indicated by the field
681: * <code>blockedPinID</code>.
682: * The user can either cancel the request
683: * or continue. If the user enters the PIN values and chooses to continue,
684: * the implementation is responsible
685: * for presenting the PIN values to the card for unblocking the
686: * blocked PIN.
687: * If padding is required for either of the PIN values, the
688: * implementation is responsible for providing appropriate padding.
689: * @param blockedPinID the ID of PIN that is to be unblocked.
690: * @param unblockingPinID the ID of unblocking PIN.
691: * @return result of unblocking the PIN value which is the status word
692: * received from the smart card in the form of a byte array. This method
693: * would return null if the user cancels the request.
694: * @exception IOException is thrown if the PIN could not be communicated
695: * with the card because the connection was
696: * closed before this method was called or because
697: * of communication problems.
698: * @throws InterruptedIOException can be thrown in any of these situations:
699: * <ul>
700: * <li>if this <code>Connection</code>
701: * object is closed during the exchange
702: * operation</li>
703: * <li>if the card is removed after connection is established and
704: * then reinserted, and attempt is made to unblock PIN
705: * without re-establishing the connection</li>
706: * </ul>
707: * @exception SecurityException is thrown if the J2ME application does
708: * not have appropriate rights to ask for unblocking the PIN.
709: * @exception UnsupportedOperationException is thrown if the
710: * implementation does not support this method.
711: */
712: byte[] unblockPin(int blockedPinID, int unblockingPinID)
713: throws IOException;
714:
715: }
|