Java Card 2.2.1 API

304 Pages·2003·2.57 MB·English

Application Programming Interface
Java Card™ Platform, Version 2.2.1
Sun Microsystems, Inc.
4150 Network Circle
Santa Clara, California 95054
U.S.A. 650-960-1300
October 21, 2003
JavaCard™Specification(“Specification”)
Version:2.2.1
Status:FCS
Release:October29,2003
Copyright2003SunMicrosystems,Inc.
4150NetworkCircle,SantaClara,California95054,U.S.A
Allrightsreserved.
NOTICE
TheSpecificationisprotectedbycopyrightandtheinformationdescribedthereinmaybeprotectedbyoneormoreU.S.patents,foreignpatents,or
pendingapplications.Exceptasprovidedunderthefollowinglicense,nopartoftheSpecificationmaybereproducedinanyformbyanymeanswithout
thepriorwrittenauthorizationofSunMicrosystems,Inc.(“Sun”)anditslicensors,ifany.AnyuseoftheSpecificationandtheinformationdescribed
thereinwillbegovernedbythetermsandconditionsofthislicenseandtheExportControlGuidelinesassetforthintheTermsofUseonSun'swebsite.By
viewing,downloadingorotherwisecopyingtheSpecification,youagreethatyouhaveread,understood,andwillcomplywithallofthetermsand
conditionssetforthherein.
Subjecttothetermsandconditionsofthislicense,Sunherebygrantsyouafully-paid,non-exclusive,non-transferable,worldwide,limitedlicense
(withouttherighttosublicense)underSun'sintellectualpropertyrightstoreviewtheSpecificationinternallysolelyforthepurposesofdesigningand
developingyourimplementationoftheSpecificationanddesigninganddevelopingyourappletsandapplicationsintendedtorunontheJavaCard
platform.Otherthanthislimitedlicense,youacquirenoright,titleorinterestinortotheSpecificationoranyotherSunintellectualproperty.You
acknowledgethatanycommercialorproductiveuseofanimplementationoftheSpecificationrequiresseparateandappropriatelicensingagreements.
TheSpecificationcontainstheproprietaryinformationofSunandmayonlybeusedinaccordancewiththelicensetermssetforthherein.Thislicensewill
terminateimmediatelywithoutnoticefromSunifyoufailtocomplywithanyprovisionofthislicense.Uponterminationorexpirationofthislicense,you
mustceaseuseofordestroytheSpecification.
TRADEMARKS
Noright,title,orinterestinortoanytrademarks,servicemarks,ortradenamesofSunorSun'slicensorsisgrantedhereunder.Sun,SunMicrosystems,the
Sunlogo,Java,JavaCard,andJavaCardCompatiblearetrademarksorregisteredtrademarksofSunMicrosystems,Inc.intheU.S.andothercountries.
DISCLAIMEROFWARRANTIES
THESPECIFICATIONISPROVIDED“ASIS”ANDISEXPERIMENTALANDMAYCONTAINDEFECTSORDEFICIENCIESWHICHCANNOTOR
WILLNOTBECORRECTEDBYSUN.SUNMAKESNOREPRESENTATIONSORWARRANTIES,EITHEREXPRESSORIMPLIED,INCLUDINGBUT
NOTLIMITEDTO,WARRANTIESOFMERCHANTABILITY,FITNESSFORAPARTICULARPURPOSE,ORNON-INFRINGEMENTTHATTHE
CONTENTSOFTHESPECIFICATIONARESUITABLEFORANYPURPOSEORTHATANYPRACTICEORIMPLEMENTATIONOFSUCH
CONTENTSWILLNOTINFRINGEANYTHIRDPARTYPATENTS,COPYRIGHTS,TRADESECRETSOROTHERRIGHTS.Thisdocumentdoesnot
representanycommitmenttoreleaseorimplementanyportionoftheSpecificationinanyproduct.
THESPECIFICATIONCOULDINCLUDETECHNICALINACCURACIESORTYPOGRAPHICALERRORS.CHANGESAREPERIODICALLYADDED
TOTHEINFORMATIONTHEREIN;THESECHANGESWILLBEINCORPORATEDINTONEWVERSIONSOFTHESPECIFICATION,IFANY.SUN
MAYMAKEIMPROVEMENTSAND/ORCHANGESTOTHEPRODUCT(S)AND/ORTHEPROGRAM(S)DESCRIBEDINTHESPECIFICATIONAT
ANYTIME.AnyuseofsuchchangesintheSpecificationwillbegovernedbythethen-currentlicensefortheapplicableversionoftheSpecification.
LIMITATIONOFLIABILITY
TOTHEEXTENTNOTPROHIBITEDBYLAW,INNOEVENTWILLSUNORITSLICENSORSBELIABLEFORANYDAMAGES,INCLUDING
WITHOUTLIMITATION,LOSTREVENUE,PROFITSORDATA,ORFORSPECIAL,INDIRECT,CONSEQUENTIAL,INCIDENTALORPUNITIVE
DAMAGES,HOWEVERCAUSEDANDREGARDLESSOFTHETHEORYOFLIABILITY,ARISINGOUTOFORRELATEDTOANYFURNISHING,
PRACTICING,MODIFYINGORANYUSEOFTHESPECIFICATION,EVENIFSUNAND/ORITSLICENSORSHAVEBEENADVISEDOFTHE
POSSIBILITYOFSUCHDAMAGES.
Youwillindemnify,holdharmless,anddefendSunanditslicensorsfromanyclaimsarisingorresultingfrom:(i)youruseoftheSpecification;(ii)theuse
ordistributionofyourJavaapplicationsorapplets;and/or(iii)anyclaimsthatlaterversionsorreleasesofanySpecificationfurnishedtoyouare
incompatiblewiththeSpecificationprovidedtoyouunderthislicense.
RESTRICTEDRIGHTSLEGEND
IfthisSoftwareisbeingacquiredbyoronbehalfoftheU.S.GovernmentorbyaU.S.Governmentprimecontractororsubcontractor(atanytier),thenthe
Government'srightsintheSoftwareandaccompanyingdocumentationshallbeonlyassetforthinthislicense;thisisinaccordancewith48C.F.R.227.
7201through227.7202-4(forDepartmentofDefense(DoD)acquisitions)andwith48C.F.R.2.101and12.212(fornon-DoDacquisitions).
REPORT
Youmaywishtoreportanyambiguities,inconsistenciesorinaccuraciesyoumayfindinconnectionwithyourevaluationoftheSpecification
(“Feedback”).TotheextentthatyouprovideSunwithanyFeedback,youhereby:(i)agreethatsuchFeedbackisprovidedonanon-proprietaryandnon-
confidentialbasis,and(ii)grantSunaperpetual,non-exclusive,worldwide,fullypaid-up,irrevocablelicense,withtherighttosublicensethrough
multiplelevelsofsublicensees,toincorporate,disclose,andusewithoutlimitationtheFeedbackforanypurposerelatedtotheSpecificationandfuture
versions,implementations,andtestsuitesthereof.
.
ii Application Programming Interface, Java Card Platform, Version 2.2.1 • October 21, 2003
Contents
1 Overview ......................................................................................................... 1
2 java.io .............................................................................................................. 5
IOException ................................................................................................................................................ 6
3 java.lang .......................................................................................................... 9
ArithmeticException ................................................................................................................................. 11
ArrayIndexOutOfBoundsException.......................................................................................................... 13
ArrayStoreException ................................................................................................................................. 15
ClassCastException ................................................................................................................................... 17
Exception .................................................................................................................................................. 19
IndexOutOfBoundsException ................................................................................................................... 20
NegativeArraySizeException .................................................................................................................... 22
NullPointerException ................................................................................................................................ 24
Object ........................................................................................................................................................ 26
RuntimeException ..................................................................................................................................... 28
SecurityException ..................................................................................................................................... 30
Throwable ................................................................................................................................................. 32
4 java.rmi ......................................................................................................... 33
Remote ...................................................................................................................................................... 34
RemoteException ...................................................................................................................................... 35
5 javacard.framework .................................................................................... 37
AID............................................................................................................................................................ 39
APDU ........................................................................................................................................................ 44
APDUException........................................................................................................................................ 60
Applet ........................................................................................................................................................ 64
AppletEvent .............................................................................................................................................. 71
CardException ........................................................................................................................................... 73
CardRuntimeException ............................................................................................................................. 76
ISO7816 .................................................................................................................................................... 79
ISOException ............................................................................................................................................ 86
JCSystem................................................................................................................................................... 88
MultiSelectable ......................................................................................................................................... 99
OwnerPIN ............................................................................................................................................... 101
PIN .......................................................................................................................................................... 106
PINException .......................................................................................................................................... 109
Shareable ................................................................................................................................................. 112
SystemException ..................................................................................................................................... 113
TransactionException.............................................................................................................................. 117
UserException ......................................................................................................................................... 120
Util .......................................................................................................................................................... 122
6 javacard.framework.service ..................................................................... 129
BasicService ............................................................................................................................................ 131
CardRemoteObject .................................................................................................................................. 140
Dispatcher ............................................................................................................................................... 142
RemoteService ........................................................................................................................................ 147
RMIService ............................................................................................................................................. 148
iii
Contents
SecurityService ....................................................................................................................................... 152
Service ..................................................................................................................................................... 156
ServiceException .................................................................................................................................... 158
7 javacard.security ........................................................................................ 163
AESKey .................................................................................................................................................. 165
Checksum ................................................................................................................................................ 167
CryptoException ..................................................................................................................................... 171
DESKey .................................................................................................................................................. 174
DSAKey .................................................................................................................................................. 176
DSAPrivateKey ....................................................................................................................................... 180
DSAPublicKey ........................................................................................................................................ 182
ECKey ..................................................................................................................................................... 184
ECPrivateKey.......................................................................................................................................... 192
ECPublicKey ........................................................................................................................................... 194
Key .......................................................................................................................................................... 197
KeyAgreement ........................................................................................................................................ 199
KeyBuilder .............................................................................................................................................. 203
KeyPair.................................................................................................................................................... 212
MessageDigest ........................................................................................................................................ 217
PrivateKey ............................................................................................................................................... 221
PublicKey ................................................................................................................................................ 222
RandomData............................................................................................................................................ 223
RSAPrivateCrtKey .................................................................................................................................. 226
RSAPrivateKey ....................................................................................................................................... 232
RSAPublicKey ........................................................................................................................................ 235
SecretKey ................................................................................................................................................ 238
Signature ................................................................................................................................................. 239
8 javacardx.crypto ........................................................................................ 253
Cipher ...................................................................................................................................................... 254
KeyEncryption ........................................................................................................................................ 264
Almanac ...................................................................................................... 269
Index ........................................................................................................... 289
iv Application Programming Interface, Java Card Platform, Version 2.2.1 • October 21, 2003
1
C H A P T E R
Overview
Description
This document is the specification for the Java Card 2.2.1 Application Programming Interface.
Java Card 2.2.1 API Notes
Referenced Standards
ISO - International Standards Organization
• Information Technology - Identification cards - integrated circuit cards with contacts: ISO 7816
• InformationTechnology-SecurityTechniques-DigitalSignatureSchemeGivingMessageRecovery: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
IPSec
• The Internet Key Exchange ( IKE ) document RFC 2409 (STD 1)
ANSI
• Public Key Cryptography for the Financial Industry: The Elliptic Curve Digital Signature Algorithm
(ECDSA): X9.62-1998
IEEE
• StandardSpecificationsforPublicKeyCryptography,InstituteofElectricalandElectronicEngineers,2000
: IEEE 1363
FIPS
• Advanced 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-
1
Overview
Parameter Checking
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.
Parameter Checking
Policy
All 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 Policy
In 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.
Note—Ifmultipleerroneousinputparametersexist,anyoneofseveralruntimeexceptionswillbethrownbythe
VM. Java programmers rely on this behavior, but they do not rely on getting a specific exception. It is not
necessary(norisitreasonableorpractical)todocumentthepreciseerrorhandlingforallpossiblecombinations
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 Summary
Packages
java.io A subset of thejava.io package in the standard Java programming language.
2 Application Programming Interface, Java Card Platform, Version 2.2.1 • October 21, 2003
Overview
Class Hierarchy
Package Summary
java.lang Provides classes that are fundamental to the design of the Java Card technology subset
of the Java programming language.
java.rmi Thejava.rmi package defines theRemote interface which identifies interfaces
whosemethodscanbeinvokedfromcardacceptancedevice(CAD)clientapplications.
javacard.framework Provides a framework of classes and interfaces for building, communicating with and
working with Java Card technology-based applets.
javacard.framework. Provides a service framework of classes and interfaces that allow a Java Card
service technology-based 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 the Java Card platform.
javacardx.crypto Extensionpackagethatcontainsfunctionality,whichmaybesubjecttoexportcontrols,
for implementing a security and cryptography framework on the Java Card platform.
Class Hierarchy
java.lang.Object
javacard.framework.AID
javacard.framework.APDU
javacard.framework.Applet
javacard.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.Checksum
javacardx.crypto.Cipher
javacard.framework.service.Dispatcher
javacard.framework.JCSystem
javacard.security.KeyAgreement
javacard.security.KeyBuilder
javacard.security.KeyPair
javacard.security.MessageDigest
javacard.framework.OwnerPIN (implements javacard.framework.PIN)
javacard.security.RandomData
javacard.security.Signature
java.lang.Throwable
java.lang.Exception
javacard.framework.CardException
javacard.framework.UserException
java.io.IOException
java.rmi.RemoteException
java.lang.RuntimeException
java.lang.ArithmeticException
java.lang.ArrayStoreException
javacard.framework.CardRuntimeException
javacard.framework.APDUException
javacard.security.CryptoException
javacard.framework.ISOException
javacard.framework.PINException
javacard.framework.service.ServiceException
javacard.framework.SystemException
javacard.framework.TransactionException
java.lang.ClassCastException
java.lang.IndexOutOfBoundsException
java.lang.ArrayIndexOutOfBoundsException
java.lang.NegativeArraySizeException
java.lang.NullPointerException
java.lang.SecurityException
javacard.framework.Util
Overview 3
Overview
Interface Hierarchy
Interface Hierarchy
javacard.framework.AppletEvent
javacard.security.DSAKey
javacard.security.DSAPrivateKey
javacard.security.DSAPublicKey
javacard.security.ECKey
javacard.security.ECPrivateKey
javacard.security.ECPublicKey
javacard.framework.ISO7816
javacard.security.Key
javacard.security.PrivateKey
javacard.security.DSAPrivateKey
javacard.security.ECPrivateKey
javacard.security.RSAPrivateCrtKey
javacard.security.RSAPrivateKey
javacard.security.PublicKey
javacard.security.DSAPublicKey
javacard.security.ECPublicKey
javacard.security.RSAPublicKey
javacard.security.SecretKey
javacard.security.AESKey
javacard.security.DESKey
javacardx.crypto.KeyEncryption
javacard.framework.MultiSelectable
javacard.framework.PIN
java.rmi.Remote
javacard.framework.service.Service
javacard.framework.service.RemoteService
javacard.framework.service.SecurityService
javacard.framework.Shareable
4 Application Programming Interface, Java Card Platform, Version 2.2.1 • October 21, 2003
2
C H A P T E R
Package
java.io
Description
A subset of thejava.io package in the standard Java programming language.
Thejava.io.IOException class is included in the Java Card API to maintain a hierarchy of exceptions
identicaltothestandardJavaprogramminglanguage.Thejava.io.IOExceptionclassisthesuperclassof
java.rmi.RemoteException, that indicates an exception occurred during a remote method call.
Class Summary
Exceptions
IOException A Java Card runtime environment-owned instance ofIOException is thrown to
signal that an I/O exception of some sort has occurred.
5
IOException java.io
Declaration
java.io
IOException
Declaration
public class IOException extends java.lang.Exception
java.lang.Object
|
+--java.lang.Throwable
|
+--java.lang.Exception
|
+--java.io.IOException
Direct Known Subclasses: java.rmi.RemoteException
Description
A Java Card runtime environment-owned instance ofIOException 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.
Java Card runtime environment-owned instances of exception classes are temporary Java Card runtime
environment Entry Point Objects and can be accessed from any applet context. References to these temporary
objectscannotbestoredinclassvariablesorinstancevariablesorarraycomponents.SeeRuntimeSpecification
for the Java Card Platform, section 6.2.1 for details.
This Java Card platform class’s functionality is a strict subset of the definition in theJava 2 Platform Standard
Edition API Specification.
Member Summary
Constructors
IOException()
Constructs anIOException.
Inherited Member Summary
Methods inherited from classObject
equals(Object)
6 Application Programming Interface, Java Card Platform, Version 2.2.1 • October 21, 2003