Java tutorial
/* * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.smartcardio; import java.util.Arrays; import java.nio.ByteBuffer; /** * A command APDU following the structure defined in ISO/IEC 7816-4. * It consists of a four byte header and a conditional body of variable length. * This class does not attempt to verify that the APDU encodes a semantically * valid command. * * <p>Note that when the expected length of the response APDU is specified * in the {@linkplain #CommandAPDU(int,int,int,int,int) constructors}, * the actual length (Ne) must be specified, not its * encoded form (Le). Similarly, {@linkplain #getNe} returns the actual * value Ne. In other words, a value of 0 means "no data in the response APDU" * rather than "maximum length." * * <p>This class supports both the short and extended forms of length * encoding for Ne and Nc. However, note that not all terminals and Smart Cards * are capable of accepting APDUs that use the extended form. * * <p>For the header bytes CLA, INS, P1, and P2 the Java type <code>int</code> * is used to represent the 8 bit unsigned values. In the constructors, only * the 8 lowest bits of the <code>int</code> value specified by the application * are significant. The accessor methods always return the byte as an unsigned * value between 0 and 255. * * <p>Instances of this class are immutable. Where data is passed in or out * via byte arrays, defensive cloning is performed. * * @see ResponseAPDU * @see CardChannel#transmit CardChannel.transmit * * @since 1.6 * @author Andreas Sterbenz * @author JSR 268 Expert Group */ public final class CommandAPDU implements java.io.Serializable { private static final long serialVersionUID = 398698301286670877L; private static final int MAX_APDU_SIZE = 65544; /** @serial */ private byte[] apdu; // value of nc private transient int nc; // value of ne private transient int ne; // index of start of data within the apdu array private transient int dataOffset; /** * Constructs a CommandAPDU from a byte array containing the complete * APDU contents (header and body). * * <p>Note that the apdu bytes are copied to protect against * subsequent modification. * * @param apdu the complete command APDU * * @throws NullPointerException if apdu is null * @throws IllegalArgumentException if apdu does not contain a valid * command APDU */ public CommandAPDU(byte[] apdu) { this.apdu = apdu.clone(); parse(); } /** * Constructs a CommandAPDU from a byte array containing the complete * APDU contents (header and body). The APDU starts at the index * <code>apduOffset</code> in the byte array and is <code>apduLength</code> * bytes long. * * <p>Note that the apdu bytes are copied to protect against * subsequent modification. * * @param apdu the complete command APDU * @param apduOffset the offset in the byte array at which the apdu * data begins * @param apduLength the length of the APDU * * @throws NullPointerException if apdu is null * @throws IllegalArgumentException if apduOffset or apduLength are * negative or if apduOffset + apduLength are greater than apdu.length, * or if the specified bytes are not a valid APDU */ public CommandAPDU(byte[] apdu, int apduOffset, int apduLength) { checkArrayBounds(apdu, apduOffset, apduLength); this.apdu = new byte[apduLength]; System.arraycopy(apdu, apduOffset, this.apdu, 0, apduLength); parse(); } private void checkArrayBounds(byte[] b, int ofs, int len) { if ((ofs < 0) || (len < 0)) { throw new IllegalArgumentException("Offset and length must not be negative"); } if (b == null) { if ((ofs != 0) && (len != 0)) { throw new IllegalArgumentException("offset and length must be 0 if array is null"); } } else { if (ofs > b.length - len) { throw new IllegalArgumentException("Offset plus length exceed array size"); } } } /** * Creates a CommandAPDU from the ByteBuffer containing the complete APDU * contents (header and body). * The buffer's <code>position</code> must be set to the start of the APDU, * its <code>limit</code> to the end of the APDU. Upon return, the buffer's * <code>position</code> is equal to its limit; its limit remains unchanged. * * <p>Note that the data in the ByteBuffer is copied to protect against * subsequent modification. * * @param apdu the ByteBuffer containing the complete APDU * * @throws NullPointerException if apdu is null * @throws IllegalArgumentException if apdu does not contain a valid * command APDU */ public CommandAPDU(ByteBuffer apdu) { this.apdu = new byte[apdu.remaining()]; apdu.get(this.apdu); parse(); } /** * Constructs a CommandAPDU from the four header bytes. This is case 1 * in ISO 7816, no command body. * * @param cla the class byte CLA * @param ins the instruction byte INS * @param p1 the parameter byte P1 * @param p2 the parameter byte P2 */ public CommandAPDU(int cla, int ins, int p1, int p2) { this(cla, ins, p1, p2, null, 0, 0, 0); } /** * Constructs a CommandAPDU from the four header bytes and the expected * response data length. This is case 2 in ISO 7816, empty command data * field with Ne specified. If Ne is 0, the APDU is encoded as ISO 7816 * case 1. * * @param cla the class byte CLA * @param ins the instruction byte INS * @param p1 the parameter byte P1 * @param p2 the parameter byte P2 * @param ne the maximum number of expected data bytes in a response APDU * * @throws IllegalArgumentException if ne is negative or greater than * 65536 */ public CommandAPDU(int cla, int ins, int p1, int p2, int ne) { this(cla, ins, p1, p2, null, 0, 0, ne); } /** * Constructs a CommandAPDU from the four header bytes and command data. * This is case 3 in ISO 7816, command data present and Ne absent. The * value Nc is taken as data.length. If <code>data</code> is null or * its length is 0, the APDU is encoded as ISO 7816 case 1. * * <p>Note that the data bytes are copied to protect against * subsequent modification. * * @param cla the class byte CLA * @param ins the instruction byte INS * @param p1 the parameter byte P1 * @param p2 the parameter byte P2 * @param data the byte array containing the data bytes of the command body * * @throws IllegalArgumentException if data.length is greater than 65535 */ public CommandAPDU(int cla, int ins, int p1, int p2, byte[] data) { this(cla, ins, p1, p2, data, 0, arrayLength(data), 0); } /** * Constructs a CommandAPDU from the four header bytes and command data. * This is case 3 in ISO 7816, command data present and Ne absent. The * value Nc is taken as dataLength. If <code>dataLength</code> * is 0, the APDU is encoded as ISO 7816 case 1. * * <p>Note that the data bytes are copied to protect against * subsequent modification. * * @param cla the class byte CLA * @param ins the instruction byte INS * @param p1 the parameter byte P1 * @param p2 the parameter byte P2 * @param data the byte array containing the data bytes of the command body * @param dataOffset the offset in the byte array at which the data * bytes of the command body begin * @param dataLength the number of the data bytes in the command body * * @throws NullPointerException if data is null and dataLength is not 0 * @throws IllegalArgumentException if dataOffset or dataLength are * negative or if dataOffset + dataLength are greater than data.length * or if dataLength is greater than 65535 */ public CommandAPDU(int cla, int ins, int p1, int p2, byte[] data, int dataOffset, int dataLength) { this(cla, ins, p1, p2, data, dataOffset, dataLength, 0); } /** * Constructs a CommandAPDU from the four header bytes, command data, * and expected response data length. This is case 4 in ISO 7816, * command data and Ne present. The value Nc is taken as data.length * if <code>data</code> is non-null and as 0 otherwise. If Ne or Nc * are zero, the APDU is encoded as case 1, 2, or 3 per ISO 7816. * * <p>Note that the data bytes are copied to protect against * subsequent modification. * * @param cla the class byte CLA * @param ins the instruction byte INS * @param p1 the parameter byte P1 * @param p2 the parameter byte P2 * @param data the byte array containing the data bytes of the command body * @param ne the maximum number of expected data bytes in a response APDU * * @throws IllegalArgumentException if data.length is greater than 65535 * or if ne is negative or greater than 65536 */ public CommandAPDU(int cla, int ins, int p1, int p2, byte[] data, int ne) { this(cla, ins, p1, p2, data, 0, arrayLength(data), ne); } private static int arrayLength(byte[] b) { return (b != null) ? b.length : 0; } /** * Command APDU encoding options: * * case 1: |CLA|INS|P1 |P2 | len = 4 * case 2s: |CLA|INS|P1 |P2 |LE | len = 5 * case 3s: |CLA|INS|P1 |P2 |LC |...BODY...| len = 6..260 * case 4s: |CLA|INS|P1 |P2 |LC |...BODY...|LE | len = 7..261 * case 2e: |CLA|INS|P1 |P2 |00 |LE1|LE2| len = 7 * case 3e: |CLA|INS|P1 |P2 |00 |LC1|LC2|...BODY...| len = 8..65542 * case 4e: |CLA|INS|P1 |P2 |00 |LC1|LC2|...BODY...|LE1|LE2| len =10..65544 * * LE, LE1, LE2 may be 0x00. * LC must not be 0x00 and LC1|LC2 must not be 0x00|0x00 */ private void parse() { if (apdu.length < 4) { throw new IllegalArgumentException("apdu must be at least 4 bytes long"); } if (apdu.length == 4) { // case 1 return; } int l1 = apdu[4] & 0xff; if (apdu.length == 5) { // case 2s this.ne = (l1 == 0) ? 256 : l1; return; } if (l1 != 0) { if (apdu.length == 4 + 1 + l1) { // case 3s this.nc = l1; this.dataOffset = 5; return; } else if (apdu.length == 4 + 2 + l1) { // case 4s this.nc = l1; this.dataOffset = 5; int l2 = apdu[apdu.length - 1] & 0xff; this.ne = (l2 == 0) ? 256 : l2; return; } else { throw new IllegalArgumentException("Invalid APDU: length=" + apdu.length + ", b1=" + l1); } } if (apdu.length < 7) { throw new IllegalArgumentException("Invalid APDU: length=" + apdu.length + ", b1=" + l1); } int l2 = ((apdu[5] & 0xff) << 8) | (apdu[6] & 0xff); if (apdu.length == 7) { // case 2e this.ne = (l2 == 0) ? 65536 : l2; return; } if (l2 == 0) { throw new IllegalArgumentException( "Invalid APDU: length=" + apdu.length + ", b1=" + l1 + ", b2||b3=" + l2); } if (apdu.length == 4 + 3 + l2) { // case 3e this.nc = l2; this.dataOffset = 7; return; } else if (apdu.length == 4 + 5 + l2) { // case 4e this.nc = l2; this.dataOffset = 7; int leOfs = apdu.length - 2; int l3 = ((apdu[leOfs] & 0xff) << 8) | (apdu[leOfs + 1] & 0xff); this.ne = (l3 == 0) ? 65536 : l3; } else { throw new IllegalArgumentException( "Invalid APDU: length=" + apdu.length + ", b1=" + l1 + ", b2||b3=" + l2); } } /** * Constructs a CommandAPDU from the four header bytes, command data, * and expected response data length. This is case 4 in ISO 7816, * command data and Le present. The value Nc is taken as * <code>dataLength</code>. * If Ne or Nc * are zero, the APDU is encoded as case 1, 2, or 3 per ISO 7816. * * <p>Note that the data bytes are copied to protect against * subsequent modification. * * @param cla the class byte CLA * @param ins the instruction byte INS * @param p1 the parameter byte P1 * @param p2 the parameter byte P2 * @param data the byte array containing the data bytes of the command body * @param dataOffset the offset in the byte array at which the data * bytes of the command body begin * @param dataLength the number of the data bytes in the command body * @param ne the maximum number of expected data bytes in a response APDU * * @throws NullPointerException if data is null and dataLength is not 0 * @throws IllegalArgumentException if dataOffset or dataLength are * negative or if dataOffset + dataLength are greater than data.length, * or if ne is negative or greater than 65536, * or if dataLength is greater than 65535 */ public CommandAPDU(int cla, int ins, int p1, int p2, byte[] data, int dataOffset, int dataLength, int ne) { checkArrayBounds(data, dataOffset, dataLength); if (dataLength > 65535) { throw new IllegalArgumentException("dataLength is too large"); } if (ne < 0) { throw new IllegalArgumentException("ne must not be negative"); } if (ne > 65536) { throw new IllegalArgumentException("ne is too large"); } this.ne = ne; this.nc = dataLength; if (dataLength == 0) { if (ne == 0) { // case 1 this.apdu = new byte[4]; setHeader(cla, ins, p1, p2); } else { // case 2s or 2e if (ne <= 256) { // case 2s // 256 is encoded as 0x00 byte len = (ne != 256) ? (byte) ne : 0; this.apdu = new byte[5]; setHeader(cla, ins, p1, p2); this.apdu[4] = len; } else { // case 2e byte l1, l2; // 65536 is encoded as 0x00 0x00 if (ne == 65536) { l1 = 0; l2 = 0; } else { l1 = (byte) (ne >> 8); l2 = (byte) ne; } this.apdu = new byte[7]; setHeader(cla, ins, p1, p2); this.apdu[5] = l1; this.apdu[6] = l2; } } } else { if (ne == 0) { // case 3s or 3e if (dataLength <= 255) { // case 3s apdu = new byte[4 + 1 + dataLength]; setHeader(cla, ins, p1, p2); apdu[4] = (byte) dataLength; this.dataOffset = 5; System.arraycopy(data, dataOffset, apdu, 5, dataLength); } else { // case 3e apdu = new byte[4 + 3 + dataLength]; setHeader(cla, ins, p1, p2); apdu[4] = 0; apdu[5] = (byte) (dataLength >> 8); apdu[6] = (byte) dataLength; this.dataOffset = 7; System.arraycopy(data, dataOffset, apdu, 7, dataLength); } } else { // case 4s or 4e if ((dataLength <= 255) && (ne <= 256)) { // case 4s apdu = new byte[4 + 2 + dataLength]; setHeader(cla, ins, p1, p2); apdu[4] = (byte) dataLength; this.dataOffset = 5; System.arraycopy(data, dataOffset, apdu, 5, dataLength); apdu[apdu.length - 1] = (ne != 256) ? (byte) ne : 0; } else { // case 4e apdu = new byte[4 + 5 + dataLength]; setHeader(cla, ins, p1, p2); apdu[4] = 0; apdu[5] = (byte) (dataLength >> 8); apdu[6] = (byte) dataLength; this.dataOffset = 7; System.arraycopy(data, dataOffset, apdu, 7, dataLength); if (ne != 65536) { int leOfs = apdu.length - 2; apdu[leOfs] = (byte) (ne >> 8); apdu[leOfs + 1] = (byte) ne; } // else le == 65536: no need to fill in, encoded as 0 } } } } private void setHeader(int cla, int ins, int p1, int p2) { apdu[0] = (byte) cla; apdu[1] = (byte) ins; apdu[2] = (byte) p1; apdu[3] = (byte) p2; } /** * Returns the value of the class byte CLA. * * @return the value of the class byte CLA. */ public int getCLA() { return apdu[0] & 0xff; } /** * Returns the value of the instruction byte INS. * * @return the value of the instruction byte INS. */ public int getINS() { return apdu[1] & 0xff; } /** * Returns the value of the parameter byte P1. * * @return the value of the parameter byte P1. */ public int getP1() { return apdu[2] & 0xff; } /** * Returns the value of the parameter byte P2. * * @return the value of the parameter byte P2. */ public int getP2() { return apdu[3] & 0xff; } /** * Returns the number of data bytes in the command body (Nc) or 0 if this * APDU has no body. This call is equivalent to * <code>getData().length</code>. * * @return the number of data bytes in the command body or 0 if this APDU * has no body. */ public int getNc() { return nc; } /** * Returns a copy of the data bytes in the command body. If this APDU as * no body, this method returns a byte array with length zero. * * @return a copy of the data bytes in the command body or the empty * byte array if this APDU has no body. */ public byte[] getData() { byte[] data = new byte[nc]; System.arraycopy(apdu, dataOffset, data, 0, nc); return data; } /** * Returns the maximum number of expected data bytes in a response * APDU (Ne). * * @return the maximum number of expected data bytes in a response APDU. */ public int getNe() { return ne; } /** * Returns a copy of the bytes in this APDU. * * @return a copy of the bytes in this APDU. */ public byte[] getBytes() { return apdu.clone(); } /** * Returns a string representation of this command APDU. * * @return a String representation of this command APDU. */ public String toString() { return "CommmandAPDU: " + apdu.length + " bytes, nc=" + nc + ", ne=" + ne; } /** * Compares the specified object with this command APDU for equality. * Returns true if the given object is also a CommandAPDU and its bytes are * identical to the bytes in this CommandAPDU. * * @param obj the object to be compared for equality with this command APDU * @return true if the specified object is equal to this command APDU */ public boolean equals(Object obj) { if (this == obj) { return true; } if (obj instanceof CommandAPDU == false) { return false; } CommandAPDU other = (CommandAPDU) obj; return Arrays.equals(this.apdu, other.apdu); } /** * Returns the hash code value for this command APDU. * * @return the hash code value for this command APDU. */ public int hashCode() { return Arrays.hashCode(apdu); } private void readObject(java.io.ObjectInputStream in) throws java.io.IOException, ClassNotFoundException { apdu = (byte[]) in.readUnshared(); // initialize transient fields parse(); } }