1 /* 2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.smartcardio; 27 28 import java.nio.*; 29 30 /** 31 * A logical channel connection to a Smart Card. It is used to exchange APDUs 32 * with a Smart Card. 33 * A CardChannel object can be obtained by calling the method 34 * {@linkplain Card#getBasicChannel} or {@linkplain Card#openLogicalChannel}. 35 * 36 * @see Card 37 * @see CommandAPDU 38 * @see ResponseAPDU 39 * 40 * @since 1.6 41 * @author Andreas Sterbenz 42 * @author JSR 268 Expert Group 43 */ 44 public abstract class CardChannel { 45 46 /** 47 * Constructs a new CardChannel object. 48 * 49 * <p>This constructor is called by subclasses only. Application should 50 * call the {@linkplain Card#getBasicChannel} and 51 * {@linkplain Card#openLogicalChannel} methods to obtain a CardChannel 52 * object. 53 */ CardChannel()54 protected CardChannel() { 55 // empty 56 } 57 58 /** 59 * Returns the Card this channel is associated with. 60 * 61 * @return the Card this channel is associated with 62 */ getCard()63 public abstract Card getCard(); 64 65 /** 66 * Returns the channel number of this CardChannel. A channel number of 67 * 0 indicates the basic logical channel. 68 * 69 * @return the channel number of this CardChannel. 70 * 71 * @throws IllegalStateException if this channel has been 72 * {@linkplain #close closed} or if the corresponding Card has been 73 * {@linkplain Card#disconnect disconnected}. 74 */ getChannelNumber()75 public abstract int getChannelNumber(); 76 77 /** 78 * Transmits the specified command APDU to the Smart Card and returns the 79 * response APDU. 80 * 81 * <p>The CLA byte of the command APDU is automatically adjusted to 82 * match the channel number of this CardChannel. 83 * 84 * <p>Note that this method cannot be used to transmit 85 * <code>MANAGE CHANNEL</code> APDUs. Logical channels should be managed 86 * using the {@linkplain Card#openLogicalChannel} and {@linkplain 87 * CardChannel#close CardChannel.close()} methods. 88 * 89 * <p>Implementations should transparently handle artifacts 90 * of the transmission protocol. 91 * For example, when using the T=0 protocol, the following processing 92 * should occur as described in ISO/IEC 7816-4: 93 * 94 * <ul> 95 * <li><p>if the response APDU has an SW1 of <code>61</code>, the 96 * implementation should issue a <code>GET RESPONSE</code> command 97 * using <code>SW2</code> as the <code>Le</code>field. 98 * This process is repeated as long as an SW1 of <code>61</code> is 99 * received. The response body of these exchanges is concatenated 100 * to form the final response body. 101 * 102 * <li><p>if the response APDU is <code>6C XX</code>, the implementation 103 * should reissue the command using <code>XX</code> as the 104 * <code>Le</code> field. 105 * </ul> 106 * 107 * <p>The ResponseAPDU returned by this method is the result 108 * after this processing has been performed. 109 * 110 * @param command the command APDU 111 * @return the response APDU received from the card 112 * 113 * @throws IllegalStateException if this channel has been 114 * {@linkplain #close closed} or if the corresponding Card has been 115 * {@linkplain Card#disconnect disconnected}. 116 * @throws IllegalArgumentException if the APDU encodes a 117 * <code>MANAGE CHANNEL</code> command 118 * @throws NullPointerException if command is null 119 * @throws CardException if the card operation failed 120 */ transmit(CommandAPDU command)121 public abstract ResponseAPDU transmit(CommandAPDU command) throws CardException; 122 123 /** 124 * Transmits the command APDU stored in the command ByteBuffer and receives 125 * the response APDU in the response ByteBuffer. 126 * 127 * <p>The command buffer must contain valid command APDU data starting 128 * at <code>command.position()</code> and the APDU must be 129 * <code>command.remaining()</code> bytes long. 130 * Upon return, the command buffer's position will be equal 131 * to its limit; its limit will not have changed. The output buffer 132 * will have received the response APDU bytes. Its position will have 133 * advanced by the number of bytes received, which is also the return 134 * value of this method. 135 * 136 * <p>The CLA byte of the command APDU is automatically adjusted to 137 * match the channel number of this CardChannel. 138 * 139 * <p>Note that this method cannot be used to transmit 140 * <code>MANAGE CHANNEL</code> APDUs. Logical channels should be managed 141 * using the {@linkplain Card#openLogicalChannel} and {@linkplain 142 * CardChannel#close CardChannel.close()} methods. 143 * 144 * <p>See {@linkplain #transmit transmit()} for a discussion of the handling 145 * of response APDUs with the SW1 values <code>61</code> or <code>6C</code>. 146 * 147 * @param command the buffer containing the command APDU 148 * @param response the buffer that shall receive the response APDU from 149 * the card 150 * @return the length of the received response APDU 151 * 152 * @throws IllegalStateException if this channel has been 153 * {@linkplain #close closed} or if the corresponding Card has been 154 * {@linkplain Card#disconnect disconnected}. 155 * @throws NullPointerException if command or response is null 156 * @throws ReadOnlyBufferException if the response buffer is read-only 157 * @throws IllegalArgumentException if command and response are the 158 * same object, if <code>response</code> may not have 159 * sufficient space to receive the response APDU 160 * or if the APDU encodes a <code>MANAGE CHANNEL</code> command 161 * @throws CardException if the card operation failed 162 */ transmit(ByteBuffer command, ByteBuffer response)163 public abstract int transmit(ByteBuffer command, ByteBuffer response) 164 throws CardException; 165 166 /** 167 * Closes this CardChannel. The logical channel is closed by issuing 168 * a <code>MANAGE CHANNEL</code> command that should use the format 169 * <code>[xx 70 80 0n]</code> where <code>n</code> is the channel number 170 * of this channel and <code>xx</code> is the <code>CLA</code> 171 * byte that encodes this logical channel and has all other bits set to 0. 172 * After this method returns, calling other 173 * methods in this class will raise an IllegalStateException. 174 * 175 * <p>Note that the basic logical channel cannot be closed using this 176 * method. It can be closed by calling {@link Card#disconnect}. 177 * 178 * @throws CardException if the card operation failed 179 * @throws IllegalStateException if this CardChannel represents a 180 * connection the basic logical channel 181 */ close()182 public abstract void close() throws CardException; 183 184 } 185