Java Card API

901 San Antonio RoadPalo Alto, CA 94303 USA650 960-1300 fax 650 969-9131

Sun Microsystems, Inc.

Java Card™ 2.2 Application Programming Interface

Revision 1.1 for the 2.2_01 Release

September, 2002

Java CardTM 2.2 Application Programming Interface Specification ("Specification")Version: 2.2Status: FCS Release: September 23, 2002

Copyright 2002 Sun Microsystems, Inc.

4150 Network Circle, Santa Clara, California 95054, U.S.AAll rights reserved.

NOTICE The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of Sun Microsystems, Inc. ("Sun") and its licensors, if any. Any use of the Specification and the information described therein will be governed by the terms and conditions of this license and the Export Control Guidelines as set forth in the Terms of Use on Sun's website. By viewing, downloading or otherwise copying the Specification, you agree that you have read, understood, and will comply with all of the terms and conditions set forth herein.

Subject to the terms and conditions of this license, Sun hereby grants you a fully-paid, non-exclusive, non-transferable, worldwide, limited license (without the right to sublicense) under Sun's intellectual property rights to review the Specification internally solely for the purposes of designing and developing your implementation of the Specification and designing and developing your applets and applications intended to run on the Java Card platform. Other than this limited license, you acquire no right, title or interest in or to the Specification or any other Sun intellectual property. You acknowlegde that any commercial or productive use of an implementation of the Specification requires separate and appropriate licensing agreements. The Specification contains the proprietary information of Sun and may only be used in accordance with the license terms set forth herein. This license will terminate immediately without notice from Sun if you fail to comply with any provision of this license. Upon termination or expiration of this license, you must cease use of or destroy the Specification.

TRADEMARKS No right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sun's licensors is granted hereunder. Sun, Sun Microsystems, the Sun logo, Java, Java Card, and Java Card Compatible are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

DISCLAIMER OF WARRANTIES THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY SUN. SUN MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product.

THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. SUN MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification.

LIMITATION OF LIABILITY TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF SUN AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

You will indemnify, hold harmless, and defend Sun and its licensors from any claims arising or resulting from: (i) your use of the Specification; (ii) the use or distribution of your Java applications or applets; and/or (iii) any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license.

RESTRICTED RIGHTS LEGEND If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).

REPORT

You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification ("Feedback"). To the extent that you provide Sun with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Sun a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification and future versions, implementations, and test suites thereof. (LFI#119369/Form ID#011801)

Contents

Overview ..........................................................................................................11 Java Card 2.2 API Notes .................................................................................32 Parameter Checking ........................................................................................5

java.io ............................................................................................................... 7IOException ................................................................................................................................................ 8

java.lang......................................................................................................... 11ArithmeticException ................................................................................................................................. 13ArrayIndexOutOfBoundsException .......................................................................................................... 14ArrayStoreException ................................................................................................................................. 16ClassCastException ................................................................................................................................... 18Exception .................................................................................................................................................. 20IndexOutOfBoundsException ................................................................................................................... 21NegativeArraySizeException .................................................................................................................... 23NullPointerException ................................................................................................................................ 24Object ........................................................................................................................................................ 26RuntimeException ..................................................................................................................................... 28SecurityException ..................................................................................................................................... 30Throwable ................................................................................................................................................. 32

java.rmi .......................................................................................................... 33Remote ...................................................................................................................................................... 34RemoteException ...................................................................................................................................... 35

javacard.framework ..................................................................................... 37AID ............................................................................................................................................................ 39APDU ........................................................................................................................................................ 44APDUException ........................................................................................................................................ 59Applet ........................................................................................................................................................ 63CardException ........................................................................................................................................... 70CardRuntimeException ............................................................................................................................. 72ISO7816 .................................................................................................................................................... 74ISOException ............................................................................................................................................ 79JCSystem ................................................................................................................................................... 81MultiSelectable ......................................................................................................................................... 91OwnerPIN ................................................................................................................................................. 93PIN ............................................................................................................................................................ 97

Contents iii

Contents

PINException .......................................................................................................................................... 100Shareable ................................................................................................................................................. 102SystemException ..................................................................................................................................... 103TransactionException .............................................................................................................................. 106UserException ......................................................................................................................................... 109Util .......................................................................................................................................................... 111

javacard.framework.service ...................................................................... 117BasicService ............................................................................................................................................ 119CardRemoteObject .................................................................................................................................. 127Dispatcher ............................................................................................................................................... 129RemoteService ........................................................................................................................................ 133RMIService ............................................................................................................................................. 134SecurityService ....................................................................................................................................... 138Service ..................................................................................................................................................... 141ServiceException .................................................................................................................................... 143

javacard.security......................................................................................... 147AESKey .................................................................................................................................................. 149Checksum ................................................................................................................................................ 151CryptoException ..................................................................................................................................... 155DESKey .................................................................................................................................................. 158DSAKey .................................................................................................................................................. 160DSAPrivateKey ....................................................................................................................................... 164DSAPublicKey ........................................................................................................................................ 166ECKey ..................................................................................................................................................... 168ECPrivateKey .......................................................................................................................................... 176ECPublicKey ........................................................................................................................................... 178Key .......................................................................................................................................................... 180KeyAgreement ........................................................................................................................................ 182KeyBuilder .............................................................................................................................................. 185KeyPair .................................................................................................................................................... 193MessageDigest ........................................................................................................................................ 197PrivateKey ............................................................................................................................................... 201PublicKey ................................................................................................................................................ 202RandomData ............................................................................................................................................ 203RSAPrivateCrtKey .................................................................................................................................. 206RSAPrivateKey ....................................................................................................................................... 212RSAPublicKey ........................................................................................................................................ 215SecretKey ................................................................................................................................................ 218Signature ................................................................................................................................................. 219

javacardx.crypto ......................................................................................... 231Cipher ...................................................................................................................................................... 232KeyEncryption ........................................................................................................................................ 241

Almanac ...................................................................................................... 243

Index ............................................................................................................263

iv Java Card 2.2 Application Programming Interface, Revision 1.1 for the 2.2_01 Release • September, 2002

Overview

Class Hierarchyjava.lang.Object

javacard.framework.AIDjavacard.framework.APDUjavacard.framework.Appletjavacard.framework.service.BasicService (implements javacard.framework.service.Service)

javacard.framework.service.RMIService (implements javacard.framework.service.RemoteService)

javacard.framework.service.CardRemoteObject (implements java.rmi.Remote)javacard.security.Checksumjavacardx.crypto.Cipherjavacard.framework.service.Dispatcherjavacard.framework.JCSystemjavacard.security.KeyAgreementjavacard.security.KeyBuilderjavacard.security.KeyPairjavacard.security.MessageDigestjavacard.framework.OwnerPIN (implements javacard.framework.PIN)javacard.security.RandomDatajavacard.security.Signaturejava.lang.Throwable

java.lang.Exceptionjavacard.framework.CardException

javacard.framework.UserExceptionjava.io.IOException

java.rmi.RemoteExceptionjava.lang.RuntimeException

java.lang.ArithmeticExceptionjava.lang.ArrayStoreException

Package Summary

Packages

java.io A subset of the java.io package in the standard Java programming language.

java.lang Provides classes that are fundamental to the design of the Java Card technology subset of the Java programming language.

java.rmi The java.rmi package defines the Remote interface which identifies interfaces whose methods can be invoked from card acceptance device (CAD) client applications.

javacard.framework Provides a framework of classes and interfaces for building, communicating with and working with Java Card applets.

javacard.framework.service Provides a service framework of classes and interfaces that allow a Java Card applet to be designed as an aggregation of service components.

javacard.security Provides classes and interfaces that contain publicly-available functionality for implementing a security and cryptography framework on Java Card.

javacardx.crypto Extension package that contains functionality, which may be subject to export controls, for implementing a security and cryptography framework on Java Card.

Overview 1

Overview

javacard.framework.CardRuntimeExceptionjavacard.framework.APDUExceptionjavacard.security.CryptoExceptionjavacard.framework.ISOExceptionjavacard.framework.PINExceptionjavacard.framework.service.ServiceExceptionjavacard.framework.SystemExceptionjavacard.framework.TransactionException

java.lang.ClassCastExceptionjava.lang.IndexOutOfBoundsException

java.lang.ArrayIndexOutOfBoundsExceptionjava.lang.NegativeArraySizeExceptionjava.lang.NullPointerExceptionjava.lang.SecurityException

javacard.framework.Util

Interface Hierarchyjavacard.security.DSAKey

javacard.security.DSAPrivateKeyjavacard.security.DSAPublicKey

javacard.security.ECKeyjavacard.security.ECPrivateKeyjavacard.security.ECPublicKey

javacard.framework.ISO7816javacard.security.Key

javacard.security.PrivateKeyjavacard.security.DSAPrivateKeyjavacard.security.ECPrivateKeyjavacard.security.RSAPrivateCrtKeyjavacard.security.RSAPrivateKey

javacard.security.PublicKeyjavacard.security.DSAPublicKeyjavacard.security.ECPublicKeyjavacard.security.RSAPublicKey

javacard.security.SecretKeyjavacard.security.AESKeyjavacard.security.DESKey

javacardx.crypto.KeyEncryptionjavacard.framework.MultiSelectablejavacard.framework.PINjava.rmi.Remotejavacard.framework.service.Service

javacard.framework.service.RemoteServicejavacard.framework.service.SecurityService

javacard.framework.Shareable

2 Java Card 2.2 Application Programming Interface, Revision 1.1 for the 2.2_01 Release • September, 2002

CHAPTER 1

Java Card 2.2 API Notes

Referenced Standards

ISO - International Standards Organization■ Information Technology — Identification cards — integrated circuit cards with

contacts: ISO 7816■ Information Technology — Security Techniques — Digital Signature Scheme

Giving Message Recovery: ISO 9796■ Information Technology — Data integrity mechanism using a cryptographic

check function employing a block cipher algorithm: ISO 9797■ Information technology — Security techniques — Digital signatures with

appendix: ISO 14888

RSA Data Security, Inc.■ RSA Encryption Standard: PKCS #1 Version 2.1■ Password-Based Encryption Standard: PKCS #5 Version 1.5

EMV■ The EMV 2000 ICC Specifications for Payments systems Version 4.0

■ The EMV ’96 ICC Specifications for Payments systems Version 3.0

3

IPSecThe Internet Key Exchange ( IKE ) document RFC 2409 (STD 1)

ANSIPublic Key Cryptography for the Financial Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA): X9.62-1998

IEEEStandard Specifications for Public Key Cryptography, Institute of Electrical and Electronic Engineers, 2000 : IEEE 1363

FIPSAdvanced Encryption Standard (AES): FIPS-197

Standard Names for Security and Crypto Packages

■ SHA (also SHA-1): Secure Hash Algorithm, as defined in Secure Hash Standard, NIST FIPS 180-1.

■ MD5: The Message Digest algorithm RSA-MD5, as defined by RSA DSI in RFC 1321.

■ RIPEMD-160: as defined in ISO/IEC 10118-3:1998 Information technology — Security techniques — Hash-functions — Part 3: Dedicated hash-functions

■ DSA: Digital Signature Algorithm, as defined in Digital Signature Standard, NIST FIPS 186.

■ DES: The Data Encryption Standard, as defined by NIST in FIPS 46-1 and 46-2.■ RSA: The Rivest, Shamir and Adleman Asymmetric Cipher algorithm.■ ECDSA: Elliptic Curve Digital Signature Algorithm.■ ECDH: Elliptic Curve Diffie-Hellman algorithm.■ AES: Advanced Encryption Standard (AES), as defined by NIST in FIPS 197.


CHAPTER 2

Parameter Checking

PolicyAll Java Card API implementations must conform to the Java model of parameter checking. That is, the API code should not check for those parameter errors which the VM is expected to detect. These include all parameter errors, such as null pointers, index out of bounds, and so forth, that result in standard runtime exceptions. The runtime exceptions that are thrown by the Java Card VM are:

■ ArithmeticException■ ArrayStoreException■ ClassCastException■ IndexOutOfBoundsException■ ArrayIndexOutOfBoundsException■ NegativeArraySizeException■ NullPointerException■ SecurityException

Exceptions to the PolicyIn some cases, it may be necessary to explicitly check parameters. These exceptions to the policy are documented in the Java Card API specification. A Java Card API implementation must not perform parameter checking with the intent to avoid runtime exceptions, unless this is clearly specified by the Java Card API specification.

5

Note – If multiple erroneous input parameters exist, any one of several runtime exceptions will be thrown by the VM. Java programmers rely on this behavior, but they do not rely on getting a specific exception. It is not necessary (nor is it reasonable or practical) to document the precise error handling for all possible combinations of equivalence classes of erroneous inputs. The value of this behavior is that the logic error in the calling program is detected and exposed via the runtime exception mechanism, rather than being masked by a normal return.


Package

java.ioDescriptionA subset of the java.io package in the standard Java programming language.

The java.io.IOException class is included in the Java Card API to maintain a hierarchy of exceptions identical to the standard Java programming language. The java.io.IOException class is the superclass of java.rmi.RemoteException, that indicates an exception occurred during a remote method call.

Class Summary

Exceptions

IOException A JCRE owned instance of IOException is thrown to signal that an I/O exception of some sort has occurred.

java.io 7

IOException java.io

IOException()

java.io

IOExceptionDeclarationpublic class IOException extends Exception java.lang.Object

|+--java.lang.Throwable

|+--java.lang.Exception

|+--java.io.IOException

Direct Known Subclasses: RemoteException

DescriptionA JCRE owned instance of IOException is thrown to signal that an I/O exception of some sort has occurred. This class is the general class of exceptions produced by failed or interrupted I/O operations.

JCRE owned instances of exception classes are temporary JCRE Entry Point Objects and can be accessed from any applet context. References to these temporary objects cannot be stored in class variables or instance variables or array components. See Java Card Runtime Environment (JCRE) Specification, section 6.2.1 for details.

This Java Card class’s functionality is a strict subset of the definition in the Java 2 Platform Standard Edition API Specification.

Constructors

IOException()

public IOException()

Member Summary

ConstructorsIOException()

Constructs an IOException.

Inherited Member Summary

Methods inherited from class Object

equals(Object)


java.io IOException

IOException()

Constructs an IOException.

IOException 9

IOException java.io

IOException()


Package

java.langDescriptionProvides classes that are fundamental to the design of the Java Card technology subset of the Java programming language. The classes in this package are derived from java.lang in the standard Java programming language and represent the core functionality required by the Java Card Virtual Machine. This core functionality is represented by the Object class, which is the base class for all Java language classes and the Throwable class, which is the base class for the exception and runtime exception classes.

The exceptions and runtime exceptions that are included in this package are those that can be thrown by the Java Card Virtual Machine. They represent only a subset of the exceptions available in java.lang in the standard Java programming language.

Class Summary

Classes

Object Class Object is the root of the Java Card class hierarchy.

Throwable The Throwable class is the superclass of all errors and exceptions in the Java Card subset of the Java language.

Exceptions

ArithmeticException A JCRE owned instance of ArithmeticException is thrown when an exceptional arithmetic condition has occurred.

ArrayIndexOutOfBoundsException A JCRE owned instance of ArrayIndexOutOfBoundsException is thrown to indicate that an array has been accessed with an illegal index.

ArrayStoreException A JCRE owned instance of ArrayStoreException is thrown to indicate that an attempt has been made to store the wrong type of object into an array of objects.

ClassCastException A JCRE owned instance of ClassCastException is thrown to indicate that the code has attempted to cast an object to a subclass of which it is not an instance.

Exception The class Exception and its subclasses are a form of Throwable that indicates conditions that a reasonable applet might want to catch.

IndexOutOfBoundsException A JCRE owned instance of IndexOutOfBoundsException is thrown to indicate that an index of some sort (such as to an array) is out of range.

NegativeArraySizeException A JCRE owned instance of NegativeArraySizeException is thrown if an applet tries to create an array with negative size.

NullPointerException A JCRE owned instance of NullPointerException is thrown when an applet attempts to use null in a case where an object is required.

RuntimeException RuntimeException is the superclass of those exceptions that can be thrown during the normal operation of the Java Card Virtual Machine.

java.lang 11

java.lang

SecurityException A JCRE owned instance of SecurityException is thrown by the Java Card Virtual Machine to indicate a security violation.

Class Summary


java.lang ArithmeticException

ArithmeticException()

java.lang

ArithmeticExceptionDeclarationpublic class ArithmeticException extends RuntimeException java.lang.Object



|+--java.lang.RuntimeException

|+--java.lang.ArithmeticException

DescriptionA JCRE owned instance of ArithmeticException is thrown when an exceptional arithmetic condition has occurred. For example, a “divide by zero” is an exceptional arithmetic condition.


This Java Card class’s functionality is a strict subset of the definition in the Java Platform Core API Specification.

Constructors

ArithmeticException()

public ArithmeticException()

Constructs an ArithmeticException.

Member Summary

ConstructorsArithmeticException()

Constructs an ArithmeticException.



equals(Object)

ArithmeticException 13

ArrayIndexOutOfBoundsException java.lang

ArrayIndexOutOfBoundsException()

java.lang

ArrayIndexOutOfBoundsExceptionDeclarationpublic class ArrayIndexOutOfBoundsException extends IndexOutOfBoundsException java.lang.Object




|+--java.lang.IndexOutOfBoundsException

|+--java.lang.ArrayIndexOutOfBoundsException

DescriptionA JCRE owned instance of ArrayIndexOutOfBoundsException is thrown to indicate that an array has been accessed with an illegal index. The index is either negative or greater than or equal to the size of the array.



Constructors


public ArrayIndexOutOfBoundsException()

Member Summary

ConstructorsArrayIndexOutOfBoundsException()

Constructs an ArrayIndexOutOfBoundsException.



equals(Object)


java.lang ArrayIndexOutOfBoundsException


Constructs an ArrayIndexOutOfBoundsException.

ArrayIndexOutOfBoundsException 15

ArrayStoreException java.lang


java.lang

ArrayStoreExceptionDeclarationpublic class ArrayStoreException extends RuntimeException java.lang.Object




|+--java.lang.ArrayStoreException

DescriptionA JCRE owned instance of ArrayStoreException is thrown to indicate that an attempt has been made to store the wrong type of object into an array of objects. For example, the following code generates an ArrayStoreException:

Object x[] = new AID[3];x[0] = new OwnerPIN( (byte) 3, (byte) 8);



Member Summary

ConstructorsArrayStoreException()

Constructs an ArrayStoreException.



equals(Object)


java.lang ArrayStoreException

ArrayStoreException()

Constructors


public ArrayStoreException()

Constructs an ArrayStoreException.

ArrayStoreException 17

ClassCastException java.lang


java.lang

ClassCastExceptionDeclarationpublic class ClassCastException extends RuntimeException java.lang.Object




|+--java.lang.ClassCastException

DescriptionA JCRE owned instance of ClassCastException is thrown to indicate that the code has attempted to cast an object to a subclass of which it is not an instance. For example, the following code generates a ClassCastException:

Object x = new OwnerPIN( (byte)3, (byte)8);JCSystem.getAppletShareableInterfaceObject( (AID)x, (byte)5 );



Member Summary

ConstructorsClassCastException()

Constructs a ClassCastException.



equals(Object)


java.lang ClassCastException

ClassCastException()

Constructors

ClassCastException()

public ClassCastException()

Constructs a ClassCastException.

ClassCastException 19

Exception java.lang

Exception()

java.lang

ExceptionDeclarationpublic class Exception extends Throwable java.lang.Object



Direct Known Subclasses: CardException, IOException, RuntimeException

DescriptionThe class Exception and its subclasses are a form of Throwable that indicates conditions that a reasonable applet might want to catch.


Constructors

Exception()

public Exception()

Constructs an Exception instance.

Member Summary

ConstructorsException()

Constructs an Exception instance.



equals(Object)


java.lang IndexOutOfBoundsException

Exception()

java.lang

IndexOutOfBoundsExceptionDeclarationpublic class IndexOutOfBoundsException extends RuntimeException java.lang.Object




|+--java.lang.IndexOutOfBoundsException

Direct Known Subclasses: ArrayIndexOutOfBoundsException

DescriptionA JCRE owned instance of IndexOutOfBoundsException is thrown to indicate that an index of some sort (such as to an array) is out of range.



Member Summary

ConstructorsIndexOutOfBoundsException()

Constructs an IndexOutOfBoundsException.



equals(Object)

IndexOutOfBoundsException 21

IndexOutOfBoundsException java.lang

IndexOutOfBoundsException()

Constructors

IndexOutOfBoundsException()

public IndexOutOfBoundsException()

Constructs an IndexOutOfBoundsException.


java.lang NegativeArraySizeException

NegativeArraySizeException()

java.lang

NegativeArraySizeExceptionDeclarationpublic class NegativeArraySizeException extends RuntimeException java.lang.Object




|+--java.lang.NegativeArraySizeException

DescriptionA JCRE owned instance of NegativeArraySizeException is thrown if an applet tries to create an array with negative size.



Constructors


public NegativeArraySizeException()

Constructs a NegativeArraySizeException.

Member Summary

ConstructorsNegativeArraySizeException()

Constructs a NegativeArraySizeException.



equals(Object)

NegativeArraySizeException 23

NullPointerException java.lang


java.lang

NullPointerExceptionDeclarationpublic class NullPointerException extends RuntimeException java.lang.Object




|+--java.lang.NullPointerException

DescriptionA JCRE owned instance of NullPointerException is thrown when an applet attempts to use null in a case where an object is required. These include:

• Calling the instance method of a null object.

• Accessing or modifying the field of a null object.

• Taking the length of null as if it were an array.

• Accessing or modifying the slots of null as if it were an array.

• Throwing null as if it were a Throwable value.



Member Summary

ConstructorsNullPointerException()

Constructs a NullPointerException.



equals(Object)


java.lang NullPointerException

NullPointerException()

Constructors

NullPointerException()

public NullPointerException()

Constructs a NullPointerException.

NullPointerException 25

Object java.lang

Object()

java.lang

ObjectDeclarationpublic class Object java.lang.Object

DescriptionClass Object is the root of the Java Card class hierarchy. Every class has Object as a superclass. All objects, including arrays, implement the methods of this class.


Constructors

Object()

public Object()

Methods

equals(Object)

public boolean equals(java.lang.Object obj)

Compares two Objects for equality.

The equals method implements an equivalence relation:

• It is reflexive: for any reference value x, x.equals(x) should return true.

• It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.

• It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.

• It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently

Member Summary

ConstructorsObject()

Methods boolean equals(Object obj)

Compares two Objects for equality.


java.lang Object

equals(Object)

return true or consistently return false.

• For any reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).

Parameters:obj - the reference object with which to compare.

Returns: true if this object is the same as the obj argument; false otherwise.

Object 27

RuntimeException java.lang

RuntimeException()

java.lang

RuntimeExceptionDeclarationpublic class RuntimeException extends Exception java.lang.Object




Direct Known Subclasses: ArithmeticException, ArrayStoreException, CardRuntimeException, ClassCastException, IndexOutOfBoundsException, NegativeArraySizeException, NullPointerException, SecurityException

DescriptionRuntimeException is the superclass of those exceptions that can be thrown during the normal operation of the Java Card Virtual Machine.

A method is not required to declare in its throws clause any subclasses of RuntimeException that might be thrown during the execution of the method but not caught.


Constructors

RuntimeException()

public RuntimeException()

Member Summary

ConstructorsRuntimeException()

Constructs a RuntimeException instance.



equals(Object)


java.lang RuntimeException

RuntimeException()

Constructs a RuntimeException instance.

RuntimeException 29

SecurityException java.lang

RuntimeException()

java.lang

SecurityExceptionDeclarationpublic class SecurityException extends RuntimeException java.lang.Object




|+--java.lang.SecurityException

DescriptionA JCRE owned instance of SecurityException is thrown by the Java Card Virtual Machine to indicate a security violation.

This exception is thrown when an attempt is made to illegally access an object belonging to another applet. It may optionally be thrown by a Java Card VM implementation to indicate fundamental language restrictions, such as attempting to invoke a private method in another class.

For security reasons, the JCRE implementation may mute the card instead of throwing this exception.



Member Summary

ConstructorsSecurityException()

Constructs a SecurityException.



equals(Object)


java.lang SecurityException

SecurityException()

Constructors

SecurityException()

public SecurityException()

Constructs a SecurityException.

SecurityException 31

Throwable java.lang

Throwable()

java.lang

ThrowableDeclarationpublic class Throwable java.lang.Object


Direct Known Subclasses: Exception

DescriptionThe Throwable class is the superclass of all errors and exceptions in the Java Card subset of the Java language. Only objects that are instances of this class (or of one of its subclasses) are thrown by the Java Card Virtual Machine or can be thrown by the Java throw statement. Similarly, only this class or one of its subclasses can be the argument type in a catch clause.


Constructors

Throwable()

public Throwable()

Constructs a new Throwable.

Member Summary

ConstructorsThrowable()

Constructs a new Throwable.



equals(Object)


Package

java.rmiDescriptionThe java.rmi package defines the Remote interface which identifies interfaces whose methods can be invoked from card acceptance device (CAD) client applications. It also defines a RemoteException that can be thrown to indicate an exception occurred during the execution of a remote method call.

Class Summary

Interfaces

Remote The Remote interface serves to identify interfaces whose methods may be invoked from a CAD client application.

Exceptions

RemoteException A JCRE owned instance of RemoteException is thrown to indicate that a communication-related exception has occurred during the execution of a remote method call.

java.rmi 33

Remote java.rmi

java.rmi

RemoteDeclarationpublic interface Remote

All Known Implementing Classes: CardRemoteObject

DescriptionThe Remote interface serves to identify interfaces whose methods may be invoked from a CAD client application. An object that is a remote object must directly or indirectly implement this interface. Only those methods specified in a “remote interface”, an interface that extends java.rmi.Remote are available remotely. Implementation classes can implement any number of remote interfaces and can extend other remote implementation classes. Java Card RMI provides a convenience class called javacard.framework.service.CardRemoteObject that remote object implementations can extend which facilitates remote object creation. For complete details on Java Card RMI, see the Java Card Runtime Environment Specification and the javacard.framework.service API package.


java.rmi RemoteException

RemoteException()

java.rmi

RemoteExceptionDeclarationpublic class RemoteException extends IOException java.lang.Object



|+--java.io.IOException

|+--java.rmi.RemoteException

DescriptionA JCRE owned instance of RemoteException is thrown to indicate that a communication-related exception has occurred during the execution of a remote method call. Each method of a remote interface, an interface that extends java.rmi.Remote, must list RemoteException or a superclass in its throws clause.


This Java Card class’s functionality is a strict subset of the definition in the Java 2 Platform Standard Edition API Specification.

Constructors

RemoteException()

public RemoteException()

Member Summary

ConstructorsRemoteException()

Constructs a RemoteException.



equals(Object)

RemoteException 35

RemoteException java.rmi

RemoteException()

Constructs a RemoteException.


Package

javacard.frameworkDescriptionProvides a framework of classes and interfaces for building, communicating with and working with Java Card applets. These classes and interfaces provide the minimum required functionality for a Java Card environment. If additional functionality is desired, for example to specialize the card for a particular market, other frameworks would need to be added.

The key classes and interfaces in this package are:

• AID-encapsulates the Application Identifier (AID) associated with an applet.

• APDU-provides methods for controlling card input and output.

• Applet-the base class for all Java Card applets on the card. It provides methods for working with applets to be loaded onto, installed into and executed on a Java Card-compliant smart card.

• CardException, CardRuntimeException-provide functionality similar to java.lang.Exception and java.lang.RuntimeException in the standard Java programming language, but specialized for the card environment.

• ISO7816-provides important constants for working with input and output data.

• JCSystem-provides methods for controlling system functions such as transaction management, transient objects, object deletion mechanism, resource management, and inter-applet object sharing.

• MultiSelectable-provides methods that support advanced programming techniques with logical channels.

• Shareable-provides a mechanism that lets objects that implement this interface be shared across an applet firewall.

• Util-provides convenient methods for working with arrays and array data.

Class Summary

Interfaces

ISO7816 ISO7816 encapsulates constants related to ISO 7816-3 and ISO 7816-4.

MultiSelectable The MultiSelectable interface serves to identify the implementing Applet subclass as being capable of concurrent selections.

PIN This interface represents a PIN.

Shareable The Shareable interface serves to identify all shared objects.

Classes

AID This class encapsulates the Application Identifier (AID) associated with an applet.

APDU Application Protocol Data Unit (APDU) is the communication format between the card and the off-card applications.

Applet This abstract class defines an applet in Java Card.

javacard.framework 37

javacard.framework

JCSystem The JCSystem class includes a collection of methods to control applet execution, resource management, atomic transaction management, object deletion mechanism and inter-applet object sharing in Java Card.

OwnerPIN This class represents an Owner PIN.

Util The Util class contains common utility functions.

Exceptions

APDUException APDUException represents an APDU related exception.

CardException The CardException class defines a field reason and two accessor methods getReason() and setReason().

CardRuntimeException The CardRuntimeException class defines a field reason and two accessor methods getReason() and setReason().

ISOException ISOException class encapsulates an ISO 7816-4 response status word as its reason code.

PINException PINException represents a OwnerPIN class access-related exception.

SystemException SystemException represents a JCSystem class related exception.

TransactionException TransactionException represents an exception in the transaction subsystem.

UserException UserException represents a User exception.

Class Summary


javacard.framework AID

javacard.framework

AIDDeclarationpublic class AID java.lang.Object

|+--javacard.framework.AID

DescriptionThis 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 JCRE 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 JCRE owned instances to identify itself and other applet instances.

JCRE owned instances of AID are permanent JCRE 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 JCRE 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 Java Card Runtime Environment (JCRE) Specification, section 6.2 for details.

See Also: JCSystem, SystemException

Member Summary

ConstructorsAID(byte[] bArray, short offset, byte length)

The JCRE uses this constructor to create a new AID instance encapsulating the specified AID bytes.

Methods boolean equals(byte[] bArray, short offset, byte length)

Checks if the specified AID bytes in bArray are the same as those encapsulated in this AID object.

boolean equals(java.lang.Object anObject)Compares the AID bytes in this AID instance to the AID bytes in the specified object.

byte getBytes(byte[] dest, short offset)Called to get all the AID bytes encapsulated within AID object.

byte getPartialBytes(short aidOffset, byte[] dest, short oOffset, byte oLength)

Called to get part of the AID bytes encapsulated within the AID object starting at the specified offset for the specified length.

AID 39

AID javacard.framework

AID(byte[], short, byte)

Constructors

AID(byte[], short, byte)

public AID(byte[] bArray, short offset, byte length)

throws SystemException, NullPointerException,

ArrayIndexOutOfBoundsException, SecurityException

The JCRE uses this constructor to create a new AID instance encapsulating the specified AID bytes.

Parameters:bArray - the byte array containing the AID bytes.

offset - the start of AID bytes in bArray.

length - the length of the AID bytes in bArray.

Throws:SecurityException - if the bArray array is not accessible in the caller’s context.

SystemException - with the following reason code:

• SystemException.ILLEGAL_VALUE if the length parameter is less than 5 or greater than 16.

NullPointerException - if the bArray parameter is null

ArrayIndexOutOfBoundsException - if the offset parameter or length parameter is negative or if offset+length is greater than the length of the bArray parameter

Methods

getBytes(byte[], short)

public final byte getBytes(byte[] dest, short offset)

throws NullPointerException, ArrayIndexOutOfBoundsException,

SecurityException

Called to get all the AID bytes encapsulated within AID object.

Parameters:dest - byte array to copy the AID bytes.

offset - within dest where the AID bytes begin.

Returns: the length of the AID bytes.

boolean partialEquals(byte[] bArray, short offset, byte length)Checks if the specified partial AID byte sequence matches the first length bytes of the encapsulated AID bytes within this AID object.

boolean RIDEquals(AID otherAID)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.

Member Summary



equals(Object)

Throws:SecurityException - if the dest array is not accessible in the caller’s context.

NullPointerException - if the dest parameter is null

ArrayIndexOutOfBoundsException - if the offset parameter is negative or offset+length of AID bytes is greater than the length of the dest array

equals(Object)

public final boolean equals(java.lang.Object anObject)

throws SecurityException

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.

Overrides: equals in class Object

Parameters:anObject - the object to compare this AID against.

Returns: true if the AID byte values are equal, false otherwise.

Throws:SecurityException - if anObject object is not accessible in the caller’s context.

equals(byte[], short, byte)

public final boolean equals(byte[] bArray, short offset, byte length)

throws ArrayIndexOutOfBoundsException, SecurityException

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.


Parameters:bArray - containing the AID bytes

offset - within bArray to begin

length - of AID bytes in bArray

Returns: true if equal, false otherwise.



partialEquals(byte[], short, byte)

public final boolean partialEquals(byte[] bArray, short offset, byte length)

throws ArrayIndexOutOfBoundsException, SecurityException

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

AID 41


RIDEquals(AID)

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.


Parameters:bArray - containing the partial AID byte sequence

offset - within bArray to begin

length - of partial AID bytes in bArray

Returns: true if equal, false otherwise.



RIDEquals(AID)

public final boolean RIDEquals(javacard.framework.AID otherAID)


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.


Parameters:otherAID - the AID to compare against.

Returns: true if the RID bytes match, false otherwise.

Throws:SecurityException - if the otherAID object is not accessible in the caller’s context.

getPartialBytes(short, byte[], short, byte)

public final byte getPartialBytes(short aidOffset, byte[] dest, short oOffset,

byte oLength)

throws NullPointerException, ArrayIndexOutOfBoundsException,

SecurityException

Called to get part of the AID bytes encapsulated within the AID object starting at the specified offset for the specified length.

Parameters:aidOffset - offset within AID array to begin copying bytes.

dest - the destination byte array to copy the AID bytes into.

oOffset - offset within dest where the output bytes begin.

oLength - the length of bytes requested in dest. 0 implies a request to copy all remaining AID bytes.

Returns: the actual length of the bytes returned in dest.




Throws:SecurityException - if the dest array is not accessible in the caller’s context.

NullPointerException - if the dest parameter is null

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

AID 43

APDU javacard.framework


javacard.framework

APDUDeclarationpublic final class APDU java.lang.Object

|+--javacard.framework.APDU

DescriptionApplication Protocol Data Unit (APDU) is the communication format between the card and the off-card applications. The format of the APDU is defined in ISO specification 7816-4.

This class only supports messages which conform to the structure of command and response defined in ISO 7816-4. The behavior of messages which use proprietary structure of messages ( for example with header CLA byte in range 0xD0-0xFE ) is undefined. This class does not support extended length fields.

The APDU object is owned by the JCRE. The APDU class maintains a byte array buffer which is used to transfer incoming APDU header and data bytes as well as outgoing data. The buffer length must be at least 133 bytes ( 5 bytes of header and 128 bytes of data ). The JCRE must zero out the APDU buffer before each new message received from the CAD.

The JCRE designates the APDU object as a temporary JCRE Entry Point Object (See Java Card Runtime Environment (JCRE) Specification, section 6.2.1 for details). A temporary JCRE Entry Point Object can be accessed from any applet context. References to these temporary objects cannot be stored in class variables or instance variables or array components.

The JCRE similarly marks the APDU buffer as a global array (See Java Card Runtime Environment (JCRE) Specification, section 6.2.2 for details). A global array can be accessed from any applet context. References to global arrays cannot be stored in class variables or instance variables or array components.

The applet receives the APDU instance to process from the JCRE in the Applet.process(APDU) method, and the first five bytes [ CLA, INS, P1, P2, P3 ] are available in the APDU buffer.

The APDU class API is designed to be transport protocol independent. In other words, applets can use the same APDU methods regardless of whether the underlying protocol in use is T=0 or T=1 (as defined in ISO 7816-3).

The incoming APDU data size may be bigger than the APDU buffer size and may therefore need to be read in portions by the applet. Similarly, the outgoing response APDU data size may be bigger than the APDU buffer size and may need to be written in portions by the applet. The APDU class has methods to facilitate this.

For sending large byte arrays as response data, the APDU class provides a special method sendBytesLong() which manages the APDU buffer.


javacard.framework APDU


// The purpose of this example is to show most of the methods// in use and not to depict any particular APDU processing

public void process(APDU apdu){// ...byte[] buffer = apdu.getBuffer();byte cla = buffer[ISO7816.OFFSET_CLA];byte ins = buffer[ISO7816.OFFSET_INS];...// assume this command has incoming data// Lc tells us the incoming apdu command lengthshort bytesLeft = (short) (buffer[ISO7816.OFFSET_LC] & 0x00FF);if (bytesLeft < (short)55) ISOException.throwIt( ISO7816.SW_WRONG_LENGTH );short readCount = apdu.setIncomingAndReceive();while ( bytesLeft > 0){

// process bytes in buffer[5] to buffer[readCount+4];bytesLeft -= readCount;readCount = apdu.receiveBytes ( ISO7816.OFFSET_CDATA );}

////...//// Note that for a short response as in the case illustrated here// the three APDU method calls shown : setOutgoing(),setOutgoingLength() & sendBytes()// could be replaced by one APDU method call : setOutgoingAndSend().// construct the reply APDUshort le = apdu.setOutgoing();if (le < (short)2) ISOException.throwIt( ISO7816.SW_WRONG_LENGTH );apdu.setOutgoingLength( (short)3 );// build response data in apdu.buffer[ 0.. outCount-1 ];buffer[0] = (byte)1; buffer[1] = (byte)2; buffer[3] = (byte)3;apdu.sendBytes ( (short)0 , (short)3 );// return good complete status 90 00}

The APDU class also defines a set of STATE_.. constants which represent the various processing states of the APDUobject based on the methods invoked and the state of the data transfers. The getCurrentState() method returns the current state.

Note that the state number assignments are ordered as follows: STATE_INITIAL < STATE_PARTIAL_INCOMING < STATE_FULL_INCOMING < STATE_OUTGOING < STATE_OUTGOING_LENGTH_KNOWN < STATE_PARTIAL_OUTGOING < STATE_FULL_OUTGOING.

The following are processing error states and have negative state number assignments : STATE_ERROR_NO_T0_GETRESPONSE, STATE_ERROR_T1_IFD_ABORT, STATE_ERROR_IO and STATE_ERROR_NO_T0_REISSUE. returns the current processing state of the

See Also: APDUException, ISOException

Member Summary

Fieldsstatic byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_A

Transport protocol Media - Contactless Type Astatic byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_B

Transport protocol Media - Contactless Type Bstatic byte PROTOCOL_MEDIA_DEFAULT

Transport protocol Media - Contacted Asynchronous Half Duplex

APDU 45



static byte PROTOCOL_MEDIA_MASKMedia nibble mask in protocol byte

static byte PROTOCOL_MEDIA_USBTransport protocol Media - USB

static byte PROTOCOL_T0ISO 7816 transport protocol type T=0.

static byte PROTOCOL_T1ISO 7816 transport protocol type T=1. This constant is also used to denote the variant for contactless cards defined in ISO 14443-4.

static byte PROTOCOL_TYPE_MASKType nibble mask in protocol byte

static byte STATE_ERROR_IOThis error state of a APDU object occurs when an APDUException with reason code APDUException.IO_ERROR has been thrown.

static byte STATE_ERROR_NO_T0_GETRESPONSEThis error state of a APDU object occurs when an APDUException with reason code APDUException.NO_T0_GETRESPONSE has been thrown.

static byte STATE_ERROR_NO_T0_REISSUEThis error state of a APDU object occurs when an APDUException with reason code APDUException.NO_T0_REISSUE has been thrown.

static byte STATE_ERROR_T1_IFD_ABORTThis error state of a APDU object occurs when an APDUException with reason code APDUException.T1_IFD_ABORT has been thrown.

static byte STATE_FULL_INCOMINGThis is the state of a APDU object when all the incoming data been received.

static byte STATE_FULL_OUTGOINGThis is the state of a APDU object when all outbound data has been transferred.

static byte STATE_INITIALThis is the state of a new APDU object when only the command header is valid.

static byte STATE_OUTGOINGThis is the state of a new APDU object when data transfer mode is outbound but length is not yet known.

static byte STATE_OUTGOING_LENGTH_KNOWNThis is the state of a APDU object when data transfer mode is outbound and outbound length is known.

static byte STATE_PARTIAL_INCOMINGThis is the state of a APDU object when incoming data has partially been received.

static byte STATE_PARTIAL_OUTGOINGThis is the state of a APDU object when some outbound data has been transferred but not all.

Methods byte[] getBuffer()

Returns the APDU buffer byte array.static byte getCLAChannel()

Returns the logical channel number associated with the current APDU command based on the CLA byte.

static APDU getCurrentAPDU()This method is called to obtain a reference to the current APDU object.

static byte[] getCurrentAPDUBuffer()This method is called to obtain a reference to the current APDU buffer.

byte getCurrentState()This method returns the current processing state of the APDU object.

Member Summary



STATE_INITIAL

Fields

STATE_INITIAL

public static final byte STATE_INITIAL

static short getInBlockSize()Returns the configured incoming block size. In T=1 protocol, this corresponds to IFSC (information field size for ICC), the maximum size of incoming data blocks into the card. In T=0 protocol, this method returns 1.

byte getNAD()In T=1 protocol, this method returns the Node Address byte, NAD. In T=0 protocol, this method returns 0.

static short getOutBlockSize()Returns the configured outgoing block size. In T=1 protocol, this corresponds to IFSD (information field size for interface device), the maximum size of outgoing data blocks to the CAD. In T=0 protocol, this method returns 258 (accounts for 2 status bytes).

static byte getProtocol()Returns the ISO 7816 transport protocol type, T=1 or T=0 in the low nibble and the transport media in the upper nibble in use.

short receiveBytes(short bOff)Gets as many data bytes as will fit without APDU buffer overflow, at the specified offset bOff. Gets all the remaining bytes if they fit.

void sendBytes(short bOff, short len)Sends len more bytes from APDU buffer at specified offset bOff.

void sendBytesLong(byte[] outData, short bOff, short len)Sends len more bytes from outData byte array starting at specified offset bOff.

short setIncomingAndReceive()This is the primary receive method.

short setOutgoing()This method is used to set the data transfer direction to outbound and to obtain the expected length of response (Le).

void setOutgoingAndSend(short bOff, short len)This is the “convenience” send method.

void setOutgoingLength(short len)Sets the actual length of response data.

short setOutgoingNoChaining()This method is used to set the data transfer direction to outbound without using BLOCK CHAINING (See ISO 7816-3/4) and to obtain the expected length of response (Le).

static void waitExtension()Requests additional processing time from CAD.



equals(Object)

Member Summary

APDU 47


STATE_PARTIAL_INCOMING

This is the state of a new APDU object when only the command header is valid.

STATE_PARTIAL_INCOMING

public static final byte STATE_PARTIAL_INCOMING

This is the state of a APDU object when incoming data has partially been received.

STATE_FULL_INCOMING

public static final byte STATE_FULL_INCOMING

This is the state of a APDU object when all the incoming data been received.

STATE_OUTGOING

public static final byte STATE_OUTGOING

This is the state of a new APDU object when data transfer mode is outbound but length is not yet known.

STATE_OUTGOING_LENGTH_KNOWN

public static final byte STATE_OUTGOING_LENGTH_KNOWN

This is the state of a APDU object when data transfer mode is outbound and outbound length is known.

STATE_PARTIAL_OUTGOING

public static final byte STATE_PARTIAL_OUTGOING

This is the state of a APDU object when some outbound data has been transferred but not all.

STATE_FULL_OUTGOING

public static final byte STATE_FULL_OUTGOING

This is the state of a APDU object when all outbound data has been transferred.

STATE_ERROR_NO_T0_GETRESPONSE

public static final byte STATE_ERROR_NO_T0_GETRESPONSE

This error state of a APDU object occurs when an APDUException with reason code APDUException.NO_T0_GETRESPONSE has been thrown.

STATE_ERROR_T1_IFD_ABORT

public static final byte STATE_ERROR_T1_IFD_ABORT

This error state of a APDU object occurs when an APDUException with reason code APDUException.T1_IFD_ABORT has been thrown.

STATE_ERROR_IO

public static final byte STATE_ERROR_IO

This error state of a APDU object occurs when an APDUException with reason code APDUException.IO_ERROR has been thrown.



STATE_ERROR_NO_T0_REISSUE

STATE_ERROR_NO_T0_REISSUE

public static final byte STATE_ERROR_NO_T0_REISSUE

This error state of a APDU object occurs when an APDUException with reason code APDUException.NO_T0_REISSUE has been thrown.

PROTOCOL_MEDIA_MASK

public static final byte PROTOCOL_MEDIA_MASK

Media nibble mask in protocol byte

PROTOCOL_TYPE_MASK

public static final byte PROTOCOL_TYPE_MASK

Type nibble mask in protocol byte

PROTOCOL_T0

public static final byte PROTOCOL_T0

ISO 7816 transport protocol type T=0.

PROTOCOL_T1

public static final byte PROTOCOL_T1

ISO 7816 transport protocol type T=1. This constant is also used to denote the variant for contactless cards defined in ISO 14443-4.

PROTOCOL_MEDIA_DEFAULT

public static final byte PROTOCOL_MEDIA_DEFAULT

Transport protocol Media - Contacted Asynchronous Half Duplex

PROTOCOL_MEDIA_CONTACTLESS_TYPE_A

public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_A

Transport protocol Media - Contactless Type A

PROTOCOL_MEDIA_CONTACTLESS_TYPE_B

public static final byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_B

Transport protocol Media - Contactless Type B

PROTOCOL_MEDIA_USB

public static final byte PROTOCOL_MEDIA_USB

Transport protocol Media - USB

APDU 49


getBuffer()

Methods

getBuffer()

public byte[] getBuffer()

Returns the APDU buffer byte array.

Note:

• References to the APDU buffer byte array cannot be stored in class variables or instance variables or array components. See Java Card Runtime Environment (JCRE) Specification, section 6.2.2 for details.

Returns: byte array containing the APDU buffer

getInBlockSize()

public static short getInBlockSize()

Returns the configured incoming block size. In T=1 protocol, this corresponds to IFSC (information field size for ICC), the maximum size of incoming data blocks into the card. In T=0 protocol, this method returns 1. IFSC is defined in ISO 7816-3.

This information may be used to ensure that there is enough space remaining in the APDU buffer when receiveBytes() is invoked.

Note:

• On receiveBytes() the bOff param should account for this potential blocksize.

Returns: incoming block size setting.

See Also: receiveBytes(short)

getOutBlockSize()

public static short getOutBlockSize()

Returns the configured outgoing block size. In T=1 protocol, this corresponds to IFSD (information field size for interface device), the maximum size of outgoing data blocks to the CAD. In T=0 protocol, this method returns 258 (accounts for 2 status bytes). IFSD is defined in ISO 7816-3.

This information may be used prior to invoking the setOutgoingLength() method, to limit the length of outgoing messages when BLOCK CHAINING is not allowed.

Note:

• On setOutgoingLength() the len param should account for this potential blocksize.

Returns: outgoing block size setting.

See Also: setOutgoingLength(short)

getProtocol()

public static byte getProtocol()

Returns the ISO 7816 transport protocol type, T=1 or T=0 in the low nibble and the transport media in the upper nibble in use.



getNAD()

Returns: the protocol media and type in progress. Valid nibble codes are listed in PROTOCOL_ .. constants above. See PROTOCOL_T0

getNAD()

public byte getNAD()

In T=1 protocol, this method returns the Node Address byte, NAD. In T=0 protocol, this method returns 0. This may be used as additional information to maintain multiple contexts.

Returns: NAD transport byte as defined in ISO 7816-3.

setOutgoing()

public short setOutgoing()

throws APDUException

This method is used to set the data transfer direction to outbound and to obtain the expected length of response (Le).

Notes.

• Any remaining incoming data will be discarded.

• In T=0 (Case 4) protocol, this method will return 256.

• This method sets the state of the APDU object to STATE_OUTGOING.

Returns: Le, the expected length of response.

Throws:APDUException - with the following reason codes:

• APDUException.ILLEGAL_USE if this method or setOutgoingNoChaining() method already invoked.

• APDUException.IO_ERROR on I/O error.

setOutgoingNoChaining()

public short setOutgoingNoChaining()


This method is used to set the data transfer direction to outbound without using BLOCK CHAINING (See ISO 7816-3/4) and to obtain the expected length of response (Le). This method should be used in place of the setOutgoing() method by applets which need to be compatible with legacy CAD/terminals which do not support ISO 7816-3/4 defined block chaining. See Java Card Runtime Environment (JCRE) Specification, section 9.4 for details.

Notes.

• Any remaining incoming data will be discarded.

• In T=0 (Case 4) protocol, this method will return 256.

• When this method is used, the waitExtension() method cannot be used.

• In T=1 protocol, retransmission on error may be restricted.

• In T=0 protocol, the outbound transfer must be performed without using (ISO7816.SW_BYTES_REMAINING_00+count) response status chaining.

• In T=1 protocol, the outbound transfer must not set the More(M) Bit in the PCB of the I block. See ISO

APDU 51


setOutgoingLength(short)

7816-3.

• This method sets the state of the APDU object to STATE_OUTGOING.

Returns: Le, the expected length of response data.


• APDUException.ILLEGAL_USE if this method or setOutgoing() method already invoked.


setOutgoingLength(short)

public void setOutgoingLength(short len)


Sets the actual length of response data. Default is 0.

Note:

• In T=0 (Case 2&4) protocol, the length is used by the JCRE to prompt the CAD for GET RESPONSE commands.

• This method sets the state of the APDU object to STATE_OUTGOING_LENGTH_KNOWN.

Parameters:len - the length of response data.


• APDUException.ILLEGAL_USE if setOutgoing() not called or this method already invoked.

• APDUException.BAD_LENGTH if len is greater than 256 or if non BLOCK CHAINED data transfer is requested and len is greater than (IFSD-2), where IFSD is the Outgoing Block Size. The -2 accounts for the status bytes in T=1.

• APDUException.NO_GETRESPONSE if T=0 protocol is in use and the CAD does not respond to (ISO7816.SW_BYTES_REMAINING_00+count) response status with GET RESPONSE command on the same origin logical channel number as that of the current APDU command.

• APDUException.NO_T0_REISSUE if T=0 protocol is in use and the CAD does not respond to (ISO7816.SW_CORRECT_LENGTH_00+count) response status by re-issuing same APDU command on the same origin logical channel number as that of the current APDU command with the corrected length.


See Also: getOutBlockSize()

receiveBytes(short)

public short receiveBytes(short bOff)


Gets as many data bytes as will fit without APDU buffer overflow, at the specified offset bOff. Gets all the remaining bytes if they fit.

Notes:



setIncomingAndReceive()

• The space in the buffer must allow for incoming block size.

• In T=1 protocol, if all the remaining bytes do not fit in the buffer, this method may return less bytes than the maximum incoming block size (IFSC).

• In T=0 protocol, if all the remaining bytes do not fit in the buffer, this method may return less than a full buffer of bytes to optimize and reduce protocol overhead.

• In T=1 protocol, if this method throws an APDUException with T1_IFD_ABORT reason code, the JCRE will restart APDU command processing using the newly received command. No more input data can be received. No output data can be transmitted. No error status response can be returned.

• This method sets the state of the APDU object to STATE_PARTIAL_INCOMING if all incoming bytes are not received.

• This method sets the state of the APDU object to STATE_FULL_INCOMING if all incoming bytes are received.

Parameters:bOff - the offset into APDU buffer.

Returns: number of bytes read. Returns 0 if no bytes are available.


• APDUException.ILLEGAL_USE if setIncomingAndReceive() not called or if setOutgoing() or setOutgoingNoChaining() previously invoked.

• APDUException.BUFFER_BOUNDS if not enough buffer space for incoming block size.


• APDUException.T1_IFD_ABORT if T=1 protocol is in use and the CAD sends in an ABORT S-Block command to abort the data transfer.

See Also: getInBlockSize()

setIncomingAndReceive()

public short setIncomingAndReceive()


This is the primary receive method. Calling this method indicates that this APDU has incoming data. This method gets as many bytes as will fit without buffer overflow in the APDU buffer following the header. It gets all the incoming bytes if they fit.

Notes:

• In T=0 ( Case 3&4 ) protocol, the P3 param is assumed to be Lc.

• Data is read into the buffer at offset 5.

• In T=1 protocol, if all the incoming bytes do not fit in the buffer, this method may return less bytes than the maximum incoming block size (IFSC).

• In T=0 protocol, if all the incoming bytes do not fit in the buffer, this method may return less than a full buffer of bytes to optimize and reduce protocol overhead.

• This method sets the transfer direction to be inbound and calls receiveBytes(5).

• This method may only be called once in a Applet.process() method.

• This method sets the state of the APDU object to STATE_PARTIAL_INCOMING if all incoming bytes

APDU 53


sendBytes(short, short)

are not received.

• This method sets the state of the APDU object to STATE_FULL_INCOMING if all incoming bytes are received.

Returns: number of data bytes read. The Le byte, if any, is not included in the count. Returns 0 if no bytes are available.


• APDUException.ILLEGAL_USE if setIncomingAndReceive() already invoked or if setOutgoing() or setOutgoingNoChaining() previously invoked.



sendBytes(short, short)

public void sendBytes(short bOff, short len)


Sends len more bytes from APDU buffer at specified offset bOff.

If the last part of the response is being sent by the invocation of this method, the APDU buffer must not be altered. If the data is altered, incorrect output may be sent to the CAD. Requiring that the buffer not be altered allows the implementation to reduce protocol overhead by transmitting the last part of the response along with the status bytes.

Notes:

• If setOutgoingNoChaining() was invoked, output block chaining must not be used.

• In T=0 protocol, if setOutgoingNoChaining() was invoked, Le bytes must be transmitted before (ISO7816.SW_BYTES_REMAINING_00+remaining bytes) response status is returned.

• In T=0 protocol, if this method throws an APDUException with NO_T0_GETRESPONSE or NO_T0_REISSUE reason code, the JCRE will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned.

• In T=1 protocol, if this method throws an APDUException with T1_IFD_ABORT reason code, the JCRE will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned.

• This method sets the state of the APDU object to STATE_PARTIAL_OUTGOING if all outgoing bytes have not been sent.

• This method sets the state of the APDU object to STATE_FULL_OUTGOING if all outgoing bytes have been sent.


len - the length of the data in bytes to send.


• APDUException.ILLEGAL_USE if setOutgoingLength() not called or setOutgoingAndSend() previously invoked or response byte count exceeded or if



sendBytesLong(byte[], short, short)

APDUException.NO_T0_GETRESPONSE or APDUException.NO_T0_REISSUE or APDUException.T1_IFD_ABORT previously thrown.

• APDUException.BUFFER_BOUNDS if bOff is negative or len is negative or bOff+len exceeds the buffer size.


• APDUException.NO_GETRESPONSE if T=0 protocol is in use and the CAD does not respond to (ISO7816.SW_BYTES_REMAINING_00+count) response status with GET RESPONSE command on the same origin logical channel number as that of the current APDU command.

• APDUException.NO_T0_REISSUE if T=0 protocol is in use and the CAD does not respond to (ISO7816.SW_CORRECT_LENGTH_00+count) response status by re-issuing same APDU command on the same origin logical channel number as that of the current APDU command with the corrected length.


See Also: setOutgoing(), setOutgoingNoChaining()

sendBytesLong(byte[], short, short)

public void sendBytesLong(byte[] outData, short bOff, short len)

throws APDUException, SecurityException

Sends len more bytes from outData byte array starting at specified offset bOff.

If the last of the response is being sent by the invocation of this method, the APDU buffer must not be altered. If the data is altered, incorrect output may be sent to the CAD. Requiring that the buffer not be altered allows the implementation to reduce protocol overhead by transmitting the last part of the response along with the status bytes.

The JCRE may use the APDU buffer to send data to the CAD.

Notes:

• If setOutgoingNoChaining() was invoked, output block chaining must not be used.

• In T=0 protocol, if setOutgoingNoChaining() was invoked, Le bytes must be transmitted before (ISO7816.SW_BYTES_REMAINING_00+remaining bytes) response status is returned.

• In T=0 protocol, if this method throws an APDUException with NO_T0_GETRESPONSE or NO_T0_REISSUE reason code, the JCRE will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned.

• In T=1 protocol, if this method throws an APDUException with T1_IFD_ABORT reason code, the JCRE will restart APDU command processing using the newly received command. No more output data can be transmitted. No error status response can be returned.

• This method sets the state of the APDU object to STATE_PARTIAL_OUTGOING if all outgoing bytes have not been sent.

• This method sets the state of the APDU object to STATE_FULL_OUTGOING if all outgoing bytes have been sent.

Parameters:outData - the source data byte array.

bOff - the offset into OutData array.

APDU 55


setOutgoingAndSend(short, short)

len - the byte length of the data to send.

Throws:SecurityException - if the outData array is not accessible in the caller’s context.

APDUException - with the following reason codes:

• APDUException.ILLEGAL_USE if setOutgoingLength() not called or setOutgoingAndSend() previously invoked or response byte count exceeded or if APDUException.NO_T0_GETRESPONSE or APDUException.NO_T0_REISSUE or APDUException.NO_T0_REISSUE previously thrown.


• APDUException.NO_T0_GETRESPONSE if T=0 protocol is in use and CAD does not respond to (ISO7816.SW_BYTES_REMAINING_00+count) response status with GET RESPONSE command on the same origin logical channel number as that of the current APDU command.


See Also: setOutgoing(), setOutgoingNoChaining()

setOutgoingAndSend(short, short)

public void setOutgoingAndSend(short bOff, short len)


This is the “convenience” send method. It provides for the most efficient way to send a short response which fits in the buffer and needs the least protocol overhead. This method is a combination of setOutgoing(), setOutgoingLength( len ) followed by sendBytes ( bOff, len ). In addition, once this method is invoked, sendBytes() and sendBytesLong() methods cannot be invoked and the APDU buffer must not be altered.

Sends len byte response from the APDU buffer starting at the specified offset bOff.

Notes:

• No other APDU send methods can be invoked.

• The APDU buffer must not be altered. If the data is altered, incorrect output may be sent to the CAD.

• The actual data transmission may only take place on return from Applet.process()

• This method sets the state of the APDU object to STATE_FULL_OUTGOING.


len - the bytelength of the data to send.


• APDUException.ILLEGAL_USE if setOutgoing() or setOutgoingAndSend() previously invoked or response byte count exceeded.


getCurrentState()

public byte getCurrentState()



getCurrentAPDU()

This method returns the current processing state of the APDU object. It is used by the BasicService class to help services collaborate in the processing of an incoming APDU command. Valid codes are listed in STATE_ .. constants above. See STATE_INITIAL

Returns: the current processing state of the APDU

See Also: BasicService

getCurrentAPDU()

public static javacard.framework.APDU getCurrentAPDU()


This method is called to obtain a reference to the current APDU object. This method can only be called in the context of the currently selected applet.

Note:

• Do not call this method directly or indirectly from within a method invoked remotely via Java Card RMI method invocation from the client. The APDU object and APDU buffer are reserved for use by RMIService. Remote method parameter data may become corrupted.

Returns: the current APDU object being processed

Throws:SecurityException - if

• the current context is not the context of the currently selected applet instance or

• the method is not called, directly or indirectly, from the applet’s process method.

• the method is called during applet installation.

getCurrentAPDUBuffer()

public static byte[] getCurrentAPDUBuffer()


This method is called to obtain a reference to the current APDU buffer. This method can only be called in the context of the currently selected applet.

Note:

• Do not call this method directly or indirectly from within a method invoked remotely via Java Card RMI method invocation from the client. The APDU object and APDU buffer are reserved for use by RMIService. Remote method parameter data may become corrupted.

Returns: the APDU buffer of the APDU object being processed

Throws:SecurityException - if

• the current context is not the context of the currently selected applet or

• the method is not called, directly or indirectly, from the applet’s process method.

• the method is called during applet installation.

getCLAChannel()

public static byte getCLAChannel()

APDU 57


waitExtension()

Returns the logical channel number associated with the current APDU command based on the CLA byte. A number in the range 0-3 based on the least significant two bits of the CLA byte is returned if the command contains logical channel encoding. If the command does not contain logical channel information, 0 is returned. See Java Card Runtime Environment (JCRE) Specification, section 4.3 for encoding details.

Returns: logical channel number, if present, within the CLA byte, 0 otherwise.

waitExtension()

public static void waitExtension()


Requests additional processing time from CAD. The implementation should ensure that this method needs to be invoked only under unusual conditions requiring excessive processing times.

Notes:

• In T=0 protocol, a NULL procedure byte is sent to reset the work waiting time (see ISO 7816-3).

• In T=1 protocol, the implementation needs to request the same T=0 protocol work waiting time quantum by sending a T=1 protocol request for wait time extension(see ISO 7816-3).

• If the implementation uses an automatic timer mechanism instead, this method may do nothing.


• APDUException.ILLEGAL_USE if setOutgoingNoChaining() previously invoked.



javacard.framework APDUException

waitExtension()

javacard.framework

APDUExceptionDeclarationpublic class APDUException extends CardRuntimeException java.lang.Object




|+--javacard.framework.CardRuntimeException

|+--javacard.framework.APDUException

DescriptionAPDUException represents an APDU related exception.

The APDU class throws JCRE owned instances of APDUException.


See Also: APDU

Member Summary

Fieldsstatic short BAD_LENGTH

This reason code is used by the APDU.setOutgoingLength() method to indicate that the length parameter is greater that 256 or if non BLOCK CHAINED data transfer is requested and len is greater than (IFSD-2), where IFSD is the Outgoing Block Size.

static short BUFFER_BOUNDSThis reason code is used by the APDU.sendBytes() method to indicate that the sum of buffer offset parameter and the byte length parameter exceeds the APDU buffer size.

static short ILLEGAL_USEThis APDUException reason code indicates that the method should not be invoked based on the current state of the APDU.

static short IO_ERRORThis reason code indicates that an unrecoverable error occurred in the I/O transmission layer.

static short NO_T0_GETRESPONSEThis reason code indicates that during T=0 protocol, the CAD did not return a GET RESPONSE command in response to a <61xx> response status to send additional data.

APDUException 59

APDUException javacard.framework

ILLEGAL_USE

Fields

ILLEGAL_USE

public static final short ILLEGAL_USE

This APDUException reason code indicates that the method should not be invoked based on the current state of the APDU.

BUFFER_BOUNDS

public static final short BUFFER_BOUNDS

This reason code is used by the APDU.sendBytes() method to indicate that the sum of buffer offset parameter and the byte length parameter exceeds the APDU buffer size.

BAD_LENGTH

public static final short BAD_LENGTH

This reason code is used by the APDU.setOutgoingLength() method to indicate that the length parameter is greater that 256 or if non BLOCK CHAINED data transfer is requested and len is greater than (IFSD-2), where IFSD is the Outgoing Block Size.

static short NO_T0_REISSUEThis reason code indicates that during T=0 protocol, the CAD did not reissue the same APDU command with the corrected length in response to a <6Cxx> response status to request command reissue with the specified length.

static short T1_IFD_ABORTThis reason code indicates that during T=1 protocol, the CAD returned an ABORT S-Block command and aborted the data transfer.

ConstructorsAPDUException(short reason)

Constructs an APDUException.

Methodsstatic void throwIt(short reason)

Throws the JCRE owned instance of APDUException with the specified reason.


Methods inherited from interface CardRuntimeException

getReason(), setReason(short)


equals(Object)

Member Summary


javacard.framework APDUException

IO_ERROR

IO_ERROR

public static final short IO_ERROR

This reason code indicates that an unrecoverable error occurred in the I/O transmission layer.

NO_T0_GETRESPONSE

public static final short NO_T0_GETRESPONSE

This reason code indicates that during T=0 protocol, the CAD did not return a GET RESPONSE command in response to a <61xx> response status to send additional data. The outgoing transfer has been aborted. No more data or status can be sent to the CAD in this Applet.process() method.

T1_IFD_ABORT

public static final short T1_IFD_ABORT

This reason code indicates that during T=1 protocol, the CAD returned an ABORT S-Block command and aborted the data transfer. The incoming or outgoing transfer has been aborted. No more data can be received from the CAD. No more data or status can be sent to the CAD in this Applet.process() method.

NO_T0_REISSUE

public static final short NO_T0_REISSUE

This reason code indicates that during T=0 protocol, the CAD did not reissue the same APDU command with the corrected length in response to a <6Cxx> response status to request command reissue with the specified length. The outgoing transfer has been aborted. No more data or status can be sent to the CAD in this Applet.process() method.

Constructors

APDUException(short)

public APDUException(short reason)

Constructs an APDUException. To conserve on resources use throwIt() to use the JCRE owned instance of this class.

Parameters:reason - the reason for the exception.

Methods

throwIt(short)

public static void throwIt(short reason)

Throws the JCRE owned instance of APDUException with the specified reason.


APDUException 61


throwIt(short)


Throws:APDUException - always.


javacard.framework Applet

throwIt(short)

javacard.framework

AppletDeclarationpublic abstract class Applet java.lang.Object

|+--javacard.framework.Applet

DescriptionThis abstract class defines an applet in Java Card.

The Applet class must be extended by any applet that is intended to be loaded onto, installed into and executed on a Java Card compliant smart card.

Example usage of Applet

Applet 63

Applet javacard.framework

throwIt(short)

public class MyApplet extends javacard.framework.Applet{static byte someByteArray[];public static void install( byte[] bArray, short bOffset, byte bLength ) throws

ISOException {// make all my allocations here, so I do not run// out of memory laterMyApplet theApplet = new MyApplet();// check incoming parameter databyte iLen = bArray[bOffset]; // aid lengthbOffset = (short) (bOffset+iLen+1);byte cLen = bArray[bOffset]; // info lengthbOffset = (short) (bOffset+cLen+1);byte aLen = bArray[bOffset]; // applet data length// read first applet data bytebyte bLen = bArray[(short)(bOffset+1)];if ( bLen!=0 ) { someByteArray = new byte[bLen]; theApplet.register(); return; }else ISOException.throwIt(ISO7816.SW_FUNC_NOT_SUPPORTED);}

public boolean select(){// selection initializationsomeByteArray[17] = 42; // set selection statereturn true;}

public void process(APDU apdu) throws ISOException{byte[] buffer = apdu.getBuffer();// .. process the incoming data and replyif ( buffer[ISO7816.OFFSET_CLA] == (byte)0 ) {

switch ( buffer[ISO7816.OFFSET_INS] ) {case ISO.INS_SELECT:

...// send response data to select commandshort Le = apdu.setOutgoing();// assume data containing response bytes in replyData[] array.if ( Le < ..) ISOException.throwIt( ISO7816.SW_WRONG_LENGTH);apdu.setOutgoingLength( (short)replyData.length );apdu.sendBytesLong(replyData, (short) 0, (short)replyData.length);break;

case ...}

}}

}

See Also: SystemException, JCSystem

Member Summary

Constructorsprotected Applet()

Only this class’s install() method should create the applet object.

Methods void deselect()

Called by the JCRE to inform that this currently selected applet is being deselected on this logical channel and no applet from the same package is still active on any other logical channel.

Shareable getShareableInterfaceObject(AID clientAID, byte parameter)Called by the JCRE to obtain a shareable interface object from this server applet, on behalf of a request from a client applet.



Applet()

Constructors

Applet()

protected Applet()

Only this class’s install() method should create the applet object.

Methods

install(byte[], short, byte)

public static void install(byte[] bArray, short bOffset, byte bLength)

throws ISOException

To create an instance of the Applet subclass, the JCRE will call this static method first.

The applet should perform any necessary initializations and must call one of the register() methods. Only one Applet instance can be successfully registered from within this install. The installation is considered successful when the call to register() completes without an exception. The installation is deemed unsuccessful if the install method does not call a register() method, or if an exception is thrown from within the install method prior to the call to a register() method, or if every call to the register() method results in an exception. If the installation is unsuccessful, the JCRE must

static void install(byte[] bArray, short bOffset, byte bLength)To create an instance of the Applet subclass, the JCRE will call this static method first.

abstract void process(APDU apdu)Called by the JCRE to process an incoming APDU command.

protected void register()This method is used by the applet to register this applet instance with the JCRE and to assign the Java Card name of the applet as its instance AID bytes.

protected void register(byte[] bArray, short bOffset, byte bLength)This method is used by the applet to register this applet instance with the JCRE and assign the specified AID bytes as its instance AID bytes.

boolean select()Called by the JCRE to inform this applet that it has been selected when no applet from the same package is active on any other logical channel.

protected boolean selectingApplet()This method is used by the applet process() method to distinguish the SELECT APDU command which selected this applet, from all other other SELECT APDU commands which may relate to file or internal applet state selection.



equals(Object)

Member Summary

Applet 65


process(APDU)

perform all the necessary clean up when it receives control. Successful installation makes the applet instance capable of being selected via a SELECT APDU command.

Installation parameters are supplied in the byte array parameter and must be in a format using length-value (LV) pairs as defined below:

bArray[0] = length(Li) of instance AID, bArray[1..Li] = instance AID bytes,bArray[Li+1]= length(Lc) of control info, bArray[Li+2..Li+Lc+1] = control info,bArray[Li+Lc+2] = length(La) of applet data, bArray[Li+Lc+2..Li+Lc+La+1] = applet data

In the above format, any of the lengths: Li, Lc or La may be zero. The control information is implementation dependent.

The bArray object is a global array. If the applet desires to preserve any of this data, it should copy the data into its own object.

bArray is zeroed by the JCRE after the return from the install() method.

References to the bArray object cannot be stored in class variables or instance variables or array components. See Java Card Runtime Environment (JCRE) Specification, section 6.2.2 for details.

The implementation of this method provided by Applet class throws an ISOException with reason code = ISO7816.SW_FUNC_NOT_SUPPORTED.

Note:

• Exceptions thrown by this method after successful installation are caught by the JCRE and processed by the Installer.

Parameters:bArray - the array containing installation parameters.

bOffset - the starting offset in bArray.

bLength - the length in bytes of the parameter data in bArray. The maximum value of bLength is 127.

Throws:ISOException - if the install method failed

process(APDU)

public abstract void process(javacard.framework.APDU apdu)

throws ISOException

Called by the JCRE to process an incoming APDU command. An applet is expected to perform the action requested and return response data if any to the terminal.

Upon normal return from this method the JCRE sends the ISO 7816-4 defined success status (90 00) in APDU response. If this method throws an ISOException the JCRE sends the associated reason code as the response status instead.

The JCRE zeroes out the APDU buffer before receiving a new APDU command from the CAD. The five header bytes of the APDU command are available in APDU buffer[0..4] at the time this method is called.

The APDU object parameter is a temporary JCRE Entry Point Object. A temporary JCRE Entry Point Object can be accessed from any applet context. References to these temporary objects cannot be stored in class variables or instance variables or array components.

Notes:

• APDU buffer[5..] is undefined and should not be read or written prior to invoking the APDU.setIncomingAndReceive() method if incoming data is expected. Altering the APDU buffer[5..]



select()

could corrupt incoming data.

Parameters:apdu - the incoming APDU object

Throws:ISOException - with the response bytes per ISO 7816-4

See Also: APDU

select()

public boolean select()

Called by the JCRE to inform this applet that it has been selected when no applet from the same package is active on any other logical channel.

It is called when a SELECT APDU command or MANAGE CHANNEL OPEN APDU command is received and before the applet is selected. SELECT APDU commands use instance AID bytes for applet selection. See Java Card Runtime Environment (JCRE) Specification, section 4.2 for details.

A subclass of Applet should override this method if it should perform any initialization that may be required to process APDU commands that may follow. This method returns a boolean to indicate that it is ready to accept incoming APDU commands via its process() method. If this method returns false, it indicates to the JCRE that this Applet declines to be selected.

Note:

• The javacard.framework.MultiSelectable.select() method is not called if this method is invoked.

The implementation of this method provided by Applet class returns true.

Returns: true to indicate success, false otherwise.

deselect()

public void deselect()

Called by the JCRE to inform that this currently selected applet is being deselected on this logical channel and no applet from the same package is still active on any other logical channel. After deselection, this logical channel will be closed or another applet (or the same applet) will be selected on this logical channel. It is called when a SELECT APDU command or a MANAGE CHANNEL CLOSE APDU command is received by the JCRE. This method is invoked prior to another applet’s or this very applet’s select() method being invoked.

A subclass of Applet should override this method if it has any cleanup or bookkeeping work to be performed before another applet is selected.

The default implementation of this method provided by Applet class does nothing.

Notes:

• The javacard.framework.MultiSelectable.deselect() method is not called if this method is invoked.

• Unchecked exceptions thrown by this method are caught by the JCRE but the applet is deselected.

• Transient objects of JCSystem.CLEAR_ON_DESELECT clear event type are cleared to their default value by the JCRE after this method.

• This method is NOT called on reset or power loss.

Applet 67


getShareableInterfaceObject(AID, byte)

getShareableInterfaceObject(AID, byte)

public javacard.framework.Shareable getShareableInterfaceObject(javacard.framework.AID

clientAID, byte parameter)

Called by the JCRE to obtain a shareable interface object from this server applet, on behalf of a request from a client applet. This method executes in the applet context of this applet instance. The client applet initiated this request by calling the JCSystem.getAppletShareableInterfaceObject() method. See Java Card Runtime Environment (JCRE) Specification, section 6.2.4 for details.

Note:

• The clientAID parameter is a JCRE owned AID instance. JCRE owned instances of AID are permanent JCRE Entry Point Objects and can be accessed from any applet context. References to these permanent objects can be stored and re-used.

Parameters:clientAID - the AID object of the client applet.

parameter - optional parameter byte. The parameter byte may be used by the client to specify which shareable interface object is being requested.

Returns: the shareable interface object or null.

See Also: JCSystem.getAppletShareableInterfaceObject(AID, byte)

register()

protected final void register()

throws SystemException

This method is used by the applet to register this applet instance with the JCRE and to assign the Java Card name of the applet as its instance AID bytes. One of the register() methods must be called from within install() to be registered with the JCRE. See Java Card Runtime Environment (JCRE) Specification, section 3.1 for details.

Note:

• The phrase “Java card name of the applet” is a reference to the AID[AID_length] item in the applets[] item of the applet_component, as documented in Section 6.5 Applet Component in the Java Card Virtual Machine Specification.

Throws:SystemException - with the following reason codes:

• SystemException.ILLEGAL_AID if the Applet subclass AID bytes are in use or if the applet instance has previously successfully registered with the JCRE via one of the register() methods or if a JCRE initiated install() method execution is not in progress.

register(byte[], short, byte)

protected final void register(byte[] bArray, short bOffset, byte bLength)


This method is used by the applet to register this applet instance with the JCRE and assign the specified AID bytes as its instance AID bytes. One of the register() methods must be called from within install() to be registered with the JCRE. See Java Card Runtime Environment (JCRE) Specification, section 3.1 for details.

Note:



selectingApplet()

• The implementation may require that the instance AID bytes specified are the same as that supplied in the install parameter data. An ILLEGAL_AID exception may be thrown otherwise.

Parameters:bArray - the byte array containing the AID bytes.

bOffset - the start of AID bytes in bArray.

bLength - the length of the AID bytes in bArray.

Throws:SystemException - with the following reason code:

• SystemException.ILLEGAL_VALUE if the bLength parameter is less than 5 or greater than 16.

• SystemException.ILLEGAL_AID if the specified instance AID bytes are in use or if the applet instance has previously successfully registered with the JCRE via one of the register() methods or if a JCRE initiated install() method execution is not in progress.

See Also: install(byte[], short, byte)

selectingApplet()

protected final boolean selectingApplet()

This method is used by the applet process() method to distinguish the SELECT APDU command which selected this applet, from all other other SELECT APDU commands which may relate to file or internal applet state selection.

Returns: true if this applet is being selected.

Applet 69

CardException javacard.framework

selectingApplet()

javacard.framework

CardExceptionDeclarationpublic class CardException extends Exception java.lang.Object



|+--javacard.framework.CardException

Direct Known Subclasses: UserException

DescriptionThe CardException class defines a field reason and two accessor methods getReason() and setReason(). The reason field encapsulates exception cause identifier in Java Card. All Java Card checked Exception classes should extend CardException. This class also provides a resource-saving mechanism (throwIt() method) for using a JCRE owned instance of this class.

Even if a transaction is in progress, the update of the internal reason field shall not participate in the transaction. The value of the internal reason field of JCRE owned instance is reset to 0 on a tear or reset.

Member Summary

ConstructorsCardException(short reason)

Construct a CardException instance with the specified reason.

Methods short getReason()

Get reason code void setReason(short reason)

Set reason codestatic void throwIt(short reason)

Throw the JCRE owned instance of CardException class with the specified reason.



equals(Object)


javacard.framework CardException

CardException(short)

Constructors

CardException(short)

public CardException(short reason)

Construct a CardException instance with the specified reason. To conserve on resources, use the throwIt() method to use the JCRE owned instance of this class.

Parameters:reason - the reason for the exception

Methods

getReason()

public short getReason()

Get reason code

Returns: the reason for the exception

setReason(short)

public void setReason(short reason)

Set reason code


throwIt(short)


throws CardException

Throw the JCRE owned instance of CardException class with the specified reason.



Throws:CardException - always.

CardException 71

CardRuntimeException javacard.framework

throwIt(short)

javacard.framework

CardRuntimeExceptionDeclarationpublic class CardRuntimeException extends RuntimeException java.lang.Object





Direct Known Subclasses: APDUException, CryptoException, ISOException, PINException, ServiceException, SystemException, TransactionException

DescriptionThe CardRuntimeException class defines a field reason and two accessor methods getReason() and setReason(). The reason field encapsulates exception cause identifier in Java Card. All Java Card unchecked Exception classes should extend CardRuntimeException. This class also provides a resource-saving mechanism (throwIt() method) for using a JCRE owned instance of this class.

Even if a transaction is in progress, the update of the internal reason field shall not participate in the transaction. The value of the internal reason field of JCRE owned instance is reset to 0 on a tear or reset.

Member Summary

ConstructorsCardRuntimeException(short reason)

Construct a CardRuntimeException instance with the specified reason.

Methods short getReason()

Get reason code void setReason(short reason)

Set reason code.static void throwIt(short reason)

Throw the JCRE owned instance of the CardRuntimeException class with the specified reason.




javacard.framework CardRuntimeException

CardRuntimeException(short)

Constructors

CardRuntimeException(short)

public CardRuntimeException(short reason)

Construct a CardRuntimeException instance with the specified reason. To conserve on resources, use throwIt() method to use the JCRE owned instance of this class.


Methods

getReason()

public short getReason()

Get reason code

Returns: the reason for the exception

setReason(short)

public void setReason(short reason)

Set reason code. Even if a transaction is in progress, the update of the internal reason field shall not participate in the transaction.


throwIt(short)


throws CardRuntimeException

Throw the JCRE owned instance of the CardRuntimeException class with the specified reason.



Throws:CardRuntimeException - always.

equals(Object)


CardRuntimeException 73

ISO7816 javacard.framework

throwIt(short)

javacard.framework

ISO7816Declarationpublic interface ISO7816

DescriptionISO7816 encapsulates constants related to ISO 7816-3 and ISO 7816-4. ISO7816 interface contains only static fields.

The static fields with SW_ prefixes define constants for the ISO 7816-4 defined response status word. The fields which use the _00 suffix require the low order byte to be customized appropriately e.g (ISO7816.SW_CORRECT_LENGTH_00 + (0x0025 & 0xFF)).

The static fields with OFFSET_ prefixes define constants to be used to index into the APDU buffer byte array to access ISO 7816-4 defined header information.

Member Summary

Fieldsstatic byte CLA_ISO7816

APDU command CLA : ISO 7816 = 0x00static byte INS_EXTERNAL_AUTHENTICATE

APDU command INS : EXTERNAL AUTHENTICATE = 0x82static byte INS_SELECT

APDU command INS : SELECT = 0xA4static byte OFFSET_CDATA

APDU command data offset : CDATA = 5static byte OFFSET_CLA

APDU header offset : CLA = 0static byte OFFSET_INS

APDU header offset : INS = 1static byte OFFSET_LC

APDU header offset : LC = 4static byte OFFSET_P1

APDU header offset : P1 = 2static byte OFFSET_P2

APDU header offset : P2 = 3static short SW_APPLET_SELECT_FAILED

Response status : Applet selection failed = 0x6999;static short SW_BYTES_REMAINING_00

Response status : Response bytes remaining = 0x6100static short SW_CLA_NOT_SUPPORTED

Response status : CLA value not supported = 0x6E00static short SW_COMMAND_NOT_ALLOWED

Response status : Command not allowed (no current EF) = 0x6986static short SW_CONDITIONS_NOT_SATISFIED

Response status : Conditions of use not satisfied = 0x6985static short SW_CORRECT_LENGTH_00

Response status : Correct Expected Length (Le) = 0x6C00


javacard.framework ISO7816

SW_NO_ERROR

Fields

SW_NO_ERROR

public static final short SW_NO_ERROR

Response status : No Error = (short)0x9000

SW_BYTES_REMAINING_00

public static final short SW_BYTES_REMAINING_00

Response status : Response bytes remaining = 0x6100

SW_WRONG_LENGTH

public static final short SW_WRONG_LENGTH

static short SW_DATA_INVALIDResponse status : Data invalid = 0x6984

static short SW_FILE_FULLResponse status : Not enough memory space in the file = 0x6A84

static short SW_FILE_INVALIDResponse status : File invalid = 0x6983

static short SW_FILE_NOT_FOUNDResponse status : File not found = 0x6A82

static short SW_FUNC_NOT_SUPPORTEDResponse status : Function not supported = 0x6A81

static short SW_INCORRECT_P1P2Response status : Incorrect parameters (P1,P2) = 0x6A86

static short SW_INS_NOT_SUPPORTEDResponse status : INS value not supported = 0x6D00

static short SW_LOGICAL_CHANNEL_NOT_SUPPORTEDResponse status : Card does not support logical channels = 0x6881

static short SW_NO_ERRORResponse status : No Error = (short)0x9000

static short SW_RECORD_NOT_FOUNDResponse status : Record not found = 0x6A83

static short SW_SECURE_MESSAGING_NOT_SUPPORTEDResponse status : Card does not support secure messaging = 0x6882

static short SW_SECURITY_STATUS_NOT_SATISFIEDResponse status : Security condition not satisfied = 0x6982

static short SW_UNKNOWNResponse status : No precise diagnosis = 0x6F00

static short SW_WARNING_STATE_UNCHANGEDResponse status : Warning, card state unchanged = 0x6200

static short SW_WRONG_DATAResponse status : Wrong data = 0x6A80

static short SW_WRONG_LENGTHResponse status : Wrong length = 0x6700

static short SW_WRONG_P1P2Response status : Incorrect parameters (P1,P2) = 0x6B00

Member Summary

ISO7816 75


SW_SECURITY_STATUS_NOT_SATISFIED

Response status : Wrong length = 0x6700

SW_SECURITY_STATUS_NOT_SATISFIED

public static final short SW_SECURITY_STATUS_NOT_SATISFIED

Response status : Security condition not satisfied = 0x6982

SW_FILE_INVALID

public static final short SW_FILE_INVALID

Response status : File invalid = 0x6983

SW_DATA_INVALID

public static final short SW_DATA_INVALID

Response status : Data invalid = 0x6984

SW_CONDITIONS_NOT_SATISFIED

public static final short SW_CONDITIONS_NOT_SATISFIED

Response status : Conditions of use not satisfied = 0x6985

SW_COMMAND_NOT_ALLOWED

public static final short SW_COMMAND_NOT_ALLOWED

Response status : Command not allowed (no current EF) = 0x6986

SW_APPLET_SELECT_FAILED

public static final short SW_APPLET_SELECT_FAILED

Response status : Applet selection failed = 0x6999;

SW_WRONG_DATA

public static final short SW_WRONG_DATA

Response status : Wrong data = 0x6A80

SW_FUNC_NOT_SUPPORTED

public static final short SW_FUNC_NOT_SUPPORTED

Response status : Function not supported = 0x6A81

SW_FILE_NOT_FOUND

public static final short SW_FILE_NOT_FOUND

Response status : File not found = 0x6A82

SW_RECORD_NOT_FOUND

public static final short SW_RECORD_NOT_FOUND

Response status : Record not found = 0x6A83


javacard.framework ISO7816

SW_INCORRECT_P1P2

SW_INCORRECT_P1P2

public static final short SW_INCORRECT_P1P2

Response status : Incorrect parameters (P1,P2) = 0x6A86

SW_WRONG_P1P2

public static final short SW_WRONG_P1P2

Response status : Incorrect parameters (P1,P2) = 0x6B00

SW_CORRECT_LENGTH_00

public static final short SW_CORRECT_LENGTH_00

Response status : Correct Expected Length (Le) = 0x6C00

SW_INS_NOT_SUPPORTED

public static final short SW_INS_NOT_SUPPORTED

Response status : INS value not supported = 0x6D00

SW_CLA_NOT_SUPPORTED

public static final short SW_CLA_NOT_SUPPORTED

Response status : CLA value not supported = 0x6E00

SW_UNKNOWN

public static final short SW_UNKNOWN

Response status : No precise diagnosis = 0x6F00

SW_FILE_FULL

public static final short SW_FILE_FULL

Response status : Not enough memory space in the file = 0x6A84

SW_LOGICAL_CHANNEL_NOT_SUPPORTED

public static final short SW_LOGICAL_CHANNEL_NOT_SUPPORTED

Response status : Card does not support logical channels = 0x6881

SW_SECURE_MESSAGING_NOT_SUPPORTED

public static final short SW_SECURE_MESSAGING_NOT_SUPPORTED

Response status : Card does not support secure messaging = 0x6882

SW_WARNING_STATE_UNCHANGED

public static final short SW_WARNING_STATE_UNCHANGED

Response status : Warning, card state unchanged = 0x6200

ISO7816 77


OFFSET_CLA

OFFSET_CLA

public static final byte OFFSET_CLA

APDU header offset : CLA = 0

OFFSET_INS

public static final byte OFFSET_INS

APDU header offset : INS = 1

OFFSET_P1

public static final byte OFFSET_P1

APDU header offset : P1 = 2

OFFSET_P2

public static final byte OFFSET_P2

APDU header offset : P2 = 3

OFFSET_LC

public static final byte OFFSET_LC

APDU header offset : LC = 4

OFFSET_CDATA

public static final byte OFFSET_CDATA

APDU command data offset : CDATA = 5

CLA_ISO7816

public static final byte CLA_ISO7816

APDU command CLA : ISO 7816 = 0x00

INS_SELECT

public static final byte INS_SELECT

APDU command INS : SELECT = 0xA4

INS_EXTERNAL_AUTHENTICATE

public static final byte INS_EXTERNAL_AUTHENTICATE

APDU command INS : EXTERNAL AUTHENTICATE = 0x82


javacard.framework ISOException

INS_EXTERNAL_AUTHENTICATE

javacard.framework

ISOExceptionDeclarationpublic class ISOException extends CardRuntimeException java.lang.Object





|+--javacard.framework.ISOException

DescriptionISOException class encapsulates an ISO 7816-4 response status word as its reason code.

The APDU class throws JCRE owned instances of ISOException.


Member Summary

ConstructorsISOException(short sw)

Constructs an ISOException instance with the specified status word.

Methodsstatic void throwIt(short sw)

Throws the JCRE owned instance of the ISOException class with the specified status word.





equals(Object)

ISOException 79

ISOException javacard.framework

ISOException(short)

Constructors

ISOException(short)

public ISOException(short sw)

Constructs an ISOException instance with the specified status word. To conserve on resources use throwIt() to use the JCRE owned instance of this class.

Parameters:sw - the ISO 7816-4 defined status word

Methods

throwIt(short)

public static void throwIt(short sw)

Throws the JCRE owned instance of the ISOException class with the specified status word.


Parameters:sw - ISO 7816-4 defined status word

Throws:ISOException - always.


javacard.framework JCSystem

throwIt(short)

javacard.framework

JCSystemDeclarationpublic final class JCSystem java.lang.Object

|+--javacard.framework.JCSystem

DescriptionThe JCSystem class includes a collection of methods to control applet execution, resource management, atomic transaction management, object deletion mechanism and inter-applet object sharing in Java Card. All methods in JCSystem class are static methods.

The JCSystem class also includes methods to control the persistence and transience of objects. The term persistent means that objects and their values persist from one CAD session to the next, indefinitely. Persistent object values are updated atomically using transactions.

The makeTransient...Array() methods can be used to create transient arrays. Transient array data is lost (in an undefined state, but the real data is unavailable) immediately upon power loss, and is reset to the default value at the occurrence of certain events such as card reset or deselect. Updates to the values of transient arrays are not atomic and are not affected by transactions.

The JCRE maintains an atomic transaction commit buffer which is initialized on card reset (or power on). When a transaction is in progress, the JCRE journals all updates to persistent data space into this buffer so that it can always guarantee, at commit time, that everything in the buffer is written or nothing at all is written. The JCSystem includes methods to control an atomic transaction. See Java Card Runtime Environment (JCRE) Specification for details.

See Also: SystemException, TransactionException, Applet

Member Summary

Fieldsstatic byte CLEAR_ON_DESELECT

This event code indicates that the contents of the transient object are cleared to the default value on applet deselection event or in CLEAR_ON_RESET cases.

static byte CLEAR_ON_RESETThis event code indicates that the contents of the transient object are cleared to the default value on card reset ( or power on ) event.

static byte MEMORY_TYPE_PERSISTENTConstant to indicate persistent memory type

static byte MEMORY_TYPE_TRANSIENT_DESELECTConstant to indicate transient memory of CLEAR_ON_DESELECT type

static byte MEMORY_TYPE_TRANSIENT_RESETConstant to indicate transient memory of CLEAR_ON_RESET type

static byte NOT_A_TRANSIENT_OBJECTThis event code indicates that the object is not transient.

JCSystem 81

JCSystem javacard.framework

throwIt(short)

Methodsstatic void abortTransaction()

Aborts the atomic transaction.static void beginTransaction()

Begins an atomic transaction.static void commitTransaction()

Commits an atomic transaction.static AID getAID()

Returns the JCRE owned instance of the AID object associated with the current applet context.

static Shareable getAppletShareableInterfaceObject(AID serverAID, byte parameter)

This method is called by a client applet to get a server applet’s shareable interface object.

static byte getAssignedChannel()This method is called to obtain the logical channel number assigned to the currently selected applet instance.

static short getAvailableMemory(byte memoryType)This method is called to obtain the amount of memory of the specified type that is available to the applet.

static short getMaxCommitCapacity()Returns the total number of bytes in the commit buffer.

static AID getPreviousContextAID()This method is called to obtain the JCRE owned instance of the AID object associated with the previously active applet context.

static byte getTransactionDepth()Returns the current transaction nesting depth level.

static short getUnusedCommitCapacity()Returns the number of bytes left in the commit buffer.

static short getVersion()Returns the current major and minor version of the Java Card API.

static boolean isObjectDeletionSupported()This method is used to determine if the Java Card implementation supports the object deletion mechanism.

static byte isTransient(java.lang.Object theObj)Used to check if the specified object is transient.

static AID lookupAID(byte[] buffer, short offset, byte length)Returns the JCRE owned instance of the AID object, if any, encapsulating the specified AID bytes in the buffer parameter if there exists a successfully installed applet on the card whose instance AID exactly matches that of the specified AID bytes.

static boolean[] makeTransientBooleanArray(short length, byte event)Create a transient boolean array with the specified array length.

static byte[] makeTransientByteArray(short length, byte event)Create a transient byte array with the specified array length.

static java.lang.Object[]

makeTransientObjectArray(short length, byte event)Create a transient array of Object with the specified array length.

static short[] makeTransientShortArray(short length, byte event)Create a transient short array with the specified array length.

static void requestObjectDeletion()This method is invoked by the applet to trigger the object deletion service of the JCRE.

Member Summary



MEMORY_TYPE_PERSISTENT

Fields

MEMORY_TYPE_PERSISTENT

public static final byte MEMORY_TYPE_PERSISTENT

Constant to indicate persistent memory type

MEMORY_TYPE_TRANSIENT_RESET

public static final byte MEMORY_TYPE_TRANSIENT_RESET

Constant to indicate transient memory of CLEAR_ON_RESET type

MEMORY_TYPE_TRANSIENT_DESELECT

public static final byte MEMORY_TYPE_TRANSIENT_DESELECT

Constant to indicate transient memory of CLEAR_ON_DESELECT type

NOT_A_TRANSIENT_OBJECT

public static final byte NOT_A_TRANSIENT_OBJECT

This event code indicates that the object is not transient.

CLEAR_ON_RESET

public static final byte CLEAR_ON_RESET

This event code indicates that the contents of the transient object are cleared to the default value on card reset ( or power on ) event.

CLEAR_ON_DESELECT

public static final byte CLEAR_ON_DESELECT

This event code indicates that the contents of the transient object are cleared to the default value on applet deselection event or in CLEAR_ON_RESET cases.

Notes:

• CLEAR_ON_DESELECT transient objects can be accessed only when the applet which created the object is in the same context as the currently selected applet.

• The JCRE will throw a SecurityException if a CLEAR_ON_DESELECT transient object is accessed when the currently selected applet is not in the same context as the applet which created the object.



equals(Object)

JCSystem 83


isTransient(Object)

Methods

isTransient(Object)

public static byte isTransient(java.lang.Object theObj)

Used to check if the specified object is transient.

Notes: This method returns NOT_A_TRANSIENT_OBJECT if the specified object is null or is not an array type.

Parameters:theObj - the object being queried.

Returns: NOT_A_TRANSIENT_OBJECT, CLEAR_ON_RESET, or CLEAR_ON_DESELECT.

See Also: makeTransientBooleanArray(short, byte), makeTransientByteArray(short, byte), makeTransientShortArray(short, byte), makeTransientObjectArray(short, byte)

makeTransientBooleanArray(short, byte)

public static boolean[] makeTransientBooleanArray(short length, byte event)

throws NegativeArraySizeException, SystemException

Create a transient boolean array with the specified array length.

Parameters:length - the length of the boolean array.

event - the CLEAR_ON... event which causes the array elements to be cleared.

Returns: the new transient boolean array

Throws:NegativeArraySizeException - if the length parameter is negative

SystemException - with the following reason codes:

• SystemException.ILLEGAL_VALUE if event is not a valid event code.

• SystemException.NO_TRANSIENT_SPACE if sufficient transient space is not available.

• SystemException.ILLEGAL_TRANSIENT if the current applet context is not the currently selected applet context and CLEAR_ON_DESELECT is specified.

makeTransientByteArray(short, byte)

public static byte[] makeTransientByteArray(short length, byte event)


Create a transient byte array with the specified array length.

Parameters:length - the length of the byte array.


Returns: the new transient byte array




makeTransientShortArray(short, byte)





makeTransientShortArray(short, byte)

public static short[] makeTransientShortArray(short length, byte event)


Create a transient short array with the specified array length.

Parameters:length - the length of the short array.


Returns: the new transient short array






makeTransientObjectArray(short, byte)

public static java.lang.Object[] makeTransientObjectArray(short length, byte event)


Create a transient array of Object with the specified array length.

Parameters:length - the length of the Object array.


Returns: the new transient Object array






getVersion()

public static short getVersion()

JCSystem 85


getAID()

Returns the current major and minor version of the Java Card API.

Returns: version number as byte.byte (major.minor)

getAID()

public static javacard.framework.AID getAID()

Returns the JCRE owned instance of the AID object associated with the current applet context. Returns null if the Applet.register() method has not yet been invoked.


See Java Card Runtime Environment (JCRE) Specification, section 6.2.1 for details.

Returns: the AID object.

lookupAID(byte[], short, byte)

public static javacard.framework.AID lookupAID(byte[] buffer, short offset, byte length)

Returns the JCRE owned instance of the AID object, if any, encapsulating the specified AID bytes in the buffer parameter if there exists a successfully installed applet on the card whose instance AID exactly matches that of the specified AID bytes.



Parameters:buffer - byte array containing the AID bytes.

offset - offset within buffer where AID bytes begin.

length - length of AID bytes in buffer.

Returns: the AID object, if any; null otherwise. A VM exception is thrown if buffer is null, or if offset or length are out of range.

beginTransaction()

public static void beginTransaction()

throws TransactionException

Begins an atomic transaction. If a transaction is already in progress (transaction nesting depth level != 0), a TransactionException is thrown.

Note:

• This method may do nothing if the Applet.register() method has not yet been invoked. In case of tear or failure prior to successful registration, the JCRE will roll back all atomically updated persistent state.

Throws:TransactionException - with the following reason codes:

• TransactionException.IN_PROGRESS if a transaction is already in progress.

See Also: commitTransaction(), abortTransaction()



abortTransaction()

abortTransaction()

public static void abortTransaction()


Aborts the atomic transaction. The contents of the commit buffer is discarded.

Notes:


• Do not call this method from within a transaction which creates new objects because the JCRE may not recover the heap space used by the new object instances.

• Do not call this method from within a transaction which creates new objects because the JCRE may, to ensure the security of the card and to avoid heap space loss, lock up the card session to force tear/reset processing.

• The JCRE ensures that any variable of reference type which references an object instantiated from within this aborted transaction is equivalent to a null reference.


• TransactionException.NOT_IN_PROGRESS if a transaction is not in progress.

See Also: beginTransaction(), commitTransaction()

commitTransaction()

public static void commitTransaction()


Commits an atomic transaction. The contents of commit buffer is atomically committed. If a transaction is not in progress (transaction nesting depth level == 0) then a TransactionException is thrown.

Note:



• TransactionException.NOT_IN_PROGRESS if a transaction is not in progress.

See Also: beginTransaction(), abortTransaction()

getTransactionDepth()

public static byte getTransactionDepth()

Returns the current transaction nesting depth level. At present, only 1 transaction can be in progress at a time.

Returns: 1 if transaction in progress, 0 if not.

getUnusedCommitCapacity()

public static short getUnusedCommitCapacity()

Returns the number of bytes left in the commit buffer.

JCSystem 87


getMaxCommitCapacity()

Note :

• If the number of bytes left in the commit buffer is greater than 32767, then this method returns 32767.

Returns: the number of bytes left in the commit buffer

See Also: getMaxCommitCapacity()

getMaxCommitCapacity()

public static short getMaxCommitCapacity()

Returns the total number of bytes in the commit buffer. This is approximately the maximum number of bytes of persistent data which can be modified during a transaction. However, the transaction subsystem requires additional bytes of overhead data to be included in the commit buffer, and this depends on the number of fields modified and the implementation of the transaction subsystem. The application cannot determine the actual maximum amount of data which can be modified during a transaction without taking these overhead bytes into consideration.

Note :

• If the total number of bytes in the commit buffer is greater than 32767, then this method returns 32767.

Returns: the total number of bytes in the commit buffer

See Also: getUnusedCommitCapacity()

getPreviousContextAID()

public static javacard.framework.AID getPreviousContextAID()

This method is called to obtain the JCRE owned instance of the AID object associated with the previously active applet context. This method is typically used by a server applet, while executing a shareable interface method to determine the identity of its client and thereby control access privileges.



Returns: the AID object of the previous context, or null if JCRE.

getAvailableMemory(byte)

public static short getAvailableMemory(byte memoryType)


This method is called to obtain the amount of memory of the specified type that is available to the applet. Note that implementation dependent memory overhead structures may also use the same memory pool.

Notes:

• The number of bytes returned is only an upper bound on the amount of memory available due to overhead requirements.

• Allocation of CLEAR_ON_RESET transient objects may affect the amount of CLEAR_ON_DESELECT transient memory available.

• Allocation of CLEAR_ON_DESELECT transient objects may affect the amount of CLEAR_ON_RESET transient memory available.

• If the number of available bytes is greater than 32767, then this method returns 32767.



getAppletShareableInterfaceObject(AID, byte)

• The returned count is not an indicator of the size of object which may be created since memory fragmentation is possible.

Parameters:memoryType - the type of memory being queried. One of the MEMORY_TYPE_.. constants defined above. See MEMORY_TYPE_PERSISTENT

Returns: the upper bound on available bytes of memory for the specified type


• SystemException.ILLEGAL_VALUE if memoryType is not a valid memory type.

getAppletShareableInterfaceObject(AID, byte)

public static javacard.framework.Shareable getAppletShareableInterfaceObject(javacard.

framework.AID serverAID, byte parameter)

This method is called by a client applet to get a server applet’s shareable interface object.

This method returns null if the Applet.register() has not yet been invoked or if the server does not exist or if the server returns null.

Parameters:serverAID - the AID of the server applet.

parameter - optional parameter data.

Returns: the shareable interface object or null.

See Also: Applet.getShareableInterfaceObject(AID, byte)

isObjectDeletionSupported()

public static boolean isObjectDeletionSupported()

This method is used to determine if the Java Card implementation supports the object deletion mechanism.

Returns: true if the object deletion mechanism is supported, false otherwise.

requestObjectDeletion()

public static void requestObjectDeletion()


This method is invoked by the applet to trigger the object deletion service of the JCRE. If the JCRE implements the object deletion mechanism, the request is merely logged at this time. The JCRE must schedule the object deletion service prior to the next invocation of the Applet.process() method. The object deletion mechanism must ensure that :

• Any unreferenced persistent object owned by the current applet context is deleted and the associated space is recovered for reuse prior to the next invocation of the Applet.process() method.

• Any unreferenced CLEAR_ON_DESELECT or CLEAR_ON_RESET transient object owned by the current applet context is deleted and the associated space is recovered for reuse before the next card reset session.


• SystemException.ILLEGAL_USE if the object deletion mechanism is not implemented.

JCSystem 89


getAssignedChannel()

getAssignedChannel()

public static byte getAssignedChannel()

This method is called to obtain the logical channel number assigned to the currently selected applet instance. The assigned logical channel is the logical channel on which the currently selected applet instance is or will be the active applet instance. This logical channel number is always equal to the origin logical channel number returned by the APDU.getCLAChannel() method except during selection and deselection via the MANAGE CHANNEL APDU command. If this method is called from the Applet.select(), Applet.deselect(), MultiSelectable.select(boolean) and MultiSelectable.deselect(boolean) methods during MANAGE CHANNEL APDU command processing, the logical channel number returned may be different.

Returns: the logical channel number in the range 0-3 assigned to the currently selected applet instance.


javacard.framework MultiSelectable

select(boolean)

javacard.framework

MultiSelectableDeclarationpublic interface MultiSelectable

DescriptionThe MultiSelectable interface serves to identify the implementing Applet subclass as being capable of concurrent selections. A multiselectable applet is a subclass of javacard.framework.Applet which directly or indirectly implements this interface. All applets within a applet package must be multiselectable or none at all. An instance of a multiselectable applet can be selected on one logical channel while the same applet instance or another applet instance from within the same package is active on another logical channel.

The methods of this interface are invoked by the JCRE only when :

• the same applet instance is still active on another logical channel OR

• another applet instance from the same package is still active on another logical channel.

See Java Card Runtime Environment (JCRE) Specification for details.

Methods

select(boolean)

public boolean select(boolean appInstAlreadyActive)

Called by the JCRE to inform that this applet instance has been selected while the same applet instance or another applet instance from the same package is active on another logical channel

It is called either when the MANAGE CHANNEL APDU (open) command or the SELECT APDU command is received and before the applet instance is selected. SELECT APDU commands use instance AID bytes for applet selection. See Java Card Runtime Environment (JCRE) Specification, section 4.2 for details.

A subclass of Applet should, within this method, perform any initialization that may be required to process APDU commands that may follow. This method returns a boolean to indicate that it is ready to

Member Summary

Methods void deselect(boolean appInstStillActive)

Called by the JCRE to inform that this currently selected applet instance is being deselected on this logical channel while the same applet instance or another applet instance from the same package is still active on another logical channel.

boolean select(boolean appInstAlreadyActive)Called by the JCRE to inform that this applet instance has been selected while the same applet instance or another applet instance from the same package is active on another logical channel

MultiSelectable 91

MultiSelectable javacard.framework

deselect(boolean)

accept incoming APDU commands via its process() method. If this method returns false, it indicates to the JCRE that this applet instance declines to be selected.

Note:

• The javacard.framework.Applet.select() method is not called if this method is invoked.

Parameters:appInstAlreadyActive - boolean flag is true when the same applet instance is already active on another logical channel and false otherwise

Returns: true if the applet instance accepts selection, false otherwise

deselect(boolean)

public void deselect(boolean appInstStillActive)

Called by the JCRE to inform that this currently selected applet instance is being deselected on this logical channel while the same applet instance or another applet instance from the same package is still active on another logical channel. After deselection, this logical channel will be closed or another applet instance (or the same applet instance) will be selected on this logical channel. It is called when a SELECT APDU command or a MANAGE CHANNEL (close) command is received by the JCRE. This method is invoked prior to another applet instance’s or this very applet instance’s select() method being invoked.

A subclass of Applet should, within this method, perform any cleanup or bookkeeping work before another applet instance is selected or the logical channel is closed.

Notes:

• The javacard.framework.Applet.deselect() method is not called if this method is invoked.

• Unchecked exceptions thrown by this method are caught and ignored by the JCRE but the applet instance is deselected.

• The JCRE does NOT clear any transient objects of JCSystem.CLEAR_ON_DESELECT clear event type owned by this applet instance since at least one applet instance from the same package is still active.

• This method is NOT called on reset or power loss.

Parameters:appInstStillActive - boolean flag is true when the same applet instance is still active on another logical channel and false otherwise


javacard.framework OwnerPIN

deselect(boolean)

javacard.framework

OwnerPINDeclarationpublic class OwnerPIN implements PIN java.lang.Object

|+--javacard.framework.OwnerPIN

All Implemented Interfaces: PIN

DescriptionThis class represents an Owner PIN. It implements Personal Identification Number functionality as defined in the PIN interface. It provides the ability to update the PIN and thus owner functionality.

The implementation of this class must protect against attacks based on program flow prediction. In addition, even if a transaction is in progress, update of internal state such as the try counter, the validated flag and the blocking state shall not participate in the transaction during PIN presentation.

If an implementation of this class creates transient arrays, it must ensure that they are CLEAR_ON_RESET transient objects.

The protected methods getValidatedFlag and setValidatedFlag allow a subclass of this class to optimize the storage for the validated boolean state.

Some methods of instances of this class are only suitable for sharing when there exists a trust relationship among the applets. A typical shared usage would use a proxy PIN interface which extends both the PIN interface and the Shareable interface and re-declares the methods of the PIN interface..

Any of the methods of the OwnerPIN may be called with a transaction in progress. None of the methods of OwnerPIN class initiate or alter the state of the transaction if one is in progress.

See Also: PINException, PIN, Shareable, JCSystem

Member Summary

ConstructorsOwnerPIN(byte tryLimit, byte maxPINSize)

Constructor.

Methods boolean check(byte[] pin, short offset, byte length)

Compares pin against the PIN value. byte getTriesRemaining()

Returns the number of times remaining that an incorrect PIN can be presented before the PIN is blocked.

protected boolean getValidatedFlag()This protected method returns the validated flag.

OwnerPIN 93

OwnerPIN javacard.framework

OwnerPIN(byte, byte)

Constructors

OwnerPIN(byte, byte)

public OwnerPIN(byte tryLimit, byte maxPINSize)

throws PINException

Constructor. Allocates a new PIN instance with validated flag set to false.

Parameters:tryLimit - the maximum number of times an incorrect PIN can be presented. tryLimit must be >=1.

maxPINSize - the maximum allowed PIN size. maxPINSize must be >=1.

Throws:PINException - with the following reason codes:

• PINException.ILLEGAL_VALUE if tryLimit parameter is less than 1.

• PINException.ILLEGAL_VALUE if maxPINSize parameter is less than 1.

Methods

getValidatedFlag()

protected boolean getValidatedFlag()

boolean isValidated()Returns true if a valid PIN has been presented since the last card reset or last call to reset().

void reset()If the validated flag is set, this method resets the validated flag and resets the PIN try counter to the value of the PIN try limit.

void resetAndUnblock()This method resets the validated flag and resets the PIN try counter to the value of the PIN try limit.

protected void setValidatedFlag(boolean value)This protected method sets the value of the validated flag.

void update(byte[] pin, short offset, byte length)This method sets a new value for the PIN and resets the PIN try counter to the value of the PIN try limit.



equals(Object)

Member Summary


javacard.framework OwnerPIN

setValidatedFlag(boolean)

This protected method returns the validated flag. This method is intended for subclass of this OwnerPIN to access or override the internal PIN state of the OwnerPIN.

Returns: the boolean state of the PIN validated flag.

setValidatedFlag(boolean)

protected void setValidatedFlag(boolean value)

This protected method sets the value of the validated flag. This method is intended for subclass of this OwnerPIN to control or override the internal PIN state of the OwnerPIN.

Parameters:value - the new value for the validated flag.

getTriesRemaining()

public byte getTriesRemaining()


Specified By: getTriesRemaining in interface PIN

Returns: the number of times remaining

check(byte[], short, byte)

public boolean check(byte[] pin, short offset, byte length)

throws ArrayIndexOutOfBoundsException, NullPointerException

Compares pin against the PIN value. If they match and the PIN is not blocked, it sets the validated flag and resets the try counter to its maximum. If it does not match, it decrements the try counter and, if the counter has reached zero, blocks the PIN. Even if a transaction is in progress, update of internal state - the try counter, the validated flag and the blocking state shall not participate in the transaction.

Notes:

• If NullPointerException or ArrayIndexOutOfBoundsException is thrown, the validated flag must be set to false, the try counter must be decremented and, the PIN blocked if the counter reaches zero.

• If offset or length parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.

• If offset+length is greater than pin.length, the length of the pin array, an ArrayIndexOutOfBoundsException exception is thrown.

• If pin parameter is null a NullPointerException exception is thrown.

Specified By: check in interface PIN

Parameters:pin - the byte array containing the PIN value being checked

offset - the starting offset in the pin array

length - the length of pin.

Returns: true if the PIN value matches; false otherwise

OwnerPIN 95


isValidated()

Throws:ArrayIndexOutOfBoundsException - if the check operation would cause access of data outside array bounds.

NullPointerException - if pin is null

isValidated()

public boolean isValidated()

Returns true if a valid PIN has been presented since the last card reset or last call to reset().

Specified By: isValidated in interface PIN

Returns: true if validated; false otherwise

reset()

public void reset()

If the validated flag is set, this method resets the validated flag and resets the PIN try counter to the value of the PIN try limit. If the validated flag is not set, this method does nothing.

Specified By: reset in interface PIN

update(byte[], short, byte)

public void update(byte[] pin, short offset, byte length)

throws PINException

This method sets a new value for the PIN and resets the PIN try counter to the value of the PIN try limit. It also resets the validated flag.

This method copies the input pin parameter into an internal representation. If a transaction is in progress, the new pin and try counter update must be conditional i.e the copy operation must use the transaction facility.

Parameters:pin - the byte array containing the new PIN value


length - the length of the new PIN.

Throws:PINException - with the following reason codes:

• PINException.ILLEGAL_VALUE if length is greater than configured maximum PIN size.

See Also: JCSystem.beginTransaction()

resetAndUnblock()

public void resetAndUnblock()

This method resets the validated flag and resets the PIN try counter to the value of the PIN try limit. This method is used by the owner to re-enable the blocked PIN.


javacard.framework PIN

resetAndUnblock()

javacard.framework

PINDeclarationpublic interface PIN

All Known Implementing Classes: OwnerPIN

DescriptionThis interface represents a PIN. An implementation must maintain these internal values:

• PIN value

• try limit, the maximum number of times an incorrect PIN can be presented before the PIN is blocked. When the PIN is blocked, it cannot be validated even on valid PIN presentation.

• max PIN size, the maximum length of PIN allowed

• try counter, the remaining number of times an incorrect PIN presentation is permitted before the PIN becomes blocked.

• validated flag, true if a valid PIN has been presented. This flag is reset on every card reset.

This interface does not make any assumptions about where the data for the PIN value comparison is stored.

An owner implementation of this interface must provide a way to initialize/update the PIN value.The owner implementation of the interface must protect against attacks based on program flow prediction. In addition, even if a transaction is in progress, update of internal state such as the try counter, the validated flag and the blocking state shall not participate in the transaction during PIN presentation.

A typical card global PIN usage will combine an instance of OwnerPIN class and a a Proxy PIN interface which extends both the PIN and the Shareable interfaces and re-declares the methods of the PIN interface. The OwnerPIN instance would be manipulated only by the owner who has update privilege. All others would access the global PIN functionality via the proxy PIN interface.

See Also: OwnerPIN, Shareable

Member Summary

Methods boolean check(byte[] pin, short offset, byte length)

Compares pin against the PIN value. byte getTriesRemaining()


boolean isValidated()Returns true if a valid PIN value has been presented since the last card reset or last call to reset().

void reset()If the validated flag is set, this method resets the validated flag and resets the PIN try counter to the value of the PIN try limit.

PIN 97

PIN javacard.framework

getTriesRemaining()

Methods

getTriesRemaining()

public byte getTriesRemaining()


Returns: the number of times remaining

check(byte[], short, byte)

public boolean check(byte[] pin, short offset, byte length)


Compares pin against the PIN value. If they match and the PIN is not blocked, it sets the validated flag and resets the try counter to its maximum. If it does not match, it decrements the try counter and, if the counter has reached zero, blocks the PIN. Even if a transaction is in progress, update of internal state - the try counter, the validated flag and the blocking state shall not participate in the transaction.

Notes:

• If NullPointerException or ArrayIndexOutOfBoundsException is thrown, the validated flag must be set to false, the try counter must be decremented and, the PIN blocked if the counter reaches zero.

• If offset or length parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.

• If offset+length is greater than pin.length, the length of the pin array, an ArrayIndexOutOfBoundsException exception is thrown.

• If pin parameter is null a NullPointerException exception is thrown.

Parameters:pin - the byte array containing the PIN value being checked


length - the length of pin.

Returns: true if the PIN value matches; false otherwise

Throws:ArrayIndexOutOfBoundsException - - if the check operation would cause access of data outside array bounds.

NullPointerException - - if pin is null

isValidated()

public boolean isValidated()

Returns true if a valid PIN value has been presented since the last card reset or last call to reset().

Returns: true if validated; false otherwise

reset()

public void reset()


javacard.framework PIN

reset()

If the validated flag is set, this method resets the validated flag and resets the PIN try counter to the value of the PIN try limit. If the validated flag is not set, this method does nothing.

PIN 99

PINException javacard.framework

reset()

javacard.framework

PINExceptionDeclarationpublic class PINException extends CardRuntimeException java.lang.Object





|+--javacard.framework.PINException

DescriptionPINException represents a OwnerPIN class access-related exception.

The OwnerPIN class throws JCRE owned instances of PINException.


See Also: OwnerPIN

Member Summary

Fieldsstatic short ILLEGAL_VALUE

This reason code is used to indicate that one or more input parameters is out of allowed bounds.

ConstructorsPINException(short reason)

Constructs a PINException.


Throws the JCRE owned instance of PINException with the specified reason.




javacard.framework PINException

ILLEGAL_VALUE

Fields

ILLEGAL_VALUE

public static final short ILLEGAL_VALUE


Constructors

PINException(short)

public PINException(short reason)

Constructs a PINException. To conserve on resources use throwIt() to use the JCRE owned instance of this class.


Methods

throwIt(short)


Throws the JCRE owned instance of PINException with the specified reason.



Throws:PINException - always.



equals(Object)


PINException 101

Shareable javacard.framework

throwIt(short)

javacard.framework

ShareableDeclarationpublic interface Shareable

DescriptionThe Shareable interface serves to identify all shared objects. Any object that needs to be shared through the applet firewall must directly or indirectly implement this interface. Only those methods specified in a shareable interface are available through the firewall. Implementation classes can implement any number of shareable interfaces and can extend other shareable implementation classes.


javacard.framework SystemException

throwIt(short)

javacard.framework

SystemExceptionDeclarationpublic class SystemException extends CardRuntimeException java.lang.Object





|+--javacard.framework.SystemException

DescriptionSystemException represents a JCSystem class related exception. It is also thrown by the javacard.framework.Applet.register() methods and by the AID class constructor.

These API classes throw JCRE owned instances of SystemException.


See Also: JCSystem, Applet, AID

Member Summary

Fieldsstatic short ILLEGAL_AID

This reason code is used by the javacard.framework.Applet.register() method to indicate that the input AID parameter is not a legal AID value.

static short ILLEGAL_TRANSIENTThis reason code is used to indicate that the request to create a transient object is not allowed in the current applet context.

static short ILLEGAL_USEThis reason code is used to indicate that the requested function is not allowed.

static short ILLEGAL_VALUEThis reason code is used to indicate that one or more input parameters is out of allowed bounds.

static short NO_RESOURCEThis reason code is used to indicate that there is insufficient resource in the Card for the request.

static short NO_TRANSIENT_SPACEThis reason code is used by the makeTransient..() methods to indicate that no room is available in volatile memory for the requested object.

SystemException 103

SystemException javacard.framework

ILLEGAL_VALUE

Fields

ILLEGAL_VALUE



NO_TRANSIENT_SPACE

public static final short NO_TRANSIENT_SPACE

This reason code is used by the makeTransient..() methods to indicate that no room is available in volatile memory for the requested object.

ILLEGAL_TRANSIENT

public static final short ILLEGAL_TRANSIENT

This reason code is used to indicate that the request to create a transient object is not allowed in the current applet context. See Java Card Runtime Environment (JCRE) Specification, section 6.2.1 for details.

ILLEGAL_AID

public static final short ILLEGAL_AID

This reason code is used by the javacard.framework.Applet.register() method to indicate that the input AID parameter is not a legal AID value.

NO_RESOURCE

public static final short NO_RESOURCE

ConstructorsSystemException(short reason)

Constructs a SystemException.


Throws the JCRE owned instance of SystemException with the specified reason.





equals(Object)

Member Summary


javacard.framework SystemException

ILLEGAL_USE

This reason code is used to indicate that there is insufficient resource in the Card for the request.

For example, the Java Card Virtual Machine may throw this exception reason when there is insufficient heap space to create a new instance.

ILLEGAL_USE


This reason code is used to indicate that the requested function is not allowed. For example, JCSystem.requestObjectDeletion() method throws this exception if the object deletion mechanism is not implemented.

Constructors

SystemException(short)

public SystemException(short reason)

Constructs a SystemException. To conserve on resources use throwIt() to use the JCRE owned instance of this class.


Methods

throwIt(short)



Throws the JCRE owned instance of SystemException with the specified reason.



Throws:SystemException - always.

SystemException 105

TransactionException javacard.framework

throwIt(short)

javacard.framework

TransactionExceptionDeclarationpublic class TransactionException extends CardRuntimeException java.lang.Object





|+--javacard.framework.TransactionException

DescriptionTransactionException represents an exception in the transaction subsystem. The methods referred to in this class are in the JCSystem class.

The JCSystem class and the transaction facility throw JCRE owned instances of TransactionException.


See Also: JCSystem

Member Summary

Fieldsstatic short BUFFER_FULL

This reason code is used during a transaction to indicate that the commit buffer is full.static short IN_PROGRESS

This reason code is used by the beginTransaction method to indicate a transaction is already in progress.

static short INTERNAL_FAILUREThis reason code is used during a transaction to indicate an internal JCRE problem (fatal error).

static short NOT_IN_PROGRESSThis reason code is used by the abortTransaction and commitTransaction methods when a transaction is not in progress.

ConstructorsTransactionException(short reason)

Constructs a TransactionException with the specified reason.

Methods


javacard.framework TransactionException

IN_PROGRESS

Fields

IN_PROGRESS

public static final short IN_PROGRESS

This reason code is used by the beginTransaction method to indicate a transaction is already in progress.

NOT_IN_PROGRESS

public static final short NOT_IN_PROGRESS

This reason code is used by the abortTransaction and commitTransaction methods when a transaction is not in progress.

BUFFER_FULL

public static final short BUFFER_FULL

This reason code is used during a transaction to indicate that the commit buffer is full.

INTERNAL_FAILURE

public static final short INTERNAL_FAILURE

This reason code is used during a transaction to indicate an internal JCRE problem (fatal error).

Constructors

TransactionException(short)

public TransactionException(short reason)

static void throwIt(short reason)Throws the JCRE owned instance of TransactionException with the specified reason.





equals(Object)

Member Summary

TransactionException 107


throwIt(short)

Constructs a TransactionException with the specified reason. To conserve on resources use throwIt() to use the JCRE owned instance of this class.

Methods

throwIt(short)


Throws the JCRE owned instance of TransactionException with the specified reason.


Throws:TransactionException - always.


javacard.framework UserException

throwIt(short)

javacard.framework

UserExceptionDeclarationpublic class UserException extends CardException java.lang.Object



|+--javacard.framework.CardException

|+--javacard.framework.UserException

DescriptionUserException represents a User exception. This class also provides a resource-saving mechanism (the throwIt() method) for user exceptions by using a JCRE owned instance.


Member Summary

ConstructorsUserException()

Constructs a UserException with reason = 0.UserException(short reason)

Constructs a UserException with the specified reason.


Throws the JCRE owned instance of UserException with the specified reason.


Methods inherited from interface CardException



equals(Object)

UserException 109

UserException javacard.framework

UserException()

Constructors

UserException()

public UserException()

Constructs a UserException with reason = 0. To conserve on resources use throwIt() to use the JCRE owned instance of this class.

UserException(short)

public UserException(short reason)

Constructs a UserException with the specified reason. To conserve on resources use throwIt() to use the JCRE owned instance of this class.


Methods

throwIt(short)


throws UserException

Throws the JCRE owned instance of UserException with the specified reason.



Throws:UserException - always.


javacard.framework Util

throwIt(short)

javacard.framework

UtilDeclarationpublic class Util java.lang.Object

|+--javacard.framework.Util

DescriptionThe Util class contains common utility functions. Some of the methods may be implemented as native functions for performance reasons. All methods in Util, class are static methods.

Some methods of Util namely arrayCopy(), arrayCopyNonAtomic(), arrayFillNonAtomic() and setShort(), refer to the persistence of array objects. The term persistent means that arrays and their values persist from one CAD session to the next, indefinitely. The JCSystem class is used to control the persistence and transience of objects.

See Also: JCSystem

Member Summary

Methodsstatic byte arrayCompare(byte[] src, short srcOff, byte[] dest, short

destOff, short length)Compares an array from the specified source array, beginning at the specified position, with the specified position of the destination array from left to right.

static short arrayCopy(byte[] src, short srcOff, byte[] dest, short destOff, short length)

Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array.

static short arrayCopyNonAtomic(byte[] src, short srcOff, byte[] dest, short destOff, short length)

Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array (non-atomically).

static short arrayFillNonAtomic(byte[] bArray, short bOff, short bLen, byte bValue)

Fills the byte array (non-atomically) beginning at the specified position, for the specified length with the specified byte value.

static short getShort(byte[] bArray, short bOff)Concatenates two bytes in a byte array to form a short value.

static short makeShort(byte b1, byte b2)Concatenates the two parameter bytes to form a short value.

static short setShort(byte[] bArray, short bOff, short sValue)Deposits the short value as two successive bytes at the specified offset in the byte array.

Util 111

Util javacard.framework

arrayCopy(byte[], short, byte[], short, short)

Methods

arrayCopy(byte[], short, byte[], short, short)

public static final short arrayCopy(byte[] src, short srcOff, byte[] dest, short destOff,

short length)

throws ArrayIndexOutOfBoundsException, NullPointerException,

TransactionException

Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array.

Notes:

• If srcOff or destOff or length parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.

• If srcOff+length is greater than src.length, the length of the src array a ArrayIndexOutOfBoundsException exception is thrown and no copy is performed.

• If destOff+length is greater than dest.length, the length of the dest array an ArrayIndexOutOfBoundsException exception is thrown and no copy is performed.

• If src or dest parameter is null a NullPointerException exception is thrown.

• If the src and dest arguments refer to the same array object, then the copying is performed as if the components at positions srcOff through srcOff+length-1 were first copied to a temporary array with length components and then the contents of the temporary array were copied into positions destOff through destOff+length-1 of the argument array.

• If the destination array is persistent, the entire copy is performed atomically.

• The copy operation is subject to atomic commit capacity limitations. If the commit capacity is exceeded, no copy is performed and a TransactionException exception is thrown.

Parameters:src - source byte array.

srcOff - offset within source byte array to start copy from.

dest - destination byte array.

destOff - offset within destination byte array to start copy into.

length - byte length to be copied.

Returns: destOff+length

Throws:ArrayIndexOutOfBoundsException - if copying would cause access of data outside array bounds.

NullPointerException - if either src or dest is null.



equals(Object)



arrayCopyNonAtomic(byte[], short, byte[], short, short)

TransactionException - if copying would cause the commit capacity to be exceeded.

See Also: JCSystem.getUnusedCommitCapacity()

arrayCopyNonAtomic(byte[], short, byte[], short, short)

public static final short arrayCopyNonAtomic(byte[] src, short srcOff, byte[] dest,

short destOff, short length)


Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array (non-atomically).

This method does not use the transaction facility during the copy operation even if a transaction is in progress. Thus, this method is suitable for use only when the contents of the destination array can be left in a partially modified state in the event of a power loss in the middle of the copy operation.

Notes:


• If srcOff+length is greater than src.length, the length of the src array a ArrayIndexOutOfBoundsException exception is thrown and no copy is performed.

• If destOff+length is greater than dest.length, the length of the dest array an ArrayIndexOutOfBoundsException exception is thrown and no copy is performed.


• If the src and dest arguments refer to the same array object, then the copying is performed as if the components at positions srcOff through srcOff+length-1 were first copied to a temporary array with length components and then the contents of the temporary array were copied into positions destOff through destOff+length-1 of the argument array.

• If power is lost during the copy operation and the destination array is persistent, a partially changed destination array could result.

• The copy length parameter is not constrained by the atomic commit capacity limitations.


srcOff - offset within source byte array to start copy from.


destOff - offset within destination byte array to start copy into.

length - byte length to be copied.

Returns: destOff+length

Throws:ArrayIndexOutOfBoundsException - if copying would cause access of data outside array bounds.



Util 113


arrayFillNonAtomic(byte[], short, short, byte)

arrayFillNonAtomic(byte[], short, short, byte)

public static final short arrayFillNonAtomic(byte[] bArray, short bOff, short bLen,

byte bValue)


Fills the byte array (non-atomically) beginning at the specified position, for the specified length with the specified byte value.

This method does not use the transaction facility during the fill operation even if a transaction is in progress. Thus, this method is suitable for use only when the contents of the byte array can be left in a partially filled state in the event of a power loss in the middle of the fill operation.

Notes:

• If bOff or bLen parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.

• If bOff+bLen is greater than bArray.length, the length of the bArray array an ArrayIndexOutOfBoundsException exception is thrown.

• If bArray parameter is null a NullPointerException exception is thrown.

• If power is lost during the copy operation and the byte array is persistent, a partially changed byte array could result.

• The bLen parameter is not constrained by the atomic commit capacity limitations.

Parameters:bArray - the byte array.

bOff - offset within byte array to start filling bValue into.

bLen - byte length to be filled.

bValue - the value to fill the byte array with.

Returns: bOff+bLen

Throws:ArrayIndexOutOfBoundsException - if the fill operation would cause access of data outside array bounds.

NullPointerException - if bArray is null


arrayCompare(byte[], short, byte[], short, short)

public static final byte arrayCompare(byte[] src, short srcOff, byte[] dest,

short destOff, short length)


Compares an array from the specified source array, beginning at the specified position, with the specified position of the destination array from left to right. Returns the ternary result of the comparison : less than(-1), equal(0) or greater than(1).

Notes:


• If srcOff+length is greater than src.length, the length of the src array a ArrayIndexOutOfBoundsException exception is thrown.



makeShort(byte, byte)

• If destOff+length is greater than dest.length, the length of the dest array an ArrayIndexOutOfBoundsException exception is thrown.



srcOff - offset within source byte array to start compare.


destOff - offset within destination byte array to start compare.

length - byte length to be compared.

Returns: the result of the comparison as follows:

• 0 if identical

• -1 if the first miscomparing byte in source array is less than that in destination array,

• 1 if the first miscomparing byte in source array is greater that that in destination array.

Throws:ArrayIndexOutOfBoundsException - if comparing all bytes would cause access of data outside array bounds.


makeShort(byte, byte)

public static final short makeShort(byte b1, byte b2)

Concatenates the two parameter bytes to form a short value.

Parameters:b1 - the first byte ( high order byte ).

b2 - the second byte ( low order byte ).

Returns: the short value the concatenated result

getShort(byte[], short)

public static final short getShort(byte[] bArray, short bOff)

throws NullPointerException, ArrayIndexOutOfBoundsException

Concatenates two bytes in a byte array to form a short value.

Parameters:bArray - byte array.

bOff - offset within byte array containing first byte (the high order byte).

Returns: the short value the concatenated result

Throws:NullPointerException - if the bArray parameter is null

ArrayIndexOutOfBoundsException - if the bOff parameter is negative or if bOff+1 is greater than the length of bArray

Util 115


setShort(byte[], short, short)

setShort(byte[], short, short)

public static final short setShort(byte[] bArray, short bOff, short sValue)

throws TransactionException, NullPointerException,

ArrayIndexOutOfBoundsException

Deposits the short value as two successive bytes at the specified offset in the byte array.

Parameters:bArray - byte array.

bOff - offset within byte array to deposit the first byte (the high order byte).

sValue - the short value to set into array.

Returns: bOff+2

Note:

• If the byte array is persistent, this operation is performed atomically. If the commit capacity is exceeded, no operation is performed and a TransactionException exception is thrown.

Throws:TransactionException - if the operation would cause the commit capacity to be exceeded.

ArrayIndexOutOfBoundsException - if the bOff parameter is negative or if bOff+1 is greater than the length of bArray

NullPointerException - if the bArray parameter is null



Package

javacard.framework.serviceDescriptionProvides a service framework of classes and interfaces that allow a Java Card applet to be designed as an aggregation of service components. The package contains an aggregator class called Dispatcher which includes methods to add services to its registry, dispatch APDU commands to registered services, and remove services from its registry.

The package also contains the Service interface which contains methods to process APDU commands, and allow the dispatcher to be aware of multiple services. Subinterfaces allow an implementation services with added functionality:

• RemoteService-use this subinterface to define services that allow remote processes to access the services present on a card that supports the Java Card platform.

• SecurityService-use this subinterface to define services that provide methods to query the current security status.

The class BasicService provides the basic functionality of a service, and all services are built as subclasses of this class. BasicService provides a default implementation for the methods defined in the Service interface, and defines a set of helper methods that allow the APDU buffer to enable cooperation among different services.

Java Card RMI ClassesThe CardRemoteObject and RMIService classes allow a Java program running on a virtual machine on the client platform to invoke methods on remote objects in a Java Card applet. These classes contain the minimum required functionality to implement Java Card Remote Method Invocation (JCRMI).

Class Summary

Interfaces

RemoteService This interface defines the generic API for remote object access services, which allow remote processes to access the services present on a Java Card card.

SecurityService This interface describes the functions of a generic security service.

Service This is the base interface for the service framework in Java Card.

Classes

BasicService This class should be used as the base class for implementing services.

CardRemoteObject A convenient base class for remote objects in Java Card.

Dispatcher A Dispatcher is used to build an application by aggregating several services.

RMIService An implementation of a service that is used to process Java Card RMI (JCRMI) requests for remotely accessible objects.

Exceptions

javacard.framework.service 117

javacard.framework.service

ServiceException ServiceException represents a service framework related exception.

Class Summary


javacard.framework.service BasicService


BasicServiceDeclarationpublic class BasicService implements Service java.lang.Object

|+--javacard.framework.service.BasicService

All Implemented Interfaces: Service

Direct Known Subclasses: RMIService

DescriptionThis class should be used as the base class for implementing services. It provides a default implementation for the methods defined in the Service interface, and defines a set of helper methods that manage the APDU buffer to enable co-operation among different Services.

The BasicService class uses the state of APDU processing to enforce the validity of the various helper operations. It expects and maintains the following Common Service Format (CSF) of data in the APDU Buffer corresponding to the various APDU processing states (See APDU ):

Init State format of APDU Buffer. This format corresponds to theAPDU processing state - STATE_INITIAL :0 1 2 3 4 5 <- offset+------------------------------------------------------------+| CLA | INS | P1 | P2 | P3 | ... Implementation dependent ...|+------------------------------------------------------------+Input Ready format of APDU Buffer. This format correspondsto the APDU processing state - STATE_FULL_INCOMING.0 1 2 3 4 5 <- offset

+------------------------------------------------------------+| CLA | INS | P1 | P2 | Lc | Incoming Data( Lc bytes ) |+------------------------------------------------------------+Output Ready format of APDU Buffer. This format correspondsto the APDU processing status - STATE_OUTGOING .. STATE_FULL_OUTGOING0 1 2 3 4 5 <- offset

+------------------------------------------------------------+| CLA | INS | SW1 | SW2 | La | Outgoing Data( La bytes ) |+------------------------------------------------------------+

When the APDU buffer is in the Init and Input Ready formats, the helper methods allow input access methods but flag errors if output access is attempted. Conversely, when the APDU buffer is in the Output format, input access methods result in exceptions.

If the header areas maintained by the BasicService helper methods are modified directly in the APDU buffer and the format of the APDU buffer described above is not maintained, unexpected behavior might result.

Many of the helper methods also throw exceptions if the APDU object is in an error state ( processing status code < 0 ).

See Also: APDU

BasicService 119

BasicService javacard.framework.service

Member Summary

ConstructorsBasicService()

Creates new BasicService.

Methods boolean fail(javacard.framework.APDU apdu, short sw)

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has failed.

byte getCLA(javacard.framework.APDU apdu)Returns the class byte for the command in the APDU object.

byte getINS(javacard.framework.APDU apdu)Returns the instruction byte for the command in the APDU object.

short getOutputLength(javacard.framework.APDU apdu)Returns the output length for the command in the APDU object.

byte getP1(javacard.framework.APDU apdu)Returns the first parameter byte for the command in the APDU object.

byte getP2(javacard.framework.APDU apdu)Returns the second parameter byte for the command in the APDU object.

short getStatusWord(javacard.framework.APDU apdu)Returns the response status word for the command in the APDU object.

boolean isProcessed(javacard.framework.APDU apdu)Checks if the command in the APDU object has already been processed.

boolean processCommand(javacard.framework.APDU apdu)This BasicService method is a default implementation and simply returns false without performing any processing.

boolean processDataIn(javacard.framework.APDU apdu)This BasicService method is a default implementation and simply returns false without performing any processing.

boolean processDataOut(javacard.framework.APDU apdu)This BasicService method is a default implementation and simply returns false without performing any processing.

short receiveInData(javacard.framework.APDU apdu)Receives the input data for the command in the APDU object if the input has not already been received.

boolean selectingApplet()This method is used to determine if the command in the APDU object is the applet SELECT FILE command which selected the currently selected applet.

void setOutputLength(javacard.framework.APDU apdu, short length)Sets the output length of the outgoing response for the command in the APDU object.

void setProcessed(javacard.framework.APDU apdu)Sets the processing state of the command in the APDU object to processed.

void setStatusWord(javacard.framework.APDU apdu, short sw)Sets the response status word for the command in the APDU object.

boolean succeed(javacard.framework.APDU apdu)Sets the processing state for the command in the APDU object to processed, and indicates that the processing has succeeded.

boolean succeedWithStatusWord(javacard.framework.APDU apdu, short sw)Sets the processing state for the command in the APDU object to processed, and indicates that the processing has partially succeeded.



BasicService()

Constructors

BasicService()

public BasicService()

Creates new BasicService.

Methods

processDataIn(APDU)

public boolean processDataIn(javacard.framework.APDU apdu)

This BasicService method is a default implementation and simply returns false without performing any processing.

Specified By: processDataIn in interface Service

Parameters:apdu - the APDU object containing the command being processed.

Returns: false.

processCommand(APDU)

public boolean processCommand(javacard.framework.APDU apdu)


Specified By: processCommand in interface Service


Returns: false.

processDataOut(APDU)

public boolean processDataOut(javacard.framework.APDU apdu)


Specified By: processDataOut in interface Service


Returns: false.



equals(Object)

BasicService 121


receiveInData(APDU)

receiveInData(APDU)

public short receiveInData(javacard.framework.APDU apdu)

throws ServiceException

Receives the input data for the command in the APDU object if the input has not already been received. The entire input data must fit in the APDU buffer starting at offset 5. When invoked, the APDU object must either be in STATE_INITIAL with the APDU buffer in the Init format or in STATE_FULL_INCOMING with the APDU buffer in the Input Ready format

Parameters:apdu - the APDU object containing the apdu being processed.

Returns: the length of input data received and present in the APDU Buffer.

Throws:ServiceException - with the following reason code:

• ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING or,

• ServiceException.COMMAND_DATA_TOO_LONG if the input data does not fit in the APDU buffer starting at offset 5.

setProcessed(APDU)

public void setProcessed(javacard.framework.APDU apdu)


Sets the processing state of the command in the APDU object to processed. This is done by setting the APDU object in outgoing mode by invoking the APDU.setOutgoing method. If the APDU is already in outgoing mode, this method does nothing (allowing the method to be called several times).



• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the APDU object is not accessible (APDU object in STATE_ERROR_.. )

See Also: javacard.framework.APDU.getCurrentState()

isProcessed(APDU)

public boolean isProcessed(javacard.framework.APDU apdu)

Checks if the command in the APDU object has already been processed. This is done by checking whether or not the APDU object has been set in outgoing mode via a previous invocation of the APDU.setOutgoing method.

Note:

• This method returns true if the APDU object is not accessible (APDU object in STATE_ERROR_.. ).


Returns: true if the command has been processed, false otherwise.



setOutputLength(APDU, short)

setOutputLength(APDU, short)

public void setOutputLength(javacard.framework.APDU apdu, short length)


Sets the output length of the outgoing response for the command in the APDU object. This method can be called regardless of the current state of the APDU processing.


length - the number of bytes in the response to the command.


• ServiceException.ILLEGAL_PARAM if the length parameter is greater than 256 or if the outgoing response will not fit within the APDU Buffer.

getOutputLength(APDU)

public short getOutputLength(javacard.framework.APDU apdu)


Returns the output length for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been processed.


Returns: the number of bytes to be returned for this command.


• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the command is not processed or if the APDU object is not accessible (APDU object in STATE_ERROR_.. )


setStatusWord(APDU, short)

public void setStatusWord(javacard.framework.APDU apdu, short sw)

Sets the response status word for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.


sw - the status word response for this command.

getStatusWord(APDU)

public short getStatusWord(javacard.framework.APDU apdu)


Returns the response status word for the command in the APDU object. This method can only be called if the APDU processing state indicates that the command has been processed.


BasicService 123


fail(APDU, short)

Returns: the status word response for this command.


• ServiceException.CANNOT_ACCESS_OUT_COMMAND if the command is not processed or if the APDU object is not accessible (APDU object in STATE_ERROR_.. )


fail(APDU, short)

public boolean fail(javacard.framework.APDU apdu, short sw)


Sets the processing state for the command in the APDU object to processed, and indicates that the processing has failed. Sets the output length to 0 and the status word of the response to the specified value.


sw - the status word response for this command.

Returns: true.




succeed(APDU)

public boolean succeed(javacard.framework.APDU apdu)


Sets the processing state for the command in the APDU object to processed, and indicates that the processing has succeeded. Sets the status word of the response to 0x9000. The output length of the response must be set separately.


Returns: true.




succeedWithStatusWord(APDU, short)

public boolean succeedWithStatusWord(javacard.framework.APDU apdu, short sw)




getCLA(APDU)

Sets the processing state for the command in the APDU object to processed, and indicates that the processing has partially succeeded. Sets the the status word of the response to the specified value. The output length of the response must be set separately.


sw - the status word to be returned for this command.

Returns: true.




getCLA(APDU)

public byte getCLA(javacard.framework.APDU apdu)

Returns the class byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.


Returns: the value of the CLA byte.

getINS(APDU)

public byte getINS(javacard.framework.APDU apdu)

Returns the instruction byte for the command in the APDU object. This method can be called regardless of the APDU processing state of the current command.


Returns: the value of the INS byte.

getP1(APDU)

public byte getP1(javacard.framework.APDU apdu)


Returns the first parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING.


Returns: the value of the P1 byte.


• ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING.

BasicService 125


getP2(APDU)

getP2(APDU)

public byte getP2(javacard.framework.APDU apdu)


Returns the second parameter byte for the command in the APDU object. When invoked, the APDU object must be in STATE_INITIAL or STATE_FULL_INCOMING.


Returns: the value of the P2 byte.


• ServiceException.CANNOT_ACCESS_IN_COMMAND if the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING.

selectingApplet()

public boolean selectingApplet()

This method is used to determine if the command in the APDU object is the applet SELECT FILE command which selected the currently selected applet.

Returns: true if applet SELECT FILE command is being processed.


javacard.framework.service CardRemoteObject

CardRemoteObject()


CardRemoteObjectDeclarationpublic class CardRemoteObject implements Remote java.lang.Object

|+--javacard.framework.service.CardRemoteObject

All Implemented Interfaces: Remote

DescriptionA convenient base class for remote objects in Java Card. An instance of a subclass of this CardRemoteObject class will automatically be exported upon construction.

Constructors

CardRemoteObject()

public CardRemoteObject()

Creates a new CardRemoteObject and automatically exports it. When exported, the object is enabled for remote access from outside the card until unexported. Only when the object is enabled for remote access can it be returned as the initial reference during selection or returned by a remote method. In addition, remote methods can be invoked only on objects enabled for remote access.

Member Summary

ConstructorsCardRemoteObject()

Creates a new CardRemoteObject and automatically exports it.

Methodsstatic void export(java.rmi.Remote obj)

Exports the specified remote object.static void unexport(java.rmi.Remote obj)

Unexports the specified remote object.



equals(Object)

CardRemoteObject 127

CardRemoteObject javacard.framework.service

export(Remote)

Methods

export(Remote)

public static void export(java.rmi.Remote obj)


Exports the specified remote object. The object is now enabled for remote access from outside the card until unexported. In order to remotely access the remote object from the terminal client, it must either be set as the initial reference or be returned by a remote method.

Parameters:obj - the remotely accessible object.

Throws:SecurityException - if the specified obj parameter is not owned by the caller context.

unexport(Remote)

public static void unexport(java.rmi.Remote obj)


Unexports the specified remote object. The object cannot be remotely accessed any more from outside the card, until it is exported again.

Note:

• If this method is called during the session in which the specified remote object parameter is the initial reference object or has been returned by a remote method, the specified remote object will continue to be remotely accessible until the end of the associated selection session(s).

Parameters:obj - the remotely accessible object.

Throws:SecurityException - if the specified obj parameter is not owned by the caller context.


javacard.framework.service Dispatcher

unexport(Remote)


DispatcherDeclarationpublic class Dispatcher java.lang.Object

|+--javacard.framework.service.Dispatcher

DescriptionA Dispatcher is used to build an application by aggregating several services.

The dispatcher maintains a registry of Service objects. A Service is categorized by the type of processing it performs :

• A pre-processing service pre-processes input data for the command being processed. It is associated with the PROCESS_INPUT_DATA phase.

• A command processing service processes the input data and generates output data. It is associated with the PROCESS_COMMAND phase.

• A post-processing service post-processes the generated output data. It is associated with the PROCESS_OUTPUT_DATA phase.

The dispatcher simply dispatches incoming APDU object containing the command being processed to the registered services.

Member Summary

Fieldsstatic byte PROCESS_COMMAND

Identifies the main command processing phase.static byte PROCESS_INPUT_DATA

Identifies the input data processing phase.static byte PROCESS_NONE

Identifies the null processing phase.static byte PROCESS_OUTPUT_DATA

Identifies the output data processing phase.

ConstructorsDispatcher(short maxServices)

Creates a Dispatcher with a designated maximum number of services.

Methods void addService(Service service, byte phase)

Atomically adds the specified service to the dispatcher registry for the specified processing phase.

java.lang.Exception dispatch(javacard.framework.APDU command, byte phase)Manages the processing of the command in the APDU object.

void process(javacard.framework.APDU command)Manages the entire processing of the command in the APDU object input parameter.

Dispatcher 129

Dispatcher javacard.framework.service

PROCESS_NONE

Fields

PROCESS_NONE

public static final byte PROCESS_NONE

Identifies the null processing phase.

PROCESS_INPUT_DATA

public static final byte PROCESS_INPUT_DATA

Identifies the input data processing phase.

PROCESS_COMMAND

public static final byte PROCESS_COMMAND

Identifies the main command processing phase.

PROCESS_OUTPUT_DATA

public static final byte PROCESS_OUTPUT_DATA

Identifies the output data processing phase.

Constructors

Dispatcher(short)

public Dispatcher(short maxServices)


Creates a Dispatcher with a designated maximum number of services.

Parameters:maxServices - the maximum number of services that can be registered to this dispatcher.


void removeService(Service service, byte phase)Atomically removes the specified service for the specified processing phase from the dispatcher registry.



equals(Object)

Member Summary


javacard.framework.service Dispatcher

addService(Service, byte)

• ServiceException.ILLEGAL_PARAM if the maxServices parameter is negative.

Methods

addService(Service, byte)

public void addService(javacard.framework.service.Service service, byte phase)


Atomically adds the specified service to the dispatcher registry for the specified processing phase. Services are invoked in the order in which they are added to the registry during the processing of that phase. If the requested service is already registered for the specified processing phase, this method does nothing.

Parameters:service - the Service to be added to the dispatcher.

phase - the processing phase associated with this service


• ServiceException.DISPATCH_TABLE_FULL if the maximum number of registered services is exceeded.

• ServiceException.ILLEGAL_PARAM if the phase parameter is undefined or if the service parameter is null.

removeService(Service, byte)

public void removeService(javacard.framework.service.Service service, byte phase)


Atomically removes the specified service for the specified processing phase from the dispatcher registry. Upon removal, the slot used by the specified service in the dispatcher registry is available for re-use. If the specified service is not registered for the specified processing phase, this method does nothing.

Parameters:service - the Service to be deleted from the dispatcher.

phase - the processing phase associated with this service


• ServiceException.ILLEGAL_PARAM if the phase parameter is unknown or if the service parameter is null.

dispatch(APDU, byte)

public java.lang.Exception dispatch(javacard.framework.APDU command, byte phase)


Manages the processing of the command in the APDU object. This method is called when only partial processing using the registered services is required or when the APDU response folowing an error during the processing needs to be controlled.

It sequences through the registered services by calling the appopriate processing methods. Processing starts with the phase indicated in the input parameter. Services registered for that processing phase are called in

Dispatcher 131


process(APDU)

the sequence in which they were registered until all the services for the processing phase have been called or a service indicates that processing for that phase is complete by returning true from its processing method. The dispatcher then processes the next phases in a similar manner until all the phases have been processed. The PROCESS_OUTPUT_DATA processing phase is performed only if the command processing has completed normally (APDU object state is APDU.STATE_OUTGOING).

The processing sequence is PROCESS_INPUT_DATA phase, followed by the PROCESS_COMMAND phase and lastly the PROCESS_OUTPUT_DATA. The processing is performed as follows:

• PROCESS_INPUT_DATA phase invokes the Service.processDataIn(APDU) method

• PROCESS_COMMAND phase invokes the Service.processCommand(APDU) method

• PROCESS_OUTPUT_DATA phase invokes the Service.processDataOut(APDU) method

If the command processing completes normally, the output data, assumed to be in the APDU buffer in the Common Service Format (CSF) defined in BasicService, is sent using APDU.sendBytes and the response status is generated by throwing an ISOException exception. If the command could not be processed, null is returned. If any exception is thrown by a Service during the processing, that exception is returned.

Parameters:command - the APDU object containing the command to be processed

phase - the processing phase to perform first

Returns: an exception that occurred during the processing of the command, or null if the command could not be processed.


• ServiceException.ILLEGAL_PARAM if the phase parameter is PROCESS_NONE or an undefined value.


process(APDU)

public void process(javacard.framework.APDU command)

throws ISOException

Manages the entire processing of the command in the APDU object input parameter. This method is called to delegate the complete processing of the incoming APDU command to the configured services.

This method uses the dispatch(APDU, byte) method with PROCESS_DATA_IN as the input phase parameter to sequence through the the services registered for all three phases : PROCESS_DATA_IN followed by PROCESS_DATA_COMMAND and lastly PROCESS_DATA_OUT.

If the command processing completes normally, the output data is sent using APDU.sendBytes and the response status is generated by throwing an ISOException exception or by simply returning (for status = 0x9000). If an exception is thrown by any Service during the processing, ISO7816.SW_UNKNOWN response status code is generated by throwing an ISOException. If the command could not be processed ISO7816.SW_INS_NOT_SUPPORTED response status is generated by throwing an ISOException.

Parameters:command - the APDU object containing command to be processed.

Throws:ISOException - with the response bytes per ISO 7816-4


javacard.framework.service RemoteService

process(APDU)


RemoteServiceDeclarationpublic interface RemoteService extends Service

All Superinterfaces: Service

All Known Implementing Classes: RMIService

DescriptionThis interface defines the generic API for remote object access services, which allow remote processes to access the services present on a Java Card card.


Methods inherited from interface Service

processCommand(APDU), processDataIn(APDU), processDataOut(APDU)

RemoteService 133

RMIService javacard.framework.service

process(APDU)


RMIServiceDeclarationpublic class RMIService extends BasicService implements RemoteService java.lang.Object

|+--javacard.framework.service.BasicService

|+--javacard.framework.service.RMIService

All Implemented Interfaces: RemoteService, Service

DescriptionAn implementation of a service that is used to process Java Card RMI (JCRMI) requests for remotely accessible objects.

Member Summary

Fieldsstatic byte DEFAULT_RMI_INVOKE_INSTRUCTION

The default INS value (0x38) used for the remote method invocation command (INVOKE) in the Java Card RMI protocol.

ConstructorsRMIService(java.rmi.Remote initialObject)

Creates a new RMIService and sets the specified remote object as the initial reference for the applet.

Methods boolean processCommand(javacard.framework.APDU apdu)

Processes the command within the APDU object. void setInvokeInstructionByte(byte ins)

Defines the instruction byte to be used in place of DEFAULT_RMI_INVOKE_INSTRUCTION in the JCRMI protocol for the INVOKE commands used to access the RMIService for remote method invocations.


Methods inherited from class BasicService

fail(APDU, short), getCLA(APDU), getINS(APDU), getOutputLength(APDU), getP1(APDU), getP2(APDU), getStatusWord(APDU), isProcessed(APDU), processDataIn(APDU), processDataOut(APDU), receiveInData(APDU), selectingApplet(), setOutputLength(APDU, short), setProcessed(APDU), setStatusWord(APDU, short), succeed(APDU), succeedWithStatusWord(APDU, short)


javacard.framework.service RMIService

DEFAULT_RMI_INVOKE_INSTRUCTION

Fields

DEFAULT_RMI_INVOKE_INSTRUCTION

public static final byte DEFAULT_RMI_INVOKE_INSTRUCTION

The default INS value (0x38) used for the remote method invocation command (INVOKE) in the Java Card RMI protocol.

Constructors

RMIService(Remote)

public RMIService(java.rmi.Remote initialObject)

throws NullPointerException

Creates a new RMIService and sets the specified remote object as the initial reference for the applet. The initial reference will be published to the client in response to the SELECT APDU command processed by this object.

The RMIService instance may create session data to manage exported remote objects for the current applet session in CLEAR_ON_DESELECT transient space.

Parameters:initialObject - the remotely accessible initial object.

Throws:NullPointerException - if the initialObject parameter is null.

Methods

setInvokeInstructionByte(byte)

public void setInvokeInstructionByte(byte ins)

Defines the instruction byte to be used in place of DEFAULT_RMI_INVOKE_INSTRUCTION in the JCRMI protocol for the INVOKE commands used to access the RMIService for remote method invocations.

Note:

• The new instruction byte goes into effect next time this RMIService instance processes an applet SELECT command. The JCRMI protocol until then is unchanged.


equals(Object)


processDataIn(APDU), processDataOut(APDU)


RMIService 135



Parameters:ins - the instruction byte.



Processes the command within the APDU object. When invoked, the APDU object should either be in STATE_INITIAL with the APDU buffer in the Init format or in STATE_FULL_INCOMING with the APDU buffer in the Input Ready format defined in BasicService.

This method first checks if the command in the APDU object is a Java Card RMI access command. The Java Card RMI access commands currently defined are: Applet SELECT and INVOKE. If it is not a Java Card RMI access command, this method does nothing and returns false.

If the command is a Java Card RMI access command, this method processes the command and generates the response to be returned to the terminal. For a detailed description of the APDU protocol used in Java Card RMI access commands please see the Remote Method Invocation Service chapter of Java Card Runtime Environment (JCRE) Specification.

Java Card RMI access commands are processed as follows:

• An applet SELECT command results in a Java Card RMI information structure in FCI format containing the initial reference object as the response to be returned to the terminal.

• An INVOKE command results in the following sequence -

1. The remote object is located. A remote object is accessible only if it was returned by this RMIService instance and since that time some applet instance or the other from within the applet package has been an active applet instance.

2. The method of the object is identified

3. Primitive input parameters are unmarshalled onto the stack. Array type input parameters are created as global arrays(See Java Card Runtime Environment (JCRE) Specification) and references to these are pushed onto the stack.

4. An INVOKEVIRTUAL bytecode to the remote method is simulated

5. Upon return from the method, method return or exception information is marshalled from the stack as the response to be returned to the terminal

After normal completion, this method returns true and the APDU object is in STATE_OUTGOING and the output response is in the APDU buffer in the Output Ready format defined in BasicService.

Specified By: processCommand in interface Service

Overrides: processCommand in class BasicService


Returns: true if the command has been processed, false otherwise

Throws:ServiceException - with the following reason codes:

• ServiceException.CANNOT_ACCESS_IN_COMMAND if this is a Java Card RMI access command and the APDU object is not in STATE_INITIAL or in STATE_FULL_INCOMING

• ServiceException.REMOTE_OBJECT_NOT_EXPORTED if the remote method returned a remote object which has not been exported.


javacard.framework.service RMIService


SecurityException - if one of the following conditions is met:

• if this is a Java Card RMI INVOKE command and a firewall security violation occurred while trying to simulate an INVOKEVIRTUAL bytecode on the remote object.

• if internal storage in CLEAR_ON_DESELECT transient space is accessed when the currently active context is not the context of the currently selected applet.

See Also: CardRemoteObject

RMIService 137

SecurityService javacard.framework.service



SecurityServiceDeclarationpublic interface SecurityService extends Service

All Superinterfaces: Service

DescriptionThis interface describes the functions of a generic security service. It extends the base Service interface and defines methods to query the current security status. Note that this interface is generic and does not include methods to initialize and change the security status of the service; initialization is assumed to be performed through APDU commands that the service is able to process.

A security service implementation class should extend BasicService and implement this interface.

Member Summary

Fieldsstatic short PRINCIPAL_APP_PROVIDER

The principal identifier for the application provider.static short PRINCIPAL_CARD_ISSUER

The principal identifier for the card issuer.static short PRINCIPAL_CARDHOLDER

The principal identifier for the cardholder.static byte PROPERTY_INPUT_CONFIDENTIALITY

This security property provides input confidentiality through encryption of the incoming command.

static byte PROPERTY_INPUT_INTEGRITYThis security property provides input integrity through MAC signature checking of the incoming command.

static byte PROPERTY_OUTPUT_CONFIDENTIALITYThis security property provides output confidentiality through encryption of the outgoing response.

static byte PROPERTY_OUTPUT_INTEGRITYThis security property provides output integrity through MAC signature generation for the outgoing response.

Methods boolean isAuthenticated(short principal)

Checks whether or not the specified principal is currently authenticated. boolean isChannelSecure(byte properties)

Checks whether a secure channel is established between the card and the host for the ongoing session that guarantees the indicated properties.

boolean isCommandSecure(byte properties)Checks whether a secure channel is in use between the card and the host for the ongoing command that guarantees the indicated properties.


javacard.framework.service SecurityService

PROPERTY_INPUT_CONFIDENTIALITY

Fields

PROPERTY_INPUT_CONFIDENTIALITY

public static final byte PROPERTY_INPUT_CONFIDENTIALITY

This security property provides input confidentiality through encryption of the incoming command. Note that this is a bit mask and security properties can be combined by simply adding them together.

PROPERTY_INPUT_INTEGRITY

public static final byte PROPERTY_INPUT_INTEGRITY

This security property provides input integrity through MAC signature checking of the incoming command. Note that this is a bit mask and security properties can be combined by simply adding them together.

PROPERTY_OUTPUT_CONFIDENTIALITY

public static final byte PROPERTY_OUTPUT_CONFIDENTIALITY

This security property provides output confidentiality through encryption of the outgoing response. Note that this is a bit mask and security properties can be combined by simply adding them together.

PROPERTY_OUTPUT_INTEGRITY

public static final byte PROPERTY_OUTPUT_INTEGRITY

This security property provides output integrity through MAC signature generation for the outgoing response. Note that this is a bit mask and security properties can be combined by simply adding them together.

PRINCIPAL_CARDHOLDER

public static final short PRINCIPAL_CARDHOLDER

The principal identifier for the cardholder.

PRINCIPAL_CARD_ISSUER

public static final short PRINCIPAL_CARD_ISSUER

The principal identifier for the card issuer.

PRINCIPAL_APP_PROVIDER

public static final short PRINCIPAL_APP_PROVIDER

The principal identifier for the application provider.



processCommand(APDU), processDataIn(APDU), processDataOut(APDU)

SecurityService 139


isAuthenticated(short)

Methods

isAuthenticated(short)

public boolean isAuthenticated(short principal)


Checks whether or not the specified principal is currently authenticated. The validity timeframe(selection or reset) and authentication method as well as the exact interpretation of the specified principal parameter needs to be detailed by the implementation class. The only generic guarantee is that the authentication has been performed in the current card session.

Parameters:principal - an identifier of the principal that needs to be authenticated

Returns: true if the expected principal is authenticated


• ServiceException.ILLEGAL_PARAM if the specified principal is unknown.

isChannelSecure(byte)

public boolean isChannelSecure(byte properties)


Checks whether a secure channel is established between the card and the host for the ongoing session that guarantees the indicated properties.

Parameters:properties - the required properties.

Returns: true if the required properties are true, false otherwise


• ServiceException.ILLEGAL_PARAM if the specified property is unknown.

isCommandSecure(byte)

public boolean isCommandSecure(byte properties)


Checks whether a secure channel is in use between the card and the host for the ongoing command that guarantees the indicated properties. The result is only correct after pre-processing the command (for instance during the processing of the command). For properties on incoming data, the result is guaranteed to be correct; for outgoing data, the result reflects the expectations of the client software, with no other guarantee.

Parameters:properties - the required properties.

Returns: true if the required properties are true, false othewise


• ServiceException.ILLEGAL_PARAM if the specified property is unknown.


javacard.framework.service Service

processDataIn(APDU)


ServiceDeclarationpublic interface Service

All Known Subinterfaces: RemoteService, SecurityService

All Known Implementing Classes: BasicService

DescriptionThis is the base interface for the service framework in Java Card. A Service is an object that is able to perform partial or complete processing on a set of incoming commands encapsulated in an APDU.

Services collaborate in pre-processing, command processing and post-processing of incoming APDU commands. They share the same APDU object by using the communication framework and the Common Service Format (CSF) defined in BasicService. An application is built by combining pre-built and newly defined Services within a Dispatcher object.


Methods

processDataIn(APDU)

public boolean processDataIn(javacard.framework.APDU apdu)

Pre-processes the input data for the command in the APDU object. When invoked, the APDU object should either be in STATE_INITIAL with the APDU buffer in the Init format or in STATE_FULL_INCOMING with the APDU buffer in the Input Ready format defined in BasicService.

The method must return true if no more pre-processing should be performed, and false otherwise. In particular, it must return false if it has not performed any processing on the command.

After normal completion, the APDU object is usually in STATE_FULL_INCOMING with the APDU buffer in the Input Ready format defined in BasicService. However, in some cases if the Service processes the

Member Summary

Methods boolean processCommand(javacard.framework.APDU apdu)

Processes the command in the APDU object. boolean processDataIn(javacard.framework.APDU apdu)

Pre-processes the input data for the command in the APDU object. boolean processDataOut(javacard.framework.APDU apdu)

Post-processes the output data for the command in the APDU object.

Service 141

Service javacard.framework.service


command entirely, the APDU object may be in STATE_OUTGOING with the APDU buffer in the Output Ready format defined in BasicService.


Returns: true if input processing is finished, false otherwise.



Processes the command in the APDU object. When invoked, the APDU object should normally be in STATE_INITIAL with the APDU buffer in the Init format or in STATE_FULL_INCOMING with the APDU buffer in the Input Ready format defined in BasicService. However, in some cases, if a pre-processing service has processed the command entirely, the APDU object may be in STATE_OUTGOING with the APDU buffer in the Output Ready format defined in BasicService.

The method must return true if no more command processing is required, and false otherwise. In particular, it should return false if it has not performed any processing on the command.

After normal completion, the APDU object must be in STATE_OUTGOING and the output response must be in the APDU buffer in the Output Ready format defined in BasicService.


Returns: true if the command has been processed, false otherwise..


public boolean processDataOut(javacard.framework.APDU apdu)

Post-processes the output data for the command in the APDU object. When invoked, the APDU object should be in STATE_OUTGOING with the APDU buffer in the Output Ready format defined in BasicService.

The method should return true if no more post-processing is required, and false otherwise. In particular, it should return false if it has not performed any processing on the command.

After normal completion, the APDU object should must be in STATE_OUTGOING and the output response must be in the APDU buffer in the Output Ready format defined in BasicService.


Returns: true if output processing is finished, false otherwise.


javacard.framework.service ServiceException



ServiceExceptionDeclarationpublic class ServiceException extends CardRuntimeException java.lang.Object





|+--javacard.framework.service.ServiceException

DescriptionServiceException represents a service framework related exception.

The service framework classes throw JCRE owned instances of ServiceException.


Member Summary

Fieldsstatic short CANNOT_ACCESS_IN_COMMAND

This reason code is used to indicate that the command in the APDU object cannot be accessed for input processing.

static short CANNOT_ACCESS_OUT_COMMANDThis reason code is used to indicate that the command in the APDU object cannot be accessed for output processing.

static short COMMAND_DATA_TOO_LONGThis reason code is used to indicate that the incoming data for a command in the APDU object does not fit in the APDU buffer.

static short COMMAND_IS_FINISHEDThis reason code is used to indicate that the command in the APDU object has been completely processed.

static short DISPATCH_TABLE_FULLThis reason code is used to indicate that a dispatch table is full

static short ILLEGAL_PARAMThis reason code is used to indicate that an input parameter is not allowed.

static short REMOTE_OBJECT_NOT_EXPORTEDThis reason code is used by RMIService to indicate that the remote method returned a remote object which has not been exported.

Constructors

ServiceException 143

ServiceException javacard.framework.service

ILLEGAL_PARAM

Fields

ILLEGAL_PARAM

public static final short ILLEGAL_PARAM

This reason code is used to indicate that an input parameter is not allowed.

DISPATCH_TABLE_FULL

public static final short DISPATCH_TABLE_FULL

This reason code is used to indicate that a dispatch table is full

COMMAND_DATA_TOO_LONG

public static final short COMMAND_DATA_TOO_LONG

This reason code is used to indicate that the incoming data for a command in the APDU object does not fit in the APDU buffer.

CANNOT_ACCESS_IN_COMMAND

public static final short CANNOT_ACCESS_IN_COMMAND

This reason code is used to indicate that the command in the APDU object cannot be accessed for input processing.

CANNOT_ACCESS_OUT_COMMAND

public static final short CANNOT_ACCESS_OUT_COMMAND

ServiceException(short reason)Constructs a ServiceException.


Throws the JCRE owned instance of ServiceException with the specified reason.





equals(Object)

Member Summary


javacard.framework.service ServiceException

COMMAND_IS_FINISHED

This reason code is used to indicate that the command in the APDU object cannot be accessed for output processing.

COMMAND_IS_FINISHED

public static final short COMMAND_IS_FINISHED

This reason code is used to indicate that the command in the APDU object has been completely processed.

REMOTE_OBJECT_NOT_EXPORTED

public static final short REMOTE_OBJECT_NOT_EXPORTED

This reason code is used by RMIService to indicate that the remote method returned a remote object which has not been exported.

Constructors

ServiceException(short)

public ServiceException(short reason)

Constructs a ServiceException. To conserve on resources use throwIt() to use the JCRE owned instance of this class.


Methods

throwIt(short)



Throws the JCRE owned instance of ServiceException with the specified reason.



Throws:ServiceException - always.

ServiceException 145


throwIt(short)


Package

javacard.securityDescriptionProvides classes and interfaces that contain publicly-available functionality for implementing a security and cryptography framework on Java Card. Classes which contain security and cryptography functionality which may be subject to export controls are contained in the optional package javacardx.crypto .

Classes in the javacard.security package provide the definitions of algorithms that perform these security and cryptography functions:

• implementations for a variety of different cryptographic keys

• factory for building keys (see KeyBuilder )

• data hashing (see MessageDigest )

• random data generation (see RandomData )

• signing using cryptographic keys (see Signature )

• session key exchanges (see KeyAgreement )

Class Summary

Interfaces

AESKey AESKey contains a 16/24/32 byte key for AES computations based on the Rijndael algorithm.

DESKey DESKey contains an 8/16/24 byte key for single/2 key triple DES/3 key triple DES operations.

DSAKey The DSAKey interface is the base interface for the DSA algorithms private and public key implementations.

DSAPrivateKey The DSAPrivateKey interface is used to sign data using the DSA algorithm.

DSAPublicKey The DSAPublicKey interface is used to verify signatures on signed data using the DSA algorithm.

ECKey The ECKey interface is the base interface for the EC algorithms private and public key implementations.

ECPrivateKey The ECPrivateKey interface is used to generate signatures on data using the ECDSA (Elliptic Curve Digital Signature Algorithm) and to generate shared secrets using the ECDH (Elliptic Curve Diffie-Hellman) algorithm.

ECPublicKey The ECPublicKey interface is used to verify signatures on signed data using the ECDSA algorithm and to generate shared secrets using the ECDH algorithm.

Key The Key interface is the base interface for all keys.

PrivateKey The PrivateKey interface is the base interface for private keys used in asymmetric algorithms.

PublicKey The PublicKey interface is the base interface for public keys used in asymmetric algorithms.

javacard.security 147

javacard.security

RSAPrivateCrtKey The RSAPrivateCrtKey interface is used to sign data using the RSA algorithm in its Chinese Remainder Theorem form.

RSAPrivateKey The RSAPrivateKey class is used to sign data using the RSA algorithm in its modulus/exponent form.

RSAPublicKey The RSAPublicKey is used to verify signatures on signed data using the RSA algorithm.

SecretKey The SecretKey class is the base interface for keys used in symmetric algorithms (e.g. DES).

Classes

Checksum The Checksum class is the base class for CRC (cyclic redundancy check) checksum algorithms.

KeyAgreement The KeyAgreement class is the base class for key agreement algorithms such as Diffie-Hellman and EC Diffie-Hellman [IEEE P1363].

KeyBuilder The KeyBuilder class is a key object factory.

KeyPair This class is a container for a key pair (a public key and a private key).

MessageDigest The MessageDigest class is the base class for hashing algorithms.

RandomData The RandomData abstract class is the base class for random number generation.

Signature The Signature class is the base class for Signature algorithms.

Exceptions

CryptoException CryptoException represents a cryptography-related exception.

Class Summary


javacard.security AESKey

setKey(byte[], short)

javacard.security

AESKeyDeclarationpublic interface AESKey extends SecretKey

All Superinterfaces: Key, SecretKey

DescriptionAESKey contains a 16/24/32 byte key for AES computations based on the Rijndael algorithm.

When the key data is set, the key is initialized and ready for use.

Since: Java Card 2.2

See Also: KeyBuilder, Signature, Cipher, KeyEncryption

Methods


public void setKey(byte[] keyData, short kOff)

throws CryptoException

Sets the Key data. The plaintext length of input key data is 16/24/32 bytes. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input key data is copied into the internal representation.

Note:

Member Summary

Methods byte getKey(byte[] keyData, short kOff)

Returns the Key data in plain text. void setKey(byte[] keyData, short kOff)

Sets the Key data.


Methods inherited from interface Key

clearKey(), getSize(), getType(), isInitialized()

AESKey 149

AESKey javacard.security

getKey(byte[], short)

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, keyData is decrypted using the Cipher object.

Parameters:keyData - byte array containing key initialization data

kOff - offset within keyData to start

Throws:CryptoException - with the following reason code:

• CryptoException.ILLEGAL_VALUE if the input key data length is inconsistent with the implementation or if input data decryption is required and fails.


public byte getKey(byte[] keyData, short kOff)


Returns the Key data in plain text. The length of output key data is 16/24/32 bytes. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).

Parameters:keyData - byte array to return key data

kOff - offset within keyData to start.

Returns: the byte length of the key data returned.


• CryptoException.UNINITIALIZED_KEY if the key data has not been successfully initialized using the AESKey.setKey method since the time the initialized state of the key was set to false.

See Also: Key


javacard.security Checksum


javacard.security

ChecksumDeclarationpublic abstract class Checksum java.lang.Object

|+--javacard.security.Checksum

DescriptionThe Checksum class is the base class for CRC (cyclic redundancy check) checksum algorithms. Implementations of Checksum algorithms must extend this class and implement all the abstract methods.

A tear or card reset event resets a Checksum object to the initial state (state upon construction).

Even if a transaction is in progress, update of intermediate result state in the implementation instance shall not participate in the transaction.

Member Summary

Fieldsstatic byte ALG_ISO3309_CRC16

ISO/IEC 3309 compliant 16 bit CRC algorithm.static byte ALG_ISO3309_CRC32

ISO/IEC 3309 compliant 32 bit CRC algorithm.

Constructorsprotected Checksum()

Protected Constructor

Methodsabstract short doFinal(byte[] inBuff, short inOffset, short inLength, byte[]

outBuff, short outOffset)Generates a CRC checksum of all/last input data.

abstract byte getAlgorithm()Gets the Checksum algorithm.

static Checksum getInstance(byte algorithm, boolean externalAccess)Creates a Checksum object instance of the selected algorithm.

abstract void init(byte[] bArray, short bOff, short bLen)Resets and initializes the Checksum object with the algorithm specific parameters.

abstract void update(byte[] inBuff, short inOffset, short inLength)Accumulates a partial checksum of the input data.



Checksum 151

Checksum javacard.security

ALG_ISO3309_CRC16

Fields

ALG_ISO3309_CRC16

public static final byte ALG_ISO3309_CRC16

ISO/IEC 3309 compliant 16 bit CRC algorithm. This algorithm uses the generator polynomial : x^16+x^12+x^5+1. The default initial checksum value used by this alogrithm is 0.

ALG_ISO3309_CRC32

public static final byte ALG_ISO3309_CRC32

ISO/IEC 3309 compliant 32 bit CRC algorithm. This algorithm uses the generator polynomial : X^32 +X^26 +X^23 +X^22 +X^16 +X^12 +X^11 +X^10 +X^8 +X^7 +X^5 +X^4 +X^2 +X +1. The default initial checksum value used by this alogrithm is 0.

Constructors

Checksum()

protected Checksum()


Methods

getInstance(byte, boolean)

public static final javacard.security.Checksum getInstance(byte algorithm,

boolean externalAccess)


Creates a Checksum object instance of the selected algorithm.

Parameters:algorithm - the desired checksum algorithm. Valid codes listed in ALG_ .. constants above e.g. ALG_ISO3309_CRC16

externalAccess - true indicates that the instance will be shared among multiple applet instances and that the Checksum instance will also be accessed (via a Shareable. interface) when the owner of the Checksum instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.

Returns: the Checksum object instance of the requested algorithm.

Throws:CryptoException - with the following reason codes:

equals(Object)



javacard.security Checksum

init(byte[], short, short)

• CryptoException.NO_SUCH_ALGORITHM if the requested algorithm or shared access mode is not supported.

init(byte[], short, short)

public abstract void init(byte[] bArray, short bOff, short bLen)


Resets and initializes the Checksum object with the algorithm specific parameters.

Note:

• The ALG_ISO3309_CRC16 algorithm expects 2 bytes of parameter information in bArray representing the initial checksum value.

• The ALG_ISO3309_CRC32 algorithm expects 4 bytes of parameter information in bArray representing the initial checksum value.

Parameters:bArray - byte array containing algorithm specific initialization info.

bOff - offset within bArray where the algorithm specific data begins.

bLen - byte length of algorithm specific parameter data


• CryptoException.ILLEGAL_VALUE if a byte array parameter option is not supported by the algorithm or if the bLen is an incorrect byte length for the algorithm specific data.

getAlgorithm()

public abstract byte getAlgorithm()

Gets the Checksum algorithm. Valid codes listed in ALG_ .. constants above e.g. ALG_ISO3309_CRC16

Returns: the algorithm code defined above.

doFinal(byte[], short, short, byte[], short)

public abstract short doFinal(byte[] inBuff, short inOffset, short inLength,

byte[] outBuff, short outOffset)

Generates a CRC checksum of all/last input data. The CRC engine processes input data starting with the byte at offset inOffset and continuing on until the byte at (inOffset+inLength-1) of the inBuff array. Within each byte the processing proceeeds from the least significant bit to the most.

Completes and returns the checksum computation. The Checksum object is reset to the initial state(state upon construction) when this method completes.

Note:

• The ALG_ISO3309_CRC16 and ALG_ISO3309_CRC32 algorithms reset the initial checksum value to 0. The initial checksum value can be re-initialized using the init(byte[], short, short) method.

The input and output buffer data may overlap.

Parameters:inBuff - the input buffer of data to be checksummed

Checksum 153


update(byte[], short, short)

inOffset - the offset into the input buffer at which to begin checksum generation

inLength - the byte length to checksum

outBuff - the output buffer, may be the same as the input buffer

outOffset - the offset into the output buffer where the resulting checksum value begins

Returns: number of bytes of checksum output in outBuff


public abstract void update(byte[] inBuff, short inOffset, short inLength)

Accumulates a partial checksum of the input data. The CRC engine processes input data starting with the byte at offset inOffset and continuing on until the byte at (inOffset+inLength-1) of the inBuff array. Within each byte the processing proceeeds from the least significant bit to the most.

This method requires temporary storage of intermediate results. This may result in additional resource consumption and/or slow performance. This method should only be used if all the input data required for the checksum is not available in one byte array. The doFinal() method is recommended whenever possible.

Note:

• If inLength is 0 this method does nothing.

Parameters:inBuff - the input buffer of data to be checksummed

inOffset - the offset into the input buffer at which to begin checksum generation

inLength - the byte length to checksum

See Also: doFinal(byte[], short, short, byte[], short)


javacard.security CryptoException


javacard.security

CryptoExceptionDeclarationpublic class CryptoException extends CardRuntimeException java.lang.Object





|+--javacard.security.CryptoException

DescriptionCryptoException represents a cryptography-related exception.

The API classes throw JCRE owned instances of CryptoException.

JCRE owned instances of exception classes are temporary JCRE Entry Point Objects and can be accessed from any applet context. References to these temporary objects cannot be stored in class variables or instance variables or array components.

See Also: KeyBuilder, MessageDigest, Signature, RandomData, Cipher

Member Summary

Fieldsstatic short ILLEGAL_USE

This reason code is used to indicate that the signature or cipher algorithm does not pad the incoming message and the input message is not block aligned.

static short ILLEGAL_VALUEThis reason code is used to indicate that one or more input parameters is out of allowed bounds.

static short INVALID_INITThis reason code is used to indicate that the signature or cipher object has not been correctly initialized for the requested operation.

static short NO_SUCH_ALGORITHMThis reason code is used to indicate that the requested algorithm or key type is not supported.

static short UNINITIALIZED_KEYThis reason code is used to indicate that the key is uninitialized.

ConstructorsCryptoException(short reason)

Constructs a CryptoException with the specified reason.

Methods

CryptoException 155

CryptoException javacard.security

ILLEGAL_VALUE

Fields

ILLEGAL_VALUE



UNINITIALIZED_KEY

public static final short UNINITIALIZED_KEY

This reason code is used to indicate that the key is uninitialized.

NO_SUCH_ALGORITHM

public static final short NO_SUCH_ALGORITHM

This reason code is used to indicate that the requested algorithm or key type is not supported.

INVALID_INIT

public static final short INVALID_INIT

This reason code is used to indicate that the signature or cipher object has not been correctly initialized for the requested operation.

ILLEGAL_USE


This reason code is used to indicate that the signature or cipher algorithm does not pad the incoming message and the input message is not block aligned.

static void throwIt(short reason)Throws the JCRE owned instance of CryptoException with the specified reason.





equals(Object)

Member Summary


javacard.security CryptoException

CryptoException(short)

Constructors

CryptoException(short)

public CryptoException(short reason)

Constructs a CryptoException with the specified reason. To conserve on resources use throwIt() to use the JCRE owned instance of this class.


Methods

throwIt(short)


Throws the JCRE owned instance of CryptoException with the specified reason.



Throws:CryptoException - always.

CryptoException 157

DESKey javacard.security


javacard.security

DESKeyDeclarationpublic interface DESKey extends SecretKey

All Superinterfaces: Key, SecretKey

DescriptionDESKey contains an 8/16/24 byte key for single/2 key triple DES/3 key triple DES operations.

When the key data is set, the key is initialized and ready for use.


Methods


public void setKey(byte[] keyData, short kOff)

throws CryptoException, NullPointerException, ArrayIndexOutOfBoundsExceptio

n

Sets the Key data. The plaintext length of input key data is 8 bytes for DES, 16 bytes for 2 key triple DES and 24 bytes for 3 key triple DES. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input key data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the

Member Summary

Methods byte getKey(byte[] keyData, short kOff)

Returns the Key data in plain text. void setKey(byte[] keyData, short kOff)

Sets the Key data.





javacard.security DESKey


Cipher object specified via setKeyCipher() is not null, keyData is decrypted using the Cipher object.

Parameters:keyData - byte array containing key initialization data

kOff - offset within keyData to start


• CryptoException.ILLEGAL_VALUE if input data decryption is required and fails.

ArrayIndexOutOfBoundsException - if kOff is negative or the keyData array is too short.

NullPointerException - if the keyData parameter is null.


public byte getKey(byte[] keyData, short kOff)

Returns the Key data in plain text. The length of output key data is 8 bytes for DES, 16 bytes for 2 key triple DES and 24 bytes for 3 key triple DES. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).

Parameters:keyData - byte array to return key data

kOff - offset within keyData to start.

Returns: the byte length of the key data returned.


• CryptoException.UNINITIALIZED_KEY if the key data has not been successfully initialized using the DESKey.setKey method since the time the initialized state of the key was set to false.

See Also: Key

DESKey 159

DSAKey javacard.security

setP(byte[], short, short)

javacard.security

DSAKeyDeclarationpublic interface DSAKey

All Known Subinterfaces: DSAPrivateKey, DSAPublicKey

DescriptionThe DSAKey interface is the base interface for the DSA algorithms private and public key implementations. A DSA private key implementation must also implement the DSAPrivateKey interface methods. A DSA public key implementation must also implement the DSAPublicKey interface methods.

When all four components of the key (X or Y,P,Q,G) are set, the key is initialized and ready for use.

See Also: DSAPublicKey, DSAPrivateKey, KeyBuilder, Signature, KeyEncryption

Methods


public void setP(byte[] buffer, short offset, short length)


Sets the prime parameter value of the key. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input prime parameter data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the

Member Summary

Methods short getG(byte[] buffer, short offset)

Returns the base parameter value of the key in plain text. short getP(byte[] buffer, short offset)

Returns the prime parameter value of the key in plain text. short getQ(byte[] buffer, short offset)

Returns the subprime parameter value of the key in plain text. void setG(byte[] buffer, short offset, short length)

Sets the base parameter value of the key. void setP(byte[] buffer, short offset, short length)

Sets the prime parameter value of the key. void setQ(byte[] buffer, short offset, short length)

Sets the subprime parameter value of the key.


javacard.security DSAKey

setQ(byte[], short, short)

Cipher object specified via setKeyCipher() is not null, the prime parameter value is decrypted using the Cipher object.

Parameters:buffer - the input buffer

offset - the offset into the input buffer at which the prime parameter value begins

length - the length of the prime parameter value


• CryptoException.ILLEGAL_VALUE if the input parameter data length is inconsistent with the implementation or if input data decryption is required and fails.


public void setQ(byte[] buffer, short offset, short length)


Sets the subprime parameter value of the key. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input subprime parameter data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the subprime parameter value is decrypted using the Cipher object.


offset - the offset into the input buffer at which the subprime parameter value begins

length - the length of the subprime parameter value



setG(byte[], short, short)

public void setG(byte[] buffer, short offset, short length)


Sets the base parameter value of the key. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input base parameter data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the base parameter value is decrypted using the Cipher object.


DSAKey 161


getP(byte[], short)

offset - the offset into the input buffer at which the base parameter value begins

length - the length of the base parameter value



getP(byte[], short)

public short getP(byte[] buffer, short offset)

Returns the prime parameter value of the key in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).

Parameters:buffer - the output buffer

offset - the offset into the output buffer at which the prime parameter value starts

Returns: the byte length of the prime parameter value returned


• CryptoException.UNINITIALIZED_KEY if the prime parameter has not been successfully initialized using the DSAKey.setP method since the time the initialized state of the key was set to false.

See Also: Key

getQ(byte[], short)

public short getQ(byte[] buffer, short offset)

Returns the subprime parameter value of the key in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the subprime parameter value begins

Returns: the byte length of the subprime parameter value returned


• CryptoException.UNINITIALIZED_KEY if the subprime parameter has not been successfully initialized using the DSAKey.setQ method since the time the initialized state of the key was set to false.

See Also: Key

getG(byte[], short)

public short getG(byte[] buffer, short offset)

Returns the base parameter value of the key in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


javacard.security DSAKey

getG(byte[], short)


offset - the offset into the output buffer at which the base parameter value begins

Returns: the byte length of the base parameter value returned


• CryptoException.UNINITIALIZED_KEY if the base parameter has not been successfully initialized using the DSAKey.setG method since the time the initialized state of the key was set to false.

See Also: Key

DSAKey 163

DSAPrivateKey javacard.security

setX(byte[], short, short)

javacard.security

DSAPrivateKeyDeclarationpublic interface DSAPrivateKey extends PrivateKey, DSAKey

All Superinterfaces: DSAKey, Key, PrivateKey

DescriptionThe DSAPrivateKey interface is used to sign data using the DSA algorithm. An implementation of DSAPrivateKey interface must also implement the DSAKey interface methods.

When all four components of the key (X,P,Q,G) are set, the key is initialized and ready for use.

See Also: DSAPublicKey, KeyBuilder, Signature, KeyEncryption

Methods

setX(byte[], short, short)

public void setX(byte[] buffer, short offset, short length)


Member Summary

Methods short getX(byte[] buffer, short offset)

Returns the value of the key in plain text. void setX(byte[] buffer, short offset, short length)

Sets the value of the key.


Methods inherited from interface DSAKey

getG(byte[], short), getP(byte[], short), getQ(byte[], short), setG(byte[], short, short), setP(byte[], short, short), setQ(byte[], short, short)




javacard.security DSAPrivateKey

getX(byte[], short)

Sets the value of the key. When the base, prime and subprime parameters are initialized and the key value is set, the key is ready for use. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input key data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the key value is decrypted using the Cipher object.


offset - the offset into the input buffer at which the modulus value begins

length - the length of the modulus



getX(byte[], short)

public short getX(byte[] buffer, short offset)

Returns the value of the key in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the key value starts

Returns: the byte length of the key value returned


• CryptoException.UNINITIALIZED_KEY if the value of the key has not been successfully initialized using the DSAPrivateKey.setX method since the time the initialized state of the key was set to false.

See Also: Key

DSAPrivateKey 165

DSAPublicKey javacard.security

setY(byte[], short, short)

javacard.security

DSAPublicKeyDeclarationpublic interface DSAPublicKey extends PublicKey, DSAKey

All Superinterfaces: DSAKey, Key, PublicKey

DescriptionThe DSAPublicKey interface is used to verify signatures on signed data using the DSA algorithm. An implementation of DSAPublicKey interface must also implement the DSAKey interface methods.

When all four components of the key (Y,P,Q,G) are set, the key is initialized and ready for use.

See Also: DSAPrivateKey, KeyBuilder, Signature, KeyEncryption

Methods

setY(byte[], short, short)

public void setY(byte[] buffer, short offset, short length)


Member Summary

Methods short getY(byte[] buffer, short offset)

Returns the value of the key in plain text. void setY(byte[] buffer, short offset, short length)

Sets the value of the key.


Methods inherited from interface DSAKey

getG(byte[], short), getP(byte[], short), getQ(byte[], short), setG(byte[], short, short), setP(byte[], short, short), setQ(byte[], short, short)




javacard.security DSAPublicKey

getY(byte[], short)

Sets the value of the key. When the base, prime and subprime parameters are initialized and the key value is set, the key is ready for use. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input key data is copied into the internal representation.

Note:



offset - the offset into the input buffer at which the key value begins

length - the length of the key value



getY(byte[], short)

public short getY(byte[] buffer, short offset)

Returns the value of the key in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the input buffer at which the key value starts

Returns: the byte length of the key value returned


• CryptoException.UNINITIALIZED_KEY if the value of the key has not been successfully initialized using the DSAPublicKey.setY method since the time the initialized state of the key was set to false.

See Also: Key

DSAPublicKey 167

ECKey javacard.security

getY(byte[], short)

javacard.security

ECKeyDeclarationpublic interface ECKey

All Known Subinterfaces: ECPrivateKey, ECPublicKey

DescriptionThe ECKey interface is the base interface for the EC algorithms private and public key implementations. An EC private key implementation must also implement the ECPrivateKey interface methods. An EC public key implementation must also implement the ECPublicKey interface methods.

The equation of the curves for keys of type TYPE_EC_FP_PUBLIC or TYPE_EC_FP_PRIVATE is y^2 = x^3 + A * x + B. The equation of the curves for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE is y^2 + x * y = x^3 + A * x^2 + B.

The notation used to describe parameters specific to the EC algorithm is based on the naming conventions established in [IEEE P1363].

See Also: ECPublicKey, ECPrivateKey, KeyBuilder, Signature, KeyEncryption, KeyAgreement

Member Summary

Methods short getA(byte[] buffer, short offset)

Returns the first coefficient of the curve of the key. short getB(byte[] buffer, short offset)

Returns the second coefficient of the curve of the key. short getField(byte[] buffer, short offset)

Returns the field specification parameter value of the key. short getG(byte[] buffer, short offset)

Returns the fixed point of the curve. short getK()

Returns the cofactor of the order of the fixed point G of the curve. short getR(byte[] buffer, short offset)

Returns the order of the fixed point G of the curve. void setA(byte[] buffer, short offset, short length)

Sets the first coefficient of the curve of the key. void setB(byte[] buffer, short offset, short length)

Sets the second coefficient of the curve of the key. void setFieldF2M(short e)

Sets the field specification parameter value for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE in the case where the polynomial is a trinomial, of the form x^n + x^e + 1 (where n is the bit length of the key).


javacard.security ECKey

setFieldFP(byte[], short, short)

Methods

setFieldFP(byte[], short, short)

public void setFieldFP(byte[] buffer, short offset, short length)


Sets the field specification parameter value for keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC. The specified value is the prime p corresponding to the field GF(p). The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:



offset - the offset into the input buffer at which the parameter value begins

length - the byte length of the parameter value


• CryptoException.ILLEGAL_VALUE if the input parameter is inconsistent with the key or if input data decryption is required and fails.

• CryptoException.NO_SUCH_ALGORITHM if the key is neither of type TYPE_EC_FP_PUBLIC nor TYPE_EC_FP_PRIVATE.

setFieldF2M(short)

public void setFieldF2M(short e)


void setFieldF2M(short e1, short e2, short e3)Sets the field specification parameter value for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE in the case where the polynomial is a pentanomial, of the form x^n + xê1 + xê2 + xê3 + 1 (where n is the bit length of the key).

void setFieldFP(byte[] buffer, short offset, short length)Sets the field specification parameter value for keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC.

void setG(byte[] buffer, short offset, short length)Sets the fixed point of the curve.

void setK(short K)Sets the cofactor of the order of the fixed point G of the curve.

void setR(byte[] buffer, short offset, short length)Sets the order of the fixed point G of the curve.

Member Summary

ECKey 169


setFieldF2M(short, short, short)

Sets the field specification parameter value for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE in the case where the polynomial is a trinomial, of the form x^n + xê + 1 (where n is the bit length of the key). It is required that n > e > 0.

Parameters:e - the value of the intermediate exponent of the trinomial


• CryptoException.ILLEGAL_VALUE if the input parameter e is not such that 0 < e < n.

• CryptoException.NO_SUCH_ALGORITHM if the key is neither of type TYPE_EC_F2M_PUBLIC nor TYPE_EC_F2M_PRIVATE.

setFieldF2M(short, short, short)

public void setFieldF2M(short e1, short e2, short e3)


Sets the field specification parameter value for keys of type TYPE_EC_F2M_PUBLIC or TYPE_EC_F2M_PRIVATE in the case where the polynomial is a pentanomial, of the form x^n + xê1 + xê2 + xê3 + 1 (where n is the bit length of the key). It is required for all ei where ei = {e1, e2, e3} that n > ei > 0.

Parameters:e1 - the value of the first of the intermediate exponents of the pentanomial

e2 - the value of the second of the intermediate exponent of the pentanomial

e3 - the value of the third of the intermediate exponents


• CryptoException.ILLEGAL_VALUE if the input parameters ei where ei = {e1, e2, e3} are not such that for all ei, n > ei > 0.

• CryptoException.NO_SUCH_ALGORITHM if the key is neither of type TYPE_EC_F2M_PUBLIC nor TYPE_EC_F2M_PRIVATE.

setA(byte[], short, short)

public void setA(byte[] buffer, short offset, short length)


Sets the first coefficient of the curve of the key. For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of A as an integer modulo the field specification parameter p, i.e. an integer in the range 0 to p-1. For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, the bit representation of this value specifies a polynomial with binary coefficients which represents the value of A in the field. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:




setB(byte[], short, short)


offset - the offset into the input buffer at which the coefficient value begins

length - the byte length of the coefficient value



setB(byte[], short, short)

public void setB(byte[] buffer, short offset, short length)


Sets the second coefficient of the curve of the key. For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of B as an integer modulo the field specification parameter p, i.e. an integer in the range 0 to p-1. For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, the bit representation of this value specifies a polynomial with binary coefficients which represents the value of B in the field. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:



offset - the offset into the input buffer at which the coefficient value begins

length - the byte length of the coefficient value



setG(byte[], short, short)

public void setG(byte[] buffer, short offset, short length)


Sets the fixed point of the curve. The point should be specified as per ANSI X9.62. A specific implementation need not support the compressed form, but must support the uncompressed form of the point. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:


ECKey 171


setR(byte[], short, short)


offset - the offset into the input buffer at which the point specification begins

length - the byte length of the point specification


• CryptoException.ILLEGAL_VALUE if the input parameter data format is incorrect or inconsistent with the key length, or if input data decryption is required and fails.

setR(byte[], short, short)

public void setR(byte[] buffer, short offset, short length)


Sets the order of the fixed point G of the curve. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.


offset - the offset into the input buffer at which the order begins

length - the byte length of the order


• CryptoException.ILLEGAL_VALUE if the input parameter data is inconsistent with the key length, or if input data decryption is required and fails.

• Note:


setK(short)

public void setK(short K)

Sets the cofactor of the order of the fixed point G of the curve. The cofactor need not be specified for the key to be initialized. However, the KeyAgreement algorithm type ALG_EC_SVDP_DHC requires that the cofactor, K, be initialized.

Parameters:K - the value of the cofactor

getField(byte[], short)

public short getField(byte[] buffer, short offset)


Returns the field specification parameter value of the key. For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of the prime p corresponding to the field GF(p). For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, it is the value whose bit representation specifies the polynomial with binary coefficients used to define the arithmetic operations in the field GF(2^n) The



getA(byte[], short)

plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the parameter value is to begin

Returns: the byte length of the parameter


• CryptoException.UNINITIALIZED_KEY if the field specification parameter value of the key has not been successfully initialized using the ECKey.setField method since the time the initialized state of the key was set to false.

See Also: Key

getA(byte[], short)

public short getA(byte[] buffer, short offset)


Returns the first coefficient of the curve of the key. For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of A as an integer modulo the field specification parameter p, i.e. an integer in the range 0 to p-1. For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, the bit representation of this value specifies a polynomial with binary coefficients which represents the value of A in the field. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the coefficient value is to begin

Returns: the byte length of the coefficient


• CryptoException.UNINITIALIZED_KEY if the coefficient of the curve of the key has not been successfully initialized using the ECKey.setA method since the time the initialized state of the key was set to false.

See Also: Key

getB(byte[], short)

public short getB(byte[] buffer, short offset)


Returns the second coefficient of the curve of the key. For keys of type TYPE_EC_FP_PRIVATE or TYPE_EC_FP_PUBLIC, this is the value of B as an integer modulo the field specification parameter p, i.e. an integer in the range 0 to p-1. For keys of type TYPE_EC_F2M_PRIVATE or TYPE_EC_F2M_PUBLIC, the bit representation of this value specifies a polynomial with binary coefficients which represents the value of B in the field. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).

ECKey 173


getG(byte[], short)


offset - the offset into the output buffer at which the coefficient value is to begin

Returns: the byte length of the coefficient


• CryptoException.UNINITIALIZED_KEY if the second coefficient of the curve of the key has not been successfully initialized using the ECKey.setB method since the time the initialized state of the key was set to false.

See Also: Key

getG(byte[], short)

public short getG(byte[] buffer, short offset)


Returns the fixed point of the curve. The point is represented in compressed or uncompressed forms as per ANSI X9.62. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the point specification data is to begin

Returns: the byte length of the point specificiation


• CryptoException.UNINITIALIZED_KEY if the fixed point of the curve of the key has not been successfully initialized using the ECKey.setG method since the time the initialized state of the key was set to false.

See Also: Key

getR(byte[], short)

public short getR(byte[] buffer, short offset)


Returns the order of the fixed point G of the curve. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the input buffer at which the order begins

Returns: the byte length of the order


• CryptoException.UNINITIALIZED_KEY if the order of the fixed point G of the curve of the key has not been successfully initialized using the ECKey.setR method since the time the initialized state of the key was set to false.



getK()

See Also: Key

getK()

public short getK()


Returns the cofactor of the order of the fixed point G of the curve.

Returns: the value of the cofactor


• CryptoException.UNINITIALIZED_KEY if the cofactor of the order of the fixed point G of the curve of the key has not been successfully initialized using the ECKey.setK method since the time the initialized state of the key was set to false.

See Also: Key

ECKey 175

ECPrivateKey javacard.security

getK()

javacard.security

ECPrivateKeyDeclarationpublic interface ECPrivateKey extends PrivateKey, ECKey

All Superinterfaces: ECKey, Key, PrivateKey

DescriptionThe ECPrivateKey interface is used to generate signatures on data using the ECDSA (Elliptic Curve Digital Signature Algorithm) and to generate shared secrets using the ECDH (Elliptic Curve Diffie-Hellman) algorithm. An implementation of ECPrivateKey interface must also implement the ECKey interface methods.

When all components of the key (S, A, B, G, R, Field) are set, the key is initialized and ready for use. In addition, the KeyAgreement algorithm type ALG_EC_SVDP_DHC requires that the cofactor, K, be initialized.


See Also: ECPublicKey, KeyBuilder, Signature, KeyEncryption, KeyAgreement

Member Summary

Methods short getS(byte[] buffer, short offset)

Returns the value of the secret key in plaintext form. void setS(byte[] buffer, short offset, short length)

Sets the value of the secret key.


Methods inherited from interface ECKey

getA(byte[], short), getB(byte[], short), getField(byte[], short), getG(byte[], short), getK(), getR(byte[], short), setA(byte[], short, short), setB(byte[], short, short), setFieldF2M(short, short, short), setFieldF2M(short, short, short), setFieldFP(byte[], short, short), setG(byte[], short, short), setK(short), setR(byte[], short, short)




javacard.security ECPrivateKey

setS(byte[], short, short)

Methods

setS(byte[], short, short)

public void setS(byte[] buffer, short offset, short length)


Sets the value of the secret key. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:



offset - the offset into the input buffer at which the secret value

length - the byte length of the secret value



getS(byte[], short)

public short getS(byte[] buffer, short offset)


Returns the value of the secret key in plaintext form. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the input buffer at which the secret value is to begin

Returns: the byte length of the secret value


• CryptoException.UNINITIALIZED_KEY if the value of the secret key has not been successfully initialized using the ECPrivateKey.setS method since the time the initialized state of the key was set to false.

See Also: Key

ECPrivateKey 177

ECPublicKey javacard.security

getS(byte[], short)

javacard.security

ECPublicKeyDeclarationpublic interface ECPublicKey extends PublicKey, ECKey

All Superinterfaces: ECKey, Key, PublicKey

DescriptionThe ECPublicKey interface is used to verify signatures on signed data using the ECDSA algorithm and to generate shared secrets using the ECDH algorithm. An implementation of ECPublicKey interface must also implement the ECKey interface methods.

When all components of the key (W, A, B, G, R, Field) are set, the key is initialized and ready for use.


See Also: ECPrivateKey, KeyBuilder, Signature, KeyEncryption, KeyAgreement

Member Summary

Methods short getW(byte[] buffer, short offset)

Returns the point of the curve comprising the public key in plaintext form. void setW(byte[] buffer, short offset, short length)

Sets the point of the curve comprising the public key.


Methods inherited from interface ECKey

getA(byte[], short), getB(byte[], short), getField(byte[], short), getG(byte[], short), getK(), getR(byte[], short), setA(byte[], short, short), setB(byte[], short, short), setFieldF2M(short, short, short), setFieldF2M(short, short, short), setFieldFP(byte[], short, short), setG(byte[], short, short), setK(short), setR(byte[], short, short)




javacard.security ECPublicKey

setW(byte[], short, short)

Methods

setW(byte[], short, short)

public void setW(byte[] buffer, short offset, short length)


Sets the point of the curve comprising the public key. The point should be specified as per ANSI X9.62. A specific implementation need not support the compressed form, but must support the uncompressed form of the point. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input parameter data is copied into the internal representation.

Note:



offset - the offset into the input buffer at which the point specification begins

length - the byte length of the point specification



getW(byte[], short)

public short getW(byte[] buffer, short offset)


Returns the point of the curve comprising the public key in plaintext form. The point is represented in compressed or uncompressed forms as per ANSI X9.62. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the point specification data is to begin

Returns: the byte length of the point specificiation


• CryptoException.UNINITIALIZED_KEY if the point of the curve comprising the public key has not been successfully initialized using the ECPublicKey.setW method since the time the initialized state of the key was set to false.

See Also: Key

ECPublicKey 179

Key javacard.security

isInitialized()

javacard.security

KeyDeclarationpublic interface Key

All Known Subinterfaces: AESKey, DESKey, DSAPrivateKey, DSAPublicKey, ECPrivateKey, ECPublicKey, PrivateKey, PublicKey, RSAPrivateCrtKey, RSAPrivateKey, RSAPublicKey, SecretKey

DescriptionThe Key interface is the base interface for all keys.

A Key object sets its initialized state to true only when all the associated set methods have been invoked at least once since the time the initialized state was set to false.

A newly created Key object sets its initialized state to false. Invocation of the clearKey() method sets the initialized state to false. A key with transient key data sets its initialized state to false on the associated clear events.

See Also: KeyBuilder

Methods

isInitialized()

public boolean isInitialized()

Reports the initialized state of the key. Keys must be initialized before being used.

A Key object sets its initialized state to true only when all the associated set methods have been invoked at least once since the time the initialized state was set to false.

A newly created Key object sets its initialized state to false. Invocation of the clearKey() method sets the initialized state to false. A key with transient key data sets its initialized state to false on the associated clear events.

Member Summary

Methods void clearKey()

Clears the key and sets its initialized state to false. short getSize()

Returns the key size in number of bits. byte getType()

Returns the key interface type. boolean isInitialized()

Reports the initialized state of the key.


javacard.security Key

clearKey()

Returns: true if the key has been initialized.

clearKey()

public void clearKey()

Clears the key and sets its initialized state to false.

getType()

public byte getType()

Returns the key interface type.

Returns: the key interface type. Valid codes listed in TYPE.. constants. See KeyBuilder.TYPE_DES_TRANSIENT_RESET

See Also: KeyBuilder

getSize()

public short getSize()

Returns the key size in number of bits.

Returns: the key size in number of bits.

Key 181

KeyAgreement javacard.security

getSize()

javacard.security

KeyAgreementDeclarationpublic abstract class KeyAgreement java.lang.Object

|+--javacard.security.KeyAgreement

DescriptionThe KeyAgreement class is the base class for key agreement algorithms such as Diffie-Hellman and EC Diffie-Hellman [IEEE P1363]. Implementations of KeyAgreement algorithms must extend this class and implement all the abstract methods. A tear or card reset event resets an initialized KeyAgreement object to the state it was in when previously initialized via a call to init().

Member Summary

Fieldsstatic byte ALG_EC_SVDP_DH

Elliptic curve secret value deriviation primitive, Diffie-Hellman version, as per [IEEE P1363].

static byte ALG_EC_SVDP_DHCElliptic curve secret value deriviation primitive, Diffie-Hellman version, with cofactor multiplication, as per [IEEE P1363].

Constructorsprotected KeyAgreement()

Protected constructor.

Methodsabstract short generateSecret(byte[] publicData, short publicOffset, short

publicLength, byte[] secret, short secretOffset)Generates the secret data as per the requested algorithm using the PrivateKey specified during initialisation and the public key data provided.

abstract byte getAlgorithm()Gets the KeyAgreement algorithm.

static KeyAgreement getInstance(byte algorithm, boolean externalAccess)Creates a KeyAgreement object instance of the selected algorithm.

abstract void init(PrivateKey privKey)Initializes the object with the given private key.



equals(Object)


javacard.security KeyAgreement

ALG_EC_SVDP_DH

Fields

ALG_EC_SVDP_DH

public static final byte ALG_EC_SVDP_DH

Elliptic curve secret value deriviation primitive, Diffie-Hellman version, as per [IEEE P1363].

ALG_EC_SVDP_DHC

public static final byte ALG_EC_SVDP_DHC

Elliptic curve secret value deriviation primitive, Diffie-Hellman version, with cofactor multiplication, as per [IEEE P1363]. (output value is to be equal to that from ALG_EC_SVDP_DH)

Constructors

KeyAgreement()

protected KeyAgreement()

Protected constructor.

Methods


public static final javacard.security.KeyAgreement getInstance(byte algorithm,



Creates a KeyAgreement object instance of the selected algorithm.

Parameters:algorithm - the desired key agreement algorithm. Valid codes listed in ALG_ .. constants above e.g. ALG_EC_SVDP_DH

externalAccess - if true indicates that the instance will be shared among multiple applet instances and that the KeyAgreement instance will also be accessed (via a Shareable interface) when the owner of the KeyAgreement instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.

Returns: the KeyAgreement object instance of the requested algorithm.



init(PrivateKey)

public abstract void init(javacard.security.PrivateKey privKey)


KeyAgreement 183


getAlgorithm()

Initializes the object with the given private key.

Parameters:privKey - the private key


• CryptoException.ILLEGAL_VALUE if the input key type is inconsistent with the KeyAgreement algorithm, e.g. if the KeyAgreement algorithm is ALG_EC_SVDP_DH and the key type is TYPE_RSA_PRIVATE.

• CryptoException.UNINITIALIZED_KEY if privKey is uninitialized, or if the KeyAgreement algorithm is set to ALG_EC_SVDP_DHC and the cofactor, K, has not been successfully initialized since the time the initialized state of the key was set to false.

getAlgorithm()


Gets the KeyAgreement algorithm.


generateSecret(byte[], short, short, byte[], short)

public abstract short generateSecret(byte[] publicData, short publicOffset,

short publicLength, byte[] secret, short secretOffset)


Generates the secret data as per the requested algorithm using the PrivateKey specified during initialisation and the public key data provided. Note that in the case of the algorithms ALG_EC_SVDP_DH and ALG_EC_SVDP_DHC the public key data provided should be the public elliptic curve point of the second party in the protocol, specified as per ANSI X9.62. A specific implementation need not support the compressed form, but must support the uncompressed form of the point.

Parameters:publicData - buffer holding the public data of the second party

publicOffset - offset into the publicData buffer at which the data begins

publicLength - byte length of the public data

secret - buffer to hold the secret output

secretOffset - offset into the secret array at which to start writing the secret

Returns: byte length of the secret


• CryptoException.ILLEGAL_VALUE if the publicData data format is incorrect or inconsistent with the key length.


javacard.security KeyBuilder


javacard.security

KeyBuilderDeclarationpublic class KeyBuilder java.lang.Object

|+--javacard.security.KeyBuilder

DescriptionThe KeyBuilder class is a key object factory.

Member Summary

Fieldsstatic short LENGTH_AES_128

AES Key Length LENGTH_AES_128 = 128.static short LENGTH_AES_192

AES Key Length LENGTH_AES_192 = 192.static short LENGTH_AES_256

AES Key Length LENGTH_AES_256 = 256.static short LENGTH_DES

DES Key Length LENGTH_DES = 64.static short LENGTH_DES3_2KEY

DES Key Length LENGTH_DES3_2KEY = 128.static short LENGTH_DES3_3KEY

DES Key Length LENGTH_DES3_3KEY = 192.static short LENGTH_DSA_1024

DSA Key Length LENGTH_DSA_1024 = 1024.static short LENGTH_DSA_512

DSA Key Length LENGTH_DSA_512 = 512.static short LENGTH_DSA_768

DSA Key Length LENGTH_DSA_768 = 768.static short LENGTH_EC_F2M_113

EC Key Length LENGTH_EC_F2M_113 = 113.static short LENGTH_EC_F2M_131



EC Key Length LENGTH_EC_F2M_193 = 193.static short LENGTH_EC_FP_112

EC Key Length LENGTH_EC_FP_112 = 112.static short LENGTH_EC_FP_128



EC Key Length LENGTH_EC_FP_192 = 192.

KeyBuilder 185

KeyBuilder javacard.security


static short LENGTH_RSA_1024RSA Key Length LENGTH_RSA_1024 = 1024.









static byte TYPE_AESKey object which implements interface type AESKey with persistent key data.

static byte TYPE_AES_TRANSIENT_DESELECTKey object which implements interface type AESKey with CLEAR_ON_DESELECT transient key data.

static byte TYPE_AES_TRANSIENT_RESETKey object which implements interface type AESKey with CLEAR_ON_RESET transient key data.

static byte TYPE_DESKey object which implements interface type DESKey with persistent key data.

static byte TYPE_DES_TRANSIENT_DESELECTKey object which implements interface type DESKey with CLEAR_ON_DESELECT transient key data.

static byte TYPE_DES_TRANSIENT_RESETKey object which implements interface type DESKey with CLEAR_ON_RESET transient key data.

static byte TYPE_DSA_PRIVATEKey object which implements the interface type DSAPrivateKey for the DSA algorithm.

static byte TYPE_DSA_PUBLICKey object which implements the interface type DSAPublicKey for the DSA algorithm.

static byte TYPE_EC_F2M_PRIVATEKey object which implements the interface type ECPrivateKey for EC operations over fields of characteristic 2 with polynomial basis.

static byte TYPE_EC_F2M_PUBLICKey object which implements the interface type ECPublicKey for EC operations over fields of characteristic 2 with polynomial basis.

static byte TYPE_EC_FP_PRIVATEKey object which implements the interface type ECPrivateKey for EC operations over large prime fields.

static byte TYPE_EC_FP_PUBLICKey object which implements the interface type ECPublicKey for EC operations over large prime fields.

static byte TYPE_RSA_CRT_PRIVATEKey object which implements interface type RSAPrivateCrtKey which uses Chinese Remainder Theorem.

Member Summary



TYPE_DES_TRANSIENT_RESET

Fields

TYPE_DES_TRANSIENT_RESET

public static final byte TYPE_DES_TRANSIENT_RESET

Key object which implements interface type DESKey with CLEAR_ON_RESET transient key data.

This Key object implicitly performs a clearKey() on power on or card reset.

TYPE_DES_TRANSIENT_DESELECT

public static final byte TYPE_DES_TRANSIENT_DESELECT

Key object which implements interface type DESKey with CLEAR_ON_DESELECT transient key data.

This Key object implicitly performs a clearKey() on power on, card reset and applet deselection.

TYPE_DES

public static final byte TYPE_DES

Key object which implements interface type DESKey with persistent key data.

TYPE_RSA_PUBLIC

public static final byte TYPE_RSA_PUBLIC

Key object which implements interface type RSAPublicKey.

TYPE_RSA_PRIVATE

public static final byte TYPE_RSA_PRIVATE

Key object which implements interface type RSAPrivateKey which uses modulus/exponent form.

static byte TYPE_RSA_PRIVATEKey object which implements interface type RSAPrivateKey which uses modulus/exponent form.

static byte TYPE_RSA_PUBLICKey object which implements interface type RSAPublicKey.

Methodsstatic Key buildKey(byte keyType, short keyLength, boolean

keyEncryption)Creates uninitialized cryptographic keys for signature and cipher algorithms.



equals(Object)

Member Summary

KeyBuilder 187


TYPE_RSA_CRT_PRIVATE

TYPE_RSA_CRT_PRIVATE

public static final byte TYPE_RSA_CRT_PRIVATE

Key object which implements interface type RSAPrivateCrtKey which uses Chinese Remainder Theorem.

TYPE_DSA_PUBLIC

public static final byte TYPE_DSA_PUBLIC

Key object which implements the interface type DSAPublicKey for the DSA algorithm.

TYPE_DSA_PRIVATE

public static final byte TYPE_DSA_PRIVATE

Key object which implements the interface type DSAPrivateKey for the DSA algorithm.

TYPE_EC_F2M_PUBLIC

public static final byte TYPE_EC_F2M_PUBLIC

Key object which implements the interface type ECPublicKey for EC operations over fields of characteristic 2 with polynomial basis.

TYPE_EC_F2M_PRIVATE

public static final byte TYPE_EC_F2M_PRIVATE

Key object which implements the interface type ECPrivateKey for EC operations over fields of characteristic 2 with polynomial basis.

TYPE_EC_FP_PUBLIC

public static final byte TYPE_EC_FP_PUBLIC

Key object which implements the interface type ECPublicKey for EC operations over large prime fields.

TYPE_EC_FP_PRIVATE

public static final byte TYPE_EC_FP_PRIVATE

Key object which implements the interface type ECPrivateKey for EC operations over large prime fields.

TYPE_AES_TRANSIENT_RESET

public static final byte TYPE_AES_TRANSIENT_RESET

Key object which implements interface type AESKey with CLEAR_ON_RESET transient key data.

This Key object implicitly performs a clearKey() on power on or card reset.

TYPE_AES_TRANSIENT_DESELECT

public static final byte TYPE_AES_TRANSIENT_DESELECT

Key object which implements interface type AESKey with CLEAR_ON_DESELECT transient key data.

This Key object implicitly performs a clearKey() on power on, card reset and applet deselection.



TYPE_AES

TYPE_AES

public static final byte TYPE_AES

Key object which implements interface type AESKey with persistent key data.

LENGTH_DES

public static final short LENGTH_DES

DES Key Length LENGTH_DES = 64.

LENGTH_DES3_2KEY

public static final short LENGTH_DES3_2KEY

DES Key Length LENGTH_DES3_2KEY = 128.

LENGTH_DES3_3KEY

public static final short LENGTH_DES3_3KEY

DES Key Length LENGTH_DES3_3KEY = 192.

LENGTH_RSA_512

public static final short LENGTH_RSA_512

RSA Key Length LENGTH_RSA_512 = 512.

LENGTH_RSA_736



LENGTH_RSA_768



LENGTH_RSA_896



LENGTH_RSA_1024



LENGTH_RSA_1280



KeyBuilder 189


LENGTH_RSA_1536

LENGTH_RSA_1536



LENGTH_RSA_1984



LENGTH_RSA_2048



LENGTH_DSA_512

public static final short LENGTH_DSA_512

DSA Key Length LENGTH_DSA_512 = 512.

LENGTH_DSA_768



LENGTH_DSA_1024



LENGTH_EC_FP_112

public static final short LENGTH_EC_FP_112


LENGTH_EC_F2M_113

public static final short LENGTH_EC_F2M_113

EC Key Length LENGTH_EC_F2M_113 = 113.

LENGTH_EC_FP_128



LENGTH_EC_F2M_131





LENGTH_EC_FP_160

LENGTH_EC_FP_160



LENGTH_EC_F2M_163



LENGTH_EC_FP_192



LENGTH_EC_F2M_193



LENGTH_AES_128

public static final short LENGTH_AES_128

AES Key Length LENGTH_AES_128 = 128.

LENGTH_AES_192



LENGTH_AES_256



Methods

buildKey(byte, short, boolean)

public static javacard.security.Key buildKey(byte keyType, short keyLength,

boolean keyEncryption)


Creates uninitialized cryptographic keys for signature and cipher algorithms. Only instances created by this method may be the key objects used to initialize instances of Signature, Cipher and KeyPair. Note that the object returned must be cast to their appropriate key type interface.

Parameters:keyType - the type of key to be generated. Valid codes listed in TYPE.. constants. See TYPE_DES_TRANSIENT_RESET

KeyBuilder 191



keyLength - the key size in bits. The valid key bit lengths are key type dependent. Some common key lengths are listed above above in the LENGTH_.. constants. See LENGTH_DES

keyEncryption - if true this boolean requests a key implementation which implements the javacardx.crypto.KeyEncryption interface. The key implementation returned may implement the javacardx.crypto.KeyEncryption interface even when this parameter is false.

Returns: the key object instance of the requested key type, length and encrypted access.


• CryptoException.NO_SUCH_ALGORITHM if the requested algorithm associated with the specified type, size of key and key encryption interface is not supported.


javacard.security KeyPair


javacard.security

KeyPairDeclarationpublic final class KeyPair java.lang.Object

|+--javacard.security.KeyPair

DescriptionThis class is a container for a key pair (a public key and a private key). It does not enforce any security, and, when initialized, should be treated like a PrivateKey.

In addition, this class features a key generation method.

See Also: PublicKey, PrivateKey

Member Summary

Fieldsstatic byte ALG_DSA

KeyPair object containing a DSA key pair.static byte ALG_EC_F2M

KeyPair object containing an EC key pair for EC operations over fields of characteristic 2 with polynomial basis.

static byte ALG_EC_FPKeyPair object containing an EC key pair for EC operations over large prime fields

static byte ALG_RSAKeyPair object containing a RSA key pair.

static byte ALG_RSA_CRTKeyPair object containing a RSA key pair with private key in its Chinese Remainder Theorem form.

ConstructorsKeyPair(byte algorithm, short keyLength)

Constructs a KeyPair instance for the specified algorithm and keylength. The encapsulated keys are uninitialized.

KeyPair(PublicKey publicKey, PrivateKey privateKey)Constructs a new KeyPair object containing the specified public key and private key.

Methods void genKeyPair()

(Re)Initializes the key objects encapsulated in this KeyPair instance with new key values.

PrivateKey getPrivate()Returns a reference to the private key component of this KeyPair object.

PublicKey getPublic()Returns a reference to the public key component of this KeyPair object.

KeyPair 193

KeyPair javacard.security

ALG_RSA

Fields

ALG_RSA

public static final byte ALG_RSA

KeyPair object containing a RSA key pair.

ALG_RSA_CRT

public static final byte ALG_RSA_CRT

KeyPair object containing a RSA key pair with private key in its Chinese Remainder Theorem form.

ALG_DSA

public static final byte ALG_DSA

KeyPair object containing a DSA key pair.

ALG_EC_F2M

public static final byte ALG_EC_F2M

KeyPair object containing an EC key pair for EC operations over fields of characteristic 2 with polynomial basis.

ALG_EC_FP

public static final byte ALG_EC_FP

KeyPair object containing an EC key pair for EC operations over large prime fields

Constructors

KeyPair(byte, short)

public KeyPair(byte algorithm, short keyLength)


Constructs a KeyPair instance for the specified algorithm and keylength. The encapsulated keys are uninitialized. To initialize the KeyPair instance use the genKeyPair() method.

The encapsulated key objects are of the specified keyLength size and implement the appropriate Key interface associated with the specified algorithm (example - RSAPublicKey interface for the public key and RSAPrivateKey interface for the private key within an ALG_RSA key pair).



equals(Object)


javacard.security KeyPair

KeyPair(PublicKey, PrivateKey)

Notes:

• The key objects encapsulated in the generated KeyPair object need not support the KeyEncryption interface.

Parameters:algorithm - the type of algorithm whose key pair needs to be generated. Valid codes listed in ALG_.. constants above. See ALG_RSA

keyLength - the key size in bits. The valid key bit lengths are key type dependent. See the KeyBuilder class.


• CryptoException.NO_SUCH_ALGORITHM if the requested algorithm associated with the specified type, size of key is not supported.


KeyPair(PublicKey, PrivateKey)

public KeyPair(javacard.security.PublicKey publicKey, javacard.security.

PrivateKey privateKey)


Constructs a new KeyPair object containing the specified public key and private key.

Note that this constructor only stores references to the public and private key components in the generated KeyPair object. It does not throw an exception if the key parameter objects are uninitialized.

Parameters:publicKey - the public key.

privateKey - the private key.


• CryptoException.ILLEGAL_VALUE if the input parameter key objects are inconsistent with each other - i.e mismatched algorithm, size etc.

• CryptoException.NO_SUCH_ALGORITHM if the algorithm associated with the specified type, size of key is not supported.

Methods

genKeyPair()

public final void genKeyPair()


(Re)Initializes the key objects encapsulated in this KeyPair instance with new key values. The initialized public and private key objects encapsulated in this instance will then be suitable for use with the Signature, Cipher and KeyAgreement objects. An internal secure random number generator is used during new key pair generation.

Notes:

• For the RSA algorithm, if the exponent value in the public key object is pre-initialized, it will be

KeyPair 195


getPublic()

retained; Otherwise a default value of 65537 will be used.

• For the DSA algorithm, if the p, q and g parameters of the public key object are pre-initialized, it will be retained; Otherwise default precomputed parameter sets will be used. The required default precomputed values are listed in Appendix B of Java Cryptography Architecture API Specification & Reference document.

• For the EC case, if the Field, A, B, G and R parameters of the key pair are pre-initialized, then they will be retained. Otherwise default pre-specified values MAY be used (e.g. WAP predefined curves), since computation of random generic EC keys is infeasible on the smart card platform.

• If the time taken to generate the key values is excessive, the implementation may automatically request additional APDU processing time from the CAD.


• CryptoException.ILLEGAL_VALUE if the exponent value parameter in RSA or the p,q,g parameter set in DSA is invalid.

See Also: APDU, Signature, Cipher

getPublic()

public javacard.security.PublicKey getPublic()

Returns a reference to the public key component of this KeyPair object.

Returns: a reference to the public key.

getPrivate()

public javacard.security.PrivateKey getPrivate()

Returns a reference to the private key component of this KeyPair object.

Returns: a reference to the private key.


javacard.security MessageDigest

getPrivate()

javacard.security

MessageDigestDeclarationpublic abstract class MessageDigest java.lang.Object

|+--javacard.security.MessageDigest

DescriptionThe MessageDigest class is the base class for hashing algorithms. Implementations of MessageDigest algorithms must extend this class and implement all the abstract methods.

A tear or card reset event resets a MessageDigest object to the initial state (state upon construction).


Member Summary

Fieldsstatic byte ALG_MD5

Message Digest algorithm MD5.static byte ALG_RIPEMD160

Message Digest algorithm RIPE MD-160.static byte ALG_SHA

Message Digest algorithm SHA.

Constructorsprotected MessageDigest()



outBuff, short outOffset)Generates a hash of all/last input data.

abstract byte getAlgorithm()Gets the Message digest algorithm.

static MessageDigest getInstance(byte algorithm, boolean externalAccess)Creates a MessageDigest object instance of the selected algorithm.

abstract byte getLength()Returns the byte length of the hash.

abstract void reset()Resets the MessageDigest object to the initial state for further use.

abstract void update(byte[] inBuff, short inOffset, short inLength)Accumulates a hash of the input data.

MessageDigest 197

MessageDigest javacard.security

ALG_SHA

Fields

ALG_SHA

public static final byte ALG_SHA

Message Digest algorithm SHA.

ALG_MD5

public static final byte ALG_MD5

Message Digest algorithm MD5.

ALG_RIPEMD160

public static final byte ALG_RIPEMD160

Message Digest algorithm RIPE MD-160.

Constructors

MessageDigest()

protected MessageDigest()


Methods


public static final javacard.security.MessageDigest getInstance(byte algorithm,



Creates a MessageDigest object instance of the selected algorithm.

Parameters:algorithm - the desired message digest algorithm. Valid codes listed in ALG_ .. constants above e.g. ALG_SHA

externalAccess - true indicates that the instance will be shared among multiple applet instances and that the MessageDigest instance will also be accessed (via a Shareable. interface) when the owner of the MessageDigest instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.



equals(Object)


javacard.security MessageDigest

getAlgorithm()

Returns: the MessageDigest object instance of the requested algorithm.



getAlgorithm()


Gets the Message digest algorithm.


getLength()

public abstract byte getLength()

Returns the byte length of the hash.

Returns: hash length




Generates a hash of all/last input data. Completes and returns the hash computation after performing final operations such as padding. The MessageDigest object is reset to the initial state after this call is made.


Parameters:inBuff - the input buffer of data to be hashed

inOffset - the offset into the input buffer at which to begin hash generation

inLength - the byte length to hash


outOffset - the offset into the output buffer where the resulting hash value begins

Returns: number of bytes of hash output in outBuff



Accumulates a hash of the input data. This method requires temporary storage of intermediate results. In addition, if the input data length is not block aligned (multiple of block size) then additional internal storage may be allocated at this time to store a partial input data block. This may result in additional resource consumption and/or slow performance. This method should only be used if all the input data required for the hash is not available in one byte array. If all of the input data required for the hash is located in a single byte array, use of the doFinal() method is recommended. The doFinal() method must be called to complete processing of input data accumulated by one or more calls to the update() method.

Note:


MessageDigest 199


reset()

Parameters:inBuff - the input buffer of data to be hashed

inOffset - the offset into the input buffer at which to begin hash generation

inLength - the byte length to hash

See Also: doFinal(byte[], short, short, byte[], short)

reset()

public abstract void reset()

Resets the MessageDigest object to the initial state for further use.


javacard.security PrivateKey

reset()

javacard.security

PrivateKeyDeclarationpublic interface PrivateKey extends Key

All Superinterfaces: Key

All Known Subinterfaces: DSAPrivateKey, ECPrivateKey, RSAPrivateCrtKey, RSAPrivateKey

DescriptionThe PrivateKey interface is the base interface for private keys used in asymmetric algorithms.




PrivateKey 201

PublicKey javacard.security

reset()

javacard.security

PublicKeyDeclarationpublic interface PublicKey extends Key


All Known Subinterfaces: DSAPublicKey, ECPublicKey, RSAPublicKey

DescriptionThe PublicKey interface is the base interface for public keys used in asymmetric algorithms.





javacard.security RandomData

ALG_PSEUDO_RANDOM

javacard.security

RandomDataDeclarationpublic abstract class RandomData java.lang.Object

|+--javacard.security.RandomData

DescriptionThe RandomData abstract class is the base class for random number generation. Implementations of RandomData algorithms must extend this class and implement all the abstract methods.

Fields

ALG_PSEUDO_RANDOM

public static final byte ALG_PSEUDO_RANDOM

Member Summary

Fieldsstatic byte ALG_PSEUDO_RANDOM

Utility pseudo random number generation algorithms.static byte ALG_SECURE_RANDOM

Cryptographically secure random number generation algorithms.

Constructorsprotected RandomData()

Protected constructor for subclassing.

Methodsabstract void generateData(byte[] buffer, short offset, short length)

Generates random data.static RandomData getInstance(byte algorithm)

Creates a RandomData instance of the selected algorithm.abstract void setSeed(byte[] buffer, short offset, short length)

Seeds the random data generator.



equals(Object)

RandomData 203

RandomData javacard.security

ALG_SECURE_RANDOM

Utility pseudo random number generation algorithms. The random number sequence generated by this algorithm need not be the same even if seeded with the same seed data.

Even if a transaction is in progress, the update of the internal state shall not participate in the transaction.

ALG_SECURE_RANDOM

public static final byte ALG_SECURE_RANDOM

Cryptographically secure random number generation algorithms.

Constructors

RandomData()

protected RandomData()

Protected constructor for subclassing.

Methods

getInstance(byte)

public static final javacard.security.RandomData getInstance(byte algorithm)


Creates a RandomData instance of the selected algorithm. The pseudo random RandomData instance’s seed is initialized to a internal default value.

Parameters:algorithm - the desired random number algorithm. Valid codes listed in ALG_ .. constants above. See ALG_PSEUDO_RANDOM

Returns: the RandomData object instance of the requested algorithm.


• CryptoException.NO_SUCH_ALGORITHM if the requested algorithm is not supported.

generateData(byte[], short, short)

public abstract void generateData(byte[] buffer, short offset, short length)


Generates random data.


offset - the offset into the output buffer

length - the length of random data to generate


• CryptoException.ILLEGAL_VALUE if the length parameter is zero.


javacard.security RandomData

setSeed(byte[], short, short)


public abstract void setSeed(byte[] buffer, short offset, short length)

Seeds the random data generator.


offset - the offset into the input buffer

length - the length of the seed data

RandomData 205

RSAPrivateCrtKey javacard.security


javacard.security

RSAPrivateCrtKeyDeclarationpublic interface RSAPrivateCrtKey extends PrivateKey

All Superinterfaces: Key, PrivateKey

DescriptionThe RSAPrivateCrtKey interface is used to sign data using the RSA algorithm in its Chinese Remainder Theorem form. It may also be used by the javacardx.crypto.Cipher class to encrypt/decrypt messages.

Let S = md mod n, where m is the data to be signed, d is the private key exponent, and n is private key modulus composed of two prime numbers p and q. The following names are used in the initializer methods in this interface:

P, the prime factor p Q, the prime factor q. PQ = q-1 mod p DP1 = d mod (p - 1) DQ1 = d mod (q - 1)

When all five components (P,Q,PQ,DP1,DQ1) of the key are set, the key is initialized and ready for use.

See Also: RSAPrivateKey, RSAPublicKey, KeyBuilder, Signature, Cipher, KeyEncryption

Member Summary

Methods short getDP1(byte[] buffer, short offset)

Returns the value of the DP1 parameter in plain text. short getDQ1(byte[] buffer, short offset)

Returns the value of the DQ1 parameter in plain text. short getP(byte[] buffer, short offset)

Returns the value of the P parameter in plain text. short getPQ(byte[] buffer, short offset)

Returns the value of the PQ parameter in plain text. short getQ(byte[] buffer, short offset)

Returns the value of the Q parameter in plain text. void setDP1(byte[] buffer, short offset, short length)

Sets the value of the DP1 parameter. void setDQ1(byte[] buffer, short offset, short length)

Sets the value of the DQ1 parameter. void setP(byte[] buffer, short offset, short length)

Sets the value of the P parameter. void setPQ(byte[] buffer, short offset, short length)

Sets the value of the PQ parameter.


javacard.security RSAPrivateCrtKey


Methods


public void setP(byte[] buffer, short offset, short length)


Sets the value of the P parameter. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input P parameter data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the P parameter value is decrypted using the Cipher object.



length - the length of the parameter




public void setQ(byte[] buffer, short offset, short length)


Sets the value of the Q parameter. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input Q parameter data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the Q parameter value is decrypted

void setQ(byte[] buffer, short offset, short length)Sets the value of the Q parameter.




Member Summary

RSAPrivateCrtKey 207


setDP1(byte[], short, short)

using the Cipher object.






setDP1(byte[], short, short)

public void setDP1(byte[] buffer, short offset, short length)


Sets the value of the DP1 parameter. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input DP1 parameter data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the DP1 parameter value is decrypted using the Cipher object.






setDQ1(byte[], short, short)

public void setDQ1(byte[] buffer, short offset, short length)


Sets the value of the DQ1 parameter. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input DQ1 parameter data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the DQ1 parameter value is decrypted using the Cipher object.





setPQ(byte[], short, short)




setPQ(byte[], short, short)

public void setPQ(byte[] buffer, short offset, short length)


Sets the value of the PQ parameter. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input PQ parameter data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the PQ parameter value is decrypted using the Cipher object.






getP(byte[], short)

public short getP(byte[] buffer, short offset)

Returns the value of the P parameter in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the parameter value begins

Returns: the byte length of the P parameter value returned


• CryptoException.UNINITIALIZED_KEY if the value of P parameter has not been successfully initialized using the RSAPrivateCrtKey.setP method since the time the initialized state of the key was set to false.

See Also: Key

getQ(byte[], short)

public short getQ(byte[] buffer, short offset)



getDP1(byte[], short)

Returns the value of the Q parameter in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).



Returns: the byte length of the Q parameter value returned


• CryptoException.UNINITIALIZED_KEY if the value of Q parameter has not been successfully initialized using the RSAPrivateCrtKey.setQ method since the time the initialized state of the key was set to false.

See Also: Key

getDP1(byte[], short)

public short getDP1(byte[] buffer, short offset)

Returns the value of the DP1 parameter in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).



Returns: the byte length of the DP1 parameter value returned


• CryptoException.UNINITIALIZED_KEY if the value of DP1 parameter has not been successfully initialized using the RSAPrivateCrtKey.setDP1 method since the time the initialized state of the key was set to false.

See Also: Key

getDQ1(byte[], short)

public short getDQ1(byte[] buffer, short offset)

Returns the value of the DQ1 parameter in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).



Returns: the byte length of the DQ1 parameter value returned


• CryptoException.UNINITIALIZED_KEY if the value of DQ1 parameter has not been successfully initialized using the RSAPrivateCrtKey.setDQ1 method since the time the initialized state of the key was set to false.



getPQ(byte[], short)

See Also: Key

getPQ(byte[], short)

public short getPQ(byte[] buffer, short offset)

Returns the value of the PQ parameter in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).



Returns: the byte length of the PQ parameter value returned


• CryptoException.UNINITIALIZED_KEY if the value of PQ parameter has not been successfully initialized using the RSAPrivateCrtKey.setPQ method since the time the initialized state of the key was set to false.

See Also: Key


RSAPrivateKey javacard.security

setModulus(byte[], short, short)

javacard.security

RSAPrivateKeyDeclarationpublic interface RSAPrivateKey extends PrivateKey

All Superinterfaces: Key, PrivateKey

DescriptionThe RSAPrivateKey class is used to sign data using the RSA algorithm in its modulus/exponent form. It may also be used by the javacardx.crypto.Cipher class to encrypt/decrypt messages.

When both the modulus and exponent of the key are set, the key is initialized and ready for use.

See Also: RSAPublicKey, RSAPrivateCrtKey, KeyBuilder, Signature, Cipher, KeyEncryption

Methods


public void setModulus(byte[] buffer, short offset, short length)


Member Summary

Methods short getExponent(byte[] buffer, short offset)

Returns the private exponent value of the key in plain text. short getModulus(byte[] buffer, short offset)

Returns the modulus value of the key in plain text. void setExponent(byte[] buffer, short offset, short length)

Sets the private exponent value of the key. void setModulus(byte[] buffer, short offset, short length)

Sets the modulus value of the key.





javacard.security RSAPrivateKey

setExponent(byte[], short, short)

Sets the modulus value of the key. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input modulus data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the modulus value is decrypted using the Cipher object.



length - the length of the modulus


• CryptoException.ILLEGAL_VALUE if the input modulus data length is inconsistent with the implementation or if input data decryption is required and fails.


public void setExponent(byte[] buffer, short offset, short length)


Sets the private exponent value of the key. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input exponent data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the exponent value is decrypted using the Cipher object.


offset - the offset into the input buffer at which the exponent value begins

length - the length of the exponent


• CryptoException.ILLEGAL_VALUE if the input exponent data length is inconsistent with the implementation or if input data decryption is required and fails.

getModulus(byte[], short)

public short getModulus(byte[] buffer, short offset)

Returns the modulus value of the key in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the modulus value starts

RSAPrivateKey 213


getExponent(byte[], short)

Returns: the byte length of the modulus value returned


• CryptoException.UNINITIALIZED_KEY if the modulus value of the key has not been successfully initialized using the RSAPrivateKey.setModulus method since the time the initialized state of the key was set to false.

See Also: Key


public short getExponent(byte[] buffer, short offset)

Returns the private exponent value of the key in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the exponent value begins

Returns: the byte length of the private exponent value returned


• CryptoException.UNINITIALIZED_KEY if the private exponent value of the key has not been successfully initialized using the RSAPrivateKey.setExponent method since the time the initialized state of the key was set to false.

See Also: Key


javacard.security RSAPublicKey


javacard.security

RSAPublicKeyDeclarationpublic interface RSAPublicKey extends PublicKey

All Superinterfaces: Key, PublicKey

DescriptionThe RSAPublicKey is used to verify signatures on signed data using the RSA algorithm. It may also used by the javacardx.crypto.Cipher class to encrypt/decrypt messages.

When both the modulus and exponent of the key are set, the key is initialized and ready for use.

See Also: RSAPrivateKey, RSAPrivateCrtKey, KeyBuilder, Signature, Cipher, KeyEncryption

Methods


public void setModulus(byte[] buffer, short offset, short length)


Member Summary

Methods short getExponent(byte[] buffer, short offset)

Returns the public exponent value of the key in plain text. short getModulus(byte[] buffer, short offset)

Returns the modulus value of the key in plain text. void setExponent(byte[] buffer, short offset, short length)

Sets the public exponent value of the key. void setModulus(byte[] buffer, short offset, short length)

Sets the modulus value of the key.




RSAPublicKey 215

RSAPublicKey javacard.security


Sets the modulus value of the key. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input modulus data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the modulus value is decrypted using the Cipher object.



length - the byte length of the modulus


• CryptoException.ILLEGAL_VALUE if the input modulus data length is inconsistent with the implementation or if input data decryption is required and fails.


public void setExponent(byte[] buffer, short offset, short length)


Sets the public exponent value of the key. The plaintext data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte). Input exponent data is copied into the internal representation.

Note:

• If the key object implements the javacardx.crypto.KeyEncryption interface and the Cipher object specified via setKeyCipher() is not null, the exponent value is decrypted using the Cipher object.


offset - the offset into the input buffer at which the exponent value begins

length - the byte length of the exponent


• CryptoException.ILLEGAL_VALUE if the input exponent data length is inconsistent with the implementation or if input data decryption is required and fails.

getModulus(byte[], short)

public short getModulus(byte[] buffer, short offset)

Returns the modulus value of the key in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the input buffer at which the modulus value starts


javacard.security RSAPublicKey


Returns: the byte length of the modulus value returned


• CryptoException.UNINITIALIZED_KEY if the modulus value of the key has not been successfully initialized using the RSAPublicKey.setModulus method since the time the initialized state of the key was set to false.

See Also: Key


public short getExponent(byte[] buffer, short offset)

Returns the public exponent value of the key in plain text. The data format is big-endian and right-aligned (the least significant bit is the least significant bit of last byte).


offset - the offset into the output buffer at which the exponent value begins

Returns: the byte length of the public exponent returned


• CryptoException.UNINITIALIZED_KEY if the public exponent value of the key has not been successfully initialized using the RSAPublicKey.setExponent method since the time the initialized state of the key was set to false.

See Also: Key

RSAPublicKey 217

SecretKey javacard.security


javacard.security

SecretKeyDeclarationpublic interface SecretKey extends Key


All Known Subinterfaces: AESKey, DESKey

DescriptionThe SecretKey class is the base interface for keys used in symmetric algorithms (e.g. DES).





javacard.security Signature


javacard.security

SignatureDeclarationpublic abstract class Signature java.lang.Object

|+--javacard.security.Signature

DescriptionThe Signature class is the base class for Signature algorithms. Implementations of Signature algorithms must extend this class and implement all the abstract methods.

The term “pad” is used in the public key signature algorithms below to refer to all the operations specified in the referenced scheme to transform the message digest into the encryption block size.

A tear or card reset event resets an initialized Signature object to the state it was in when previously initialized via a call to init(). For algorithms which support keys with transient key data sets, such as DES, triple DES and AES, the Signature object key becomes uninitialized on clear events associated with the Key object used to initialize the Signature object.


Note:

• On a tear or card reset event, the DES and triple DES algorithms in outer CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init(Key, byte, byte[], short, short) method.

Member Summary

Fieldsstatic byte ALG_AES_MAC_128_NOPAD

Signature algorithm ALG_AES_MAC_128_NOPAD generates a 16 byte MAC using AES with blocksize 128 in CBC mode. This algorithm does not pad input data.

static byte ALG_DES_MAC4_ISO9797_1_M2_ALG3Signature algorithm ALG_DES_MAC4_ISO9797_1_M2_ALG3 generates a 4 byte MAC using a 2-key DES3 key according to ISO9797-1 MAC algorithm 3 with method 2 (also EMV’96, EMV’2000). Input data is padded using method 2 and the data is processed as described in MAC Algorithm 3 of the ISO 9797-1 specification.

static byte ALG_DES_MAC4_ISO9797_M1Signature algorithm ALG_DES_MAC4_ISO9797_M1 generates a 4 byte MAC (most significant 4 bytes of encrypted block) using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 1 scheme.

static byte ALG_DES_MAC4_ISO9797_M2Signature algorithm ALG_DES_MAC4_ISO9797_M2 generates a 4 byte MAC (most significant 4 bytes of encrypted block) using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme.

Signature 219

Signature javacard.security


static byte ALG_DES_MAC4_NOPADSignature algorithm ALG_DES_MAC4_NOPAD generates a 4 byte MAC (most significant 4 bytes of encrypted block) using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. This algorithm does not pad input data.

static byte ALG_DES_MAC4_PKCS5Signature algorithm ALG_DES_MAC4_PKCS5 generates a 4 byte MAC (most significant 4 bytes of encrypted block) using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the PKCS#5 scheme.

static byte ALG_DES_MAC8_ISO9797_1_M2_ALG3Signature algorithm ALG_DES_MAC8_ISO9797_1_M2_ALG3 generates a 8 byte MAC using a 2-key DES3 key according to ISO9797-1 MAC algorithm 3 with method 2 (also EMV’96, EMV’2000). Input data is padded using method 2 and the data is processed as described in MAC Algorithm 3 of the ISO 9797-1 specification.

static byte ALG_DES_MAC8_ISO9797_M1Signature algorithm ALG_DES_MAC8_ISO9797_M1 generates a 8 byte MAC using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 1 scheme.

static byte ALG_DES_MAC8_ISO9797_M2Signature algorithm ALG_DES_MAC8_ISO9797_M2 generates a 8 byte MAC using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme.

static byte ALG_DES_MAC8_NOPADSignature algorithm ALG_DES_MAC_8_NOPAD generates a 8 byte MAC using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. This algorithm does not pad input data.

static byte ALG_DES_MAC8_PKCS5Signature algorithm ALG_DES_MAC8_PKCS5 generates a 8 byte MAC using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the PKCS#5 scheme.

static byte ALG_DSA_SHASignature algorithm ALG_DSA_SHA signs/verifies the 20 byte SHA digest using DSA.

static byte ALG_ECDSA_SHASignature algorithm ALG_ECDSA_SHA signs/verifies the 20 byte SHA digest using ECDSA.

static byte ALG_RSA_MD5_PKCS1Signature algorithm ALG_RSA_MD5_PKCS1 encrypts the 16 byte MD5 digest using RSA. The digest is padded according to the PKCS#1 (v1.5) scheme.

static byte ALG_RSA_MD5_PKCS1_PSSSignature algorithm ALG_RSA_MD5_PKCS1_PSS encrypts the 16 byte MD5 digest using RSA. The digest is padded according to the PKCS#1-PSS scheme (IEEE 1363-2000).

static byte ALG_RSA_MD5_RFC2409Signature algorithm ALG_RSA_MD5_RFC2409 encrypts the 16 byte MD5 digest using RSA. The digest is padded according to the RFC2409 scheme.

static byte ALG_RSA_RIPEMD160_ISO9796Signature algorithm ALG_RSA_RIPEMD160_ISO9796 encrypts the 20 byte RIPE MD-160 digest using RSA. The digest is padded according to the ISO 9796 scheme.

static byte ALG_RSA_RIPEMD160_PKCS1Signature algorithm ALG_RSA_RIPEMD160_PKCS1 encrypts the 20 byte RIPE MD-160 digest using RSA. The digest is padded according to the PKCS#1 (v1.5) scheme.

Member Summary




static byte ALG_RSA_RIPEMD160_PKCS1_PSSSignature algorithm ALG_RSA_RIPEMD160_PKCS1_PSS encrypts the 20 byte RIPE MD-160 digest using RSA. The digest is padded according to the PKCS#1-PSS scheme (IEEE 1363-2000).

static byte ALG_RSA_SHA_ISO9796Signature algorithm ALG_RSA_SHA_ISO9796 encrypts the 20 byte SHA digest using RSA. The digest is padded according to the ISO 9796-2 (EMV’96, EMV’2000) scheme.

static byte ALG_RSA_SHA_PKCS1Signature algorithm ALG_RSA_SHA_PKCS1 encrypts the 20 byte SHA digest using RSA. The digest is padded according to the PKCS#1 (v1.5) scheme.

static byte ALG_RSA_SHA_PKCS1_PSSSignature algorithm ALG_RSA_SHA_PKCS1_PSS encrypts the 20 byte SHA-1 digest using RSA. The digest is padded according to the PKCS#1-PSS scheme (IEEE 1363-2000).

static byte ALG_RSA_SHA_RFC2409Signature algorithm ALG_RSA_SHA_RFC2409 encrypts the 20 byte SHA digest using RSA. The digest is padded according to the RFC2409 scheme.

static byte MODE_SIGNUsed in init() methods to indicate signature sign mode.

static byte MODE_VERIFYUsed in init() methods to indicate signature verify mode.

Constructorsprotected Signature()


Methodsabstract byte getAlgorithm()

Gets the Signature algorithm.static Signature getInstance(byte algorithm, boolean externalAccess)

Creates a Signature object instance of the selected algorithm.abstract short getLength()

Returns the byte length of the signature data.abstract void init(Key theKey, byte theMode)

Initializes the Signature object with the appropriate Key.abstract void init(Key theKey, byte theMode, byte[] bArray, short bOff,

short bLen)Initializes the Signature object with the appropriate Key and algorithm specific parameters.

abstract short sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset)

Generates the signature of all/last input data.abstract void update(byte[] inBuff, short inOffset, short inLength)

Accumulates a signature of the input data.abstract boolean verify(byte[] inBuff, short inOffset, short inLength, byte[]

sigBuff, short sigOffset, short sigLength)Verifies the signature of all/last input data against the passed in signature.

Member Summary

Signature 221


ALG_DES_MAC4_NOPAD

Fields

ALG_DES_MAC4_NOPAD

public static final byte ALG_DES_MAC4_NOPAD

Signature algorithm ALG_DES_MAC4_NOPAD generates a 4 byte MAC (most significant 4 bytes of encrypted block) using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. This algorithm does not pad input data. If the input data is not (8 byte) block aligned it throws CryptoException with the reason code ILLEGAL_USE.

ALG_DES_MAC8_NOPAD

public static final byte ALG_DES_MAC8_NOPAD

Signature algorithm ALG_DES_MAC_8_NOPAD generates a 8 byte MAC using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. This algorithm does not pad input data. If the input data is not (8 byte) block aligned it throws CryptoException with the reason code ILLEGAL_USE.

Note:

• This algorithm must not be implemented if export restrictions apply.

ALG_DES_MAC4_ISO9797_M1

public static final byte ALG_DES_MAC4_ISO9797_M1

Signature algorithm ALG_DES_MAC4_ISO9797_M1 generates a 4 byte MAC (most significant 4 bytes of encrypted block) using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 1 scheme.



Signature algorithm ALG_DES_MAC8_ISO9797_M1 generates a 8 byte MAC using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 1 scheme.

Note:




Signature algorithm ALG_DES_MAC4_ISO9797_M2 generates a 4 byte MAC (most significant 4 bytes of encrypted block) using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme.



equals(Object)






Signature algorithm ALG_DES_MAC8_ISO9797_M2 generates a 8 byte MAC using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme.

Note:


ALG_DES_MAC4_PKCS5

public static final byte ALG_DES_MAC4_PKCS5

Signature algorithm ALG_DES_MAC4_PKCS5 generates a 4 byte MAC (most significant 4 bytes of encrypted block) using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the PKCS#5 scheme.

ALG_DES_MAC8_PKCS5

public static final byte ALG_DES_MAC8_PKCS5

Signature algorithm ALG_DES_MAC8_PKCS5 generates a 8 byte MAC using DES or triple DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the PKCS#5 scheme.

Note:


ALG_RSA_SHA_ISO9796

public static final byte ALG_RSA_SHA_ISO9796

Signature algorithm ALG_RSA_SHA_ISO9796 encrypts the 20 byte SHA digest using RSA. The digest is padded according to the ISO 9796-2 (EMV’96, EMV’2000) scheme.

Note:

• This algorithm does not support message recovery.

ALG_RSA_SHA_PKCS1

public static final byte ALG_RSA_SHA_PKCS1

Signature algorithm ALG_RSA_SHA_PKCS1 encrypts the 20 byte SHA digest using RSA. The digest is padded according to the PKCS#1 (v1.5) scheme.

Note:

• The encryption block(EB) during signing is built as follows: EB = 00 || 01 || PS || 00 || T :: where T is the DER encoding of : digestInfo ::= SEQUENCE { digestAlgorithm AlgorithmIdentifier of SHA-1, digest OCTET STRING } :: PS is an octet string of length k-3-||T|| with value FF. The length of PS must be at least 8 octets.

Signature 223


ALG_RSA_MD5_PKCS1

:: k is the RSA modulus size. DER encoded SHA-1 AlgorithmIdentifier = 30 21 30 09 06 05 2B 0E 03 02 1A 05 00 04 14.

ALG_RSA_MD5_PKCS1

public static final byte ALG_RSA_MD5_PKCS1

Signature algorithm ALG_RSA_MD5_PKCS1 encrypts the 16 byte MD5 digest using RSA. The digest is padded according to the PKCS#1 (v1.5) scheme.

Note:

• The encryption block(EB) during signing is built as follows: < EB = 00 || 01 || PS || 00 || T :: where T is the DER encoding of : digestInfo ::= SEQUENCE { digestAlgorithm AlgorithmIdentifier of MD5, digest OCTET STRING } :: PS is an octet string of length k-3-||T|| with value FF. The length of PS must be at least 8 octets. :: k is the RSA modulus size. DER encoded MD5 AlgorithmIdentifier = 30 20 30 0C 06 08 2A 86 48 86 F7 0D 02 05 05 00 04 10.

ALG_RSA_RIPEMD160_ISO9796

public static final byte ALG_RSA_RIPEMD160_ISO9796

Signature algorithm ALG_RSA_RIPEMD160_ISO9796 encrypts the 20 byte RIPE MD-160 digest using RSA. The digest is padded according to the ISO 9796 scheme.

ALG_RSA_RIPEMD160_PKCS1

public static final byte ALG_RSA_RIPEMD160_PKCS1

Signature algorithm ALG_RSA_RIPEMD160_PKCS1 encrypts the 20 byte RIPE MD-160 digest using RSA. The digest is padded according to the PKCS#1 (v1.5) scheme.

Note:

• The encryption block(EB) during signing is built as follows: < EB = 00 || 01 || PS || 00 || T :: where T is the DER encoding of : digestInfo ::= SEQUENCE { digestAlgorithm AlgorithmIdentifier of RIPEMD160, digest OCTET STRING } :: PS is an octet string of length k-3-||T|| with value FF. The length of PS must be at least 8 octets. :: k is the RSA modulus size.

ALG_DSA_SHA

public static final byte ALG_DSA_SHA



ALG_RSA_SHA_RFC2409

Signature algorithm ALG_DSA_SHA signs/verifies the 20 byte SHA digest using DSA.

ALG_RSA_SHA_RFC2409

public static final byte ALG_RSA_SHA_RFC2409

Signature algorithm ALG_RSA_SHA_RFC2409 encrypts the 20 byte SHA digest using RSA. The digest is padded according to the RFC2409 scheme.

ALG_RSA_MD5_RFC2409

public static final byte ALG_RSA_MD5_RFC2409

Signature algorithm ALG_RSA_MD5_RFC2409 encrypts the 16 byte MD5 digest using RSA. The digest is padded according to the RFC2409 scheme.

ALG_ECDSA_SHA

public static final byte ALG_ECDSA_SHA

Signature algorithm ALG_ECDSA_SHA signs/verifies the 20 byte SHA digest using ECDSA.

ALG_AES_MAC_128_NOPAD

public static final byte ALG_AES_MAC_128_NOPAD

Signature algorithm ALG_AES_MAC_128_NOPAD generates a 16 byte MAC using AES with blocksize 128 in CBC mode. This algorithm does not pad input data. If the input data is not (8 byte) block aligned it throws CryptoException with the reason code ILLEGAL_USE.

ALG_DES_MAC4_ISO9797_1_M2_ALG3

public static final byte ALG_DES_MAC4_ISO9797_1_M2_ALG3

Signature algorithm ALG_DES_MAC4_ISO9797_1_M2_ALG3 generates a 4 byte MAC using a 2-key DES3 key according to ISO9797-1 MAC algorithm 3 with method 2 (also EMV’96, EMV’2000). Input data is padded using method 2 and the data is processed as described in MAC Algorithm 3 of the ISO 9797-1 specification. The left key block of the triple DES key is used as a single DES key(K) and the right key block of the triple DES key is used as a single DES Key (K’) during MAC processing. The final result is truncated to 4 bytes as described in ISO9797-1.

ALG_DES_MAC8_ISO9797_1_M2_ALG3

public static final byte ALG_DES_MAC8_ISO9797_1_M2_ALG3

Signature algorithm ALG_DES_MAC8_ISO9797_1_M2_ALG3 generates a 8 byte MAC using a 2-key DES3 key according to ISO9797-1 MAC algorithm 3 with method 2 (also EMV’96, EMV’2000). Input data is padded using method 2 and the data is processed as described in MAC Algorithm 3 of the ISO 9797-1 specification. The left key block of the triple DES key is used as a single DES key(K) and the right key block of the triple DES key is used as a single DES Key (K’) during MAC processing. The final result is truncated to 8 bytes as described in ISO9797-1.

ALG_RSA_SHA_PKCS1_PSS

public static final byte ALG_RSA_SHA_PKCS1_PSS

Signature 225


ALG_RSA_MD5_PKCS1_PSS

Signature algorithm ALG_RSA_SHA_PKCS1_PSS encrypts the 20 byte SHA-1 digest using RSA. The digest is padded according to the PKCS#1-PSS scheme (IEEE 1363-2000).

ALG_RSA_MD5_PKCS1_PSS

public static final byte ALG_RSA_MD5_PKCS1_PSS

Signature algorithm ALG_RSA_MD5_PKCS1_PSS encrypts the 16 byte MD5 digest using RSA. The digest is padded according to the PKCS#1-PSS scheme (IEEE 1363-2000).

ALG_RSA_RIPEMD160_PKCS1_PSS

public static final byte ALG_RSA_RIPEMD160_PKCS1_PSS

Signature algorithm ALG_RSA_RIPEMD160_PKCS1_PSS encrypts the 20 byte RIPE MD-160 digest using RSA. The digest is padded according to the PKCS#1-PSS scheme (IEEE 1363-2000).

MODE_SIGN

public static final byte MODE_SIGN

Used in init() methods to indicate signature sign mode.

MODE_VERIFY

public static final byte MODE_VERIFY

Used in init() methods to indicate signature verify mode.

Constructors

Signature()

protected Signature()


Methods


public static final javacard.security.Signature getInstance(byte algorithm,



Creates a Signature object instance of the selected algorithm.

Parameters:algorithm - the desired Signature algorithm. Valid codes listed in ALG_ .. constants above e.g. ALG_DES_MAC4_NOPAD

externalAccess - true indicates that the instance will be shared among multiple applet instances and that the Signature instance will also be accessed (via a Shareable interface) when the owner of the Signature instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.



init(Key, byte)

Returns: the Signature object instance of the requested algorithm.



init(Key, byte)

public abstract void init(javacard.security.Key theKey, byte theMode)


Initializes the Signature object with the appropriate Key. This method should be used for algorithms which do not need initialization parameters or use default parameter values.

init() must be used to update the Signature object with a new key. If the Key object is modified after invoking the init() method, the behavior of the update(), sign(), and verify() methods is unspecified.

Note:

• DES and triple DES algorithms in CBC mode will use 0 for initial vector(IV) if this method is used.

Parameters:theKey - the key object to use for signing or verifying.

theMode - one of MODE_SIGN or MODE_VERIFY


• CryptoException.ILLEGAL_VALUE if theMode option is an undefined value or if the Key is inconsistent with theMode or with the Signature implementation.

• CryptoException.UNINITIALIZED_KEY if theKey instance is uninitialized.

init(Key, byte, byte[], short, short)

public abstract void init(javacard.security.Key theKey, byte theMode, byte[] bArray,

short bOff, short bLen)


Initializes the Signature object with the appropriate Key and algorithm specific parameters.

init() must be used to update the Signature object with a new key. If the Key object is modified after invoking the init() method, the behavior of the update(), sign(), and verify() methods is unspecified.

Note:

• DES and triple DES algorithms in outer CBC mode expect an 8 byte parameter value for the initial vector(IV) in bArray.

• RSA and DSA algorithms throw CryptoException.ILLEGAL_VALUE.

Parameters:theKey - the key object to use for signing.

theMode - one of MODE_SIGN or MODE_VERIFY

bArray - byte array containing algorithm specific initialization info.

Signature 227


getAlgorithm()




• CryptoException.ILLEGAL_VALUE if theMode option is an undefined value or if a byte array parameter option is not supported by the algorithm or if the bLen is an incorrect byte length for the algorithm specific data or if the Key is inconsistent with theMode or with the Signature implementation.


getAlgorithm()


Gets the Signature algorithm.


getLength()

public abstract short getLength()


Returns the byte length of the signature data.

Returns: the byte length of the signature data.


• CryptoException.INVALID_INIT if this Signature object is not initialized.

• CryptoException.UNINITIALIZED_KEY if key not initialized.




Accumulates a signature of the input data. This method requires temporary storage of intermediate results. In addition, if the input data length is not block aligned (multiple of block size) then additional internal storage may be allocated at this time to store a partial input data block. This may result in additional resource consumption and/or slow performance. This method should only be used if all the input data required for signing/verifying is not available in one byte array. If all of the input data required for signing/verifying is located in a single byte array, use of the sign() or verify() method is recommended. The sign() or verify() method must be called to complete processing of input data accumulated by one or more calls to the update() method.

Note:


Parameters:inBuff - the input buffer of data to be signed

inOffset - the offset into the input buffer at which to begin signature generation

inLength - the byte length to sign



sign(byte[], short, short, byte[], short)



• CryptoException.INVALID_INIT if this Signature object is not initialized.

See Also: sign(byte[], short, short, byte[], short), verify(byte[], short, short, byte[], short, short)

sign(byte[], short, short, byte[], short)

public abstract short sign(byte[] inBuff, short inOffset, short inLength,

byte[] sigBuff, short sigOffset)


Generates the signature of all/last input data.

A call to this method also resets this Signature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to sign another message. In addition, note that the initial vector(IV) used in DES algorithms will be reset to 0.

Note:

• DES and triple DES algorithms in outer CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init(Key, byte, byte[], short, short) method.


Parameters:inBuff - the input buffer of data to be signed



sigBuff - the output buffer to store signature data

sigOffset - the offset into sigBuff at which to begin signature data

Returns: number of bytes of signature output in sigBuff



• CryptoException.INVALID_INIT if this Signature object is not initialized or initialized for signature verify mode.

• CryptoException.ILLEGAL_USE if this Signature algorithm does not pad the message and the message is not block aligned or the total input message length is 0.

verify(byte[], short, short, byte[], short, short)

public abstract boolean verify(byte[] inBuff, short inOffset, short inLength,

byte[] sigBuff, short sigOffset, short sigLength)


Verifies the signature of all/last input data against the passed in signature.

Signature 229


verify(byte[], short, short, byte[], short, short)

A call to this method also resets this Signature object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to verify another message. In addition, note that the initial vector(IV) used in DES algorithms will be reset to 0.

Note:


Parameters:inBuff - the input buffer of data to be verified



sigBuff - the input buffer containing signature data

sigOffset - the offset into sigBuff where signature data begins.

sigLength - the byte length of the signature data

Returns: true if signature verifies false otherwise.



• CryptoException.INVALID_INIT if this Signature object is not initialized or initialized for signature sign mode.

• CryptoException.ILLEGAL_USE if this Signature algorithm does not pad the message and the message is not block aligned or the total input message length is 0.


Package

javacardx.cryptoDescriptionExtension package that contains functionality, which may be subject to export controls, for implementing a security and cryptography framework on Java Card. Classes that contain security and cryptography functionality that are not subject to export control restrictions are contained in the package javacard.security.

The javacardx.crypto package contains the Cipher class and the KeyEncryption interface. Cipher provides methods for encrypting and decrypting messages. KeyEncryption provides functionality that allows keys to be updated in a secure end-to-end fashion.

Class Summary

Interfaces

KeyEncryption KeyEncryption interface defines the methods used to enable encrypted key data access to a key implementation.

Classes

Cipher The Cipher class is the abstract base class for Cipher algorithms.

javacardx.crypto 231

Cipher javacardx.crypto

javacardx.crypto

CipherDeclarationpublic abstract class Cipher java.lang.Object

|+--javacardx.crypto.Cipher

DescriptionThe Cipher class is the abstract base class for Cipher algorithms. Implementations of Cipher algorithms must extend this class and implement all the abstract methods.

The term “pad” is used in the public key cipher algorithms below to refer to all the operations specified in the referenced scheme to transform the message block into the cipher block size.

The asymmetric key algorithms encrypt using either a public key (to cipher) or a private key (to sign). In addition they decrypt using the either a private key (to decipher) or a public key (to verify).

A tear or card reset event resets an initialized Cipher object to the state it was in when previously initialized via a call to init(). For algorithms which support keys with transient key data sets, such as DES, triple DES and AES, the Cipher object key becomes uninitialized on clear events associated with the Key object used to initialize the Cipher object.


Note:

• On a tear or card reset event, the DES and triple DES algorithms in outer CBC mode reset the initial vector(IV) to 0. The initial vector(IV) can be re-initialized using the init(Key, byte, byte[], short, short) method.

Member Summary

Fieldsstatic byte ALG_AES_BLOCK_128_CBC_NOPAD

Cipher algorithm ALG_AES_BLOCK_128_CBC_NOPAD provides a cipher using AES with block size 128 in CBC mode. This algorithm does not pad input data.

static byte ALG_AES_BLOCK_128_ECB_NOPADCipher algorithm ALG_AES_BLOCK_128_ECB_NOPAD provides a cipher using AES with block size 128 in ECB mode. This algorithm does not pad input data.

static byte ALG_DES_CBC_ISO9797_M1Cipher algorithm ALG_DES_CBC_ISO9797_M1 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 1 scheme.

static byte ALG_DES_CBC_ISO9797_M2Cipher algorithm ALG_DES_CBC_ISO9797_M2 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme.


javacardx.crypto Cipher

static byte ALG_DES_CBC_NOPADCipher algorithm ALG_DES_CBC_NOPAD provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. This algorithm does not pad input data.

static byte ALG_DES_CBC_PKCS5Cipher algorithm ALG_DES_CBC_PKCS5 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the PKCS#5 scheme.

static byte ALG_DES_ECB_ISO9797_M1Cipher algorithm ALG_DES_ECB_ISO9797_M1 provides a cipher using DES in ECB mode. Input data is padded according to the ISO 9797 method 1 scheme.

static byte ALG_DES_ECB_ISO9797_M2Cipher algorithm ALG_DES_ECB_ISO9797_M2 provides a cipher using DES in ECB mode. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme.

static byte ALG_DES_ECB_NOPADCipher algorithm ALG_DES_ECB_NOPAD provides a cipher using DES in ECB mode. This algorithm does not pad input data.

static byte ALG_DES_ECB_PKCS5Cipher algorithm ALG_DES_ECB_PKCS5 provides a cipher using DES in ECB mode. Input data is padded according to the PKCS#5 scheme.

static byte ALG_RSA_ISO14888Cipher algorithm ALG_RSA_ISO14888 provides a cipher using RSA. Input data is padded according to the ISO 14888 scheme.

static byte ALG_RSA_ISO9796This Cipher algorithm ALG_RSA_ISO9796 should not be used.

static byte ALG_RSA_NOPADCipher algorithm ALG_RSA_NOPAD provides a cipher using RSA. This algorithm does not pad input data.

static byte ALG_RSA_PKCS1Cipher algorithm ALG_RSA_PKCS1 provides a cipher using RSA. Input data is padded according to the PKCS#1 (v1.5) scheme.

static byte ALG_RSA_PKCS1_OAEPCipher algorithm ALG_RSA_PKCS1_OAEP provides a cipher using RSA. Input data is padded according to the PKCS#1-OAEP scheme (IEEE 1361-2000).

static byte MODE_DECRYPTUsed in init() methods to indicate decryption mode.

static byte MODE_ENCRYPTUsed in init() methods to indicate encryption mode.

Constructorsprotected Cipher()



outBuff, short outOffset)Generates encrypted/decrypted output from all/last input data.

abstract byte getAlgorithm()Gets the Cipher algorithm.

static Cipher getInstance(byte algorithm, boolean externalAccess)Creates a Cipher object instance of the selected algorithm.

abstract void init(javacard.security.Key theKey, byte theMode)Initializes the Cipher object with the appropriate Key.

Member Summary

Cipher 233


ALG_DES_CBC_NOPAD

Fields

ALG_DES_CBC_NOPAD

public static final byte ALG_DES_CBC_NOPAD

Cipher algorithm ALG_DES_CBC_NOPAD provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. This algorithm does not pad input data. If the input data is not (8 byte) block aligned it throws CryptoException with the reason code ILLEGAL_USE.

ALG_DES_CBC_ISO9797_M1

public static final byte ALG_DES_CBC_ISO9797_M1

Cipher algorithm ALG_DES_CBC_ISO9797_M1 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 1 scheme.

ALG_DES_CBC_ISO9797_M2

public static final byte ALG_DES_CBC_ISO9797_M2

Cipher algorithm ALG_DES_CBC_ISO9797_M2 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme.

ALG_DES_CBC_PKCS5

public static final byte ALG_DES_CBC_PKCS5

Cipher algorithm ALG_DES_CBC_PKCS5 provides a cipher using DES in CBC mode. This algorithm uses outer CBC for triple DES. Input data is padded according to the PKCS#5 scheme.

ALG_DES_ECB_NOPAD

public static final byte ALG_DES_ECB_NOPAD

abstract void init(javacard.security.Key theKey, byte theMode, byte[] bArray, short bOff, short bLen)

Initializes the Cipher object with the appropriate Key and algorithm specific parameters.

abstract short update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)

Generates encrypted/decrypted output from input data.



equals(Object)

Member Summary



ALG_DES_ECB_ISO9797_M1

Cipher algorithm ALG_DES_ECB_NOPAD provides a cipher using DES in ECB mode. This algorithm does not pad input data. If the input data is not (8 byte) block aligned it throws CryptoException with the reason code ILLEGAL_USE.


public static final byte ALG_DES_ECB_ISO9797_M1

Cipher algorithm ALG_DES_ECB_ISO9797_M1 provides a cipher using DES in ECB mode. Input data is padded according to the ISO 9797 method 1 scheme.


public static final byte ALG_DES_ECB_ISO9797_M2

Cipher algorithm ALG_DES_ECB_ISO9797_M2 provides a cipher using DES in ECB mode. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme.

ALG_DES_ECB_PKCS5

public static final byte ALG_DES_ECB_PKCS5

Cipher algorithm ALG_DES_ECB_PKCS5 provides a cipher using DES in ECB mode. Input data is padded according to the PKCS#5 scheme.

ALG_RSA_ISO14888

public static final byte ALG_RSA_ISO14888

Cipher algorithm ALG_RSA_ISO14888 provides a cipher using RSA. Input data is padded according to the ISO 14888 scheme.

ALG_RSA_PKCS1

public static final byte ALG_RSA_PKCS1

Cipher algorithm ALG_RSA_PKCS1 provides a cipher using RSA. Input data is padded according to the PKCS#1 (v1.5) scheme.

Note:

• This algorithm is only suitable for messages of limited length. The total number of input bytes processed may not be more than k-11, where k is the RSA key’s modulus size in bytes.

• The encryption block(EB) during encryption with a Public key is built as follows: EB = 00 || 02 || PS || 00 || M :: M (input bytes) is the plaintext message :: PS is an octet string of length k-3-||M|| of pseudo random nonzero octets. The length of PS must be at least 8 octets. :: k is the RSA modulus size.

• The encryption block(EB) during encryption with a Private key (used to compute signatures when the message digest is computed off-card) is built as follows: EB = 00 || 01 || PS || 00 || D :: D (input bytes) is the DER encoding of the hash computed elsewhere with an algorithm ID prepended if appropriate :: PS is an octet string of length k-3-||D|| with value FF. The length of PS must be at least 8 octets.

Cipher 235


ALG_RSA_ISO9796

:: k is the RSA modulus size.

ALG_RSA_ISO9796

public static final byte ALG_RSA_ISO9796

Deprecated. This Cipher algorithm ALG_RSA_ISO9796 should not be used. The ISO 9796 algorithm was withdrawn by ISO in July 2000.

ALG_RSA_NOPAD

public static final byte ALG_RSA_NOPAD

Cipher algorithm ALG_RSA_NOPAD provides a cipher using RSA. This algorithm does not pad input data. If the input data is bounded by incorrect padding bytes while using RSAPrivateCrtKey, incorrect output may result. If the input data is not block aligned it throws CryptoException with the reason code ILLEGAL_USE.

ALG_AES_BLOCK_128_CBC_NOPAD

public static final byte ALG_AES_BLOCK_128_CBC_NOPAD

Cipher algorithm ALG_AES_BLOCK_128_CBC_NOPAD provides a cipher using AES with block size 128 in CBC mode. This algorithm does not pad input data. If the input data is not block aligned it throws CryptoException with the reason code ILLEGAL_USE.

ALG_AES_BLOCK_128_ECB_NOPAD

public static final byte ALG_AES_BLOCK_128_ECB_NOPAD

Cipher algorithm ALG_AES_BLOCK_128_ECB_NOPAD provides a cipher using AES with block size 128 in ECB mode. This algorithm does not pad input data. If the input data is not block aligned it throws CryptoException with the reason code ILLEGAL_USE.

ALG_RSA_PKCS1_OAEP

public static final byte ALG_RSA_PKCS1_OAEP

Cipher algorithm ALG_RSA_PKCS1_OAEP provides a cipher using RSA. Input data is padded according to the PKCS#1-OAEP scheme (IEEE 1361-2000).

MODE_DECRYPT

public static final byte MODE_DECRYPT

Used in init() methods to indicate decryption mode.

MODE_ENCRYPT

public static final byte MODE_ENCRYPT

Used in init() methods to indicate encryption mode.



Cipher()

Constructors

Cipher()

protected Cipher()


Methods


public static final javacardx.crypto.Cipher getInstance(byte algorithm,



Creates a Cipher object instance of the selected algorithm.

Parameters:algorithm - the desired Cipher algorithm. Valid codes listed in ALG_ .. constants above e.g ALG_DES_CBC_NOPAD

externalAccess - true indicates that the instance will be shared among multiple applet instances and that the Cipher instance will also be accessed (via a Shareable interface) when the owner of the Cipher instance is not the currently selected applet. If true the implementation must not allocate CLEAR_ON_DESELECT transient space for internal data.

Returns: the Cipher object instance of the requested algorithm.


• CryptoException.NO_SUCH_ALGORITHM if the requested algorithm is not supported or shared access mode is not supported.

init(Key, byte)

public abstract void init(javacard.security.Key theKey, byte theMode)


Initializes the Cipher object with the appropriate Key. This method should be used for algorithms which do not need initialization parameters or use default parameter values.

init() must be used to update the Cipher object with a new key. If the Key object is modified after invoking the init() method, the behavior of the update() and doFinal() methods is unspecified.

Note:

• DES and triple DES algorithms in CBC mode will use 0 for initial vector(IV) if this method is used.

Parameters:theKey - the key object to use for encrypting or decrypting.

theMode - one of MODE_DECRYPT or MODE_ENCRYPT


Cipher 237



• CryptoException.ILLEGAL_VALUE if theMode option is an undefined value or if the Key is inconsistent with the Cipher implementation.



public abstract void init(javacard.security.Key theKey, byte theMode, byte[] bArray,

short bOff, short bLen)


Initializes the Cipher object with the appropriate Key and algorithm specific parameters.

init() must be used to update the Cipher object with a new key. If the Key object is modified after invoking the init() method, the behavior of the update() and doFinal()

Note:

• DES and triple DES algorithms in outer CBC mode expect an 8 byte parameter value for the initial vector(IV) in bArray.

• RSA and DSA algorithms throw CryptoException.ILLEGAL_VALUE.

Parameters:theKey - the key object to use for encrypting or decrypting.

theMode - one of MODE_DECRYPT or MODE_ENCRYPT

bArray - byte array containing algorithm specific initialization info.




• CryptoException.ILLEGAL_VALUE if theMode option is an undefined value or if a byte array parameter option is not supported by the algorithm or if the bLen is an incorrect byte length for the algorithm specific data or if the Key is inconsistent with the Cipher implementation.


getAlgorithm()


Gets the Cipher algorithm.






Generates encrypted/decrypted output from all/last input data. This method must be invoked to complete a cipher operation. This method processes any remaining input data buffered by one or more calls to the update() method as well as input data supplied in the inBuff parameter.

A call to this method also resets this Cipher object to the state it was in when previously initialized via a call to init(). That is, the object is reset and available to encrypt or decrypt (depending on the operation



update(byte[], short, short, byte[], short)

mode that was specified in the call to init()) more data. In addition, note that the initial vector(IV) used in DES algorithms will be reset to 0.

Notes:

• When using block-aligned data (multiple of block size), if the input buffer, inBuff and the output buffer, outBuff are the same array, then the output data area must not partially overlap the input data area such that the input data is modified before it is used; if inBuff==outBuff and inOffset < outOffset < inOffset+inLength, incorrect output may result.

• When non-block aligned data is presented as input data, no amount of input and output buffer data overlap is allowed; if inBuff==outBuff and outOffset < inOffset+inLength, incorrect output may result.


• On decryption operations (except when ISO 9797 method 1 padding is used), the padding bytes are not written to outBuff.

• On encryption and decryption operations, the number of bytes output into outBuff may be larger or smaller than inLength or even 0.

• On decryption operations resulting in an ArrayIndexOutOfBoundException, outBuff may be partially modified.

Parameters:inBuff - the input buffer of data to be encrypted/decrypted.

inOffset - the offset into the input buffer at which to begin encryption/decryption.

inLength - the byte length to be encrypted/decrypted.


outOffset - the offset into the output buffer where the resulting output data begins

Returns: number of bytes output in outBuff



• CryptoException.INVALID_INIT if this Cipher object is not initialized.

• CryptoException.ILLEGAL_USE if one of the following conditions is met:

• this Cipher algorithm does not pad the message and either the message is not block aligned or no input data has been provided in inBuff or via the update() method.

• the input message length is not supported.

• the decrypted data is not bounded by appropriate padding bytes.


public abstract short update(byte[] inBuff, short inOffset, short inLength,



Cipher 239



Generates encrypted/decrypted output from input data. This method is intended for multiple-part encryption/decryption operations.

This method requires temporary storage of intermediate results. In addition, if the input data length is not block aligned (multiple of block size) then additional internal storage may be allocated at this time to store a partial input data block. This may result in additional resource consumption and/or slow performance.

This method should only be used if all the input data required for the cipher is not available in one byte array. If all the input data required for the cipher is located in a single byte array, use of the doFinal() method to process all of the input data is recommended. The doFinal() method must be invoked to complete processing of any remaining input data buffered by one or more calls to the update() method.

Notes:

• When using block-aligned data (multiple of block size), if the input buffer, inBuff and the output buffer, outBuff are the same array, then the output data area must not partially overlap the input data area such that the input data is modified before it is used; if inBuff==outBuff and inOffset < outOffset < inOffset+inLength, incorrect output may result.

• When non-block aligned data is presented as input data, no amount of input and output buffer data overlap is allowed; if inBuff==outBuff and outOffset < inOffset+inLength, incorrect output may result.

• On decryption operations(except when ISO 9797 method 1 padding is used), the padding bytes are not written to outBuff.

• On encryption and decryption operations, block alignment considerations may require that the number of bytes output into outBuff be larger or smaller than inLength or even 0.


Parameters:inBuff - the input buffer of data to be encrypted/decrypted.

inOffset - the offset into the input buffer at which to begin encryption/decryption.

inLength - the byte length to be encrypted/decrypted.


outOffset - the offset into the output buffer where the resulting ciphertext/plaintext begins

Returns: number of bytes output in outBuff



• CryptoException.INVALID_INIT if this Cipher object is not initialized.

• CryptoException.ILLEGAL_USE if the input message length is not supported.


javacardx.crypto KeyEncryption

setKeyCipher(Cipher)

javacardx.crypto

KeyEncryptionDeclarationpublic interface KeyEncryption

DescriptionKeyEncryption interface defines the methods used to enable encrypted key data access to a key implementation.

See Also: KeyBuilder, Cipher

Methods

setKeyCipher(Cipher)

public void setKeyCipher(javacardx.crypto.Cipher keyCipher)

Sets the Cipher object to be used to decrypt the input key data and key parameters in the set methods.

Default Cipher object is null - no decryption performed.

Parameters:keyCipher - the decryption Cipher object to decrypt the input key data. null parameter indicates that no decryption is required.

getKeyCipher()

public javacardx.crypto.Cipher getKeyCipher()

Returns the Cipher object to be used to decrypt the input key data and key parameters in the set methods.

Default is null - no decryption performed.

Returns: keyCipher the decryption Cipher object to decrypt the input key data. null return indicates that no decryption is performed.

Member Summary

Methods Cipher getKeyCipher()

Returns the Cipher object to be used to decrypt the input key data and key parameters in the set methods.

void setKeyCipher(Cipher keyCipher)Sets the Cipher object to be used to decrypt the input key data and key parameters in the set methods.

KeyEncryption 241

KeyEncryption javacardx.crypto

getKeyCipher()


Almanac

Almanac LegendThe almanac presents classes and intefaces in alphabetic order, regardless of their package. Fields, methods and constructors are in alphabetic order in a single list.

This almanac is modeled after the style introduced by Patrick Chan in his book Java Developers Almanac.

1. Name of the class, interface, nested class or nested interface. Interfaces are italic.

2. Name of the package containing the class or interface.

3. Inheritance hierarchy. In this example, RealtimeThread extends Thread, which extends Object.

4. Implemented interfaces. The interface is to the right of, and on the same line as, the class that implements it. In this example, Thread implements Runnable, and RealtimeThread implements Schedulable.

5. The first column above is for the value of the @since comment, which indicates the version in which the item was introduced.

6. The second column above is for the following icons. If the “protected” symbol does not appear, the member is public. (Private and package-private modifiers also have no symbols.) One symbol from each group can appear in this column.

7. Return type of a method or declared type of a field. Blank for constructors.

Name of the constructor, field or method. Nested classes are listed in 1, not here.

Modifiers❍ abstract ● final❏ static■ static final

Access Modifiers♦ protected

Constructors and Fields❉ constructor✍ field

Object➥ Thread Runnable

➥ RealtimeThread Schedulable

RealtimeThread javax.realtime

void addToFeasibility()RealtimeThread currentRealtimeThread()

Scheduler getScheduler()❉ RealtimeThread()❉ RealtimeThread(SchedulingParameters scheduling)❏ void sleep(Clock clock, HighResolutionTime time)

➊ ➋

➌➍

➎ ➏

➐ ➑

➘➘

➙➙

➘

➚

➘1.3 ❏

1.3

throws InterruptedException➚

Almanac 243

Almanac

AESKey SecretKey

Object➥ AID

Object➥ APDU

AESKey javacard.security

byte getKey(byte[] keyData, short kOff) throws CryptoException

void setKey(byte[] keyData, short kOff) throws CryptoException


❉ AID(byte[] bArray, short offset, byte length) throws SystemException, NullPointerException, ArrayIndexOutOfBoundsException, SecurityException

● boolean equals(byte[] bArray, short offset, byte length) throws ArrayIndexOutOfBoundsException, SecurityException

● boolean equals(Object anObject) throws SecurityException

● byte getBytes(byte[] dest, short offset) throws NullPointerException, ArrayIndexOutOfBoundsException, SecurityException

● byte getPartialBytes(short aidOffset, byte[] dest, short oOffset, byte oLength) throws NullPointerException, ArrayIndexOutOfBoundsException, SecurityException

● boolean partialEquals(byte[] bArray, short offset, byte length) throws ArrayIndexOutOfBoundsException, SecurityException

● boolean RIDEquals(AID otherAID) throws SecurityException


byte[] getBuffer()

❏ byte getCLAChannel()

❏ APDU getCurrentAPDU() throws SecurityException

❏ byte[] getCurrentAPDUBuffer() throws SecurityException

byte getCurrentState()

❏ short getInBlockSize()

byte getNAD()

❏ short getOutBlockSize()

❏ byte getProtocol()

✍■ byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_A

✍■ byte PROTOCOL_MEDIA_CONTACTLESS_TYPE_B

✍■ byte PROTOCOL_MEDIA_DEFAULT

✍■ byte PROTOCOL_MEDIA_MASK

✍■ byte PROTOCOL_MEDIA_USB

✍■ byte PROTOCOL_T0

✍■ byte PROTOCOL_T1

✍■ byte PROTOCOL_TYPE_MASK

short receiveBytes(short bOff) throws APDUException

void sendBytes(short bOff, short len) throws APDUException

void sendBytesLong(byte[] outData, short bOff, short len) throws APDUException, SecurityException


Almanac

Object➥ Throwable

➥ Exception➥ RuntimeException

➥ CardRuntimeException➥ APDUException

Object➥ Applet

short setIncomingAndReceive() throws APDUException

short setOutgoing() throws APDUException

void setOutgoingAndSend(short bOff, short len) throws APDUException

void setOutgoingLength(short len) throws APDUException

short setOutgoingNoChaining() throws APDUException

✍■ byte STATE_ERROR_IO

✍■ byte STATE_ERROR_NO_T0_GETRESPONSE

✍■ byte STATE_ERROR_NO_T0_REISSUE

✍■ byte STATE_ERROR_T1_IFD_ABORT

✍■ byte STATE_FULL_INCOMING

✍■ byte STATE_FULL_OUTGOING

✍■ byte STATE_INITIAL

✍■ byte STATE_OUTGOING

✍■ byte STATE_OUTGOING_LENGTH_KNOWN

✍■ byte STATE_PARTIAL_INCOMING

✍■ byte STATE_PARTIAL_OUTGOING

❏ void waitExtension() throws APDUException


❉ APDUException(short reason)

✍■ short BAD_LENGTH

✍■ short BUFFER_BOUNDS

✍■ short ILLEGAL_USE

✍■ short IO_ERROR

✍■ short NO_T0_GETRESPONSE

✍■ short NO_T0_REISSUE

✍■ short T1_IFD_ABORT

❏ void throwIt(short reason)


❉♦ Applet()

void deselect()

Shareable getShareableInterfaceObject(AID clientAID, byte parameter)

❏ void install(byte[] bArray, short bOffset, byte bLength) throws ISOException

❍ void process(APDU apdu) throws ISOException

●♦ void register() throws SystemException

Almanac 245

Almanac

Object➥ Throwable


➥ ArithmeticException

Object➥ Throwable


➥ IndexOutOfBoundsException➥ ArrayIndexOutOfBoundsException

Object➥ Throwable


➥ ArrayStoreException

Object➥ BasicService Service

●♦ void register(byte[] bArray, short bOffset, byte bLength) throws SystemException

boolean select()

●♦ boolean selectingApplet()

ArithmeticException java.lang

❉ ArithmeticException()

ArrayIndexOutOfBoundsException java.lang

❉ ArrayIndexOutOfBoundsException()

ArrayStoreException java.lang

❉ ArrayStoreException()


❉ BasicService()

boolean fail(javacard.framework.APDU apdu, short sw) throws ServiceException

byte getCLA(javacard.framework.APDU apdu)

byte getINS(javacard.framework.APDU apdu)

short getOutputLength(javacard.framework.APDU apdu) throws ServiceException

byte getP1(javacard.framework.APDU apdu) throws ServiceException

byte getP2(javacard.framework.APDU apdu) throws ServiceException

short getStatusWord(javacard.framework.APDU apdu) throws ServiceException

boolean isProcessed(javacard.framework.APDU apdu)

boolean processCommand(javacard.framework.APDU apdu)

boolean processDataIn(javacard.framework.APDU apdu)

boolean processDataOut(javacard.framework.APDU apdu)

short receiveInData(javacard.framework.APDU apdu) throws ServiceException


Almanac

Object➥ Throwable

➥ Exception➥ CardException

Object➥ CardRemoteObject java.rmi.Remote

Object➥ Throwable


➥ CardRuntimeException

Object➥ Checksum

boolean selectingApplet()

void setOutputLength(javacard.framework.APDU apdu, short length) throws ServiceException

void setProcessed(javacard.framework.APDU apdu) throws ServiceException

void setStatusWord(javacard.framework.APDU apdu, short sw)

boolean succeed(javacard.framework.APDU apdu) throws ServiceException

boolean succeedWithStatusWord(javacard.framework.APDU apdu, short sw) throws ServiceException

CardException javacard.framework

❉ CardException(short reason)

short getReason()

void setReason(short reason)

❏ void throwIt(short reason) throws CardException

CardRemoteObject javacard.framework.service

❉ CardRemoteObject()

❏ void export(java.rmi.Remote obj) throws SecurityException

❏ void unexport(java.rmi.Remote obj) throws SecurityException

CardRuntimeException javacard.framework

❉ CardRuntimeException(short reason)

short getReason()

void setReason(short reason)

❏ void throwIt(short reason) throws CardRuntimeException


✍■ byte ALG_ISO3309_CRC16

✍■ byte ALG_ISO3309_CRC32

❉♦ Checksum()

❍ short doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)

❍ byte getAlgorithm()

Almanac 247

Almanac

Object➥ Cipher

Object➥ Throwable


➥ ClassCastException

■ Checksum getInstance(byte algorithm, boolean externalAccess) throws CryptoException

❍ void init(byte[] bArray, short bOff, short bLen) throws CryptoException

❍ void update(byte[] inBuff, short inOffset, short inLength)


✍■ byte ALG_AES_BLOCK_128_CBC_NOPAD

✍■ byte ALG_AES_BLOCK_128_ECB_NOPAD

✍■ byte ALG_DES_CBC_ISO9797_M1

✍■ byte ALG_DES_CBC_ISO9797_M2

✍■ byte ALG_DES_CBC_NOPAD

✍■ byte ALG_DES_CBC_PKCS5

✍■ byte ALG_DES_ECB_ISO9797_M1

✍■ byte ALG_DES_ECB_ISO9797_M2

✍■ byte ALG_DES_ECB_NOPAD

✍■ byte ALG_DES_ECB_PKCS5

✍■ byte ALG_RSA_ISO14888

✍■ byte ALG_RSA_ISO9796

✍■ byte ALG_RSA_NOPAD

✍■ byte ALG_RSA_PKCS1

✍■ byte ALG_RSA_PKCS1_OAEP

❉♦ Cipher()

❍ short doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) throws javacard.security.CryptoException


■ Cipher getInstance(byte algorithm, boolean externalAccess) throws javacard.security.CryptoException

❍ void init(javacard.security.Key theKey, byte theMode) throws javacard.security.CryptoException

❍ void init(javacard.security.Key theKey, byte theMode, byte[] bArray, short bOff, short bLen) throws javacard.security.CryptoException

✍■ byte MODE_DECRYPT

✍■ byte MODE_ENCRYPT

❍ short update(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset) throws javacard.security.CryptoException

ClassCastException java.lang

❉ ClassCastException()


Almanac

Object➥ Throwable


➥ javacard.framework.CardRuntimeException➥ CryptoException

DESKey SecretKey

Object➥ Dispatcher

DSAKey

CryptoException javacard.security

❉ CryptoException(short reason)


✍■ short ILLEGAL_VALUE

✍■ short INVALID_INIT

✍■ short NO_SUCH_ALGORITHM


✍■ short UNINITIALIZED_KEY

DESKey javacard.security

byte getKey(byte[] keyData, short kOff)

void setKey(byte[] keyData, short kOff) throws CryptoException, NullPointerException, ArrayIndexOutOfBoundsException


void addService(Service service, byte phase) throws ServiceException

Exception dispatch(javacard.framework.APDU command, byte phase) throws ServiceException

❉ Dispatcher(short maxServices) throws ServiceException

✍■ byte PROCESS_COMMAND

✍■ byte PROCESS_INPUT_DATA

✍■ byte PROCESS_NONE

✍■ byte PROCESS_OUTPUT_DATA

void process(javacard.framework.APDU command) throws javacard.framework.ISOException

void removeService(Service service, byte phase) throws ServiceException


short getG(byte[] buffer, short offset)

short getP(byte[] buffer, short offset)

short getQ(byte[] buffer, short offset)

void setG(byte[] buffer, short offset, short length) throws CryptoException

void setP(byte[] buffer, short offset, short length) throws CryptoException

void setQ(byte[] buffer, short offset, short length) throws CryptoException

Almanac 249

Almanac

DSAPrivateKey PrivateKey, DSAKey

DSAPublicKey PublicKey, DSAKey

ECKey

ECPrivateKey PrivateKey, ECKey

ECPublicKey PublicKey, ECKey

Object➥ Throwable

➥ Exception

DSAPrivateKey javacard.security

short getX(byte[] buffer, short offset)

void setX(byte[] buffer, short offset, short length) throws CryptoException

DSAPublicKey javacard.security

short getY(byte[] buffer, short offset)

void setY(byte[] buffer, short offset, short length) throws CryptoException


short getA(byte[] buffer, short offset) throws CryptoException

short getB(byte[] buffer, short offset) throws CryptoException

short getField(byte[] buffer, short offset) throws CryptoException

short getG(byte[] buffer, short offset) throws CryptoException

short getK() throws CryptoException

short getR(byte[] buffer, short offset) throws CryptoException

void setA(byte[] buffer, short offset, short length) throws CryptoException

void setB(byte[] buffer, short offset, short length) throws CryptoException

void setFieldF2M(short e) throws CryptoException

void setFieldF2M(short e1, short e2, short e3) throws CryptoException

void setFieldFP(byte[] buffer, short offset, short length) throws CryptoException

void setG(byte[] buffer, short offset, short length) throws CryptoException

void setK(short K)

void setR(byte[] buffer, short offset, short length) throws CryptoException

ECPrivateKey javacard.security

short getS(byte[] buffer, short offset) throws CryptoException

void setS(byte[] buffer, short offset, short length) throws CryptoException

ECPublicKey javacard.security

short getW(byte[] buffer, short offset) throws CryptoException

void setW(byte[] buffer, short offset, short length) throws CryptoException

Exception java.lang

❉ Exception()


Almanac

Object➥ Throwable


➥ IndexOutOfBoundsException

Object➥ Throwable

➥ Exception➥ IOException

ISO7816

IndexOutOfBoundsException java.lang

❉ IndexOutOfBoundsException()

IOException java.io

❉ IOException()


✍■ byte CLA_ISO7816

✍■ byte INS_EXTERNAL_AUTHENTICATE

✍■ byte INS_SELECT

✍■ byte OFFSET_CDATA

✍■ byte OFFSET_CLA

✍■ byte OFFSET_INS

✍■ byte OFFSET_LC

✍■ byte OFFSET_P1

✍■ byte OFFSET_P2

✍■ short SW_APPLET_SELECT_FAILED

✍■ short SW_BYTES_REMAINING_00

✍■ short SW_CLA_NOT_SUPPORTED

✍■ short SW_COMMAND_NOT_ALLOWED

✍■ short SW_CONDITIONS_NOT_SATISFIED

✍■ short SW_CORRECT_LENGTH_00

✍■ short SW_DATA_INVALID

✍■ short SW_FILE_FULL

✍■ short SW_FILE_INVALID

✍■ short SW_FILE_NOT_FOUND

✍■ short SW_FUNC_NOT_SUPPORTED

✍■ short SW_INCORRECT_P1P2

✍■ short SW_INS_NOT_SUPPORTED

✍■ short SW_LOGICAL_CHANNEL_NOT_SUPPORTED

✍■ short SW_NO_ERROR

✍■ short SW_RECORD_NOT_FOUND

✍■ short SW_SECURE_MESSAGING_NOT_SUPPORTED

✍■ short SW_SECURITY_STATUS_NOT_SATISFIED

✍■ short SW_UNKNOWN

Almanac 251

Almanac

Object➥ Throwable


➥ CardRuntimeException➥ ISOException

Object➥ JCSystem

✍■ short SW_WARNING_STATE_UNCHANGED

✍■ short SW_WRONG_DATA

✍■ short SW_WRONG_LENGTH

✍■ short SW_WRONG_P1P2

ISOException javacard.framework

❉ ISOException(short sw)

❏ void throwIt(short sw)


❏ void abortTransaction() throws TransactionException

❏ void beginTransaction() throws TransactionException

✍■ byte CLEAR_ON_DESELECT

✍■ byte CLEAR_ON_RESET

❏ void commitTransaction() throws TransactionException

❏ AID getAID()

❏ Shareable getAppletShareableInterfaceObject(AID serverAID, byte parameter)

❏ byte getAssignedChannel()

❏ short getAvailableMemory(byte memoryType) throws SystemException

❏ short getMaxCommitCapacity()

❏ AID getPreviousContextAID()

❏ byte getTransactionDepth()

❏ short getUnusedCommitCapacity()

❏ short getVersion()

❏ boolean isObjectDeletionSupported()

❏ byte isTransient(Object theObj)

❏ AID lookupAID(byte[] buffer, short offset, byte length)

❏ boolean[] makeTransientBooleanArray(short length, byte event) throws NegativeArraySizeException, SystemException

❏ byte[] makeTransientByteArray(short length, byte event) throws NegativeArraySizeException, SystemException

❏ Object[] makeTransientObjectArray(short length, byte event) throws NegativeArraySizeException, SystemException

❏ short[] makeTransientShortArray(short length, byte event) throws NegativeArraySizeException, SystemException

✍■ byte MEMORY_TYPE_PERSISTENT

✍■ byte MEMORY_TYPE_TRANSIENT_DESELECT

✍■ byte MEMORY_TYPE_TRANSIENT_RESET

✍■ byte NOT_A_TRANSIENT_OBJECT

❏ void requestObjectDeletion() throws SystemException


Almanac

Key

Object➥ KeyAgreement

Object➥ KeyBuilder

Key javacard.security

void clearKey()

short getSize()

byte getType()

boolean isInitialized()


✍■ byte ALG_EC_SVDP_DH

✍■ byte ALG_EC_SVDP_DHC

❍ short generateSecret(byte[] publicData, short publicOffset, short publicLength, byte[] secret, short secretOffset) throws CryptoException


■ KeyAgreement getInstance(byte algorithm, boolean externalAccess) throws CryptoException

❍ void init(PrivateKey privKey) throws CryptoException

❉♦ KeyAgreement()


❏ Key buildKey(byte keyType, short keyLength, boolean keyEncryption) throws CryptoException

✍■ short LENGTH_AES_128



✍■ short LENGTH_DES

✍■ short LENGTH_DES3_2KEY

✍■ short LENGTH_DES3_3KEY

✍■ short LENGTH_DSA_1024



✍■ short LENGTH_EC_F2M_113




✍■ short LENGTH_EC_FP_112




✍■ short LENGTH_RSA_1024



Almanac 253

Almanac

KeyEncryption

Object➥ KeyPair







✍■ byte TYPE_AES

✍■ byte TYPE_AES_TRANSIENT_DESELECT

✍■ byte TYPE_AES_TRANSIENT_RESET

✍■ byte TYPE_DES

✍■ byte TYPE_DES_TRANSIENT_DESELECT

✍■ byte TYPE_DES_TRANSIENT_RESET

✍■ byte TYPE_DSA_PRIVATE

✍■ byte TYPE_DSA_PUBLIC

✍■ byte TYPE_EC_F2M_PRIVATE

✍■ byte TYPE_EC_F2M_PUBLIC

✍■ byte TYPE_EC_FP_PRIVATE

✍■ byte TYPE_EC_FP_PUBLIC

✍■ byte TYPE_RSA_CRT_PRIVATE

✍■ byte TYPE_RSA_PRIVATE

✍■ byte TYPE_RSA_PUBLIC

KeyEncryption javacardx.crypto

Cipher getKeyCipher()

void setKeyCipher(Cipher keyCipher)


✍■ byte ALG_DSA

✍■ byte ALG_EC_F2M

✍■ byte ALG_EC_FP

✍■ byte ALG_RSA

✍■ byte ALG_RSA_CRT

● void genKeyPair() throws CryptoException

PrivateKey getPrivate()

PublicKey getPublic()

❉ KeyPair(byte algorithm, short keyLength) throws CryptoException

❉ KeyPair(PublicKey publicKey, PrivateKey privateKey) throws CryptoException


Almanac

Object➥ MessageDigest

MultiSelectable

Object➥ Throwable


➥ NegativeArraySizeException

Object➥ Throwable


➥ NullPointerException

Object


✍■ byte ALG_MD5

✍■ byte ALG_RIPEMD160

✍■ byte ALG_SHA

❍ short doFinal(byte[] inBuff, short inOffset, short inLength, byte[] outBuff, short outOffset)


■ MessageDigest getInstance(byte algorithm, boolean externalAccess) throws CryptoException

❍ byte getLength()

❉♦ MessageDigest()

❍ void reset()

❍ void update(byte[] inBuff, short inOffset, short inLength)

MultiSelectable javacard.framework

void deselect(boolean appInstStillActive)

boolean select(boolean appInstAlreadyActive)

NegativeArraySizeException java.lang

❉ NegativeArraySizeException()

NullPointerException java.lang

❉ NullPointerException()

Object java.lang

boolean equals(Object obj)

❉ Object()

Almanac 255

Almanac

Object➥ OwnerPIN PIN

PIN

Object➥ Throwable


➥ CardRuntimeException➥ PINException

PrivateKey Key

PublicKey Key


boolean check(byte[] pin, short offset, byte length) throws ArrayIndexOutOfBoundsException, NullPointerException

byte getTriesRemaining()

♦ boolean getValidatedFlag()

boolean isValidated()

❉ OwnerPIN(byte tryLimit, byte maxPINSize) throws PINException

void reset()

void resetAndUnblock()

♦ void setValidatedFlag(boolean value)

void update(byte[] pin, short offset, byte length) throws PINException

PIN javacard.framework

boolean check(byte[] pin, short offset, byte length) throws ArrayIndexOutOfBoundsException, NullPointerException

byte getTriesRemaining()

boolean isValidated()

void reset()

PINException javacard.framework


❉ PINException(short reason)


PrivateKey javacard.security

PublicKey javacard.security


Almanac

Object➥ RandomData

Remote

Object➥ Throwable

➥ Exception➥ java.io.IOException

➥ RemoteException

RemoteService Service

Object➥ BasicService Service

➥ RMIService RemoteService

RSAPrivateCrtKey PrivateKey

RandomData javacard.security

✍■ byte ALG_PSEUDO_RANDOM

✍■ byte ALG_SECURE_RANDOM

❍ void generateData(byte[] buffer, short offset, short length) throws CryptoException

■ RandomData getInstance(byte algorithm) throws CryptoException

❉♦ RandomData()

❍ void setSeed(byte[] buffer, short offset, short length)

Remote java.rmi

RemoteException java.rmi

❉ RemoteException()

RemoteService javacard.framework.service


✍■ byte DEFAULT_RMI_INVOKE_INSTRUCTION


❉ RMIService(java.rmi.Remote initialObject) throws NullPointerException

void setInvokeInstructionByte(byte ins)


short getDP1(byte[] buffer, short offset)

short getDQ1(byte[] buffer, short offset)

short getP(byte[] buffer, short offset)

short getPQ(byte[] buffer, short offset)

short getQ(byte[] buffer, short offset)

void setDP1(byte[] buffer, short offset, short length) throws CryptoException

void setDQ1(byte[] buffer, short offset, short length) throws CryptoException

Almanac 257

Almanac

RSAPrivateKey PrivateKey

RSAPublicKey PublicKey

Object➥ Throwable


SecretKey Key

Object➥ Throwable


➥ SecurityException

SecurityService Service

void setP(byte[] buffer, short offset, short length) throws CryptoException

void setPQ(byte[] buffer, short offset, short length) throws CryptoException

void setQ(byte[] buffer, short offset, short length) throws CryptoException


short getExponent(byte[] buffer, short offset)

short getModulus(byte[] buffer, short offset)

void setExponent(byte[] buffer, short offset, short length) throws CryptoException

void setModulus(byte[] buffer, short offset, short length) throws CryptoException

RSAPublicKey javacard.security

short getExponent(byte[] buffer, short offset)

short getModulus(byte[] buffer, short offset)

void setExponent(byte[] buffer, short offset, short length) throws CryptoException

void setModulus(byte[] buffer, short offset, short length) throws CryptoException

RuntimeException java.lang

❉ RuntimeException()

SecretKey javacard.security

SecurityException java.lang

❉ SecurityException()


boolean isAuthenticated(short principal) throws ServiceException

boolean isChannelSecure(byte properties) throws ServiceException

boolean isCommandSecure(byte properties) throws ServiceException

✍■ short PRINCIPAL_APP_PROVIDER


Almanac

Service

Object➥ Throwable


➥ javacard.framework.CardRuntimeException➥ ServiceException

Shareable

Object➥ Signature

✍■ short PRINCIPAL_CARD_ISSUER

✍■ short PRINCIPAL_CARDHOLDER

✍■ byte PROPERTY_INPUT_CONFIDENTIALITY

✍■ byte PROPERTY_INPUT_INTEGRITY

✍■ byte PROPERTY_OUTPUT_CONFIDENTIALITY

✍■ byte PROPERTY_OUTPUT_INTEGRITY

Service javacard.framework.service


boolean processDataIn(javacard.framework.APDU apdu)

boolean processDataOut(javacard.framework.APDU apdu)


✍■ short CANNOT_ACCESS_IN_COMMAND

✍■ short CANNOT_ACCESS_OUT_COMMAND

✍■ short COMMAND_DATA_TOO_LONG

✍■ short COMMAND_IS_FINISHED

✍■ short DISPATCH_TABLE_FULL

✍■ short ILLEGAL_PARAM

✍■ short REMOTE_OBJECT_NOT_EXPORTED

❉ ServiceException(short reason)

❏ void throwIt(short reason) throws ServiceException

Shareable javacard.framework


✍■ byte ALG_AES_MAC_128_NOPAD

✍■ byte ALG_DES_MAC4_ISO9797_1_M2_ALG3

✍■ byte ALG_DES_MAC4_ISO9797_M1


✍■ byte ALG_DES_MAC4_NOPAD

✍■ byte ALG_DES_MAC4_PKCS5

✍■ byte ALG_DES_MAC8_ISO9797_1_M2_ALG3



Almanac 259

Almanac

Object➥ Throwable


➥ CardRuntimeException➥ SystemException

✍■ byte ALG_DES_MAC8_NOPAD

✍■ byte ALG_DES_MAC8_PKCS5

✍■ byte ALG_DSA_SHA

✍■ byte ALG_ECDSA_SHA

✍■ byte ALG_RSA_MD5_PKCS1

✍■ byte ALG_RSA_MD5_PKCS1_PSS

✍■ byte ALG_RSA_MD5_RFC2409

✍■ byte ALG_RSA_RIPEMD160_ISO9796

✍■ byte ALG_RSA_RIPEMD160_PKCS1

✍■ byte ALG_RSA_RIPEMD160_PKCS1_PSS

✍■ byte ALG_RSA_SHA_ISO9796

✍■ byte ALG_RSA_SHA_PKCS1

✍■ byte ALG_RSA_SHA_PKCS1_PSS

✍■ byte ALG_RSA_SHA_RFC2409


■ Signature getInstance(byte algorithm, boolean externalAccess) throws CryptoException

❍ short getLength() throws CryptoException

❍ void init(Key theKey, byte theMode) throws CryptoException

❍ void init(Key theKey, byte theMode, byte[] bArray, short bOff, short bLen) throws CryptoException

✍■ byte MODE_SIGN

✍■ byte MODE_VERIFY

❍ short sign(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset) throws CryptoException

❉♦ Signature()

❍ void update(byte[] inBuff, short inOffset, short inLength) throws CryptoException

❍ boolean verify(byte[] inBuff, short inOffset, short inLength, byte[] sigBuff, short sigOffset, short sigLength) throws CryptoException

SystemException javacard.framework

✍■ short ILLEGAL_AID

✍■ short ILLEGAL_TRANSIENT



✍■ short NO_RESOURCE

✍■ short NO_TRANSIENT_SPACE

❉ SystemException(short reason)

❏ void throwIt(short reason) throws SystemException


Almanac

Object➥ Throwable

Object➥ Throwable


➥ CardRuntimeException➥ TransactionException

Object➥ Throwable

➥ Exception➥ CardException

➥ UserException

Object➥ Util

Throwable java.lang

❉ Throwable()


✍■ short BUFFER_FULL

✍■ short IN_PROGRESS

✍■ short INTERNAL_FAILURE

✍■ short NOT_IN_PROGRESS


❉ TransactionException(short reason)

UserException javacard.framework

❏ void throwIt(short reason) throws UserException

❉ UserException()

❉ UserException(short reason)


■ byte arrayCompare(byte[] src, short srcOff, byte[] dest, short destOff, short length) throws ArrayIndexOutOfBoundsException, NullPointerException

■ short arrayCopy(byte[] src, short srcOff, byte[] dest, short destOff, short length) throws ArrayIndexOutOfBoundsException, NullPointerException, TransactionException

■ short arrayCopyNonAtomic(byte[] src, short srcOff, byte[] dest, short destOff, short length) throws ArrayIndexOutOfBoundsException, NullPointerException

■ short arrayFillNonAtomic(byte[] bArray, short bOff, short bLen, byte bValue) throws ArrayIndexOutOfBoundsException, NullPointerException

■ short getShort(byte[] bArray, short bOff) throws NullPointerException, ArrayIndexOutOfBoundsException

■ short makeShort(byte b1, byte b2)

■ short setShort(byte[] bArray, short bOff, short sValue) throws TransactionException, NullPointerException, ArrayIndexOutOfBoundsException

Almanac 261

Almanac


Index

AabortTransaction()

of javacard.framework.JCSystem 87addService(Service, byte)

of javacard.framework.service.Dispatcher 131AESKey

of javacard.security 149AID

of javacard.framework 39AID(byte[], short, byte)

of javacard.framework.AID 40ALG_AES_BLOCK_128_CBC_NOPAD

of javacardx.crypto.Cipher 236ALG_AES_BLOCK_128_ECB_NOPAD

of javacardx.crypto.Cipher 236ALG_AES_MAC_128_NOPAD

of javacard.security.Signature 225ALG_DES_CBC_ISO9797_M1

of javacardx.crypto.Cipher 234ALG_DES_CBC_ISO9797_M2

of javacardx.crypto.Cipher 234ALG_DES_CBC_NOPAD

of javacardx.crypto.Cipher 234ALG_DES_CBC_PKCS5

of javacardx.crypto.Cipher 234ALG_DES_ECB_ISO9797_M1

of javacardx.crypto.Cipher 235ALG_DES_ECB_ISO9797_M2

of javacardx.crypto.Cipher 235ALG_DES_ECB_NOPAD

of javacardx.crypto.Cipher 234ALG_DES_ECB_PKCS5

of javacardx.crypto.Cipher 235

ALG_DES_MAC4_ISO9797_1_M2_ALG3of javacard.security.Signature 225

ALG_DES_MAC4_ISO9797_M1of javacard.security.Signature 222


ALG_DES_MAC4_NOPADof javacard.security.Signature 222

ALG_DES_MAC4_PKCS5of javacard.security.Signature 223

ALG_DES_MAC8_ISO9797_1_M2_ALG3of javacard.security.Signature 225



ALG_DES_MAC8_NOPADof javacard.security.Signature 222

ALG_DES_MAC8_PKCS5of javacard.security.Signature 223

ALG_DSAof javacard.security.KeyPair 194

ALG_DSA_SHAof javacard.security.Signature 224

ALG_EC_F2Mof javacard.security.KeyPair 194

ALG_EC_FPof javacard.security.KeyPair 194

ALG_EC_SVDP_DHof javacard.security.KeyAgreement 183

ALG_EC_SVDP_DHCof javacard.security.KeyAgreement 183

ALG_ECDSA_SHAof javacard.security.Signature 225

263

ALG_ISO3309_CRC16of javacard.security.Checksum 152

ALG_ISO3309_CRC32of javacard.security.Checksum 152

ALG_MD5of javacard.security.MessageDigest 198

ALG_PSEUDO_RANDOMof javacard.security.RandomData 203

ALG_RIPEMD160of javacard.security.MessageDigest 198

ALG_RSAof javacard.security.KeyPair 194

ALG_RSA_CRTof javacard.security.KeyPair 194

ALG_RSA_ISO14888of javacardx.crypto.Cipher 235

ALG_RSA_ISO9796of javacardx.crypto.Cipher 236

ALG_RSA_MD5_PKCS1of javacard.security.Signature 224

ALG_RSA_MD5_PKCS1_PSSof javacard.security.Signature 226

ALG_RSA_MD5_RFC2409of javacard.security.Signature 225

ALG_RSA_NOPADof javacardx.crypto.Cipher 236

ALG_RSA_PKCS1of javacardx.crypto.Cipher 235

ALG_RSA_PKCS1_OAEPof javacardx.crypto.Cipher 236

ALG_RSA_RIPEMD160_ISO9796of javacard.security.Signature 224

ALG_RSA_RIPEMD160_PKCS1of javacard.security.Signature 224

ALG_RSA_RIPEMD160_PKCS1_PSSof javacard.security.Signature 226

ALG_RSA_SHA_ISO9796of javacard.security.Signature 223

ALG_RSA_SHA_PKCS1of javacard.security.Signature 223

ALG_RSA_SHA_PKCS1_PSSof javacard.security.Signature 225

ALG_RSA_SHA_RFC2409of javacard.security.Signature 225

ALG_SECURE_RANDOMof javacard.security.RandomData 204

ALG_SHAof javacard.security.MessageDigest 198

APDU

of javacard.framework 44APDUException

of javacard.framework 59APDUException(short)

of javacard.framework.APDUException 61Applet

of javacard.framework 63Applet()

of javacard.framework.Applet 65ArithmeticException

of java.lang 13ArithmeticException()

of java.lang.ArithmeticException 13arrayCompare(byte[], short, byte[], short, short)

of javacard.framework.Util 114arrayCopy(byte[], short, byte[], short, short)

of javacard.framework.Util 112arrayCopyNonAtomic(byte[], short, byte[], short,

short)of javacard.framework.Util 113

arrayFillNonAtomic(byte[], short, short, byte)of javacard.framework.Util 114

ArrayIndexOutOfBoundsExceptionof java.lang 14

ArrayIndexOutOfBoundsException()of java.lang.ArrayIndexOutOfBoundsException

14ArrayStoreException

of java.lang 16ArrayStoreException()

of java.lang.ArrayStoreException 17

BBAD_LENGTH

of javacard.framework.APDUException 60BasicService

of javacard.framework.service 119BasicService()

of javacard.framework.service.BasicService 121beginTransaction()

of javacard.framework.JCSystem 86BUFFER_BOUNDS

of javacard.framework.APDUException 60BUFFER_FULL

of javacard.framework.TransactionException 107



of javacard.security.KeyBuilder 191

CCANNOT_ACCESS_IN_COMMAND

of javacard.framework.service.ServiceException 144

CANNOT_ACCESS_OUT_COMMANDof javacard.framework.service.ServiceException

144CardException

of javacard.framework 70CardException(short)

of javacard.framework.CardException 71CardRemoteObject

of javacard.framework.service 127CardRemoteObject()

of javacard.framework.service.CardRemoteObject 127

CardRuntimeExceptionof javacard.framework 72

CardRuntimeException(short)of javacard.framework.CardRuntimeException

73check(byte[], short, byte)

of javacard.framework.OwnerPIN 95of javacard.framework.PIN 98

Checksumof javacard.security 151

Checksum()of javacard.security.Checksum 152

Cipherof javacardx.crypto 232

Cipher()of javacardx.crypto.Cipher 237

CLA_ISO7816of javacard.framework.ISO7816 78

ClassCastExceptionof java.lang 18

ClassCastException()of java.lang.ClassCastException 19

CLEAR_ON_DESELECTof javacard.framework.JCSystem 83

CLEAR_ON_RESETof javacard.framework.JCSystem 83

clearKey()of javacard.security.Key 181

COMMAND_DATA_TOO_LONGof javacard.framework.service.ServiceException

144COMMAND_IS_FINISHED


commitTransaction()of javacard.framework.JCSystem 87

CryptoExceptionof javacard.security 155

CryptoException(short)of javacard.security.CryptoException 157

DDEFAULT_RMI_INVOKE_INSTRUCTION

of javacard.framework.service.RMIService 135deselect()

of javacard.framework.Applet 67deselect(boolean)

of javacard.framework.MultiSelectable 92DESKey

of javacard.security 158dispatch(APDU, byte)

of javacard.framework.service.Dispatcher 131DISPATCH_TABLE_FULL


Dispatcherof javacard.framework.service 129

Dispatcher(short)of javacard.framework.service.Dispatcher 130

doFinal(byte[], short, short, byte[], short)of javacard.security.Checksum 153of javacard.security.MessageDigest 199of javacardx.crypto.Cipher 238

DSAKeyof javacard.security 160

DSAPrivateKeyof javacard.security 164

DSAPublicKeyof javacard.security 166

EECKey

of javacard.security 168

Index 265

ECPrivateKeyof javacard.security 176

ECPublicKeyof javacard.security 178

equals(byte[], short, byte)of javacard.framework.AID 41

equals(Object)of java.lang.Object 26of javacard.framework.AID 41

Exceptionof java.lang 20

Exception()of java.lang.Exception 20

export(Remote)of

javacard.framework.service.CardRemoteObject 128

Ffail(APDU, short)

of javacard.framework.service.BasicService 124

GgenerateData(byte[], short, short)

of javacard.security.RandomData 204generateSecret(byte[], short, short, byte[], short)

of javacard.security.KeyAgreement 184genKeyPair()

of javacard.security.KeyPair 195getA(byte[], short)

of javacard.security.ECKey 173getAID()

of javacard.framework.JCSystem 86getAlgorithm()

of javacard.security.Checksum 153of javacard.security.KeyAgreement 184of javacard.security.MessageDigest 199of javacard.security.Signature 228of javacardx.crypto.Cipher 238

getAppletShareableInterfaceObject(AID, byte)of javacard.framework.JCSystem 89

getAssignedChannel()of javacard.framework.JCSystem 90

getAvailableMemory(byte)of javacard.framework.JCSystem 88

getB(byte[], short)of javacard.security.ECKey 173

getBuffer()of javacard.framework.APDU 50

getBytes(byte[], short)of javacard.framework.AID 40

getCLA(APDU)of javacard.framework.service.BasicService 125

getCLAChannel()of javacard.framework.APDU 57

getCurrentAPDU()of javacard.framework.APDU 57

getCurrentAPDUBuffer()of javacard.framework.APDU 57

getCurrentState()of javacard.framework.APDU 56

getDP1(byte[], short)of javacard.security.RSAPrivateCrtKey 210

getDQ1(byte[], short)of javacard.security.RSAPrivateCrtKey 210

getExponent(byte[], short)of javacard.security.RSAPrivateKey 214of javacard.security.RSAPublicKey 217

getField(byte[], short)of javacard.security.ECKey 172

getG(byte[], short)of javacard.security.DSAKey 162of javacard.security.ECKey 174

getInBlockSize()of javacard.framework.APDU 50

getINS(APDU)of javacard.framework.service.BasicService 125

getInstance(byte)of javacard.security.RandomData 204

getInstance(byte, boolean)of javacard.security.Checksum 152of javacard.security.KeyAgreement 183of javacard.security.MessageDigest 198of javacard.security.Signature 226of javacardx.crypto.Cipher 237

getK()of javacard.security.ECKey 175

getKey(byte[], short)of javacard.security.AESKey 150of javacard.security.DESKey 159

getKeyCipher()of javacardx.crypto.KeyEncryption 241

getLength()of javacard.security.MessageDigest 199


of javacard.security.Signature 228getMaxCommitCapacity()

of javacard.framework.JCSystem 88getModulus(byte[], short)

of javacard.security.RSAPrivateKey 213of javacard.security.RSAPublicKey 216

getNAD()of javacard.framework.APDU 51

getOutBlockSize()of javacard.framework.APDU 50

getOutputLength(APDU)of javacard.framework.service.BasicService 123

getP(byte[], short)of javacard.security.DSAKey 162of javacard.security.RSAPrivateCrtKey 209

getP1(APDU)of javacard.framework.service.BasicService 125

getP2(APDU)of javacard.framework.service.BasicService 126

getPartialBytes(short, byte[], short, byte)of javacard.framework.AID 42

getPQ(byte[], short)of javacard.security.RSAPrivateCrtKey 211

getPreviousContextAID()of javacard.framework.JCSystem 88

getPrivate()of javacard.security.KeyPair 196

getProtocol()of javacard.framework.APDU 50

getPublic()of javacard.security.KeyPair 196

getQ(byte[], short)of javacard.security.DSAKey 162of javacard.security.RSAPrivateCrtKey 209

getR(byte[], short)of javacard.security.ECKey 174

getReason()of javacard.framework.CardException 71of javacard.framework.CardRuntimeException

73getS(byte[], short)

of javacard.security.ECPrivateKey 177getShareableInterfaceObject(AID, byte)

of javacard.framework.Applet 68getShort(byte[], short)

of javacard.framework.Util 115getSize()

of javacard.security.Key 181getStatusWord(APDU)

of javacard.framework.service.BasicService 123getTransactionDepth()

of javacard.framework.JCSystem 87getTriesRemaining()

of javacard.framework.OwnerPIN 95of javacard.framework.PIN 98

getType()of javacard.security.Key 181

getUnusedCommitCapacity()of javacard.framework.JCSystem 87

getValidatedFlag()of javacard.framework.OwnerPIN 94

getVersion()of javacard.framework.JCSystem 85

getW(byte[], short)of javacard.security.ECPublicKey 179

getX(byte[], short)of javacard.security.DSAPrivateKey 165

getY(byte[], short)of javacard.security.DSAPublicKey 167

IILLEGAL_AID

of javacard.framework.SystemException 104ILLEGAL_PARAM


ILLEGAL_TRANSIENTof javacard.framework.SystemException 104

ILLEGAL_USEof javacard.framework.APDUException 60of javacard.framework.SystemException 105of javacard.security.CryptoException 156

ILLEGAL_VALUEof javacard.framework.PINException 101of javacard.framework.SystemException 104of javacard.security.CryptoException 156

IN_PROGRESSof javacard.framework.TransactionException

107IndexOutOfBoundsException

of java.lang 21IndexOutOfBoundsException()

of java.lang.IndexOutOfBoundsException 22init(byte[], short, short)

of javacard.security.Checksum 153init(Key, byte)

Index 267

of javacard.security.Signature 227of javacardx.crypto.Cipher 237

init(Key, byte, byte[], short, short)of javacard.security.Signature 227of javacardx.crypto.Cipher 238

init(PrivateKey)of javacard.security.KeyAgreement 183

INS_EXTERNAL_AUTHENTICATEof javacard.framework.ISO7816 78

INS_SELECTof javacard.framework.ISO7816 78

install(byte[], short, byte)of javacard.framework.Applet 65

INTERNAL_FAILUREof javacard.framework.TransactionException

107INVALID_INIT

of javacard.security.CryptoException 156IO_ERROR

of javacard.framework.APDUException 61IOException

of java.io 8IOException()

of java.io.IOException 8isAuthenticated(short)

of javacard.framework.service.SecurityService 140

isChannelSecure(byte)of javacard.framework.service.SecurityService

140isCommandSecure(byte)


isInitialized()of javacard.security.Key 180

ISO7816of javacard.framework 74

isObjectDeletionSupported()of javacard.framework.JCSystem 89

ISOExceptionof javacard.framework 79

ISOException(short)of javacard.framework.ISOException 80

isProcessed(APDU)of javacard.framework.service.BasicService 122

isTransient(Object)of javacard.framework.JCSystem 84

isValidated()of javacard.framework.OwnerPIN 96

of javacard.framework.PIN 98

Jjava.io

package 7java.lang

package 11java.rmi

package 33javacard.framework

package 37javacard.framework.service

package 117javacard.security

package 147javacardx.crypto

package 231JCSystem

of javacard.framework 81

KKey

of javacard.security 180KeyAgreement

of javacard.security 182KeyAgreement()

of javacard.security.KeyAgreement 183KeyBuilder

of javacard.security 185KeyEncryption

of javacardx.crypto 241KeyPair

of javacard.security 193KeyPair(byte, short)

of javacard.security.KeyPair 194KeyPair(PublicKey, PrivateKey)

of javacard.security.KeyPair 195

LLENGTH_AES_128

of javacard.security.KeyBuilder 191LENGTH_AES_192



LENGTH_AES_256of javacard.security.KeyBuilder 191

LENGTH_DESof javacard.security.KeyBuilder 189

LENGTH_DES3_2KEYof javacard.security.KeyBuilder 189

LENGTH_DES3_3KEYof javacard.security.KeyBuilder 189

LENGTH_DSA_1024of javacard.security.KeyBuilder 190



LENGTH_EC_F2M_113of javacard.security.KeyBuilder 190




LENGTH_EC_FP_112of javacard.security.KeyBuilder 190




LENGTH_RSA_1024of javacard.security.KeyBuilder 189









lookupAID(byte[], short, byte)

of javacard.framework.JCSystem 86

MmakeShort(byte, byte)

of javacard.framework.Util 115makeTransientBooleanArray(short, byte)

of javacard.framework.JCSystem 84makeTransientByteArray(short, byte)

of javacard.framework.JCSystem 84makeTransientObjectArray(short, byte)

of javacard.framework.JCSystem 85makeTransientShortArray(short, byte)

of javacard.framework.JCSystem 85MEMORY_TYPE_PERSISTENT

of javacard.framework.JCSystem 83MEMORY_TYPE_TRANSIENT_DESELECT

of javacard.framework.JCSystem 83MEMORY_TYPE_TRANSIENT_RESET

of javacard.framework.JCSystem 83MessageDigest

of javacard.security 197MessageDigest()

of javacard.security.MessageDigest 198MODE_DECRYPT

of javacardx.crypto.Cipher 236MODE_ENCRYPT

of javacardx.crypto.Cipher 236MODE_SIGN

of javacard.security.Signature 226MODE_VERIFY

of javacard.security.Signature 226MultiSelectable

of javacard.framework 91

NNegativeArraySizeException

of java.lang 23NegativeArraySizeException()

of java.lang.NegativeArraySizeException 23NO_RESOURCE

of javacard.framework.SystemException 104NO_SUCH_ALGORITHM

of javacard.security.CryptoException 156NO_T0_GETRESPONSE

of javacard.framework.APDUException 61

Index 269

NO_T0_REISSUEof javacard.framework.APDUException 61

NO_TRANSIENT_SPACEof javacard.framework.SystemException 104

NOT_A_TRANSIENT_OBJECTof javacard.framework.JCSystem 83

NOT_IN_PROGRESSof javacard.framework.TransactionException

107NullPointerException

of java.lang 24NullPointerException()

of java.lang.NullPointerException 25

OObject

of java.lang 26Object()

of java.lang.Object 26OFFSET_CDATA

of javacard.framework.ISO7816 78OFFSET_CLA

of javacard.framework.ISO7816 78OFFSET_INS

of javacard.framework.ISO7816 78OFFSET_LC

of javacard.framework.ISO7816 78OFFSET_P1

of javacard.framework.ISO7816 78OFFSET_P2

of javacard.framework.ISO7816 78OwnerPIN

of javacard.framework 93OwnerPIN(byte, byte)

of javacard.framework.OwnerPIN 94

PpartialEquals(byte[], short, byte)

of javacard.framework.AID 41PIN

of javacard.framework 97PINException

of javacard.framework 100PINException(short)

of javacard.framework.PINException 101

PRINCIPAL_APP_PROVIDERof javacard.framework.service.SecurityService

139PRINCIPAL_CARD_ISSUER


PRINCIPAL_CARDHOLDERof javacard.framework.service.SecurityService

139PrivateKey

of javacard.security 201process(APDU)

of javacard.framework.Applet 66of javacard.framework.service.Dispatcher 132

PROCESS_COMMANDof javacard.framework.service.Dispatcher 130

PROCESS_INPUT_DATAof javacard.framework.service.Dispatcher 130

PROCESS_NONEof javacard.framework.service.Dispatcher 130

PROCESS_OUTPUT_DATAof javacard.framework.service.Dispatcher 130

processCommand(APDU)of javacard.framework.service.BasicService 121of javacard.framework.service.RMIService 136of javacard.framework.service.Service 142

processDataIn(APDU)of javacard.framework.service.BasicService 121of javacard.framework.service.Service 141

processDataOut(APDU)of javacard.framework.service.BasicService 121of javacard.framework.service.Service 142

PROPERTY_INPUT_CONFIDENTIALITYof javacard.framework.service.SecurityService

139PROPERTY_INPUT_INTEGRITY


PROPERTY_OUTPUT_CONFIDENTIALITYof javacard.framework.service.SecurityService

139PROPERTY_OUTPUT_INTEGRITY


PROTOCOL_MEDIA_CONTACTLESS_TYPE_Aof javacard.framework.APDU 49

PROTOCOL_MEDIA_CONTACTLESS_TYPE_Bof javacard.framework.APDU 49

PROTOCOL_MEDIA_DEFAULT


of javacard.framework.APDU 49PROTOCOL_MEDIA_MASK

of javacard.framework.APDU 49PROTOCOL_MEDIA_USB

of javacard.framework.APDU 49PROTOCOL_T0

of javacard.framework.APDU 49PROTOCOL_T1

of javacard.framework.APDU 49PROTOCOL_TYPE_MASK

of javacard.framework.APDU 49PublicKey

of javacard.security 202

RRandomData

of javacard.security 203RandomData()

of javacard.security.RandomData 204receiveBytes(short)

of javacard.framework.APDU 52receiveInData(APDU)

of javacard.framework.service.BasicService 122register()

of javacard.framework.Applet 68register(byte[], short, byte)

of javacard.framework.Applet 68Remote

of java.rmi 34REMOTE_OBJECT_NOT_EXPORTED


RemoteExceptionof java.rmi 35

RemoteException()of java.rmi.RemoteException 35

RemoteServiceof javacard.framework.service 133

removeService(Service, byte)of javacard.framework.service.Dispatcher 131

requestObjectDeletion()of javacard.framework.JCSystem 89

reset()of javacard.framework.OwnerPIN 96of javacard.framework.PIN 98of javacard.security.MessageDigest 200

resetAndUnblock()

of javacard.framework.OwnerPIN 96RIDEquals(AID)

of javacard.framework.AID 42RMIService

of javacard.framework.service 134RMIService(Remote)

of javacard.framework.service.RMIService 135RSAPrivateCrtKey

of javacard.security 206RSAPrivateKey

of javacard.security 212RSAPublicKey

of javacard.security 215RuntimeException

of java.lang 28RuntimeException()

of java.lang.RuntimeException 28

SSecretKey

of javacard.security 218SecurityException

of java.lang 30SecurityException()

of java.lang.SecurityException 31SecurityService

of javacard.framework.service 138select()

of javacard.framework.Applet 67select(boolean)

of javacard.framework.MultiSelectable 91selectingApplet()

of javacard.framework.Applet 69of javacard.framework.service.BasicService 126

sendBytes(short, short)of javacard.framework.APDU 54

sendBytesLong(byte[], short, short)of javacard.framework.APDU 55

Serviceof javacard.framework.service 141

ServiceExceptionof javacard.framework.service 143

ServiceException(short)of javacard.framework.service.ServiceException

145setA(byte[], short, short)

of javacard.security.ECKey 170

Index 271

setB(byte[], short, short)of javacard.security.ECKey 171

setDP1(byte[], short, short)of javacard.security.RSAPrivateCrtKey 208

setDQ1(byte[], short, short)of javacard.security.RSAPrivateCrtKey 208

setExponent(byte[], short, short)of javacard.security.RSAPrivateKey 213of javacard.security.RSAPublicKey 216

setFieldF2M(short)of javacard.security.ECKey 169

setFieldF2M(short, short, short)of javacard.security.ECKey 170

setFieldFP(byte[], short, short)of javacard.security.ECKey 169

setG(byte[], short, short)of javacard.security.DSAKey 161of javacard.security.ECKey 171

setIncomingAndReceive()of javacard.framework.APDU 53

setInvokeInstructionByte(byte)of javacard.framework.service.RMIService 135

setK(short)of javacard.security.ECKey 172

setKey(byte[], short)of javacard.security.AESKey 149of javacard.security.DESKey 158

setKeyCipher(Cipher)of javacardx.crypto.KeyEncryption 241

setModulus(byte[], short, short)of javacard.security.RSAPrivateKey 212of javacard.security.RSAPublicKey 215

setOutgoing()of javacard.framework.APDU 51

setOutgoingAndSend(short, short)of javacard.framework.APDU 56

setOutgoingLength(short)of javacard.framework.APDU 52

setOutgoingNoChaining()of javacard.framework.APDU 51

setOutputLength(APDU, short)of javacard.framework.service.BasicService 123

setP(byte[], short, short)of javacard.security.DSAKey 160of javacard.security.RSAPrivateCrtKey 207

setPQ(byte[], short, short)of javacard.security.RSAPrivateCrtKey 209

setProcessed(APDU)of javacard.framework.service.BasicService 122

setQ(byte[], short, short)of javacard.security.DSAKey 161of javacard.security.RSAPrivateCrtKey 207

setR(byte[], short, short)of javacard.security.ECKey 172

setReason(short)of javacard.framework.CardException 71of javacard.framework.CardRuntimeException

73setS(byte[], short, short)

of javacard.security.ECPrivateKey 177setSeed(byte[], short, short)

of javacard.security.RandomData 205setShort(byte[], short, short)

of javacard.framework.Util 116setStatusWord(APDU, short)

of javacard.framework.service.BasicService 123setValidatedFlag(boolean)

of javacard.framework.OwnerPIN 95setW(byte[], short, short)

of javacard.security.ECPublicKey 179setX(byte[], short, short)

of javacard.security.DSAPrivateKey 164setY(byte[], short, short)

of javacard.security.DSAPublicKey 166Shareable

of javacard.framework 102sign(byte[], short, short, byte[], short)

of javacard.security.Signature 229Signature

of javacard.security 219Signature()

of javacard.security.Signature 226STATE_ERROR_IO

of javacard.framework.APDU 48STATE_ERROR_NO_T0_GETRESPONSE

of javacard.framework.APDU 48STATE_ERROR_NO_T0_REISSUE

of javacard.framework.APDU 49STATE_ERROR_T1_IFD_ABORT

of javacard.framework.APDU 48STATE_FULL_INCOMING

of javacard.framework.APDU 48STATE_FULL_OUTGOING

of javacard.framework.APDU 48STATE_INITIAL

of javacard.framework.APDU 47STATE_OUTGOING

of javacard.framework.APDU 48


STATE_OUTGOING_LENGTH_KNOWNof javacard.framework.APDU 48

STATE_PARTIAL_INCOMINGof javacard.framework.APDU 48

STATE_PARTIAL_OUTGOINGof javacard.framework.APDU 48

succeed(APDU)of javacard.framework.service.BasicService 124

succeedWithStatusWord(APDU, short)of javacard.framework.service.BasicService 124

SW_APPLET_SELECT_FAILEDof javacard.framework.ISO7816 76

SW_BYTES_REMAINING_00of javacard.framework.ISO7816 75

SW_CLA_NOT_SUPPORTEDof javacard.framework.ISO7816 77

SW_COMMAND_NOT_ALLOWEDof javacard.framework.ISO7816 76

SW_CONDITIONS_NOT_SATISFIEDof javacard.framework.ISO7816 76

SW_CORRECT_LENGTH_00of javacard.framework.ISO7816 77

SW_DATA_INVALIDof javacard.framework.ISO7816 76

SW_FILE_FULLof javacard.framework.ISO7816 77

SW_FILE_INVALIDof javacard.framework.ISO7816 76

SW_FILE_NOT_FOUNDof javacard.framework.ISO7816 76

SW_FUNC_NOT_SUPPORTEDof javacard.framework.ISO7816 76

SW_INCORRECT_P1P2of javacard.framework.ISO7816 77

SW_INS_NOT_SUPPORTEDof javacard.framework.ISO7816 77

SW_LOGICAL_CHANNEL_NOT_SUPPORTEDof javacard.framework.ISO7816 77

SW_NO_ERRORof javacard.framework.ISO7816 75

SW_RECORD_NOT_FOUNDof javacard.framework.ISO7816 76

SW_SECURE_MESSAGING_NOT_SUPPORTEDof javacard.framework.ISO7816 77

SW_SECURITY_STATUS_NOT_SATISFIEDof javacard.framework.ISO7816 76

SW_UNKNOWNof javacard.framework.ISO7816 77

SW_WARNING_STATE_UNCHANGED

of javacard.framework.ISO7816 77SW_WRONG_DATA

of javacard.framework.ISO7816 76SW_WRONG_LENGTH

of javacard.framework.ISO7816 75SW_WRONG_P1P2

of javacard.framework.ISO7816 77SystemException

of javacard.framework 103SystemException(short)

of javacard.framework.SystemException 105

TT1_IFD_ABORT

of javacard.framework.APDUException 61Throwable

of java.lang 32Throwable()

of java.lang.Throwable 32throwIt(short)

of javacard.framework.APDUException 61of javacard.framework.CardException 71of javacard.framework.CardRuntimeException

73of javacard.framework.ISOException 80of javacard.framework.PINException 101of javacard.framework.service.ServiceException

145of javacard.framework.SystemException 105of javacard.framework.TransactionException

108of javacard.framework.UserException 110of javacard.security.CryptoException 157

TransactionExceptionof javacard.framework 106

TransactionException(short)of javacard.framework.TransactionException

107TYPE_AES

of javacard.security.KeyBuilder 189TYPE_AES_TRANSIENT_DESELECT

of javacard.security.KeyBuilder 188TYPE_AES_TRANSIENT_RESET

of javacard.security.KeyBuilder 188TYPE_DES

of javacard.security.KeyBuilder 187TYPE_DES_TRANSIENT_DESELECT

Index 273

of javacard.security.KeyBuilder 187TYPE_DES_TRANSIENT_RESET

of javacard.security.KeyBuilder 187TYPE_DSA_PRIVATE

of javacard.security.KeyBuilder 188TYPE_DSA_PUBLIC

of javacard.security.KeyBuilder 188TYPE_EC_F2M_PRIVATE

of javacard.security.KeyBuilder 188TYPE_EC_F2M_PUBLIC

of javacard.security.KeyBuilder 188TYPE_EC_FP_PRIVATE

of javacard.security.KeyBuilder 188TYPE_EC_FP_PUBLIC

of javacard.security.KeyBuilder 188TYPE_RSA_CRT_PRIVATE

of javacard.security.KeyBuilder 188TYPE_RSA_PRIVATE

of javacard.security.KeyBuilder 187TYPE_RSA_PUBLIC


Uunexport(Remote)

of javacard.framework.service.CardRemoteObject 128

UNINITIALIZED_KEYof javacard.security.CryptoException 156

update(byte[], short, byte)of javacard.framework.OwnerPIN 96

update(byte[], short, short)of javacard.security.Checksum 154of javacard.security.MessageDigest 199of javacard.security.Signature 228

update(byte[], short, short, byte[], short)of javacardx.crypto.Cipher 239

UserExceptionof javacard.framework 109

UserException()of javacard.framework.UserException 110

UserException(short)of javacard.framework.UserException 110

Utilof javacard.framework 111

Vverify(byte[], short, short, byte[], short, short)

of javacard.security.Signature 229

WwaitExtension()

of javacard.framework.APDU 58


Java Card API

Documents

Transcript of Java Card API