javacard.framework.AID Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of jcardsim Show documentation
jCardSim is open-source library contains implementation of Java Card API
There is a newer version: 2.2.2
/*
 * Copyright 2011 Licel LLC.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package javacard.framework;

/**
 * This class encapsulates the Application Identifier (AID) associated with an applet.
 * An AID is defined in ISO 7816-5 to be a sequence of bytes between 5 and 16 bytes in length.
 *
 * 
 * The Java Card runtime environment creates instances of AID class to identify and manage every applet on the card.
 * Applets need not create instances of this class. An applet may request and use the Java Card runtime environment-owned
 * instances to identify itself and other applet instances.
 *
 *

 * Java Card runtime environment-owned instances of AID are permanent Java Card runtime environment Entry Point Objects and can be accessed
 * from any applet context. References to these permanent objects can be stored and re-used.
 *
 * 

 * An applet instance can obtain a reference to Java Card runtime environment-owned instances of its own AID object
 * by using the JCSystem.getAID() method and another applet's AID object via the JCSystem.lookupAID() method.
 *
 * 

 *An applet uses AID instances to request to share another applet's object or to control access to its own shared object from another applet.
 *See Runtime Environment Specification for the Java Card Platform, section 6.2 for details.
 *
 *@see JCSystem
 *@see SystemException
 *
 */
public class AID {

    byte aid[];

    /**
     * The Java Card runtime environment uses this constructor to create a new AID instance
     * encapsulating the specified AID bytes.
     * @param bArray the byte array containing the AID bytes
     * @param offset the start of AID bytes in bArray
     * @param length the length of the AID bytes in bArray
     * @throws SystemException with the following reason code:
     * 

     *       SystemException.ILLEGAL_VALUE if the length parameter is
     *       less than 5 or greater than 16
     * 
     * @throws NullPointerException  if the bArray parameter is null
     * @throws ArrayIndexOutOfBoundsException if the offset parameter or length parameter is negative or if offset+length is greater than the length of the bArray parameter
     * @throws SecurityException if the bArray array is not accessible in the caller's context
     */
    public AID(byte bArray[], short offset, byte length)
            throws SystemException, NullPointerException, ArrayIndexOutOfBoundsException, SecurityException {
        if (length < 5 || length > 16) {
            SystemException.throwIt(SystemException.ILLEGAL_VALUE);
        }
        aid = new byte[length];
        Util.arrayCopy(bArray, offset, aid, (short) 0, length);
    }

    /**
     * Called to get all the AID bytes encapsulated within AID object.
     * @param dest byte array to copy the AID bytes
     * @param offset within dest where the AID bytes begin
     * @return the length of the AID bytes
     * @throws NullPointerException if the dest parameter is null
     * @throws ArrayIndexOutOfBoundsException  if the offset parameter is negative or offset+length of AID bytes is greater than the length of the dest array
     * @throws SecurityException if the dest array is not accessible in the caller's context
     */

    public final byte getBytes(byte dest[], short offset)
            throws NullPointerException, ArrayIndexOutOfBoundsException, SecurityException {
        Util.arrayCopy(aid, (short) 0, dest, offset, (short) aid.length);
        return (byte) aid.length;
    }

    /**
     * Compares the AID bytes in this AID instance to the AID bytes in the
     * specified object.
     *
     * The result is true if and only if the argument is not null
     * and is an AID object that encapsulates the same AID bytes as this
     * object.
     *
     * 
     * This method does not throw NullPointerException.
     * @param anObject the object to compare this AID against
     * @return true if the AID byte values are equal, false otherwise
     * @throws SecurityException anObject object is not accessible in the caller's context
     */
    public final boolean equals(Object anObject)
            throws SecurityException {
        if (anObject == null) {
            return false;
        }
        if (!(anObject instanceof AID) || ((AID) anObject).aid.length != aid.length) {
            return false;
        } else {
            return Util.arrayCompare(((AID) anObject).aid, (short) 0, aid, (short) 0, (short) aid.length) == 0;
        }
    }

    /**
     * Checks if the specified AID bytes in bArray are the same as those encapsulated
     * in this AID object.
     *
     * The result is true if and only if the bArray argument is not null
     * and the AID bytes encapsulated in this AID object are equal to
     * the specified AID bytes in bArray.
     *
     * 

     * This method does not throw NullPointerException.
     * @param bArray containing the AID bytes
     * @param offset within bArray to begin
     * @param length of AID bytes in bArray
     * @return true if equal, false otherwise
     * @throws ArrayIndexOutOfBoundsException if the offset parameter or length parameter is negative or
     * if offset+length is greater than the length of the bArray parameter
     * @throws SecurityException if the bArray array is not accessible in the caller's context
     */
    public final boolean equals(byte bArray[], short offset, byte length)
            throws ArrayIndexOutOfBoundsException, SecurityException {
        return length == aid.length && Util.arrayCompare(bArray, offset, aid, (short) 0, length) == 0;
    }

    /**
     * Checks if the specified partial AID byte sequence matches the first length bytes
     * of the encapsulated AID bytes within this AID object.
     * The result is true if and only if the bArray argument is not null
     * and the input length is less than or equal to the length of the encapsulated AID
     * bytes within this AID object and the specified bytes match.
     *
     * 

     * This method does not throw NullPointerException.
     *
     * @param bArray containing the partial AID byte sequence
     * @param offset within bArray to begin
     * @param length of partial AID bytes in bArray
     * @return true if equal, false otherwise
     * @throws ArrayIndexOutOfBoundsException if the offset parameter or length parameter is negative or
     * if offset+length is greater than the length of the bArray parameter
     * @throws SecurityException if the bArray array is not accessible in the caller's context
     */
    public final boolean partialEquals(byte bArray[], short offset, byte length)
            throws ArrayIndexOutOfBoundsException, SecurityException {
        if (length > aid.length) {
            return false;
        } else {
            return Util.arrayCompare(bArray, offset, aid, (short) 0, length) == 0;
        }
    }

    /**
     * Checks if the RID (National Registered Application provider identifier) portion of the encapsulated
     * AID bytes within the otherAID object matches
     * that of this AID object.
     * The first 5 bytes of an AID byte sequence is the RID. See ISO 7816-5 for details.
     * The result is true if and only if the argument is not null
     * and is an AID object that encapsulates the same RID bytes as this
     * object.
     *
     *

     * This method does not throw NullPointerException.
     * @param otherAID the AID to compare against
     * @return true if the RID bytes match, false otherwise
     * @throws SecurityException if the otherAID object is not accessible in the caller's context
     */
    public final boolean RIDEquals(AID otherAID)
            throws SecurityException {
        if (otherAID == null) {
            return false;
        }
        return Util.arrayCompare(aid, (short) 0, otherAID.aid, (short) 0, (short) 5) == 0;
    }

    /**
     * Called to get part of the AID bytes encapsulated within the AID object starting
     * at the specified offset for the specified length.
     * @param aidOffset offset within AID array to begin copying bytes
     * @param dest the destination byte array to copy the AID bytes into
     * @param oOffset offset within dest where the output bytes begin
     * @param oLength the length of bytes requested in dest. 0
     * implies a request to copy all remaining AID bytes.
     * @return the actual length of the bytes returned in dest
     * @throws NullPointerException if the dest parameter is null
     * @throws ArrayIndexOutOfBoundsException if the aidOffset parameter is
     * negative or greater than the length of the encapsulated AID bytes or the
     * oOffset parameter is negative
     * or oOffset+length of bytes requested is greater than the length of the
     * dest array
     * @throws SecurityException if the dest array is not accessible in the caller's context
     */
    public final byte getPartialBytes(short aidOffset, byte dest[], short oOffset, byte oLength)
            throws NullPointerException, ArrayIndexOutOfBoundsException, SecurityException {
        short copyLen = oLength;
        if (oLength == 0) {
            copyLen = (short) (aid.length - aidOffset);
        }
        Util.arrayCopy(aid, aidOffset, dest, oOffset, copyLen);
        return (byte) copyLen;
    }
}