0% found this document useful (0 votes)

2K views219 pages

GP Systems Scripting Language 1.1.0 (FINAL)

Uploaded by

奇刘

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

2K views219 pages

GP Systems Scripting Language 1.1.0 (FINAL)

Uploaded by

奇刘

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 219

GlobalPlatform Systems

Scripting Language Specification

An ECMAScript Representation
Version 1.1.0
24 September 2003

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Table of Contents
1. INTRODUCTION....................................................................................................................................... 1
1.1 SUMMARY ......................................................................................................................................... 1
1.2 SCOPE ............................................................................................................................................. 1
1.3 AUDIENCE ........................................................................................................................................ 2
1.4 NORMATIVE REFERENCES ................................................................................................................. 2
1.4.1 List of References ................................................................................................................... 2
1.4.2 GlobalPlatform Document Navigation ..................................................................................... 5
1.5 TERMINOLOGY AND DEFINITIONS ....................................................................................................... 5
1.6 ABBREVIATIONS AND NOTATIONS ..................................................................................................... 11
1.7 CONVENTIONS ................................................................................................................................ 12
1.8 REVISIONS HISTORY ....................................................................................................................... 12
1.8.1 Overview of Changes in Version 1.1.0 over Version 1.0 ...................................................... 12
2. OVERVIEW............................................................................................................................................. 16
2.1 GLOBALPLATFORM INITIATIVE .......................................................................................................... 16
2.2 GLOBALPLATFORM CARD CUSTOMIZATION REQUIREMENTS .............................................................. 17
3. ECMASCRIPT LANGUAGE CHOICE.................................................................................................... 19
4. GLOBALPLATFORM SCRIPTS OVERVIEW........................................................................................ 21
4.1 SCRIPT LANGUAGE ......................................................................................................................... 21
4.2 SCRIPT PROCESSING ...................................................................................................................... 21
4.2.1 Creating Objects for an Application (excluding Security Domain) ........................................ 23
4.2.2 Creating Objects for a Security Domain Application (including Card Manager) ................... 26
4.2.3 Creating Objects for a Smart Card ........................................................................................ 32
4.3 SCRIPT OBJECT CATEGORIES .......................................................................................................... 34
4.3.1 Overview of GP Scripting Language Native ECMAScript Objects........................................ 34
4.4 DESERIALIZING PROFILE XML CONTENT INTO SCRIPTING OBJECTS .................................................. 42
4.4.1 Deserializing the XML Documents into the Profile Property ................................................. 42
4.4.1.1 Deserialization of Elements with Multiple Occurrances ................................................. 43
4.4.2 Deserializing DataElement and Declaration Elements into the Data Property ..................... 45
4.4.2.1 Impact of the ReadWrite Attribute on Deserialization .................................................... 47
4.4.2.2 Impact of the Encoding Attribute on Deserializiation ..................................................... 47
4.4.2.3 Impact of the Tag Attribute on Deserializiation .............................................................. 47
4.4.2.4 Impact of the Value, External and Optional Attributes on Deserializiation .................... 48
4.4.2.5 Executing Successive Scripts and Data Scoping Between Scripts ............................... 49
4.4.3 Deserializing Key and KeyDeclaration Elements into the Key Property ............................... 50
4.4.3.1 Executing Successive Scripts and Key Scoping Between Scripts................................. 51
4.4.4 Deserializing Function Elements into Scripting Language Functions ................................... 51
4.5 CREATING AND USING SECURE CHANNEL OBJECTS .......................................................................... 52
4.5.1 Creating Secure Channel Objects......................................................................................... 52
4.5.2 Opening Secure Channels .................................................................................................... 52

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4.5.3 Using Secure Channels......................................................................................................... 53

5. GLOBAL GP SCRIPTING LANGUAGE CONSTANTS......................................................................... 54
6. GLOBALPLATFORM OBJECT ERROR HANDLING ........................................................................... 55
7. GLOBALPLATFORM SCRIPTING OBJECTS ...................................................................................... 56
7.1 GP SCRIPTING LANGUAGE NATIVE ECMASCRIPT OBJECTS ............................................................. 56
7.1.1 GPError ................................................................................................................................. 58
7.1.1.1 Summary ........................................................................................................................58
7.1.1.2 Constants ....................................................................................................................... 58
7.1.1.3 Properties ....................................................................................................................... 58
7.1.1.3.1 className.................................................................................................................. 58
7.1.1.3.2 error............................................................................................................................ 59
7.1.1.3.3 message..................................................................................................................... 59
7.1.1.3.4 name .......................................................................................................................... 59
7.1.1.3.5 reason ........................................................................................................................ 59
7.1.1.4 Methods.......................................................................................................................... 59
7.1.1.4.1 Constructor................................................................................................................. 59
7.1.2 Crypto .................................................................................................................................... 60
7.1.2.1 Summary ........................................................................................................................60
7.1.2.2 Constants ....................................................................................................................... 60
7.1.2.3 Properties ....................................................................................................................... 61
7.1.2.4 Methods.......................................................................................................................... 61
7.1.2.4.1 Constructor() .............................................................................................................. 61
7.1.2.4.2 decrypt() ..................................................................................................................... 61
7.1.2.4.3 decryptEncrypt() ......................................................................................................... 62
7.1.2.4.4 deriveKey() ................................................................................................................. 63
7.1.2.4.5 digest() .......................................................................................................................64
7.1.2.4.6 encrypt() ..................................................................................................................... 64
7.1.2.4.7 generateKey()............................................................................................................. 65
7.1.2.4.8 generateKeyPair() ...................................................................................................... 65
7.1.2.4.9 generateRandom() ..................................................................................................... 66
7.1.2.4.10 sign() ........................................................................................................................ 66
7.1.2.4.11 unwrap() ................................................................................................................... 67
7.1.2.4.12 unwrapWrap()........................................................................................................... 68
7.1.2.4.13 verify() ...................................................................................................................... 69
7.1.2.4.14 wrap() ....................................................................................................................... 69
7.1.3 GPSystem ............................................................................................................................. 71
7.1.3.1 Summary ........................................................................................................................71
7.1.3.2 Constants ....................................................................................................................... 71
7.1.3.3 Properties ....................................................................................................................... 71
7.1.3.4 Methods.......................................................................................................................... 71
7.1.3.4.1 Constructor................................................................................................................. 71
7.1.3.4.2 dateTimeByteString() ................................................................................................. 71
7.1.3.4.3 getSystemID() ............................................................................................................ 72

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.3.4.4 getVendorObject() ...................................................................................................... 72

7.1.3.4.5 getVersion()................................................................................................................ 73
7.1.3.4.6 trace() ......................................................................................................................... 73
7.1.3.4.7 wait()........................................................................................................................... 74
7.1.4 Application ............................................................................................................................. 75
7.1.4.1 Summary ........................................................................................................................75
7.1.4.2 Constants ....................................................................................................................... 75
7.1.4.3 Properties ....................................................................................................................... 75
7.1.4.3.1 aid............................................................................................................................... 75
7.1.4.3.2 card ............................................................................................................................ 76
7.1.4.3.3 crypto.......................................................................................................................... 76
7.1.4.3.4 data[] .......................................................................................................................... 76
7.1.4.3.5 key[]............................................................................................................................ 76
7.1.4.3.6 lifecycle.name............................................................................................................. 77
7.1.4.3.7 lifecycle.value ............................................................................................................. 77
7.1.4.3.8 order ........................................................................................................................... 77
7.1.4.3.9 profile.......................................................................................................................... 77
7.1.4.3.10 secureChannel ......................................................................................................... 77
7.1.4.4 Methods.......................................................................................................................... 78
7.1.4.4.1 Constructor................................................................................................................. 78
7.1.4.4.2 openSecureChannel() ................................................................................................ 78
7.1.4.4.3 select()........................................................................................................................ 78
7.1.4.4.4 sendApdu()................................................................................................................. 79
7.1.5 GPApplication........................................................................................................................ 81
7.1.5.1 Summary ........................................................................................................................81
7.1.5.2 Constants ....................................................................................................................... 81
7.1.5.3 Properties ....................................................................................................................... 82
7.1.5.3.1 aid............................................................................................................................... 82
7.1.5.3.2 appSpecificInstallParams........................................................................................... 82
7.1.5.3.3 card ............................................................................................................................ 82
7.1.5.3.4 crypto.......................................................................................................................... 82
7.1.5.3.5 data[] .......................................................................................................................... 82
7.1.5.3.6 key[]............................................................................................................................ 83
7.1.5.3.7 lifecycle.name............................................................................................................. 83
7.1.5.3.8 lifecycle.value ............................................................................................................. 83
7.1.5.3.9 nonVolatileDataSpaceLimit ........................................................................................ 84
7.1.5.3.10 order ......................................................................................................................... 84
7.1.5.3.11 privilege .................................................................................................................... 84
7.1.5.3.12 profile........................................................................................................................ 84
7.1.5.3.13 securityDomain ........................................................................................................ 85
7.1.5.3.14 volatileDataSpaceLimit............................................................................................. 85
7.1.5.4 Methods.......................................................................................................................... 85
7.1.5.4.1 Constructor................................................................................................................. 85
7.1.5.4.2 getData() .................................................................................................................... 85
7.1.5.4.3 getStatus().................................................................................................................. 86

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.5.4.4 putKey()...................................................................................................................... 86
7.1.5.4.5 select()........................................................................................................................ 88
7.1.5.4.6 sendApdu()................................................................................................................. 89
7.1.5.4.7 setStatus() .................................................................................................................. 90
7.1.5.4.8 storeData() ................................................................................................................. 91
7.1.6 GPSecurityDomain................................................................................................................ 92
7.1.6.1 Summary ........................................................................................................................92
7.1.6.2 Constants ....................................................................................................................... 93
7.1.6.3 Properties ....................................................................................................................... 93
7.1.6.3.1 aid............................................................................................................................... 93
7.1.6.3.2 appSpecificInstallParams........................................................................................... 93
7.1.6.3.3 card ............................................................................................................................ 93
7.1.6.3.4 crypto.......................................................................................................................... 93
7.1.6.3.5 data[] .......................................................................................................................... 93
7.1.6.3.6 key[]............................................................................................................................ 94
7.1.6.3.7 lifecycle.name............................................................................................................. 94
7.1.6.3.8 lifecycle.value ............................................................................................................. 94
7.1.6.3.9 nonVolatileDataSpaceLimit ........................................................................................ 95
7.1.6.3.10 order ......................................................................................................................... 95
7.1.6.3.11 privilege .................................................................................................................... 95
7.1.6.3.12 profile........................................................................................................................ 95
7.1.6.3.13 secureChannel ......................................................................................................... 96
7.1.6.3.14 securityDomain ........................................................................................................ 96
7.1.6.3.15 volatileDataSpaceLimit............................................................................................. 96
7.1.6.4 Methods.......................................................................................................................... 96
7.1.6.4.1 Constructor................................................................................................................. 96
7.1.6.4.2 deleteAID() ................................................................................................................. 96
7.1.6.4.3 getData() .................................................................................................................... 97
7.1.6.4.4 getStatus().................................................................................................................. 97
7.1.6.4.5 installForExtradition() ................................................................................................. 98
7.1.6.4.6 installForInstall() ......................................................................................................... 99
7.1.6.4.7 installForInstallAndSelectable().................................................................................. 99
7.1.6.4.8 installForLoad() ........................................................................................................ 100
7.1.6.4.9 installForPersonalization()........................................................................................ 101
7.1.6.4.10 load() ...................................................................................................................... 101
7.1.6.4.11 loadByName() ........................................................................................................ 102
7.1.6.4.12 loadWithProfile()..................................................................................................... 103
7.1.6.4.13 openSecureChannel() ............................................................................................ 104
7.1.6.4.14 putKey().................................................................................................................. 105
7.1.6.4.15 select().................................................................................................................... 106
7.1.6.4.16 sendApdu().............................................................................................................107
7.1.6.4.17 setStatus() .............................................................................................................. 108
7.1.6.4.18 storeData() ............................................................................................................. 108
7.1.7 SecureChannel.................................................................................................................... 110
7.1.7.1 Summary ...................................................................................................................... 110

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.7.2 Constants ..................................................................................................................... 110

7.1.7.3 Properties .....................................................................................................................110
7.1.7.3.1 crypto........................................................................................................................ 110
7.1.7.3.2 state..........................................................................................................................110
7.1.8 GPScp01 ............................................................................................................................. 111
7.1.8.1 Summary ...................................................................................................................... 111
7.1.8.2 Constants ..................................................................................................................... 111
7.1.8.3 Properties .....................................................................................................................111
7.1.8.3.1 cardChallenge .......................................................................................................... 111
7.1.8.3.2 cardCryptogram........................................................................................................ 111
7.1.8.3.3 crypto........................................................................................................................ 112
7.1.8.3.4 diversificationData.................................................................................................... 112
7.1.8.3.5 hostChallenge .......................................................................................................... 112
7.1.8.3.6 keyIndex ................................................................................................................... 112
7.1.8.3.7 keyVersion................................................................................................................ 112
7.1.8.3.8 mac........................................................................................................................... 112
7.1.8.3.9 option........................................................................................................................ 112
7.1.8.3.10 securityLevel .......................................................................................................... 113
7.1.8.3.11 state........................................................................................................................ 113
7.1.8.4 Methods........................................................................................................................113
7.1.8.4.1 Constructor............................................................................................................... 113
7.1.8.4.2 decryptEncryptKek()................................................................................................. 113
7.1.8.4.3 encryptKek() ............................................................................................................. 114
7.1.8.4.4 externalAuthenticate() .............................................................................................. 114
7.1.8.4.5 getDekKey() ............................................................................................................. 115
7.1.8.4.6 initializeUpdate()....................................................................................................... 115
7.1.8.4.7 setDekKey().............................................................................................................. 115
7.1.8.4.8 setEncKey().............................................................................................................. 116
7.1.8.4.9 setMacKey() ............................................................................................................. 116
7.1.8.4.10 unwrapWrapKek() .................................................................................................. 116
7.1.9 GPScp02 ............................................................................................................................. 118
7.1.9.1 Summary ...................................................................................................................... 118
7.1.9.2 Constants ..................................................................................................................... 118
7.1.9.3 Properties .....................................................................................................................118
7.1.9.3.1 cardChallenge .......................................................................................................... 118
7.1.9.3.2 cardCryptogram........................................................................................................ 118
7.1.9.3.3 crypto........................................................................................................................ 119
7.1.9.3.4 diversificationData.................................................................................................... 119
7.1.9.3.5 hostChallenge .......................................................................................................... 119
7.1.9.3.6 keyVersion................................................................................................................ 119
7.1.9.3.7 option........................................................................................................................ 119
7.1.9.3.8 rmac ......................................................................................................................... 119
7.1.9.3.9 securityLevel ............................................................................................................ 119
7.1.9.3.10 sequenceCounter................................................................................................... 120
7.1.9.3.11 smac....................................................................................................................... 120

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.9.3.12 state........................................................................................................................ 120

7.1.9.4 Methods........................................................................................................................120
7.1.9.4.1 Constructor............................................................................................................... 120
7.1.9.4.2 beginRMac()............................................................................................................. 120
7.1.9.4.3 decryptEncryptDek() ................................................................................................ 121
7.1.9.4.4 encryptDek()............................................................................................................. 121
7.1.9.4.5 endRMac()................................................................................................................ 122
7.1.9.4.6 externalAuthenticate() .............................................................................................. 122
7.1.9.4.7 getDekKey() ............................................................................................................. 123
7.1.9.4.8 initializeUpdate()....................................................................................................... 123
7.1.9.4.9 setBaseKey()............................................................................................................ 123
7.1.9.4.10 setDekKey()............................................................................................................ 124
7.1.9.4.11 setEncKey()............................................................................................................ 124
7.1.9.4.12 setMacKey() ........................................................................................................... 124
7.1.9.4.13 unwrapWrapDek() .................................................................................................. 125
7.1.10 Card..................................................................................................................................... 126
7.1.10.1 Summary ...................................................................................................................... 126
7.1.10.2 Constants ..................................................................................................................... 126
7.1.10.3 Properties .....................................................................................................................126
7.1.10.3.1 profile...................................................................................................................... 126
7.1.10.3.2 response................................................................................................................. 127
7.1.10.3.3 SW.......................................................................................................................... 127
7.1.10.3.4 SW1........................................................................................................................ 127
7.1.10.3.5 SW2........................................................................................................................ 128
7.1.10.4 Methods........................................................................................................................128
7.1.10.4.1 Constructor............................................................................................................. 128
7.1.10.4.2 baudRate() .............................................................................................................128
7.1.10.4.3 clock()..................................................................................................................... 128
7.1.10.4.4 powerDown() .......................................................................................................... 129
7.1.10.4.5 pps() ....................................................................................................................... 129
7.1.10.4.6 reset() ..................................................................................................................... 130
7.1.10.4.7 sendApdu().............................................................................................................130
7.1.10.4.8 vcc()........................................................................................................................ 131
7.1.11 Key ...................................................................................................................................... 133
7.1.11.1 Summary ...................................................................................................................... 133
7.1.11.2 Constants ..................................................................................................................... 134
7.1.11.3 Properties .....................................................................................................................134
7.1.11.4 Methods........................................................................................................................134
7.1.11.4.1 Constructor............................................................................................................. 134
7.1.11.4.2 getAttribute()........................................................................................................... 135
7.1.11.4.3 getComponent() ..................................................................................................... 135
7.1.11.4.4 getEnd().................................................................................................................. 136
7.1.11.4.5 getKcv() .................................................................................................................. 136
7.1.11.4.6 getOwner() .............................................................................................................136
7.1.11.4.7 getProfileID() .......................................................................................................... 137

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.11.4.8 getSize() .................................................................................................................137

7.1.11.4.9 getStart() ................................................................................................................ 138
7.1.11.4.10 getType() .............................................................................................................. 138
7.1.11.4.11 getUsage()............................................................................................................ 138
7.1.11.4.12 getVersion().......................................................................................................... 139
7.1.11.4.13 getWrapKey() ....................................................................................................... 139
7.1.11.4.14 setAttribute()......................................................................................................... 140
7.1.11.4.15 setComponent() ................................................................................................... 140
7.1.11.4.16 setEnd()................................................................................................................141
7.1.11.4.17 setOwner()............................................................................................................ 141
7.1.11.4.18 setSize() ............................................................................................................... 142
7.1.11.4.19 setStart()............................................................................................................... 142
7.1.11.4.20 setType() .............................................................................................................. 143
7.1.11.4.21 setUsage()............................................................................................................ 143
7.1.11.4.22 setVersion() .......................................................................................................... 144
7.1.12 Atr ........................................................................................................................................ 145
7.1.12.1 Summary ...................................................................................................................... 145
7.1.12.2 Constants ..................................................................................................................... 145
7.1.12.3 Properties .....................................................................................................................145
7.1.12.3.1 formatByte .............................................................................................................. 145
7.1.12.3.2 historicalBytes ........................................................................................................ 145
7.1.12.3.3 interfaceBytes......................................................................................................... 145
7.1.12.3.4 tckByte.................................................................................................................... 145
7.1.12.4 Methods........................................................................................................................146
7.1.12.4.1 Constructor............................................................................................................. 146
7.1.12.4.2 toByteString() ......................................................................................................... 146
7.1.13 ByteBuffer............................................................................................................................ 147
7.1.13.1 Summary ...................................................................................................................... 147
7.1.13.2 Constants ..................................................................................................................... 148
7.1.13.3 Properties .....................................................................................................................148
7.1.13.3.1 length...................................................................................................................... 148
7.1.13.4 Methods........................................................................................................................148
7.1.13.4.1 Constructor............................................................................................................. 148
7.1.13.4.2 append() ................................................................................................................. 148
7.1.13.4.3 byteAt()................................................................................................................... 149
7.1.13.4.4 clear() ..................................................................................................................... 150
7.1.13.4.5 copy() ..................................................................................................................... 150
7.1.13.4.6 find() ....................................................................................................................... 151
7.1.13.4.7 insert() ....................................................................................................................151
7.1.13.4.8 toByteString() ......................................................................................................... 152
7.1.13.4.9 toString()................................................................................................................. 152
7.1.14 ByteString ............................................................................................................................ 154
7.1.14.1 Summary ...................................................................................................................... 154
7.1.14.2 Constants ..................................................................................................................... 155
Properties................................................................................................................................ 155

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.14.3 .......................................................................................................................................... 155

7.1.14.3.1 length...................................................................................................................... 155
7.1.14.4 Methods........................................................................................................................155
7.1.14.4.1 Constructor............................................................................................................. 155
7.1.14.4.2 and() ....................................................................................................................... 156
7.1.14.4.3 byteAt()................................................................................................................... 156
7.1.14.4.4 bytes() .................................................................................................................... 157
7.1.14.4.5 concat() .................................................................................................................. 157
7.1.14.4.6 crc() ........................................................................................................................ 157
7.1.14.4.7 equals() .................................................................................................................. 158
7.1.14.4.8 find() ....................................................................................................................... 158
7.1.14.4.9 getL() ...................................................................................................................... 159
7.1.14.4.10 getLV().................................................................................................................. 159
7.1.14.4.11 left() ...................................................................................................................... 160
7.1.14.4.12 neg() ..................................................................................................................... 160
7.1.14.4.13 not() ...................................................................................................................... 161
7.1.14.4.14 or()........................................................................................................................ 161
7.1.14.4.15 pad() ..................................................................................................................... 161
7.1.14.4.16 right() .................................................................................................................... 162
7.1.14.4.17 startsWith() ........................................................................................................... 162
7.1.14.4.18 toBase64()............................................................................................................ 163
7.1.14.4.19 toBcd().................................................................................................................. 163
7.1.14.4.20 toHex().................................................................................................................. 164
7.1.14.4.21 toSigned().............................................................................................................165
7.1.14.4.22 toString()............................................................................................................... 165
7.1.14.4.23 toUnsigned()......................................................................................................... 166
7.1.14.4.24 xor() ...................................................................................................................... 166
7.1.15 TLV ...................................................................................................................................... 167
7.1.15.1 Summary ...................................................................................................................... 167
7.1.15.2 Constants ..................................................................................................................... 167
7.1.15.3 Properties .....................................................................................................................167
7.1.15.3.1 encodingMode........................................................................................................ 167
7.1.15.3.2 size ......................................................................................................................... 167
7.1.15.4 Methods........................................................................................................................168
7.1.15.4.1 Constructor............................................................................................................. 168
7.1.15.4.2 getL() ...................................................................................................................... 168
7.1.15.4.3 getLV().................................................................................................................... 169
7.1.15.4.4 getTag().................................................................................................................. 169
7.1.15.4.5 getTLV() ................................................................................................................. 169
7.1.15.4.6 getTV() ................................................................................................................... 170
7.1.15.4.7 getValue()............................................................................................................... 170
7.1.16 TLVList ................................................................................................................................ 171
7.1.16.1 Summary ...................................................................................................................... 171
7.1.16.2 Constants ..................................................................................................................... 171
7.1.16.3 Properties .....................................................................................................................171

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.16.3.1 encodingMode........................................................................................................ 171

7.1.16.3.2 length...................................................................................................................... 171
7.1.16.4 Methods........................................................................................................................171
7.1.16.4.1 Constructor............................................................................................................. 171
7.1.16.4.2 append() ................................................................................................................. 172
7.1.16.4.3 appendValue()........................................................................................................ 173
7.1.16.4.4 appendValueIndex()............................................................................................... 173
7.1.16.4.5 deleteByIndex() ...................................................................................................... 174
7.1.16.4.6 deleteByTag()......................................................................................................... 175
7.1.16.4.7 find() ....................................................................................................................... 175
7.1.16.4.8 findIndex() .............................................................................................................. 176
7.1.16.4.9 index() .................................................................................................................... 176
7.1.16.4.10 toByteString() ....................................................................................................... 177
7.1.16.4.11 updateValue()....................................................................................................... 177
7.1.16.4.12 updateValueIndex().............................................................................................. 178
A. SAMPLE SCRIPTS .............................................................................................................................. 180
A.1 EXAMPLE SCRIPTS FOR DATA PREPARATION .................................................................................. 180
A.2 EXAMPLE OPEN SECURE CHANNEL SCRIPT .................................................................................... 191
A.3 EXAMPLE SCRIPT FOR LOADING APPLETS ...................................................................................... 193
A.4 EXAMPLE SCRIPT FOR INSTALLING APPLET..................................................................................... 195
A.5 COMPLETE EXAMPLE WITH SCRIPTS FOR DATA PREPARATION AND PERSONALIZATION ..................... 196
B. TLV LENGTH CODING........................................................................................................................ 207
C. IMPLICIT SECURE CHANNEL MODIFICATION OF APDU COMMANDS........................................ 208

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

1. Introduction
1.1 Summary
The GlobalPlatform Systems Scripting Language Specification [GP_SYS_SCR] defines a
standard to which instructions for card customization purposes can be written. In this version, the
latest version of the ECMAScript language [ECMA 262] has been defined as the language
specification to which distinctive parcels of code, or scripts, can be developed by application
developers to perform card customization operations for their applet.
ECMAScript is more popularly known as JavaScript, which is implemented around the world in
Internet browsers by Microsoft and Netscape. While Microsoft and Netscape have augmented
the language with support for web browsing requirements, JavaScript consists of a core lanuage.
It is this core language which is based entirely on [ECMA_262].
By utilizing the ECMAScript scripting language and the smart card specific objects detailed in this
document, an application developer can create, for the most part, card independent scripts for
card customization operations. These card customization operations, when designed using the
ECMAScript language specified and the smart card specific scripting objects, become very
portable instruction sets for use by a variety of card issuers across any number of smart card
implementations.
Scripts developed according to this specification will often require access to external data and
keys supplied by the host environment. While the scripts will access the external data and keys
using objects defined in the scripting objects, the Application Profile, a container for information
about the application and its requirements, will define the external data and key requirements of
the application and its individual scripts. Therefore, scripts developed according to this
specification require the Application Profile in order to operate correctly. However, the converse
is not true. Application Profiles can be used to manage smart card products irrespective of
scripts.
This work presents a choice of ECMAScript and a set of objects for that language to facilitate the
standardized exchange of card customization instructions for applications. As well, by having the
language constructs of the scripting language ECMAScript at their disposal, application
developers are given a flexible tool to develop scripts according to the manner in which they
choose to prepare data and personalize smart cards. Hence, the GlobalPlatform scripting
approach, as a tool for card customization, can create and personalize off of any data format as
required, including widely adopted P3 and emerging Common Personalization formats.
The Card Configurator and Script Builder specification has been replaced with these
specifications, namely the GlobalPlatform Systems Scripting Language Specification 1.0
[GP_SYS_SCR] and GlobalPlatform Systems Profiles Specification 1.0 [GP_SYS_PRF].
In summary, in conjunction with the GlobalPlatform Systems Profiles Specification
[GP_SYS_PRF] and the GlobalPlatform Card Customization Guide [GP_SYS_CCG], this
specification provides a method for developing interoperable smart card implementations on the
card customization front. As the ECMAScript language evolves towards a truer object oriented
language, as is proposed for the next major release of ECMA 262, the GlobalPlatform
organization can migrate or adopt the scripting objects as necessary to meet the future needs of
the multi-application smart card industry.

1.2 Scope
The objectives of this document are:
To provide a description of the role of GlobalPlatform scripting in card customization
tasks;

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

1.3 Audience
This document is targeted towards audiences who have a requirement to understanding how card
customization tasks such as Data Preparation, Card Personalization, and Card Verification can
be facilitated using a language enabling a write once, use anywhere philosophy. Specific
audiences include but are not limited to:
Card Manufacturers who will couple Application Profiles with their Card Profiles in order
to describe core GlobalPlatform applications such as Card Manager, Security Domains.
In designing the Application Profiles, Card Manufacturers must either procure or create
the appropriate Scripts for these applications.
Application Developers who will create Application Profiles and Application Scripts
required for their applications. Application Developers will have the key investment in
ensuring that their applications are accompanied with the required Scripts for Data
Preparation, pre- and post-issuance personalization, and essential Card Verification
tasks. This will help them ensure that their applications reach the widest available
audience, and ensure that implementation of their applications can be performed as
seamlessly as possible.
Actors involved in the architecture, design, and implementation of data preparation
systems, personalization systems and devices, or verification systems, including both
smart card software and hardware vendors. These actors will be assuming the role of
Application Loader, Card Enabler, or any other roles providing card customization related
responsibilities.
Actors who need to understand how legitimate application portfolio and card
combinations can be constructed, and how scripts rely on information in GlobalPlatform
Profiles [GP_SYS_PRF] to correctly operate.

1.4 Normative References

1.4.1 List of References
Standard / Specification Description
Multi Application Smart Card [GP SYS_SCMS_REQ] describes the necessary components for
Management Systems effectively managing the life cycle of an GlobalPlatform multi
GlobalPlatform Functional application smart card and its related applications.
Requirements v3.4

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Standard / Specification Description

GlobalPlatform A Primer to the [GP SYS_SCMS_IMP] Provides a broad overview of the processes
Implementation of Smart Card involved in launching a multi application program and describes some
Management and Related of the initial services that issuers, vendors or system integrators may
Systems v1.0 choose to implement.

[GP_SYS_CCG] Describes the major customization components

required to implement the card customization process, the
GlobalPlatform Card
responsibilities for each of the major roles and how GP profiles and
Customization Guide v1.0
the GP scripting language should be used for card customization
under GlobalPlatform. Available at http://www.globalplatform.org/

GlobalPlatform Card Specification

2.0.1’ [GP_CARD_CS] Defines the requirements for a GlobalPlatform smart
GlobalPlatform Card Specification card. Available at http://www.globalplatform.org/
2.1

GlobalPlatform Card Specification [GP_CARD_CS] Errata clarfies the GlobalPlatform Card

Errata and Precisions List 0.4 Specification. Available at http://www.globalplatform.org/

[GP_SYS_SCR] Defines the language to use to create code to

GlobalPlatform Systems Scripting
customize multi-application smart cards. Available at
Language Specification v1.1.0
http://www.globalplatform.org/
[GP_SYS_PRF] Basic XML data structures used to describe smart
GlobalPlatform Systems Profiles
cards, applications, and related entities. Available at
Specification v1.1.0
http://www.globalplatform.org/

Table 1.1 – GlobalPlatform Normative References

Standard / Specification Remarks

Borenstein, N. and Freed, N.,
Internet Engineering Task Force
RFC 1521 Multipurpose Internet
Mail Extensions (MIME) part One: [IETF_RFC1521] Defines the BASE64 format.
Mechanisms for Specifying and
Describing the Format of Internet
Message Bodies

ECMAScript – 3rd Edition (ECMA

[ECMA 262]
262 Standard)

Extensible Markup Language

(XML) 1.0, W3C Recommendation [W3C_XML]
10-Feb-98, REC-xml-19980210

ISO/IEC 7811-6: Identification

cards -- Recording technique --
[IS7811-6] Compact Numeric format defined.
Part 6: Magnetic stripe -- High
coercivity

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Standard / Specification Remarks

ISO/IEC 7816-3: Information
Technology – Identification Cards
– Integrated Circuit(s) Cards with
[IS7816-3]
Contacts – Part 3: Electronic
Signals and Transmission
nd
Protocols, 2 Edition

ISO/IEC 7816-4: Information

Technology – Identification Cards
– Integrated Circuit(s) Cards with
[IS7816-4]
Contacts – Part 4: Interindustry
st
Commands for Interchange, 1
Edition

ISO/IEC 7816-5: Identification

Cards – Integrated Circuit(s)
Cards with Contacts – Part 5:
[IS7816-5]
Numbering System and
Registration Procedure for
st
Application Identifier, 1 Edition

ISO/IEC 7816-6: Identification

Cards – Integrated Circuit(s)
[IS7816-6]
Cards with Contacts – Part 6:
Interindustry Data Elements

ISO/IEC 8825 - International

Standard Organization -
[IS8825]
Information Technology - ASN.1
Encoding Rules

ISO/IEC 9797-1:1999 -
International Standard
Organization - Information
technology - Security techniques -- [IS9797]
Message Authentication Codes
(MACs) – Part 1: Messages using
a block cipher
PKCS #1 - RSA Laboratories -
RSA Encryption Standard - [PKCS#1]
Version 1.5
Rivest, R., Internet Engineering
Task Force RFC 132 - The MD5
Message-Digest Algorithm
The UniCode Consortium, The
[UNICODE] Defines the UTF-8 format.
Unicode Standard - Version 3.2

Table 1.2 – Non-GlobalPlatform Normative References

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

1.4.2 GlobalPlatform Document Navigation

This document provides a standardized set of ECMAScript objects that are required to support
GlobalPlatform card customization activities. The GlobalPlatform Systems Profiles Specification
[GP_SYS_PRF] defines the profiles which are utilized to set up the card customization
environment. The GlobalPlatform Systems Card Customization Guide [GP_SYS_CCG] suggests
how scripts written according to this specification can be used in conjunction with profiles, and the
GlobalPlatform Messaging Specification will describe how the Profiles are interchanged between
independent systems in a GlobalPlatform systems infrastructure.
GlobalPlatform Systems Card Customization Guide [GP_SYS_CCG]: Defines how
multi-application smart cards can be managed using GlobalPlatform Profiles
[GP_SYS_PRF] and Scripts. This document serves as a guideline only. For
interoperability purposes, the general methodology described in the guide needs to be
adhered to.
GlobalPlatform Systems Scripting Profiles Specification [GP_SYS_PRF]: Defines
the XML formatted documents used to supply information about smart cards,
applications, load files, and keys. Provides the information necessary to create the GP
scripting language context and objects for executing a script;
GlobalPlatform Systems Scripting Languge Specification [GP_SYS_SCR]: Defines
the language and objects to use to create smart card application scripts to customize
smart cards. Makes explicit use several of the GlobalPlatform Profiles [GP_SYS_PRF].

1.5 Terminology and Definitions

Term Definition

Actor Unique entity participating in an GlobalPlatform compliant smart card

environment. These entities can take forms such as card issuers,
application developers, and personalization bureaus.

Application Developer Actor responsible for the development of Smart Card applications.

Uniquely identifies an application in a smart card according to ISO

Application Identifier
7816-5.

Instance of an Executable Module after it has been installed and made

Application Instance
selectable.

The Application Profile describes a smart card application, independent

Application Profile of any particular smart card. It acts as a template for creating the
actual application.

Application Protocol Data Unit Standard communication messaging protocol between a card
(APDU) accepting device and a smart card.

Entity that owns an application and is responsible for the application's

Application Provider
behavior.

The link between the application and the external world during a Card
Application Session Session starting with the Application selection and ending with
Application de-selection or termination of the Card Session.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Term Definition
The current life cycle state of an application on a GlobalPlatform smart
Application State
card.

A cryptographic technique that uses two related transformations, a

public transformation (defined by the Public Key component) and a
Asymmetric Cryptography private transformation (defined by the Private Key component); these
two key components have a property so that it is computationally
infeasible to discover the Private Key, even if given the Public Key.

This has been replaced with the specification GlobalPlatform Systems

Card Configuration and Script
Scripting Language Specification 1.0 and GlobalPlatform Systems
Builder (CCSB).
Profiles Specification 1.0.

Code and Application information (but not Application data) contained

Card Content in the card that is under the responsibility of the OPEN e.g. Executable
Load Files, Application instances, etc.

Card customization includes loading applets, installing applets, data

preparation, card issuance or pre-issuance personalization, post-
Card Customization
issuance personalization, as well as verifying whether cards have been
personalized correctly.

Card Image Number (CIN) An identifier for a specific GlobalPlatform card.

Cardholder The end user of a card.

Entity that owns the card and is ultimately responsible for the behavior
Card Issuer
of the card.

Generic term for the 3 card management entities of an GlobalPlatform

Card Manager card (i.e. the GlobalPlatform Environment, Issuer Security Domain and
the Cardholder Verification Method Services provider).

Role that is responsible for producing (smart) cards on behalf of a Card

Issuer. What services are performed depend on its contractual
(Smart) Card Manufacturer
relationship with the Card Issuer and may include part or all of the card
production process.

Card personalization is defined in this document as the process of

producing a card customized to a specific cardholder and eventually
modifying its contents after issuance to add and delete functionality. In
Card Personalization that broad sense, Card Personalization starts as early as application
software is loaded onto a chip, ends temporarily with card issuance,
and is re-enacted as soon as a new application is added (or deleted) or
when some on-card data is updated post-issuance.

Products are provided by card manufacturers. A product is an

implementation of an operating system on a chip; it is a card ‘model.’
Card Product
Some application instances may exist on a product (pre-loaded
applications).

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Term Definition
The Card Profile describes a smart card. This card could be a
singularly unique card or a card that shares common characteristics, as
Card Profile defined in the Card Profile, with other cards. Depending on how it is
used, it either acts as a base template for a smart card or represents a
single smart card by itself.

Information that tells an external system, in particular a Card and

Card Recognition Data Application Management System (CAMS), how to work with the card
(including indicating that this is a GlobalPlatform card).

The link between the card and the external world starting with the ATR
Card Session
and ending with a subsequent reset or a deactivation of the card.

Data that uniquely identifies a card being the concatenation of the

Card Unique Data
Issuer Identification Number and Card Image Number.

A DES encryption method where the results of the encryption of

previous blocks are fed back into the encryption of the current block;
Cipher Block Chaining
therefore each cipher text block is dependent not just on the plaintext
block that generated it but on all the previous plaintext blocks.

A corporation that manufactures processor chips used in Smart Cards

Chip Manufacturer
and Smart Card related form factor.

A message sent by the host to the smart card that initiates an action
Command
and solicits a response from the smart card.

Description of the rules of compatibility between both Card and

Application Profiles as used by Card Configurator functionality, whether
Conflict Determination Table
this functionality resides within a Smart Card Management System or is
resident elsewhere.

Cryptogram The result of a cryptographic operation.

DAP Block Part of the Load File used for ensuring Load File Data Block verification

Data Authentication Pattern Used to authenticate and/or verify the integrity of the data. This can be
(DAP) done using a DES key or Public key mechanism.

A Security Domain with a DAP Verification Privilege will perform the

DAP Verification Privilege
verification of the Load File Data Block DAP.

Data Encryption Standard (DES) A symmetric cryptographic algorithm.

Data Grouping Identifier (DGI) A construct that holds data.

The process of gathering and preparing the necessary application data

and keys for input into the personalization device. The process can be
Data Preparation
driven by the Data Preparation Scripts provided in the Application
Profile.

The reversal of the corresponding encryption, reversible transformation

Decryption of a cryptogram by cryptographic algorithm to retrieve the original plain
text data.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Term Definition
Delegated Management allows an Application Provider to load and
Delegated Management install an application on a card, with the Card Issuer still retaining
control over the content of the card.

Physical piece of hardware used in card Card Personalization, both

Device
pre-issuance and post-issuance or card acceptance scenarios.

Device Manufacturer A corporation which manufacturers devices.

Used to contain minimum device related content in order for a SCMS to

Device Profile
perform conflict determination.

An asymmetric cryptographic transformation of data that allows the

recipient of the data to prove the origin and integrity of the data; it
Digital Signature
protects the sender and the recipient of the data against forgery by
third parties; it also protects the sender against forgery by the recipient

A DES encryption method where one block of plaintext always encrypts

Electronic Code Book (ECB) to the same block of cipher text; therefore each plaintext block is
encrypted independently (see also Cipher Block Chaining).

The reversible transformation of data by cryptographic algorithm to

Encryption
produce a cryptogram.

Actual on-card container of one or more application’s executable code

(Executable Modules). It may reside in immutable persistent memory or
Executable Load File
may be created in mutable persistent memory as the resulting image of
a Load File Data Block.

Contains the on-card executable code of a single application present

Executable Module
within an Executable Load File.

A logical term used to represent the back end systems that support the
GlobalPlatform system; hosts perform functions such as authorization
Host
and authentication, administration, post-issuance application code and
data downloading, and transactional processing.

Immutable Persistent Memory Memory that can only be read.

Issuer Identification Number

The Issuer unique Identifier as defined in ISO 7812.
(IIN)

On-card entity providing support for the control, security, and

Issuer Security Domain
communication requirements of the card issuer.

A sequence of bits that controls the operation of cryptographic

transformation. Keys are used in symmetric algorithms (secret keys,
Key
e.g., DES) and asymmetric algorithms (public key and private key pair,
e.g., RSA).

The Key Profile describes a cryptographic key, independent of any

Key Profile particular instance of the key. It acts as a template for creating the
actual key.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Term Definition
The existence of Card Content on an GlobalPlatform card and the
Life Cycle
various stages of this existence where applicable.

Life Cycle State A specific state within the Life Cycle of the card or of Card Content.

A file transferred to an GlobalPlatform card that contains a Load File

Load File
Data Block and possibly one or more DAP Blocks.

Part of the Load File that contains one or more application(s) and
Load File Data Block libraries or support information for the application(s) as required by the
specific platform.

Load File Data Block Hash A value providing integrity for the Load File Data Block.

A value encompassing the Load File Data Block Hash and providing
Load File Data Block Signature
both integrity and authenticity of the Load File Data Block.

One-way hash method to generate a 16 byte digital signature which is,

MD5
in all likelihood, unique.

Mutable Persistent Memory Memory that can be modified.

The central on-card administrator that owns the GlobalPlatform

GlobalPlatform Environment
Registry.

GlobalPlatform Registry A container of information related to Card Content management.

A smart card operating system or run-time environment that provides a

consistent and hardware neutral execution environment for
OS Platform applications, ensuring inter-operability and portability of applications
across products compliant to the same platform specification,
independently of the product supplier.

A corporation delegated by a card issuer the responsibility to manage

Personalization Bureau
and personalize smart cards for that card issuer.

Scripts that are created by the scripting process and used for the Card
Personalization process. There are three types of scripts:
Data Preparation Script (DPS),
Card Creation Script (CCS),
Personalization Script Data Verification Script (DVS),
And other scripts used for post-issuance personalization activities.
Each script will be unique for each personalization run.

The script langage is defined in [GP_SYS_SCR]

Plain text Un-encrypted clear text information.

Post-Issuance Phase following the card being issued to the cardholder.

Pre-Issuance Phase prior to the card being issued to the cardholder.

Private Key The private component of the asymmetric key pair.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Term Definition
Combination of a set of applications selected by an card issuer with a
selected smart card platform. The product Profile is represented by a
Product Profile combination of Application Profiles (an application portfolio) and a Card
Profile. A product Profile will, at a minimum, contain Application
Profile(s) and a Card Profile.

Information in a XML document describing smart card, application, load

file, and key components.
Profile

Profiles are defined in [GP_SYS_PRF].

Public Key The public component of the asymmetric key pair.

An asymmetric transformation of the public key by a certification

authority and intended to prove to the public key’s recipient the origin
Public Key Certificate
and integrity of the public key. It also contains information about the
owner of the key.

Interfaces between a Smart Card Management System and

SCMS Interface systems/applications resident at the same actor or at different actors.
The interfaces will be used to transport Profile data.

A communication mechanism between an off-card entity and a card

Secure Channel
that provides a level of assurance, to one or both entities.

A session, during an application session, starting with the Secure

Secure Channel Session Channel Initiation and ending with a Secure Channel Termination or
termination of either the application session or card session.

On-card entity providing support for the control, security, and

Security Domain
communication requirements of the application provider.

Functionality which may be resident in an singular application or

Smart Card Management incorporated into existing card management systems that provides
System (SCMS) facilities for supporting the administration, personalization, and
issuance of smart cards.

A cryptographic technique that uses the same secret key for both the
Symmetric Cryptography
originator's and the recipient's transformation.

A mechanism from which the Card Manager on a card can determine

Token whether or not pre-approval / pre-authorization from the Card Issuer
was given to perform a given function.

Either in a Card Profile or a Card Profile format which contains

information regarding specific applications for a cardholder or set of
cardholders. The updated Card Profile is a concept used to represent
Updated Card Profile
smart cards that have been issued. Updated Card Profiles may need
to be managed on an individual cardholder basis depending on the
extent to which personalized cards are unique.

XML document A file containing XML-formatted information.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

1.6 Abbreviations and Notations

Abbreviation Meaning

AID Application Identifier

APDU Application Protocol Data Unit

ASN1 Abstract Syntax Notation 1 (see [IS8825])

ATR Answer-to-Reset

BER Basic Encoding Rules

CIN Card Image Number / Card Identification Number

CLA Class Byte of the Command Message

CVM Cardholder Verification Method

DAP Data Authentication Pattern

DES Data Encryption Standard

DGI Data Grouping Identifier

Europay, MasterCard, and Visa; used to refer to the ICC Specifications

EMV
for Payment Systems

FCI File Control Information

IC Integrated Circuit

ICC Integrated Circuit Card

IIN Issuer Identification Number

INS Instruction Byte of Command Message

ISO International Organization for Standardization

Lc Exact Length of Data in a Case 3 or Case 4 Command

Maximum Length of Data Expected in Response to a Case 2 or Case 4

Le
Command

LV Length Value

MAC Message Authentication Code

OID Object Identifier specified by ASN1.

OPEN GlobalPlatform Environment

P1 Parameter 1

P2 Parameter 2

P3 Parameter 3

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Abbreviation Meaning
PIN Personal Identification Number

RAM Random Access Memory

RFU Reserved for Future Use

RID Registered Application Provider Identifier

ROM Read-only Memory

RSA Rivest / Shamir / Adleman asymmetric algorithm

SCMS Smart Card Management System

SW Status Word

SW1 Status Word One

SW2 Status Word Two

TLV Tag Length Value

XML Extensive Markup Language

Table 1.4 – Abbreviations and Notations

1.7 Conventions
Text in Lucida Console refers to GlobalPlatform scripting language, examples, or references
as defined in this specification to the GlobalPlatform Systems Scripting Language Specification
[GP_SYS_SCR].
Text in Verdana Bold refers to elements and attributes from XML document type definition
files, XML schema files, XML documents, XML elements, and XML attributes as defined in the
GlobalPlatform Systems Profiles Specification [GP_SYS_PRF].

1.8 Revisions History

1.8.1 Overview of Changes in Version 1.1.0 over Version 1.0
Version 1.1.0 of GlobalPlatform Systems Scripting Language Specification replaces Version 1.0,
published in August 2002. It must be used in conjunction with GlobalPlatform Systems Profiles
Specification Version 1.1.0.
The changes can be separated into those which aim to improve consistency and those which aim
to improve functionality. In the first case, the goal is to ensure as little variance as possible
between implementations of interpreters for the GP scripting language and reduce ambiguity in
writing scripts under the GP scripting language. In the latter case, improved functionality is
achieved from correcting technical errors in version 1.0 and adding functionality to accommodate
improvements in key management and Key Profiles and contactless smart cards.
The major changes in version 1.1.0 over version 1.0 are noted below:
Application of errata and precisions documented in GlobalPlatform Scripting Language
Errata version 0.1. Some of the major errata are summarized here. However, for a
review of all errors and clarifications to version 1.0, it is advised that the reader refer to
the errata documents for both [GP_SYS_SCR] and [GP_SYS_PRF].

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Changes to Application object

Version 1.0 script object usage should be backward compatible in version 1.1.0
environments.
Addition of properties populated from the ApplicationInstance element in the
Card Profile.
Specifying handling of implicitly executed scripts to modify the resultant APDU for a
secure channel provided in the Wrap element of the Application Profile.
Correction to data[] property to ensure that only ByteString or TLV objects are
created. Thus, Boolean or Number objects should not be created.
Changes to GPApplication object
Version 1.0 script object usage should be backward compatible in version 1.1.0
environments.
Addition of properties populated from the ApplicationInstance element in the
Card Profile.
Specifying handling of implicitly executed scripts to modify the resultant APDU for a
secure channel provided in the Wrap element of the Application Profile.
Addition of example for putKey() method.
Correction to data[] property to ensure that only ByteString or TLV objects are
created. Thus, Boolean or Number objects should not be created.
Changes to GPSecurityDomain objects
Version 1.0 script object usage should be backward compatible in version 1.1.0
environments.
Addition of properties populated from the ApplicationInstance element in the
Card Profile.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Changes to Key object

Modifications have been made to the Key object in order to accommodate the new
and more comprehensive Key Profile in [GP_SYS_PRF]. Some backward
compatibility problems may exist with v1.0 Key object usage on v1.1.0 interpreters
due to the removal of some methods.
Removal of several methods related to blob. These have been replaced with a more
comprehensive set of component functions, setComponent() and
getComponent().
Modification of getKcv() method to support different means of key check value
derivation in the future.
Modification of parameters used in getAttribute() and setAttribute()
methods. Instead of Key.PERMANENT, now attribute consists of Key.IMPORTABLE,
Key.EXPORTABLE, and Key.SENSITIVE as per the updated Key Profile.

Changes to ByteBuffer object

Version 1.0 script object usage has been changed to correct bugs and incorporate
errata changes. Methods may require minor method invocation adjustments.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

2. Overview
GlobalPlatform scripting is used to enable a common, flexible, and extensible means of card
customization. Card customization is defined in this document as the process of producing a
card customized to a specific Cardholder and eventually modifying its contents after issuance to
add and delete functionality. In that broad sense, card customization starts as early as
application software is loaded onto a chip, ends temporarily with card issuance, and is re-enacted
as soon as a new application is added (or deleted) or when some on-card data is updated post-
issuance. Therefore, card customization includes loading applets, installing applets, data
preparation, card issuance or pre-issuance personalization, post-issuance personalization, as
well as verifying whether cards have been personalized correctly.
This GlobalPlatform Systems Scripting Language Specification [GP_SYS_SCR] forms, in
conjunction with GlobalPlatform Systems Profiles Specification [GP_SYS_PRF] and
GlobalPlatform Systems Card Customization Guide [GP_SYS_CCG], the backbone of the
GlobalPlatform card customization processes. The GlobalPlatformCard Systems Card
Customization Guide provides insight and a recommendation for delivering card customization
processes using scripts and profiles.
Today’s personalization environments have a number of limitations in the ability to deliver smart
cards supporting multiple applications in a cost-effective and timely manner. The major
limitations include:
Requirements of highly specialized and scarce skills;
Lengthy time to market for new applications;
Single application card focus;
Recurring development and testing costs;
Difficulty to provide customized solutions to Card Issuers and Application Providers.
The expected benefits of GlobalPlatform scripting in the GlobalPlatform card customization
architecture will include overcoming all these limitations and:
Facilitate the issuance of chip based applications by Card Issuers and Application
Providers through standardization and open standards driven selection of the language to
represent card customization instructions;
Enable the accelerated deployment of smart cards, including multiple payment and value-
added applications integrated into a single card, through the support of GlobalPlatform
scripting through different issuance delivery channels (e.g. Personalization Bureaus,
post-issuance systems);
Facilitate high levels of security through standardized interfaces to cryptography and
secure modules in the GlobalPlatform cryptographic object;
Minimize operational impact of new applications through consistent processes,
specifically the creation of scripts for a minimal set of card customization processes;
Reduce time and costs for smart card customization through standardization of
customization processes which traditionally have relied on proprietary processes and
substantial systems integration efforts.

2.1 GlobalPlatform Initiative

The GlobalPlatform initiative envisions a world where Card Issuers offer their customers access
to a wide range of financial and non-financial products and services, anytime, anywhere. In such
a world, Card Issuers will manage:

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

2.2 GlobalPlatform Card Customization Requirements

The GlobalPlatform card customization architecture conforms to all the GlobalPlatform card
architecture requirements, that are:
A single Card Issuer per smart card;
Card Issuer control of the smart card enforced on-card, throughout its life cycle;
Multiple applications per smart card with each application being under the control of a
single Application Provider;
Multiple Application Providers per smart card, as business partners of the Card Issuer,
with each Application Provider controlling one or more applications per smart card;
Application life cycle independent of each other on the same smart card, e.g.
independent load, install, or personalization process (see GlobalPlatform Card
Specification in section 1.4 Normative References);
Application defined and controlled personalization, e.g. data and security requirements
are application specific and verified on card by each application.
The following objectives are also be met by the GlobalPlatform Card Personalization architecture:
Support centralized issuance by Personalization Bureaus;
Support instant issuance by Card Issuers;
Support post-issuance modifications of the card contents (addition and deletion of
applications);
Support multi-pass personalization by subsequent Personalization Bureaus for the same
smart card;
Support Data Preparation by which the Card Issuer or an Application Provider generates
all the personalization data required to personalize all applications in a portfolio or solely
its own applications;

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

3. ECMAScript Language Choice

To implement scripts using this specification, as well as to develop products which interpret
GlobalPlatform scripts and support the scripting objects, the reader must be comfortable working
with ECMAScript. This document references the terminology, expressions, keywords, definitions,
native ECMAScript objects, and so forth in [ECMA 262]. Since there is some reference to XML in
the associated specification [GP_SYS_PRF], a general knowledge of XML terminology is
necessary as well.
[ECMA 262] is essentially synonymous with JavaScript. The rationale for selecting ECMAScript
is explored in this section.
The high level requirements for a standardized language for the GlobalPlatform card
customization architectire is that the language choice must be:
Reusable;
Industry supported open standards based so that GlobalPlatform is not responsible for
language maintenance;
Easy to implement support for;
Easy to develop resuable packages of code for;
Capable of supporting error handling;
Capable of supporting conditional processing;
Flexible to support future changes in functionality as mandated by GlobalPlatform;
Easily be referenced by or encapsulating within GlobalPlatform Application Profiles
[GP_SYS_PRF];
A specification that is supportable by the GlobalPlatform member community and actors
who will be involved in GlobalPlatform Smart Card implementations.
In terms of type of programming language, specifically interpreted versus compiled, a scripting
language is a better choice given the dynamic nature of card product creation, especially in the
post-issuance realm. A scripting language distinguishes itself from procedural and object
oriented languages in that a scripting language is comparatively simple in scope and typically
implemented in a host environment where scripts are interpreted and executed in real time. Host
environments in the GlobalPlatform card customization architecture can include commonly
available systems such as data preparation systems, personalization systems, verification and
testing systems, and post issuance systems.
While a compiled language, which procedural and object oriented languages predominantly are,
may offer speed advantages, the selection of a scripting language remains a more flexible choice
as it does not preclude the compilation of scripts into optimized object code, if a particular solution
decides to purse this. However, this choice of run time script selection and interpretation is
absent if a traditionally compiled language is selected as the standard at the onset. Likewise, a
choice of a more complex language or other scripting language was ruled out given the
widespread adoption of JavaScript, which is based on ECMAScript, and semantics similar to
programming languages such as C and Java.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4. GlobalPlatform Scripts Overview

4.1 Script Language
Scripts need to be written conforming to ECMAScript – 3rd Edition [ECMA 262] and can use any
of the features of the objects defined in this document.

4.2 Script Processing

The Script Interpreter will be provided, at any given time, only a single script to execute. Upon
execution of the script, a Boolean value of either true or false is returned to the host
environment which is instructing that a script be executed. The true value is returned to the
requesting host environment if the script has executed properly without any exceptions being
thrown. If the script cannot complete execution, and an exception has been thrown, the script
interpreter will return a false to the requesting host environment.
Prior to executing this script, the following objects may need to be created depending on script
requirements:
GPApplication for GlobalPlatform applications;
Card for the target smart card;
GPSecurityDomain for a GlobalPlatform application representing a security domain;
GPSecurityDomain for a GlobalPlatform application representing a card manager.
For example, a data preparation script for an application would not require the creation of either a
Card or GPSecurityDomain object.
Figure 4.1 provides a straightforward look at the three different steps involved in creating the
objects for GlobalPlatform applications required prior to executing a script.
Create the GPApplication or Application object (refer to Section 4.2.1). Leave
empty pointers to other objects pending their creation.
Create the Card object (refer to Section 4.2.3). Update card property to point to this
Card object. Card object creation is not necessary for scripts which do not require
access to the smart card, such as in the case of scripts for personalization data
preparation.
Create the GPSecurityDomain object (refer to Section 4.2.2) based on the Security
Domains or Card Manager present in the Card Profile and selected by the requesting
host environment (i.e., a SCMS specifies a load/install using a particular Security Domain
on the card). Again, this is not necessary for scripts which do not require access to the
smart card. Update the SecurityDomain property to point to the GPSecurityDomain
objects created.
The three objects do not have to be created in the order specified; the exact methodology and
sequence used to create the objects is dependent on the design of the Script Interpreter.
The primary objective is that the objects are created and populated accordingly prior to executing
a script. As well, depending on the source application, such as a script being executed for a
Security Domain, the GPApplication object described in the first bullet point does not need to
be created.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPApplication objects are created for GP

GPApplication applications which are not security
domains. The Application Profile to use is
determined by the script to execute.

Card The Card object can be created from the

Card Profile for the target smart card.

GPSecurity Security domain objects as defined in the

Domain
Object3 Card Profile should be created. As well, if
the GP application is a security domain,
then a GPSecurityDomain object is created
instead of a GPApplication object.

Figure 4.1 – Objects Required Prior to Script Execution

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4.2.1 Creating Objects for an Application (excluding Security

Domain)
When deserializing an Application Profile for an application which is not a Security Domain, either
an Application or GPApplication object is created. The difference between these objects
rests in the fact that GPApplication objects possess properties and methods specific to
GlobalPlatform applications. Figure 4.2 summarizes the contents of an Application Profile, and
Figure 4.3 provides an example of the creation of a GPApplication object for a GlobalPlatform
application specified in such an Application Profile. Each of these objects, when created, will
derive all the properties and methods according to the prototype-based inheritance capability of
ECMAScript.
Any object references in the scripts written for the Application Profile associated with the
application using the this keyword would be accessing the GPApplication or Application
object. Effectively, the this keyword evaluates to the this value of the execution context, as
described in [ECMA 262], which in this case is one of these two objects. Thus, valid references
for a GPApplication inside script code attached to the Application Profile for the application
would be:
// Property to access to the array of Key objects
this.key;
// Property to access to the array of ByteString and/or TLV objects
this.data;
// Property to access to the elements and attributes of the
// Application Profile
this.profile;
// Property providing access to the target card object
// Created as in Figure 4.7 - Refer to Section 4.2.3 for what
// this.card can access
this.card;
// Property providing access to the crypto object available to
// the application
this.crypto;

// Property providing access to the GPSecurityDomain object for the

// security domain associated with this application
// Created as in Figure 4.5 or 4.6 - Refer to Section 4.2.2 for
// what this.securityDomain can access
this.securityDomain;

// Functions available to all scripts in the Application Profile

this.function();
// where function is the function name defined in the
// Application Profile
// Functions defined in this specification for GPApplication
this.method();
// where method is a method defined for the GPApplication object

Each of these objects would contain properties and methods as specified in the scripting objects.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

The GPApplication object is created

GP Application from the ApplicationProfile XML
JS XML Profile where the attributes Type="GP" and
Subtype="APP".
GP Scripts

Figure 4.2 – The GP Application Profile XML Document Contains GP Scripting Language Conforming Script Fragments

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

On e G P A p p l i c a t i o n o b je c t is c r e a t e d f o r t h e
A pplica tionProfile . It is the context f rom w hich the
script is executed, and can be accessed in the application's
script f ragments as this . The GPA pplication object is Function me t h o d s a s s u p p lie d in
c r e a t e d f r o m t h e A p p lic a t io n Pr o f ile X ML w h e r e t h e GPApplication object f rom the F unction XML
attributes Ty pe ="GP" and Subty pe ="A PP" . in t h e A p p l i c a t i o n P r o f i l e . In v o ke d v ia
this. function w here function is the name of
the f unction.

GPApplication

K e y o b je c t s a r e c r e a t e d f o r a ll t h e K e y X ML
elements def ined f or the A pplica tionProfile .
security function
The Ke y De cla ra tion child XML elements of the key data profile card crypto Clas s 1
Object1 Object2 Domain
ScriptF ra gm e nt provide inf ormation regarding
w hether the keys required by the script are supplied
ex ter nally . Key s ar e ac c es s ed as
th i s . k e y . k e y n a m e o r th i s . k e y [ k e y n a m e ]
w here keyname is the name of the Key . P o i n t e r t o a
Po i n t e r t o a
GPSecurityDomai
The GPApplication C r y p t o
n o b je c t c r e a t e d
object contains the XML object used by
Objects ( ByteString or TLV ) are created for, f rom a GP A pplication
elements and attributes, the application.
a t a m i n i m u m , th e De c la r a tio n XML Pr o f ile f o r t h e
e x c lu d in g t h e K e y ,
elements defined for the ScriptF ra gm e nt S e c u r it y Do ma in
Ke y De c l a r a ti o n ,
for the script unde r e x e cution. Po i n t e r t o a u n d e r w h ic h t h is
Da ta E le m e n t and
D a t a E l e m e n t elements are accessed as C a r d o b je c t a p plic a tion w as
D e c l a r a t i o n X ML ,
this.data. d ataname or this.data[ datana me ] c r eated f r om installed.
as native ECMA Script
whe r e d a ta na m e is the na m e o f the objects. th e GP Ca r d
Da ta Ele m e nt . The type of object created Prof ile.
d e p e n d s o n th e T y p e a ttr i b u te o f th e
Da ta Ele m e nt .

Figure 4.3 – Creating the GPApplication Object from the GP Application Profile

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4.2.2 Creating Objects for a Security Domain Application (including

Card Manager)
When deserializing an Application Profile for an application which is a Security Domain or a Card
Manager, a GPSecurityDomain object is created. Figure 4.4 provides an illustration of the
Application Profile for a Security Domain or a Card Manager, and Figure 4.5 summarizes the
creation of a GPSecurityDomain object for a GlobalPlatform Security Domain application.
Any object references in the scripts written for the Application Profile associated with the Security
Domain application using “this” would be accessing the GPSecurityDomain object. Thus, valid
references for a GPSecurityDomain object representing the security domain inside script code
attached to the Application Profile for the security domain would be:
// Property to access to the array of Key objects
this.key;
// Property to access to the array of ByteString and/or TLV objects
this.data;
// Property to access to the elements and attributes of the
// Application Profile
this.profile;
// Property providing access to the target card object
// Created as in Figure 4.7 - Refer to Section 4.2.3 for what
// this.card can access
this.card;
// Property providing access to the crypto object available to
// the application
this.crypto;
// Functions available to all scripts in the Application Profile
this.function();
// where function is the actual function name)

// Functions defined in this specification for GPSecurityDomain

this.method();
// where method is a method defined for the GPSecurityDomain object
// Property providing access to the security domain under which this
// security domain was installed
this.securityDomain;

If the Security Domain is a Card Manager, then Figure 4.6 should be referred to. Thus, valid
references for a GPSecurityDomain representing the Card Manager inside script code
attached to the Application Profile for the Card Manager would be:
// Property to access to the array of Key objects
this.key;
// Property to access to the array of ByteString and/or TLV objects
this.data;
// Property to access to the elements and attributes of the
// Application Profile
this.profile;
// Property providing access to the target card object
// Created as in Figure 4.7 - Refer to Section 4.2.3 for what
// this.card can access
this.card;

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

// Property providing access to the crypto object available to

// the application
this.crypto;
// Functions available to all scripts in the Application Profile
this.function();
// where function is the actual function name)

// Functions defined in this specification for GPSecurityDomain

this.method();
// where method is a method defined for the GPSecurityDomain object

Thus, when the Card Manager or Security Domain GPSecurityDomain object is a child object
of a GPApplication object, the following references would be valid inside script code attached
to the Application Profile for the application for which the GPApplication object is created:
// Property to access to the array of Key objects
this.securityDomain.key;
// for keys from the application profile for the Security Domain
// Property to access to the array of ByteString and/or TLV objects
this.securityDomain.data;
// for data elements from the application profile for the Security
// Domain
// Property to access to the elements and attributes of the
// Application Profile
this.securityDomain.profile;
// profile tree for the application profile for the Security
// Domain

// Functions defined in this specification for GPSecurityDomain

this.securityDomain.method();

// Property providing access to the target card object

// Created as in Figure 4.7 - Refer to Section 4.2.3 for what
// this.card can access
this.securityDomain.card;
// same object pointer as in this.card for the GPApplication
// object - see part 3
// Property providing access to the crypto object available to
// the application
this.securityDomain.crypto;
// crypto functionality used by the Security Domain
// Functions available to all scripts in the Application Profile
this.securityDomain.function();
// same object pointer as in this.function for the GPApplication
// object
this.securityDomain.securityDomain;
// is null since modifications to the application’s securityDomain
// should not be made from the application)

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

The GPSecurityDomain object is created

GP Application from the ApplicationProfile XML where
JS XML Profile the attributes Type="GP" and
Subtype="CM" or Subtype="SD" .
GP Scripts

Figure 4.4 – The GP Application Profile XML Document Contains GP Scripting Language Conforming Script Fragments

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Fo r th e Se c u r ity Do ma in a p p lic a tio n , o n e

GPSecurityDomain o b je c t is c r e a t e d f r o m t h e
Applica tionProfile corresponding to the Security Domain
application. It is the context f rom w hich Security Domain
scripts are executed, and can be accessed f rom the security
d o ma in 's s c r ip t f r a g me n ts a s t h i s . The Function me t h o d s a s s u p p lie d in
GPSecurityDomain o b je c t is c r e a t e d f r o m t h e GPSecurityDomain object f rom the F unction
ApplicationProfile XML w here the attributes Ty pe ="GP" XML in the A p p l i c a t i o n P r o f i l e . Invoked via
and Subty pe ="CM" or Subty pe ="SD" . this. function w here function is the name of
the f unction.
GPSecurity
Domain
K e y o b je c t s a r e c r e a t e d f o r a ll t h e K e y X ML
elements def ined f or the Applica tionProfile .
The Ke y De cla ra tion child XML elements of the
ScriptF ra gm e nt provide inf ormation regarding key data profile card crypto securityDomain function
Clas s 1
Object1 Object2
w hether the keys required by the script are supplied
ex ter nally . Key s ar e ac c es s ed as
th i s . k e y . k e y n a m e o r th i s . k e y [ k e y n a m e ]
w here keyname is the name of the Key .
Pointer to a GPSecurityDomain
Po in t e r t o a
o b je c t c r e a te d f r o m a GP
C r y p t o o b je c t
The GPSecurityDomain A pplication Prof ile f or the Security
used by the
Objects ( ByteString or TLV ) are created for, o b je c t c o n t a in s t h e X ML Domain under w hich this security
application.
a t a m i n i m u m , th e De c la r a tio n XML e le me n t s a n d a t t r ib u t e s , d o ma in w a s in s t a lle d . On ly
elements defined for the ScriptF ra gm e nt e x c lu d in g th e Ke y , applicable is the application is not
for the script unde r e x e cutio n. Ke y De c la r a tio n , the Card Manager.
D a t a E l e m e n t elements are accessed as Da ta Ele m e nt and Po in t e r t o a
this.data. dataname or this.data[ datana me ] D e c l a r a t i o n X ML , a s C a r d o b je c t
w h e r e d a ta na m e is th e na m e o f the native ECMA Script objects. created f rom the
Da ta Ele m e nt . The type of object created GP Card Prof ile.
d e p e n d s o n th e T y p e a ttr i b u te o f th e
Da ta Ele m e nt .

Figure 4.5 – Creating the GPSecurityDomain Object for a Security Domain from the GP Application Profile

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

For the Card Manager application, one GPSecurityDomain

o b je c t is c r e a t e d f r o m t h e A p p lic a tio nPr o file
Function me th o d s a s s u p p lie d in
corresponding to the Card Manager application. It is the
GPSecurityDomain object f rom the F unction
context f rom w hich Card Manager scripts are executed, and
XML in the A p p l i c a t i o n P r o f i l e . Invoked via
can be accessed f rom the Card Manager's script f ragments as
this. function w here function is the name of
t h i s . Th e G P S e c u r i t y D o m a i n o b je c t f o r t h e Ca r d
the f unction.
Manager is created f rom the ApplicationProfile XML w here
the attributes Ty pe ="GP" and Subty pe ="CM" .
GPSecurity
Domain
K e y o b je c t s a r e c r e a t e d f o r a ll t h e K e y X ML
elements def ined f or the Applica tionProfile .
The Ke y De cla ra tion child XML elements of the key data profile card crypto function
ScriptF ra gm e nt provide inf ormation regarding Object1 Object2 Clas s 1
w hether the keys required by the script are supplied
ex ter nally . Key s ar e ac c es s ed as
th i s . k e y . k e y n a m e o r th i s . k e y [ k e y n a m e ]
w here keyname is the name of the Key .
Po i n t e r t o a
C r y p t o
The GPSecurityDomain
object used by
Objects ( ByteString or TLV ) are created for, o b je c t c o n t a in s t h e X ML
the application.
a t a m i n i m u m , th e De c la r a tio n XML e le me n t s a n d a t t r ib u t e s ,
elements defined for the ScriptF ra gm e nt e x c lu d in g th e Ke y ,
fo r the script unde r e x e cutio n. Ke y De c la r a tio n , Po i n t e r t o a
D a t a E l e m e n t elements are accessed as Da ta Ele m e nt and C a r d o b je c t
this.data. d ataname or this.data[ datana me ] D e c l a r a t i o n X ML , a s c r eated f r om
w he r e d a ta na m e is the n a m e o f the native ECMA Script objects. t h e GP Ca r d
Da ta Ele m e nt . The type of object created Prof ile.
d e p e n d s o n th e T y p e a ttr i b u te o f th e
Da ta Ele m e nt .

Figure 4.6 – Creating the GPSecurityDomain Object for the Card Manager Application from the GP Application Profile

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4.2.3 Creating Objects for a Smart Card

When deserializing a Card Profile, a Card object is created. Figure 4.7 provides an example of
the creation of the Card object. Since Card Profiles themselves do not contain script code, the
only reference to the card object is available through the application type object created for the
Application Profile where the script code resides. These application type objects include
GPApplication, Application, and GPSecurityDomain. Thus, valid references for a Card
object representing the smart card inside script code attached to an Application Profile for all
applications, including security domains and card managers, would be:
// Property to access to the elements and attributes of the Card
// Profile
this.card.profile
// Functions defined in this specification for Card
this.card.method
// where method is a method defined for the Card object
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0

GP Card The Card object is created from

XML
Profile the GP Card Profile XML.

Card One Card object is created for the

Card Profile. It is accessible as
this.card within the script.

Profile The Card object contains the

XML elements and attributes as
native ECMAScript objects.

Figure 4.7 – Creating the Card Object from the GP Card Profile
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 34

4.3 Script Object Categories

This section provides an overview of the objects comprising the objects in addition to core
ECMAScript required for implementing the GlobalPlatform scripting objects.
The ECMAScript Language Specification, Edition 3, specifies three types of objects (refer to page
6 of this specification):
1. Native Object – A native object is any object supplied by an ECMAScript implementation
independent of the host environment. Standard native objects are defined in this
specification. Some native objects are built-in; others may be constructed during the
course of execution of an ECMAScript program.
2. Built-in Object – A built-in object is any object supplied by an ECMAScript
implementation, independent of the host environment, which is present at the start of the
execution of an ECMAScript program. Standard built-in objects are defined in the
ECMAScript Language Specification, and an ECMAScript implementation may specify
and define others. Every built-in object is a native object.
3. Host Object – A host object is any object supplied by the host environment to complete
the execution environment of ECMAScript. Any object that is not native is a host object.
The GlobalPlatform scripting objects presented in this document presents additional native
objects required in a GlobalPlatform ECMAScript implementation. Depending on the context of
the script being executed, some scripting objects are built-in in the GP Scripting Language
implementation.
Native objects can be created via supplied constructor methods or returned via method calls.
The presence of constructor methods basically mean that objects can be created using the new
operator. The method calls are not necessarily limited to methods of instantiable objects. If an
instantiable object does not specify a constructor method, then it is only created via method
invocation. Instantiable objects include Atr, ByteBuffer, ByteString, TLV and TLVList.
A subset of the native objects have only one instance of the object existing in each script
execution context and is always available to all scripts. However, the prototype properties and
methods for these objects are not available until the object is created by the script execution
context. For example, once GPApplication is created as the context for execution of a script
for a GlobalPlatform application, the prototypes of GPApplication, as well as the prototypes of
the objects represented by the GPApplication object’s properties are available. These are
essentially the objects which are built-in objects for the GP Scripting Language implementation.
Such built-in objects include GPSystem, and are accessible in scripts by the object name
GPSystem, respectively. Additional built-in objects which will be present include Application,
GPApplication, GPSecurityDomain, Card, Crypto, SecureChannel, GPScp01,
GPScp02 and Key. Finally, each of the built-in objects may throw a GPError object when it
encounters an exception, which itself is a built-in object.
The following section summarize the public constants, properties and methods of the Native
GlobalPlatform scripting language objects.

4.3.1 Overview of GP Scripting Language Native ECMAScript Objects

GPError objects are created when GlobalPlatform scripting language
GPError
objects encounter an exception

GPError.ACCESS_DENIED
GPError.CARD_COMM_ERROR
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 35
GPError.CARD_INVALID_SW
GPError.CRYPTO_FAILED
GPError.DATA_TOO_LARGE
GPError.DEVICE_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_ENCODING
GPError.INVALID_INDEX
GPError.INVALID_KEY
GPError.INVALID_LENGTH
GPError.INVALID_MECH
GPError.INVALID_TAG
GPError.INVALID_TYPE
GPError.INVALID_USAGE
GPError.KEY_NOT_FOUND
GPError.OBJECTCREATIONFAILED
GPError.SECURE_CHANNEL_WRONG_STATE
GPError.TAG_ALREADY_EXISTS
GPError.TAG_NOT_FOUND
GPError.UNDEFINED
GPError.UNSUPPORTED
GPError.USER_DEFINED
GPError.prototype.className
GPError.prototype.error
GPError.prototype.message
GPError.prototype.name
GPError.prototype.reason

GPError.prototype.constructor()

The Crypto object is responsible for performing cryptographic operations in

Crypto
scripts

Crypto.DES
Crypto.DES_CBC
Crypto.DES_CBC_LP
Crypto.DES_CBC_P
Crypto.DES_ECB
Crypto.DES_ECB_LP
Crypto.DES_ECB_P
Crypto.DES_MAC
Crypto.DES_MAC_EMV
Crypto.DES2
Crypto.ISO9797_METHOD_1
Crypto.ISO9797_METHOD_2
Crypto.MD5
Crypto.RSA
Crypto.SHA_1
Crypto.prototype.decrypt()
Crypto.prototype.decryptEncrypt()
Crypto.prototype.deriveKey()
Crypto.prototype.digest()
Crypto.prototype.encrypt()
Crypto.prototype.generateKey()
Crypto.prototype.generateKeyPair()
Crypto.prototype.generateRandom()
Crypto.prototype.sign()
Crypto.prototype.unwrap()
Crypto.prototype.unwrapWrap()
Crypto.prototype.verify()
Crypto.prototype.wrap()
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 36

GPSystem represents generic system functionality which may be available,

GPSystem
depending on the host environment’s capability, to all scripts

GPSystem.dateTimeByteString()
GPSystem.getSystemID()
GPSystem.getVendorObject()
GPSystem.getVersion()
GPSystem.trace()
GPSystem.wait()

Application is a built-in object used to represent the application,

Application
specifically a non-GlobalPlatform application, for which the script is being run

Application.prototype.aid
Application.prototype.card
Application.prototype.crypto
Application.prototype.data[]
Application.prototype.key[]
Application.prototype.lifeCycle.name
Application.prototype.lifeCycle.value
Application.prototype.order
Application.prototype.profile
Application.prototype.secureChannel
Application.prototype.openSecureChannel()
Application.prototype.select()
Application.prototype.sendApdu()

GPApplication is a built-in object used to represent the GlobalPlatform

GPApplication
application, where that application is not a Security Domain or a Card
Manager application, for which the script is being run
GPApplication.prototype.aid
GPApplication.prototype.appSpecificInstallParams
GPApplication.prototype.card
GPApplication.prototype.crypto
GPApplication.prototype.data[]
GPApplication.prototype.key[]
GPApplication.prototype.lifeCycle.name
GPApplication.prototype.lifeCycle.value
GPApplication.prototype.order
GPApplication.prototype.privilege
GPApplication.prototype.profile
GPApplication.prototype.securityDomain
GPApplication.prototype.getData()
GPApplication.prototype.getStatus()
GPApplication.prototype.putKey()
GPApplication.prototype.select()
GPApplication.prototype.sendApdu()
GPApplication.prototype.setStatus()
GPApplication.prototype.storeData()

GPSecurityDomain is a built-in object used to represent the application

GPSecurityDomain
for the script is being run when the application is a GlobalPlatform security
domain or a card manager
GPSecurityDomain.prototype.aid
GPSecurityDomain.prototype.appSpecificInstallParams
GPSecurityDomain.prototype.card
GPSecurityDomain.prototype.crypto
GPSecurityDomain.prototype.data[]
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 37
GPSecurityDomain.prototype.key[]
GPSecurityDomain.prototype.lifeCycle.name
GPSecurityDomain.prototype.lifeCycle.value
GPSecurityDomain.prototype.nonVolatileDataSpaceLimit
GPSecurityDomain.prototype.order
GPSecurityDomain.prototype.privilege
GPSecurityDomain.prototype.profile
GPSecurityDomain.prototype.secureChannel
GPSecurityDomain.prototype.securityDomain
GPSecurityDomain.prototype.volatileDataSpaceLimit
GPSecurityDomain.prototype.deleteAID()
GPSecurityDomain.prototype.getData()
GPSecurityDomain.prototype.getStatus()
GPSecurityDomain.prototype.installForExtradition()
GPSecurityDomain.prototype.installForInstall()
GPSecurityDomain.prototype.installForInstallAndSelectable()
GPSecurityDomain.prototype.installForLoad()
GPSecurityDomain.prototype.installForPersonalization()
GPSecurityDomain.prototype.load()
GPSecurityDomain.prototype.loadByName()
GPSecurityDomain.prototype.loadWithProfileID()
GPSecurityDomain.prototype.openSecureChannel()
GPSecurityDomain.prototype.putKey()
GPSecurityDomain.prototype.select()
GPSecurityDomain.prototype.sendApdu()
GPSecurityDomain.prototype.setStatus()
GPSecurityDomain.prototype.storeData()

A SecureChannel object is used to perform transformation (like MACing,

SecureChannel
Encryption) on an APDU based on a security level, specifically for those
instances where the secure channel is not a standard GlobalPlatform secure
channel or one which is not supported by another scripting language object
(i.e., GPScp01 and GPScp02)
SecureChannel.prototype.crypto
SecureChannel.prototype.state

The GPScp01 object is an implementation of the Secure Channel Protocol

GPScp01
01 described in the GP Card Specification

GPScp01.prototype.cardChallenge
GPScp01.prototype.cardCryptogram
GPScp01.prototype.crypto
GPScp01.prototype.diversificationData
GPScp01.prototype.hostChallenge
GPScp01.prototype.keyIndex
GPScp01.prototype.keyVersion
GPScp01.prototype.mac
GPScp01.prototype.option
GPScp01.prototype.securityLevel
GPScp01.prototype.state
GPScp01.prototype.decryptEncryptKek()
GPScp01.prototype.encryptKek()
GPScp01.prototype.externalAuthenticate()
GPScp01.prototype.getDekKey()
GPScp01.prototype.initializeUpdate()
GPScp01.prototype.setDekKey()
GPScp01.prototype.setEncKey()
GPScp01.prototype.setMacKey()
GPScp01.prototype.unwrapWrapKek()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPScp02.prototype.cardChallenge
GPScp02.prototype.cardCryptogram
GPScp02.prototype.crypto
GPScp02.prototype.diversificationData
GPScp02.prototype.hostChallenge
GPScp02.prototype.keyVersion
GPScp02.prototype.option
GPScp02.prototype.rmac
GPScp02.prototype.securityLevel
GPScp02.prototype.sequenceCounter
GPScp02.prototype.smac
GPScp02.prototype.state
GPScp02.prototype.beginRMac()
GPScp02.prototype.decryptEncryptDek()
GPScp02.prototype.encryptDek()
GPScp02.prototype.endRMac()
GPScp02.prototype.externalAuthenticate()
GPScp02.prototype.getDekKey()
GPScp02.prototype.initializeUpdate()
GPScp02.prototype.setBaseKey()
GPScp02.prototype.setDekKey()
GPScp02.prototype.setEncKey(()
GPScp02.prototype.setMacKey()
GPScp02.prototype.unwrapWrapDek()

Card is a built-in object used to represent the target smart card for the
Card
current personalization script

Card.OTHER
Card.PICCA
Card.PICCB
Card.RESET_COLD
Card.RESET_WARM
Card.T0
Card.T1
Card.T14
Card.prototype.profile
Card.prototype.response
Card.prototype.SW
Card.prototype.SW1
Card.prototype.SW2
Card.prototype.baudRate()
Card.prototype.clock()
Card.prototype.powerDown()
Card.prototype.pps()
Card.prototype.reset()
Card.prototype.sendApdu()
Card.prototype.vcc()

Key is a built-in object used to represent the keys defined in the Application
Key
Profile

Key.CRT_DP1
Key.CRT_DQ1
Key.CRT_P
Key.CRT_PQ
Key.CRT_Q
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 39
Key.DES
Key.EIGHTZEROS
Key.EXPONENT
Key.EXPORTABLE
Key.DECRYPT
Key.DECRYPT_ENCRYPT
Key.DERIVE
Key.ENCRYPT
Key.IMPORTABLE
Key.MODULUS
Key.PRIVATE
Key.PUBLIC
Key.SECRET
Key.SENSITIVE
Key.SIGN
Key.UNWRAP
Key.UNWRAP_WRAP
Key.VERIFY
Key.WRAP
Key.prototype.getAttribute()
Key.prototype.getComponent()
Key.prototype.getEnd()
Key.prototype.getKcv()
Key.prototype.getOwner()
Key.prototype.getProfileID()
Key.prototype.getSize()
Key.prototype.getStart()
Key.prototype.getType()
Key.prototype.getUsage()
Key.prototype.getVersion()
Key.prototype.getWrapKey()
Key.prototype.setAttribute()
Key.prototype.setComponent()
Key.prototype.setEnd()
Key.prototype.setOwner()
Key.prototype.setSize()
Key.prototype.setStart()
Key.prototype.setType()
Key.prototype.setUsage()
Key.prototype.setVersion()

The Atr object provides methods to return the value of the sequence of bytes
Atr
sent by the card to the interface device as the answer to a reset as defined in
[IS7816-3]
Atr.prototype.formatByte
Atr.prototype.historicalBytes
Atr.prototype.interfaceBytes
Atr.prototype.tckByte
Atr.prototype.toByteString()

A ByteBuffer object is a mutable object that can be used to manipulate a

ByteBuffer
sequence of bytes

ByteBuffer.prototype.length
ByteBuffer.prototype.constructor()
ByteBuffer.prototype.append()
ByteBuffer.prototype.byteAt()
ByteBuffer.prototype.clear()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

The ByteString object describes an ordered series of bytes which cannot be

ByteString
modified once created

ByteString.XOR
ByteString.prototype.length
ByteString.prototype.constructor()
ByteString.prototype.and()
ByteString.prototype.byteAt()
ByteString.prototype.bytes()
ByteString.prototype.concat()
ByteString.prototype.crc()
ByteString.prototype.equals()
ByteString.prototype.find()
ByteString.prototype.getL()
ByteString.prototype.getLV()
ByteString.prototype.left()
ByteString.prototype.neg()
ByteString.prototype.not()
ByteString.prototype.or()
ByteString.prototype.pad()
ByteString.prototype.right()
ByteString.prototype.startsWith()
ByteString.prototype.toBase64()
ByteString.prototype.toBcd()
ByteString.prototype.toHex()
ByteString.prototype.toSigned()
ByteString.prototype.toString()
ByteString.prototype.toUnsigned()
ByteString.prototype.xor()

The TLV object describes a single Tag Length Value (TLV) object
TLV

TLV.DGI
TLV.EMV
TLV.L16
TLV.prototype.encodingMode
TLV.prototype.size
TLV.prototype.constructor()
TLV.prototype.getL()
TLV.prototype.getLV()
TLV.prototype.getTag()
TLV.prototype.getTLV()
TLV.prototype.getTV()
TLV.prototype.getValue()

The TLVList object holds a collection of TLVs as they are created into the
TLVList
TLVList object

TLVList.prototype.encodingMode
TLVList.prototype.length
TLVList.prototype.constructor()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4.4 Deserializing Profile XML Content into Scripting

Objects
The suggested approach is to deserialize the XML into GlobalPlatform scripting objects. The
XML is deserialized into three distinct areas, accessible through various properties of several GP
scripting language objects. These properties are summarized below:
Application.profile, GPApplication.profile or
GPSecurityDomain.profile representing the elements and attributes of the
Application Profile XML document (refer to Section 4.4.1)
Application.card.profile or GPApplication.card.profile, or
GPSecurityDomain.card.profile representing the elements and attributes of the
Card Profile XML document (refer to Section 4.4.1)
Application.data, GPApplication.data or GPSecurityDomain.data for the
objects created from the DataElement and Declaration elements from the
Application Profile (refer to Section 0)
Application.key, GPApplication.key or GPSecurityDomain.key for the Key
objects created from the Key and KeyDeclaration elements from the Application
Profile (refer to Section 4.4.3)

4.4.1 Deserializing the XML Documents into the Profile Property

The Application, GPApplication, and GPSecurityDomain objects will be created with a
profile property that contains the GlobalPlatform XML formatted Application Profile for the
application deserialized into a tree of ByteString, Boolean or Number objects. The
ApplicationProfile XML element of the Application Profile will correspond to the first node
deserialized in this profile property. For the Application Profile, all nodes of the XML
document need to be accessible through the profile property except for DataElement,
Declaration, Key and KeyDeclaration. These latter elements populate the array
properties data[] and key[] for these objects, and have a structure to facilitate easy navigation
using the name of the element.
Likewise, when present, the Card object will be created with a profile property that contains
the GlobalPlatform XML formatted Card Profile for the smart card similarly deserialized into a tree
of ByteString, Boolean or Number objects.
The fundamental principle in the deserialization of XML documents can be summarized as the
following key points:
Elements in the document are deserialized as GP scripting language objects with
properties as described in the remaining bullet points.
If the element in the document possesses a value, this object will contain the property
elementValue containing this value.
Where an element contains one or more attributes, each attribute will be a property of the
object representing the element.
Where an element contains one or more child elements, each child element is
represented by a property of the object representing the parent element.
Where an element can occur more than once, the element is deserialized as an
ECMAScript Array object.
Each property created will have the ECMAScript property attributes ReadOnly and
DontDelete.
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 43
The rules for which type of objects to create for the element values and attributes of the XML
document are summarized in Table 4.1.
It is important to note that in XML document deserialization, due to the different methods
available for XML parsing, multiple occurances of the same element will not necessarily be
deserialized in the same order they appear in the XML document.

Data Type for Element Value or Attribute Object Created in GP Scripting Language
Data Type
ByteString
String (or String based Data Type)
with encoding as specified for Element or Attribute
Boolean
Boolean
Number
Integer
Table 4.1 - Profile Property Object Creation XML Mapping Table

Here is some example script code which illustrates the usage of the profile property:
// Will retrieve UniqueID of the ApplicationProfile element in the
// Application Profile
apUniqueID = GPApplication.profile.UniqueID;
// Will retrieve Version of the ApplicationInfo element in the
// Application Profile
apVersion = GPApplication.profile.ApplicationInfo.Version;

The Card object’s profile property is created in the same way, but for the Card Profile instead of
the Application Profile.
Here is some example script code which illustrates the usage of the Card object’s profile
property:
// Will retrieve UniqueID of the CardProfile element in the Card
// Profile
cpUniqueID = GPApplication.card.profile.UniqueID;
// Will retrieve Name of the CardManufacturerProduct element in the
// Card Profile
cpCmpName = GPApplication.card.profile.CardManufacturerProduct.Name;

For those elements which contain a value, the respective branch of the profile property will
contain the value of the property.
Here is some example script code which illustrates the deserialization of the following
Description element from a profile.
<Description>Sample GlobalPlatform Application</Description>

The Description element is one of the elements which contains a value not associated with an
attribute. The code to retrieve the text “Sample GlobalPlatform Application” is provided below:
// Will retrieve value of the Description element
text = this.profile.Description;
// text will contain an ASCII encoding ByteString with the
// contents “Sample GlobalPlatform Application”
4.4.1.1 Deserialization of Elements with Multiple Occurrances
For certain elements which occur a multiple of times, the requirement is that they be deserialized
as an array. In the [GP_SYS_PRF] specification, these elements possess the XML attributes
arrayElement and arrayIndex.
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 44
The arrayElement attribute identifies the name of the child element of the XML element of which
the attribute is associated with to deserialize as an array. If the child element is not defined, then
a deserialization error will occur. If the child element is present, the arrayIndex attribute
identifies the name of the attribute of this child element to use as the index when creating the
array. Likewise, if the attribute identified by arrayIndex is not found in the child element, a
deserialization error will occur.
Since an element may contain more than one child element which needs to be deserialized as an
array, the arrayElement and arrayIndex attributes will contain comma delimited lists of child
elements and child element attributes, respectively.
Furthermore, if the arrayIndex attribute contains a # for a particular child element, then this is an
indication that the array created for the child element needs to be indexed numerically starting at
zero. When using numeric indexing, as the order of deserialization is dependent on the how the
XML document is parsed, there is no guarantee that, when deserialized into an array, elements
with multiple occurrences will be indexed in the order they appear in the document. Therefore,
scripts should not be written with this expectation.
Note that these principles for creating arrays do not apply when deserializing DataElement,
Declaration, Key, and KeyDeclaration elements, which are not deserialized as part of the
profile property.
Here is an example which illustrates the representation of the following Revision element from
a profile. The Revision element can have multiple occurrences in the XML document.
<Revisions arrayElement="Revision" arrayIndex="#">
<Revision ProfileID="00001AAAAA" Version="1.0.0" Date="2003-03-01"
Time="12:34:56" By="Customer" Digest="0000"/>
<Revision ProfileID="00001AAAAA" Version="0.0.2" Date="2002-12-11"
Time="02:12:22" By="GP Application Vendor" Digest="0000"/>
<Revision ProfileID="00001AAAAA" Version="0.0.1" Date="2002-09-11"
Time="16:44:39" By="GlobalPlatform" Digest="0000"/>
</Revisions>
Since the arrayIndex attribute of Revisions specifies a #, the resultant array for the child
element Revision would be created using a numeric index starting at zero. Assuming that the
Revision element is deserialized in the order listed in the above XML excerpt, the following is
some example script code which illustrates the deserialization of the above Revisions element
and the three children Revision elements.
// Create a pointer to the Revisions element
myRevisions = this.profile.Revisions;
// Will retrieve the first Revision element
firstRev = myRevisions.Revision[0];
firstRevAuthor = myRevisions.Revision[0].by;
// firstRevAuthor will contain “Customer”

// Will retrieve the second Revision element

thirdRev = myRevisions.Revision[2];
thirdRevAuthor = myRevisions.Revision[2].by;
// thirdRevAuthor will contain “GlobalPlatform”

Alternatively, if arrayIndex specified another attribute, such as Version, then the corresponding
array would have three elements created:
firstRev = myRevisions.Revision[1.0.0];

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4.4.2 Deserializing DataElement and Declaration Elements into the

Data Property
DataElement and Declaration elements are used to create the data property’s objects in
the GP scripting language for the Application, GPApplication and GPSecurityDomain
objects. These objects are important as they form the linkage between data provided from
environments external to the script interpreter to the internal runtime environment of the script
interpreter. These XML elements essentially are deserailized in array elements of the property
data.
The data[] property is deserialized using the value of the Name attribute of the
DataElement or Declaration as a property of the data[] array as the means to assist in
the easy retrieval of objects representing DataElement elements.
For example, consider an Application Profile with three DataElement XML elements which are
deserialized in the sequence which they appear:
<DataElement Name=”a”…
<DataElement Name=”b”…
<DataElement Name=”c”…

These data elements will be available in the script environment as:

// Using ECMAScript’s index by name capability, the array will be
// indexable by the value of the Name attribute of the DataElement
this.data[‘a’];
// the reference to this.data[‘a’] will also be replicated as the
// property a of this.data
this.data.a;
// Likewise, for the DataElement named B
this.data[‘b’];
this.data.b;

// Finally, for the DataElement named C

this.data[‘c’];
this.data.c;

DataElement XML elements occur at a higher hierarchical level of the Application Profile XML
document than do the Declaration elements, which are found at the same level as script code.
The intent of having both DataElement and Declaration is to ensure runtime execution
consistency amongst environments with different levels of external data availability, and runtime
execution efficiency where only data used by a particular script should need to be present.
DataElement XML elements represent all data populated externally or internally by the scripts
in an Application Profile (i.e., akin to global variables where the scope is the entire profile and all
the scripts contained within). Declaration XML elements are used by each individual script to
represent all data populated externally or internally by that particular script (i.e., akin to local
variables where the scope is the specific script for which they are specified).
To facilitate the balance of execution consistency and runtime efficiency, the rule to follow for
deserializing DataElement and Declaration elements is as follows:

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Attribute Declaration Element

Encoding Attribute
ByteString
ByteString HEX
ByteString
ByteString UTF8
ByteString
ByteString ASCII
ByteString
ByteString BASE64
ByteString
ByteString CN
TLV
ByteString
with enough bytes to accommodate the Tag and
and Tag and TagEncoding
Length of the data (if any) for the encoding
attributes provided
specified by TagEncoding
Table 4.2 - Data Property Object Creation XML Mapping Table

For example, if in the Application Profile XML, there are DataElement XML elements named
AccountName and PAN, and for a particular script, Declaration elements for
AccountName and PAN with no attributes from the respective DataElement modified,
these can be accessed as follows in that script as follows:
// Assume that AccountName is specified as a DataElement element in
// the Application Profile and it has a Type attibute of
// ByteString, then the ByteString accountName can be created as:
accountName = this.data.AccountName;
// or alternatively using ECMAScript array by name capability
accountName = this.data[‘AccountName’];
// Assume that PAN is specified as a DataElement element in the
// Application Profile and it has a Type attibute of ByteString,
// and an encoding of HEX, then the ByteString object can
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 47
// be created as:
pan = this.data.PAN;
// or alternatively using ECMAScript array by name capability
pan = this.data[‘PAN’];

For DataElement elements (and the corresponding Declaration elements) in the Application
Profile which contain a Tag and a TagEncoding attribute, the resultant object created in the
GP scripting environment will be a TLV object. For example:
// Assume that Address is specified as a DataElement element in the
// Application Profile and it has a Type attibute of ByteString, an
// encoding of HEX, and has a Tag attribute of 0x1234 and a
// TagEncoding attribute of DGI, then the Tlv object address can be
// created as:
address = this.data.address;
// or alternatively using ECMAScript array by name capability
address = this.data[‘address’];

DataElement and Declaration XML elements in the ApplicationProfile are the only interface
to input and output data and parameters in the script environment. The following subsections
provide insight into how to handle the deserialization and subsequent manipulation of
DataElement XML elements in the script environment.
4.4.2.1 Impact of the ReadWrite Attribute on Deserialization
ReadWrite Attribute:
The ReadWrite attribute for a DataElement or Declaration will have an impact on how
the corresponding element of the this.data array can be manipulated by the script developer.
This is summarized in Table 4.3.

ReadWrite Attribute Script Environment Implementation

true The value of this array element could be replaced by a script during script
execution. As ECMAScript does not have typed variable declarations, it is
the responsibility of the developer to be sure that assignment of the
this.data array element match the declaration specified in the
corresponding DataElement XML element in the Application Profile.
false The DataElement must be deserialized as a ReadOnly element of the
this.data array.

Table 4.3 - Impact of ReadWrite Attribute in DataElement Deserialization and Usage

4.4.2.2 Impact of the Encoding Attribute on Deserializiation

Encoding Attribute:
When the Value attribute is present, the Encoding attribute specifies the encoding format for
deserialized the DataElement or Declaration XML element into a ByteString object
4.4.2.3 Impact of the Tag Attribute on Deserializiation
Tag Attribute:
When the Tag attribute is specified, a TLV object is created as opposed to a ByteString object.
This is detailed in Table 4.2.
It is important that the TagEncoding attribute be specified if a Tag attribute is specified in
order to correctly create the TLV object. Otherwise, the encoding to use for the resultant TLV
object becomes ambiguous.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4.4.2.4 Impact of the Value, External and Optional Attributes on

Deserializiation
Value, External and Optional Attributes:
The Value attribute has a different impact depending on the values of the External and
Optional attributes in the DataElement XML element. These are summarized in Table 4.4.

Value Attribute External Attribute Optional Attribute Script Environment

Implementation
Defined in true false System should throw an
DataElement XML exception
element
Defined in true, but not satisfied by true The Value attribute
DataElement XML the script environment specified is the default
element value for the object in
the
this.data[]property
Defined in true, and is satisfied by true The object in the
DataElement XML the script environment this.data[]
element property is populated
with the external value.
Undefined in the true, but not satisfied by true Script execution can
DataElement XML the script environment proceed, but the value
element of the object in the
this.data[]
property is left as an
empty ByteString at
the start of script
execution.
Undefined in the true, and is satisfied by true The object in the
DataElement XML the script environment this.data[]
element property is populated
with the external value.
Defined in the false The object in the
DataElement XML this.data[]
element property takes the value
provided in the Value
attribute as the initial
(ReadWrite = true) or
only (ReadWrite = false)
value of the
this.data[]
property depending on
the value of the
ReadWrite attribute.
Undefined in the false Script execution can
DataElement XML commence, but the
element corresponding object in
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 49

the this.data[]
property must be set to
an empty ByteString.

Table 4.4 - Impact of Value Attribute in DataElement Deserialization and Usage

4.4.2.5 Executing Successive Scripts and Data Scoping Between Scripts

The underlying principle for script execution is that each script executes in its own separate
runtime environment. Hence, there is no valid basis for making assumptions on DataElement
element values as a result of another script or scripts execution beforehand. Each script
executes within its own virtual machine or runtime environment, with data elements in the
this.data[] property populated based on the rules defined for DataElement and
Declaration deserialization.
Specifically, scripts should be written to assume that any ByteString objects for
DataElement XML elements required, which are populated from external sources, contain the
most current values for these DataElement elements from the external data source. For
scripting engine generated ByteString objects for DataElement elements (External =
”false”), the script developer should assume that the corresponding objects in the
this.data[] property are null upon the successful execution of the script, and should not write
a script expecting otherwise.
Scoping of objects should always reinforce the rules stated for the DataElement and
Declaration deserialization. For example, Table 4.5 outlines what happens to the
DataElement data when several scripts are executed in succession.

Sample Script Execution Sequence Beginning of End of Script External

Script Value After
Script End
Step 1: Initial value of data is available in external value1
source and mapped to scripting environment

<DataElement Name=”data”
External=”true” Update=”true”>
value1 value2 value1
Step 2: Execute Script 1

<Declaration Name=”data”
External=”true” Update=”false”>
this.data.data = new ByteString(“value2”);
value1 value2 value2
Step 3: Execute Script 2

this.data.data = new ByteString(“value2”);

Since Update is not specified in the Declaration,

the value defined in the DataElement is used. The
value of Update modified in Step 2 is not used.
null value2
Step 4: Execute Script 3

this.data.data = new ByteString(“value2”);

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 50
value1 value2 value2
Step 5: Execute Script 2

<Declaration Name=”data”
External=”true” Update=”true”>
this.data.data = new ByteString(“value2”);
value2 value3 value2
Script 4

<Declaration Name=”data”
External=”true”>
this.data.data = new ByteString(“value2”);

Table 4.5 - Example Successive Script Execution with Separate Runtime Contexts

4.4.3 Deserializing Key and KeyDeclaration Elements into the Key

Property
Key and KeyDeclaration elements are used to create the key property’s objects in the GP
scripting language for the Application, GPApplication and GPSecurityDomain objects.
These objects are important as they form the linkage between keys provided from environments
external to the script interpreter to the internal runtime environment of the script interpreter.
These XML elements essentially are deserailized in array elements of the property key.
The key[] property is deserialized by using value of the Name attribute of each Key or
KeyDeclaration as the property of each elelment of the key[] array.
For example, consider an Application Profile with three Key XML elements (identifying their
respective Key Profiles by UniqueID attribute) which are deserialized in the sequence which
they appear:
<Key Name=”a”…
<Key Name=”b”…
<Key Name=”c”…

These data elements will be available in the script environment as:

// Using ECMAScript’s index by name capability, the array will be
// indexable by the value of the Name attribute of the Key
this.key[‘a’];

// the reference to this.key[‘a’] will also be replicated as the

// property a of this.key
this.key.a;
// Likewise, for the Key named B
this.key[‘b’];
this.key.b;
// Finally, for the Key named C
this.key[‘c’];
this.key.c;

Key XML elements occur at a higher hierarchical level of the Application Profile XML document
than do the KeyDeclaration elements, which are found at the same level as script code.
Although objects are created for every Key element, the KeyDeclaration element allows
specificity per script as to whether a key is provided externally or created within the script itself.
Runtime execution consistency is ensured by the fact that there is no constructor method for the
Key object, unlike the case for the DataElement and Declaration deserialization.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4.4.4 Deserializing Function Elements into Scripting Language

Functions
Function elements in the Application Profile are used to specify general purpose functions
which can be used by any script within the Application Profile. The functions need to be available
for prototype-inheritance as a native GP scripting language object along the same lines as
existing native objects such as the ByteString, ByteBuffer, and TLV objects, for example.
Specifically, the objects will be inherited as functions by any of the Application,
GPApplication and GPSecurityDomain objects created for executing a script specified in
the same Application Profile.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

4.5 Creating and Using Secure Channel Objects

4.5.1 Creating Secure Channel Objects
The scripting objects offers three types of secure channels to be created based upon the type of
secure channel specified in the Application Profile. These three objects are:
SecureChannel
GPScp01
GPScp02
Which object is created depends on the secure channel requirements of the Security Domain and
the smart card. All three of these objects represent a secure channel. SecureChannel
represents a general secure channel, while GPScp01 and GPScp02 represent GlobalPlatform
secure channel 01 and secure channel 02, respectively. The object is created as a built-in object
based on the secure channel requirements as specified in the Card Profile’s application
instances.

4.5.2 Opening Secure Channels

A secure channel is opened by invoking methods from one of three possible application type
objects. These three objects and their respective methods for opening secure channels are as
follows:
Application
The Application object represents a general application and will be created if the
Application Profile specifies an application Type that is not a GlobalPlatform
application (Type attribute does not have the value GP).
For an Application object, a secure channel is optional. If a secure channel is
available for use, then a secure channel can be opened using the
openSecureChannel() method.
The secure channel is opened using an openSecureChannel() method call.
Since the Application object is used for a non-GP application, the retrieval and
subsequent establishment of a secure channel object uses the open secure channel
script specified in the Application Profile identified by the SecurityDomain
attribute for the ApplicationInstance in the Card Profile.

GPApplication
The GPApplication object represents a GP application and will be created if the
Application Profile specifies that the application Type is a GlobalPlatform application
(Type attribute has value GP) and the application Subtype is a GP compliant
application (Subtype attribute has value APP).
The establishment of a secure channel for a GP application is completed using a
single openSecureChannel() method call. Depending on the Security Domain
specified and the version of the GP platform on the smart card, either a GPScp01 or
GPScp02 secure channel object will be created. It is conceivable that the
GPApplication will be working with a non-GP card, in which case, a platform-
independent SecureChannel object is created.

GPSecurityDomain
The GPSecurityDomain object represents a GP security domain or card manager
application. This object will be created if the Application Profile specifies that the
application Type is a GlobalPlatform security domain or GlobalPlatform card
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 53
manager (Type attribute has value GP) and the application Subtype is a GP card
manager or security domain application (Subtype attribute has value CM or SD).
The establishment of a secure channel for a GP security domain, including card the
manager which is the issuer security domain, is completed using a single
openSecureChannel() method call. Depending on the security domain specified
and the GP secure channels supported on the smart card, either a GPScp01 or
GPScp02 secure channel object will be created.

The creation of a secure channel effectively affects the APDU commands which are sent to the
card. The design of the scripting objects is such that APDU commands for application type
objects (Application, GPApplication, and GPSecurityDomain) will be created according
to the requirements of the security domain. The APDU commands for the Card object remain
unaffected by the establishment of a secure channel, and can be utilized to ensure that APDU
commands are sent directly to the smart card without any alteration.
In the implementation of each of the APDU related commands for the application type objects,
confirmation of whether a secure channel is in existence needs to occur prior to constructing the
APDU and sending to the smart card.

4.5.3 Using Secure Channels

Using the GPApplication object for a GlobalPlatform application as an example, the secure
channel establishment and resultant affect on APDU related method calls are as follows (note
that this refers to the GPApplication object):
If a secure channel is open (the method openSecureChannel() has been executed from the
GPApplication object successfully and this.secureChannel points to a secureChannel,
GPScp01 or GPScp02 object):
All APDU related commands in the secure channel object (SecureChannel, GPScp01
or GPScp02), as well as the GPApplication and GPSecurityDomain objects, which
require a secure channel, will be sent through the secure channel. In effect, the APDU
will be wrapped/MACed or otherwise transformed based on the secure channel security
level.
All APDU related commands in the Card object will not be sent through the secure
channel, but sent directly to the smart card.
If a secure channel is not open):
All APDU related commands in Application, GPApplication and
GPSecurityDomain aren't sent through a secure channel. They are sent unwrapped to
the smart card and would be equivalent to sending the APDU through the Card object.
All APDU related commands in the Card object remain indifferent to the failure to
establish a secure channel. The APDUs are sent directly to the smart card.
Refer to Appendix C for more detail on the impact of secure channels on methods which send
APDU commands to the target smart card.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

5. Global GP Scripting Language Constants

These are the constants which are used in two or more GP scripting objects.

Constant Usage
APPS_ONLY applications only
ASCII encoding value
BASE64 encoding value
CM_ONLY card manager only
CN encoding value
HEX encoding value
LF_ONLY load files only
LFE_ONLY load files and executables only
SC_CLOSE secure channel state
SC_INITIALIZE secure channel state
SC_OPEN secure channel state
UTF8 encoding value

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

6. GlobalPlatform Object Error Handling

The GPError object should be used to handle errors. The constants defined in this section for
the error values will correspond to implementation dependent unique numeric values which can
be used as the value property for the GPError object. While a description of the error is
provided here, the message property of the GPError object is entirely implementation
dependent.

Constant Usage
GPError.ACCESS_DENIED This property or method currently can’t be accessed.

GPError.ARGUMENTS_MISSING Required arguments are missing on a method call.

GPError.CARD_COMM_ERROR The communication with the card failed (card not

present, card is mute, etc…)

GPError.CARD_INVALID_SW Status word returned by the card is invalid: either the

SW returned by the card is not present in the SW list
provided, or the no SW list is provided and the SW
returned by the card is not 0x9000.

GPError.CRYPTO_FAILED The cryptographic operation failed.

GPError.DATA_TOO_LARGE An object is too large to be manipulated or stored.

GPError.DEVICE_ERROR The device has encountered an error.

GPError.INVALID_ARGUMENTS One or more arguments required for a method are

invalid.

GPError.INVALID_DATA The data supplied is invalid.

GPError.INVALID_ENCODING An unsupported encoding method was specified.

GPError.INVALID_INDEX An index provided was out of the allowed range.

GPError.INVALID_KEY The key is not valid for the operation specified.

GPError.INVALID_LENGTH A length parameter is invalid, or the length of a data

parameter is invalid.

GPError.INVALID_MECH The mechanism or algorithm specified is not supported

by the cryptographic device or the method..

GPError.INVALID_TAG Invalid tag based on encoding method.

GPError.INVALID_TYPE Invalid data type for parameter supplied.

GPError.INVALID_USAGE The key does not have the usage specified for the
operation specified.

GPError.KEY_NOT_FOUND The key is not recognized by the cryptographic device.

GPError.OBJECTCREATIONFAILED Object could not be created.

GPError.SECURE_CHANNEL_WRONG_STATE The secure channel is not in the state expected for this
operation.

GPError.TAG_ALREADY_EXISTS An object already exists in a collection.

GPError.TAG_NOT_FOUND An object was not found in a collection.

GPError.UNDEFINED An undefined error.

GPError.UNSUPPORTED The device does not support the requested

functionality.

GPError.USER_DEFINED An user defined error.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7. GlobalPlatform Scripting Objects

7.1 GP Scripting Language Native ECMAScript Objects
Native scripting objects represent objects which are always available as well as those which are
created from the XML for Application, Card and Key Profiles for the purpose of providing access
to XML document information, external data and parameters, and keys where necessary.
There is one type of native object which is always available:
1. GPSystem Object: This object provides access to general purpose methods required for
GlobalPlatform smart card support. This object is only available as GPSystem.
There are four types of native objects which are created from the XML information:
1. Application Type Objects: These objects include Application, GPApplication and
GPSecurityDomain used to represent general applications, GlobalPlatform
applications, and GlobalPlatform security domains, respectively. GlobalPlatform security
domains are used to also represent issuer security domains, referred to as card manager
applications in this document.
2. Secure Channel Type Objects: These objects include SecureChannel, GPScp01 and
GPScp02 used to represent general secure channels, and GlobalPlatform secure
channels 01 and 02, respectively.
3. Card Object: The Card object is a native object available through the application type
objects.
4. Key Object: The Key object is used to represent Key objects created, and deserialized,
from information in the Application Profile. The Key objects created are available through
the application type objects.
There are additional objects which are created for the above four objects, or are created as
needed during script execution:
1. Crypto Object: This object provides access to the functions of the cryptographic device
in which the host environment has an interface to. This object is available through the
Application type objects listed above.
2. GPError Object: Used to represent exceptions thrown by any of the GlobalPlatform
scripting language objects.
For each selected script, there should only be one application type object created. This
provides the object on which the script executes and thus can be accessed using the this
keyword.
While only one application type object is created, it will contain a reference to the native Card
object and possibly more application type objects representing other applications the application
may require access to, such as security domains and card managers for GlobalPlatform cards.
Likewise, the application type object will contain an array of objects created depending on the
DataElement XML elements defined for the Application Profile’s scripts. At a minimum, the
data elements defined in the Declaration element for the ScriptFragment element need to
be created as objects within the scripting environment. The data elements will be available as the
name of the data element as defined in the Declaration and DataElement in the XML
Profile.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.1 GPError
GPError is a native object in the GlobalPlatform Systems Scripting Language Specification
[GP_SYS_SCR]. In ECMAScript terminology, GPError is in effect a native and native object of
the GlobalPlatform scripting language which is available to all scripts at all times.
GPError objects are created when GlobalPlatform scripting language objects encounter an
exception.
7.1.1.1 Summary
GPError.ACCESS_DENIED
GPError.ARGUMENTS_MISSING
GPError.CARD_COMM_ERROR
GPError.CARD_INVALID_SW
GPError.CRYPTO_FAILED
GPError.DATA_TOO_LARGE
GPError.DEVICE_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_ENCODING
GPError.INVALID_INDEX
GPError.INVALID_KEY
GPError.INVALID_LENGTH
GPError.INVALID_MECH
GPError.INVALID_TAG
GPError.INVALID_TYPE
GPError.INVALID_USAGE
GPError.KEY_NOT_FOUND
GPError.OBJECTCREATIONFAILED
GPError.SECURE_CHANNEL_WRONG_STATE
GPError.TAG_ALREADY_EXISTS
GPError.TAG_NOT_FOUND
GPError.UNDEFINED
GPError.UNSUPPORTED
GPError.USER_DEFINED
GPError.prototype.className
GPError.prototype.error
GPError.prototype.message
GPError.prototype.name
GPError.prototype.reason

GPError.prototype.constructor()

7.1.1.2 Constants
The error handling constants used by the GPError object are described in Section 0.
7.1.1.3 Properties

7.1.1.3.1 className

GPError.prototype.className String
The className property is an ECMAScript String object.
Name of the object which has generated the error condition. For example, if a Key object generated the error, the
className property should be Key.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPError.prototype.error Number
The error property is an ECMAScript Number object.
The error property corresponds to the constant values defined for the GPError object.

7.1.1.3.3 message

GPError.prototype.message String
The message property is an ECMAScript String object.
Description of the error. This is an open text field.

7.1.1.3.4 name

GPError.prototype.name String
The name property is an ECMAScript String object.
The value of this property will always be “GPError”, and is ReadOnly.

7.1.1.3.5 reason

GPError.prototype.reason Number
The reason property is an ECMAScript Number object.
This is a property to place an implementation specific reason code for the error.

7.1.1.4 Methods

7.1.1.4.1 Constructor

GPError.prototype.constructor()
GPError new GPError(String className, Number error, Number reason, String message)
The constructor method for the GPError object can be used to construct a GPError object..

Example
sampleError = new GPError(“ByteString”, 0, 0, “An error with the ByteString”);

Parameter Type Description

className String Value to populate the className property.

error Number Value to populate the error property.

reason Number Value to populate the reason property.

message String Value to populate the message property.

returns None

exception GPError GPError.INVALID_ARGUMENTS

GPError.INVALID_TYPE

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.2 Crypto
In ECMAScript terminology, Crypto is in effect a native object of the GlobalPlatform scripting
language. The constants of this object are always available, and instances of the objects are
available through properties of the application type objects Application, GPApplication and
GPSecurityDomain. This means that no new Crypto objects can be created.
The Crypto object is responsible for performing cryptographic operations in scripts. There can
be several different cryptographic devices represented by different Crypto objects in a script
execution context. For example, the GPApplication.crypto property may refer to a different
cryptographic device than a GPApplication.card.crypto property.
7.1.2.1 Summary
Crypto.DES
Crypto.DES_CBC
Crypto.DES_CBC_LP
Crypto.DES_CBC_P
Crypto.DES_ECB
Crypto.DES_ECB_LP
Crypto.DES_ECB_P
Crypto.DES_MAC
Crypto.DES_MAC_EMV
Crypto.DES2
Crypto.ISO9797_METHOD_1
Crypto.ISO9797_METHOD_2
Crypto.MD5
Crypto.RSA
Crypto.SHA_1
Crypto.prototype.decrypt()
Crypto.prototype.decryptEncrypt()
Crypto.prototype.deriveKey()
Crypto.prototype.digest()
Crypto.prototype.encrypt()
Crypto.prototype.generateKey()
Crypto.prototype.generateKeyPair()
Crypto.prototype.generateRandom()
Crypto.prototype.sign()
Crypto.prototype.unwrap()
Crypto.prototype.unwrapWrap()
Crypto.prototype.verify()
Crypto.prototype.wrap()
7.1.2.2 Constants
Each of these constants must be assigned an unique value within the Crypto object.

Constant Usage
Crypto.DES Single length DES key for GenerateKey() method

Crypto.DES_CBC General Crypto Algorithm

Variant of DES_CBC algorithm for wrap operations which
Crypto.DES_CBC_LP will wrap length + key value + padding of 0x80 and up to
seven 0x00s
Variant of DES_CBC algorithm for wrap operations which
Crypto.DES_CBC_P will wrap key value + padding of 0x80 and up to seven
0x00s

Crypto.DES_ECB General Crypto Algorithm

Variant of DES_ECB algorithm for wrap operations which
Crypto.DES_ECB_LP
will wrap length + key value + padding of 0x80 and up to

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Constant Usage
seven 0x00s
Variant of DES_ECB algorithm for wrap operations which
Crypto.DES_ECB_P will wrap key value + padding of 0x80 and up to seven
0x00s
Crypto.DES_MAC Sign and Verify methods
Full Triple DES MAC in GP Card Spec.

Crypto.DES_MAC_EMV Sign and Verify Methods

Single DES plus final triple DES MAC in GP Card Spec.

Crypto.DES2 Double length DES key for GenerateKey() method

Crypto.ISO9797_METHOD_1 padding method (see [IS9797])

Crypto.ISO9797_METHOD_2 padding method (see [IS9797])

Crypto.MD5 Digest Algorithm

Crypto.RSA RSA Digital Signature verification

Crypto.SHA_1 Digest Algorithm

7.1.2.3 Properties
There are no properties for the Crypto object.
7.1.2.4 Methods

7.1.2.4.1 Constructor()

Crypto.prototype.constructor()
new Crypto()
new Crypto(arguments)
There is no constructor function for this object.

Example
None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED

7.1.2.4.2 decrypt()

Crypto.prototype.decrypt()
ByteString decrypt(Key value, Number mech, ByteString data)
ByteString decrypt(Key value, Number mech, ByteString data, ByteString iv)
Performs a decryption operation, using the key specified by the value parameter, and the algorithm specified by the
mech parameter. If the algorithm specified by the mech parameter requires an initial vector value, specifically the
algorithm Crypto.DES_CBC, the iv parameter will contain the initial vector. Otherwise it is ignored.
If the cryptographic device does not support certain values of mech, then an exception should be thrown.

Example
// myData will contain the value in dataToDecrypt decrypted using the
// sampleKey key, DES algorithm with CBC, and initial vector supplied

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Parameter Type Description

value Key Key object to use in decrypt() operation.
mech Number Crypto.DES_ECB
Crypto.DES_CBC
Crypto.RSA

data ByteString Data to encrypt.

iv ByteString Initial vector to use if provided and depending if required by the
algorithm specified by the mechmech parameter. Only valid for
Crypto.DES_CBC.

returns ByteString A new ByteString object containing the decrypted data.

exception GPError GPError.ARGUMENTS_MISSING

GPError.DEVICE_ERROR
GPError.KEY_NOT_FOUND
GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_KEY
GPError.INVALID_MECH
GPError.INVALID_TYPE
GPError.INVALID_USAGE
GPError.UNDEFINED
GPError.UNSUPPORTED
GPError.USER_DEFINED

7.1.2.4.3 decryptEncrypt()

crypto.prototype.decryptEncrypt()
ByteString decryptEncrypt(Key decryptKey, Number decryptMech, Key encryptKey,
Number encryptMech, ByteString data)
ByteString decryptEncrypt(Key decryptKey, Number decryptMech, Key encryptKey,
Number encryptMech, ByteString data, ByteString decryptIV)
ByteString decryptEncrypt(Key decryptKey, Number decryptMech, Key encryptKey,
Number encryptMech, ByteString data, ByteString decryptIv,
ByteString encryptIV)
Performs a decryption operation using the key specified by the decryptKey parameter, the algorithm specified by the
decryptMech parameter, followed immediately by an encrypt operation using the key passed as encryptKey and the
mechanism passed as a encryptMech.
If the algorithm specified by the decryptMech property requires an initial value parameter, such as Crypto.DES_CBC
or Crypto.DES_EBC, the initial parameter is used as specified in decryptIV, otherwise it is ignored.
Also if the mechanism specified by the encryptMech parameter requires a parameter, the encryptIV parameter is
used, otherwise it is ignored.
Depending on the cryptographic device, certain combinations of decrypt algorithms and encrypt algorithms as specified
by the decryptMech and encryptMech parameters, respectively, may be incompatible. Likewise, certain algorithms
may not be supported at all by the cryptographic device. In both these cases, a GPError object should be thrown with a
vaule of GPError.INVALID_MECH.
If the cryptographic device does not support certain combinations of algorithm, then an exception should be thrown.

Example
// newData will contain the data produced in a decryption of the data
// in myData decrypted using the DES algorithm with ECB and the key
// myDecryptKey and a subsequent encryption of this result using the
// DES algorithm with ECB and the key myEncryptKey
myDecryptKey = this.key[“keyA”];
myEncryptKey = this.key[“keyB”];
myData = new ByteString(“0001020304050607”, HEX);
newData = this.crypto.decryptEncrypt(myDecryptKey, Crypto.DES_ECB,

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Parameter Type Description

decryptKey Key Key object to use in decrypt operation.

decryptMech Number Crypto.DES_ECB

Crypto.DES_CBC
Crypto.RSA
encryptKey Key Key object to use in encrypt operation.
encryptMech Number Crypto.DES_ECB
Crypto.DES_CBC
Crypto.RSA
data ByteString Data to encrypt.
decryptIV ByteString Initial vector to use for the decrypt operation if provided and
depending if the value Crypto.DES_CBC for the parameter
decryptMech is specified. If provided and not required, it will be
ignored. If an encryptIV is specified, the invocation of the
method requires that a decryptIV must always be provided even
if it is null.

encryptIV ByteString Initial vector to use for the encrypt operation if provided and
depending if Crypto.DES_CBC encryptMech value specified. If
provided and not required, this parameter will be ignored.

returns ByteString A new ByteString containing the result of the decrypt and
encrypt operations on data.

exception GPError GPError.ARGUMENTS_MISSING

GPError.DEVICE_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_KEY
GPError.INVALID_MECH
GPError.INVALID_TYPE
GPError.INVALID_USAGE
GPError.KEY_NOT_FOUND
GPError.UNDEFINED
GPError.UNSUPPORTED
GPError.USER_DEFINED

7.1.2.4.4 deriveKey()

Crypto.prototype.deriveKey()
deriveKey (Key masterKey, Number mech, ByteString data, Key derivedKey)
Derives the key derivedKey using the masterKey specified, and the algorithm specified by the mech parameter. The
data parameter is used to specify the diversification data to be used in the operation.

Example
myMasterKey = this.key[“masterKey”];
keyToDerive = this.key[“resultKey”];
myData = new ByteString(“0001020304050607”, HEX);
this.crypto.deriveKey(myMasterKey, Crypto.DES_ECB, myData, keyToDerive);

Parameter Type Description

masterKey Key Key object to derive from.
mech Number Crypto.DES_CBC
Crypto.DES_ECB
data ByteString Deriviation data to use.

derivedKey Key Key object to derive. This parameter will be modified upon
successful execution of this method.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.DEVICE_ERROR
GPError.KEY NOT FOUND

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.2.4.5 digest()

Crypto.prototype.digest()
ByteString digest(Number digestMech, ByteString data)
Creates a digest of the data specified, using the algorithm specified by the mech parameter

Example
// myDigest will contain the digest of myData using the MD5 algorithm
myData = new ByteString(“00010203”, HEX);
myDigest = this.crypto.digest (Crypto.MD5, myData);

Parameter Type Description

digestMech Number Crypto.SHA_1
Crypto.MD5
data ByteString Data to operate on.

returns ByteString A ByteString containing the digest of data.

exception GPError GPError.ARGUMENTS_MISSING

GPError.DEVICE_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_MECH
GPError.INVALID_TYPE
GPError.UNDEFINED
GPError.UNSUPPORTED
GPError.USER_DEFINED

7.1.2.4.6 encrypt()

Crypto.prototype.encrypt()
ByteString encrypt(Key value, Number mech, ByteString data)
ByteString encrypt(Key value, Number mech, ByteString data, ByteString iv)
Performs an encryption operation, using the key specified by the value parameter, the algorithm specified by the mech
parameter. If the algorithm specified by the mech parameter requires an initial vector, such as Crypto.DES_CBC, the
initial vector is provided. Otherwise, the iv, even if provided, is ignored.
If the cryptographic device does not support certain combinations of mech, then an exception should be thrown.

Example
// myData will contain the data specified in dataToEncrypt encrypted
// under the key sampleKey using the DES algorithm with CBC,
// and the initial vector value specified in initialVector
sampleKey = this.key[“keyA”];
dataToEncrypt = new ByteString(“0001020304050607”, HEX);
initialVector = new ByteString(“0000000000000000”, HEX);
myData = this.crypto.encrypt (sampleKey, Crypto.DES_CBC, dataToEncrypt,
initialVector);

Parameter Type Description

value Key Key object to use in encrypt operation.

mech Number Crypto.DES_ECB

Crypto.DES CBC

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

iv ByteString Initial vector to use if provided and depending if required by the

algorithm specified by the mech parameter.

returns ByteString A ByteString containing the encrypted data.

exception GPError GPError.ARGUMENTS_MISSING

7.1.2.4.7 generateKey()

Crypto.prototype.generateKey()
generateKey(Number mech, Key keyToGen)
Generates a secret key, using the algorithm specified by the mech parameter. The secret key to generate must already
exist as a key object. To ensure this, the key must be defined in the respective Application Profile for the script wishing
to use this method.
The features of the key to generate will have been specified by the Key Profile definition referenced by the key in the
Application Profile. The minimum feature is that the Key will have key generation as an allowed operation. As well, the
type of key must be compatible with the algorithm specified in the mech parameter.

Example
// The following operation will attempt to generate the key myKey using
// the DES algorithm.
myKey = this.key[“resultKey”];
generateKey(Crypto.DES, myKey);

Parameter Type Description

mech Number Crypto.DES
Crypto.DES2
keyToGen Key The key object to generate.

returns None

exception GPError GPError.ARGUMENTS_MISSING

7.1.2.4.8 generateKeyPair()

Crypto.prototype.generateKeyPair()
generateKeyPair(Number mech, Key publicKey, Key privateKey)
Generates a public/private key pair using the algorithm specified by the mech parameter and the key pair specified by
the publicKey and privateKey parameters. The two key parts to generate must already exist as Key objects. To

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
// The following operation will generate the public key and private key
// components for the key parts keyPartA and keyPartB using the RSA
// algorithm.
keyPartA = this.key[“keyPartA”];
keyPartB = this.key[“keyPartB”];
generateKeyPair(Crypto.RSA, keyPartA, keyPartB);

Parameter Type Description

mech Number Crypto.RSA
publicKey Key Public key part to generate.

privateKey Key Private key part to generate.

returns None

exception GPError GPError.ARGUMENTS_MISSING

7.1.2.4.9 generateRandom()

Crypto.prototype.generateRandom()
ByteString generateRandom(Number rdmLength);
Generates a string of random bytes of length specified

Example
// aRandomString will contain a randomly generated 12 byte field.
aRandomString = this.crypto.generateRandom(12);

Parameter Type Description

rdmLength Number Length of random data to generate in bytes.

returns ByteString A ByteString with length bytes of random data.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.2.4.10 sign()

Crypto.prototype.sign()
ByteString sign(Key signingKey, Number signingMech, ByteString data)

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
// signedData will contain the data contained in myData signed using the
// RSA algorithm
mySigningKey = this.key[“keyA”];
myData = new ByteString(“00010203”, HEX);
signedData = this.crypto.sign (mySigningKey, Crypto.RSA, myData);

Parameter Type Description

signingKey Key Key to use for signing operation.
signingMech Number Crypto.DES_MAC
Crypto.DES_MAC_EMV
Crypto.RSA
data ByteString Data to sign.

iv ByteString Optional initial vector.

returns ByteString A ByteString containing the signature of data.

exception GPError GPError.ARGUMENTS_MISSING

GPError.DEVICE_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_MECH
GPError.INVALID_KEY
GPError.INVALID_TYPE
GPError.INVALID_USAGE
GPError.KEY_NOT_FOUND
GPError.UNDEFINED
GPError.UNSUPPORTED
GPError.USER_DEFINED

7.1.2.4.11 unwrap()

Crypto.prototype.unwrap()
unwrap(Key keyToUnwrap, Key keyResult)
Decrypts a previously wrapped key, implicitly using the wrap key Key object associated with the Key object specified for
keyToUnwrap. The algorithm required to unwrap the key and any required initial vector needs to be known by the
implementation of the scripting interpreter and/or associated key management system. The algorithm and initial vector
can be retrieved from the Key Profile for keyToUnwrap.
The key to unwrap must already exist as a Key object. To ensure this, the key must be defined in the respective
Application Profile for the script wishing to use this method.
The features of the key to unwrap will have been specified by the Key Profile definition referenced by the key in the
Application Profile. As well, the type of key must be compatible with the algorithm utilized by the scripting host
environment and/or key management system.

Example
// Wrap keyB with keyC using DES in ECB mode and place result in keyA
this.crypto.wrap(this.key[“keyC”], Crypto.DES_ECB, this.key[“keyB”], this.key[“keyA”]);
// Unwrap keyA and place in keyD
// The host environment knows that keyA has been wrapped by keyC using DES in ECB mode
this.crypto.unwrap(this.key[“keyA”], this.key[“keyD”]);

Parameter Type Description

keyToUnwrap Key The key to unwrap.

keyResult Key The unwrapped key is placed in this object.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

exception GPError GPError.ARGUMENTS_MISSING

GPError.DEVICE_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_KEY
GPError.INVALID_TYPE
GPError.INVALID_USAGE
GPError.KEY_NOT_FOUND
GPError.UNDEFINED
GPError.UNSUPPORTED
GPError.USER_DEFINED

7.1.2.4.12 unwrapWrap()

Crypto.prototype.unwrapWrap()
unwrapWrap( Key wrapKey, Number wrapMech, Key keyToUW, Key keyResult)
unwrapWrap( Key wrapKey, Number wrapMech, Key keyToUW, Key keyResult, ByteString
wrapIV)
Unwraps the key specified in keyToUW using key returned by the getWrapKey() method of the keyToUW object, and
wraps the result using the key supplied in wrapKey, utilizing the algorithm specified by wrapMech. The algorithm
required to unwrap the key and any required initial vector needs to be known by the implementation of the scripting
interpreter and/or associated key management system. If the wrapMech algorithm requires an additional parameter, it
needs to be supplied as the ByteString wrapIV .
The key to unwrap and then wrap must already exist as a Key object. To ensure this, the key must be defined in the
respective Application Profile for the script wishing to use this method.
The features of the key to unwrap and then wrap will have been specified by the Key Profile definition referenced by the
key in the Application Profile. As well, the type of key must be compatible with the algorithms used for the unwrap and
wrap procedures.
If the wrapMech is specified as Crypto.DES_CBC_P, Crypto.DES_CBC_LP, Crypto.DES_EBC_P, or
Crypto.DES_EBC_LP, then the resultant getComponent() and setComponent() methods on the resultant keys will
retreive and set, respectively, the value which is modified as a result of this method invocation. For example, if
Crypto.DES_CBC_P is specified as the wrapMech, the resultant getComponent() on the wrapped key will return "key
value + padding".
Depending on the cryptographic device, certain combinations of unwrap algorithms and wrap algorithms, respectively,
may be incompatible. Likewise, certain algorithms may not be supported at all by the cryptographic device. In both
these cases, a GPError exception should be thrown.

Example
// Wrap keyB with keyC using DES in ECB mode and place result in keyA
this.crypto.wrap(this.key[“keyC”], Crypto.DES_ECB, this.key[“keyB”], this.key[“keyA”]);
// The host environment knows that keyA has been wrapped by keyC using DES in ECB mode
// Once the key has bee unwrapped, then it is subsequently wrapped using the key
// myWrapKey and the DES algorithm in ECB mode
wrapKey = this.key[“keyE”];
targetKey = this.key[“keyA”];
myWrappedKey = this.key[“keyD”];
this.crypto.unwrapWrap(myWrapKey, this.crypto.DES_ECB, targetKey, myWrappedKey, null);
// In effect, keyD will contain keyB wrapped with keyE (keyB wrapped with keyC then
// unwrapped with keyC and rewrapped with keyE)

Parameter Type Description

wrapKey Key Key to perform wrap operation with.

wrapMech Number Crypto.DES_ECB

Crypto.DES_ECB_LP
Crypto.DES_ECB_P
Crypto.DES_CBC
Crypto.DES_CBC_LP
Crypto.DES_CBC_P
Crypto.RSA
keyToUW Key Key to perform wrap and unwrap operation on.

keyResult Key The final result of the unwrapWrap operation on the keyToWU.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

returns None

exception GPError GPError.ARGUMENTS_MISSING

7.1.2.4.13 verify()

Crypto.prototype.verify()
Boolean verify(Key verifyKey, Number verifyMech, ByteString data,
ByteString signature)
Verifies that the signature specified is the correct signature for the data specified, using the key specified by
verifyKey, and the algorithm specified by verifyMech.

Example
// verifyResult will contain a true value if the signature created by
// applying the DES algorithm with MAC using the key myVerifyKey on the
// data in myData matches the value contained in signature
myVerifyKey = this.key[“keyA”];
mySigningKey = myVerifyKey;
myData = new ByteString(“00010203”, HEX);
mySignature = this.crypto.sign(mySigningKey, Crypto.DES_MAC, myData);
verifyResult = this.crypto.verify(myVerifyKey, Crypto.DES_MAC, myData,
mySignature);

Parameter Type Description

verifyKey Key Key used for signature verification.

verifyMech Number Crypto.DES_MAC

Crypto.RSA
Crypto.DES_MAC_EMV
data ByteString Data on which the signature is based (or generated).

signature ByteString Signature to verify.

returns Boolean True or false depending if verify() was successful or not.

exception GPError GPError.ARGUMENTS_MISSING

7.1.2.4.14 wrap()

Crypto.prototype.wrap()
wrap(Key wrapKey, Number wrapMech, Key keyToWrap, key keyResult)
wrap(Key wrapKey, Number wrapMech, Key keyToWrap, Key keyResult, ByteString mechIV)

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
// myKeyToWrap will be wrapped under the DES algorithm with ECB
// using the key myWrapKey
myWrapKey = this.key[“keyA”];
myKeyToWrap = this.key[“keyB”];
this.crypto.wrap(myWrapKey, Crypto.DES_ECB, myKeyToWrap, myKeyResult);

Parameter Type Description

wrapKey Key Key to wrap keyToWrap with.

wrapMech Number Crypto.DES_ECB

Crypto.DES_ECB_LP
Crypto.DES_ECB_P
Crypto.DES_CBC
Crypto.DES_CBC_LP
Crypto.DES_CBC_P
Crypto.RSA
keyToWrap Key Key to wrap.

keyResult Key The wrapped key is placed into this object.

mechIV ByteString Optional initial vector required by particular wrapMech.

returns None

exception GPError GPError.ARGUMENTS_MISSING

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.3 GPSystem
In ECMAScript terminology, GPSystem is in effect a native object of the GlobalPlatform scripting
language which is available to all scripts at all times. The GPSystem object is only available as
GPSystem and is not instantiable or created by any other methods.
GPSystem represents generic system functionality which may be available, depending on the
host environment’s capability, to all scripts.
7.1.3.1 Summary
GPSystem.dateTimeByteString()
GPSystem.getSystemID()
GPSystem.getVendorObject()
GPSystem.getVersion()
GPSystem.trace()
GPSystem.wait()
7.1.3.2 Constants
There are no constants for the GPSystem object.
7.1.3.3 Properties
There are no properties for the GPSystem object.
7.1.3.4 Methods

7.1.3.4.1 Constructor

GPSystem.prototype.constructor()
new GPSystem()
new GPSystem(arguments)
There is no constructor function for this object.

Example
None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED

7.1.3.4.2 dateTimeByteString()

GPSystem.dateTimeByteString()
ByteString dateTimeByteString()
Return a ByteString object containing the current date and time. The result will be seven bytes long, and will contain
the date and time formatted as follows:
Bytes 0 and 1: the year as four BCD digits, range 0x2001 to 0x9999.
Byte 2: the month as two BCD digits, range 0x01 to 0x12.
Byte 3: the day of the month as two BCD digits, range 0x01 to 0x31.
Byte 4: the hour as two BCD digits, range 0x00 to 0x23.
Byte 5: the minute as two BCD digits, range 0x00 to 0x59.
Byte 6: the second as two BCD digits, range 0x00 to 0x59.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
// returns in a 6 byte long ByteString object myDateTime the hexadecimal
// value 0x20010926124610 if the time at execution were 12:46:10
// on September 26, 2001.
myDateTime = GPSystem.dateTimeByteString();

Parameter Type Description

None

returns ByteString A ByteString containing the date and time as described above.

exception None

7.1.3.4.3 getSystemID()

GPSystem.getSystemID()
ByteString getSystemID()
Returns the vendor dependent system ID value. Could be null if none available.

Example
myID = GPSystem.getSystemID();

Parameter Type Description

None

returns ByteString Vendor dependent system ID value.

exception

7.1.3.4.4 getVendorObject()

GPSystem.getVendorObject()
Object getVendorObject(String objectName)
Retrieve a vendor specific object specified by the parameter supplied in objectName. The advantage of this approach
over supplying vendor specific objects is that implementations do not have to check for supportability of vendor objects.
In particular, if an object isn’t found, a null could just be returned. Scripts need to be written to not rely on the presence
of vendor objects to ensure the greatest level of interoperability possible.
If the object is not implemented by the vendor, then a null is returned. The script writer should check to see if the
result of the method call is null before proceeding to use the vendor object returned in objectName.

Example
// If the vendor implemention offers a native object for “CPS Support”
// in its implementation of the GP scripting language, then the object
// CPSProcessing will map to this native object. This example shows
// that the vendor object returned possesses the method storeData to
// faciliate the processing of common personalization files. If the
// vendor object is not present, an alternate method of processing the
// common personalization file represented by myDGIStream will be used.
CPSProcessing = GPSystem.get
VendorObject("CPSSupport");
If (CPSProcessing <> null) CPSProcessing.storeData(myDGIStream)
else { // code to process myDGIStream }

Parameter Type Description

objectName String Name of the object to retrieve. The names assigned to vendor
objects is specific to a vendor’s implementation.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE
GPError.OBJECTCREATIONFAILED

7.1.3.4.5 getVersion()

GPSystem.getVersion()
String getVersion()
Retrieve as a String the version of GlobalPlatform scripting implemented by the scripting interpreter. This is not the
same as the version of the XML profiles. This latter information can be obtained by navigating the XML document for the
appropriate attribute.
This is the version of the specification being used by the interpreter when executing the script. For example, for a script
interpreter written to support this specification, the GPSystem.getVersion() method will return an ASCII encoded String
containing "1.1.0".
The version returned may contain a fourth number specifying the version of the errata implemented in the scripting
interpreter. If this fourth number is zero, then the original specification without any errata has been implemented. If this
number is not returned, the interpreter has implemented no errata for the specification.

Example
// Assume the version of the scripting language implemented by the
// interpreter is version 1.1.0
ScriptingVersion = GPSystem.getVersion();
// ScriptingVersion will contain the ASCII string “1.1.0”

// Likewise, if the interpreter supports version 1.0

ScriptingVersion = GPSystem.getVersion();
// ScriptingVersion will contain ASCII String “1.0.0”

// Assume the version of the scripting language implemented by the

// interpreter is version 1.1.0.1
ScriptingVersion = GPSystem.getVersion();
// ScriptingVersion will contain the ASCII string "1.1.0.1"

// Likewise, if the interpreter supports version 1.1.0 with errata version 0.1 applied
ScriptingVersion = GPSystem.getVersion();
// ScriptingVersion will contain ASCII String "1.1.0.1"

Parameter Type Description

None

returns String The version of scripting implemented as an ASCII encoded String

and formatted according to GP versioning conventions (x.x.x.y where
x is a number from 0-9 and y is a decimal number representing the
errata version implemented and is optional).

exception None

7.1.3.4.6 trace()

GPSystem.trace()
Boolean trace(Object traceData)
Append data to vendor specific trace file as a String the value contained in the object specified by traceData using
the ECMAScript method toString().
The means in which trace() appends the data specified in the object is entirely vendor dependent. File access
operations for the trace file are handled by the vendor implementation of trace().

Example
// Log the value contained in dataToLog object to the trace file

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Parameter Type Description

traceData Object Contains the object or expression to be appended to the trace file.

returns Boolean Boolean value of true or false, depending on success of trace

operation. If vendor implementation of trace() doesn’t support
output of that object to the trace file, execution of the script should
continue with false being returned. However, no exceptions should
be thrown to stop execution of the script.
exception None GPError.ARGUMENTS_MISSING
GPError.INVALID_ARGUMENTS

7.1.3.4.7 wait()

GPSystem.wait()
wait(Number value)
Pause for a period of value milliseconds.

Example
// Pause script execution for 20 ms before proceeding with next script
// instruction
GPSystem.wait(20);

Parameter Type Description

value Number Number of milliseconds to wait.
If the number of milliseconds is invalid, such as the number is
negative, then a GPError with GPError.INVALID_DATA will be
generated.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_TYPE

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.4 Application
Application is a native object used to represent the application, specifically a non-
GlobalPlatform application, for which the script is being run. When a script for the application is
being written, the application object is referred to as the this object.
As defined in the ECMAScript specification, native objects are present at the start of the
execution of an ECMAScript program.
An Application object should be created if in the Application Profile, the Type attribute of the
ApplicationInfo element has a non-GlobalPlatform value. For example,
<ApplicationInfo Type=”OTHER” />

The Application object implements methods providing support for platform independent
secure channel commands and a means to send APDUs. If a secure channel has been set for
the Application object, the APDU will be sent through the secure channel.
If a secure channel is opened for the Application object, then the resultant APDUs, except for
the select() method, sent from this object are affected as per the script provided in the Wrap
subelement of the Application Profile. Refer to Appendix C for an overview of which methods are
affected.
7.1.4.1 Summary
Application.prototype.aid
Application.prototype.card
Application.prototype.crypto
Application.prototype.data[]
Application.prototype.key[]
Application.prototype.lifeCycle.name
Application.prototype.lifeCycle.value
Application.prototype.order
Application.prototype.profile
Application.prototype.secureChannel
Application.prototype.openSecureChannel()
Application.prototype.select()
Application.prototype.sendApdu()

7.1.4.2 Constants
There are no constants for the Application object.
7.1.4.3 Properties

7.1.4.3.1 aid

Application.prototype.aid ByteString
The aid property is a GlobalPlatform scripting language ByteString object.
The aid property represents a ReadOnly, DontDelete property. It represents the application id of the application
instance for the script being executed. It is populated from the ApplicationInstance subelement of the Card Profile.
If it is not available or applicable, then it will contain an empty value.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.4.3.2 card

Application.prototype.card Card
The card property is a GlobalPlatform scripting language Card object.
The card property represents a ReadOnly, DontDelete property. Card object used by the application.

7.1.4.3.3 crypto

Application.prototype.crypto Crypto
The crypto property is a GlobalPlatform scripting language Crypto object.
A ReadOnly, DontDelete property. Crypto object used by the application.

7.1.4.3.4 data[]

Application.prototype.data[] Object[]
The data property is an array of GlobalPlatform scripting language ByteString and/or TLV objects.
The Application object will be created with an array of objects which contains the deserialized data elements for an
Application Profile. Each object will be deseralized according to its type defined in the profile and with its name as an
index value. Refer to Section 4.4.2 for more information and examples.
The Type attribute in the DataElement element of the Application Profile determines the object type. The object type
is either a native GP scripting language or ECMAScript object. Specifically,
XML Application Profile DataElement Element GP Scripting Language
Type Attribute Encoding Attribute Scripting Object Created
ByteString HEX ByteString
ByteString UTF8 ByteString
ByteString ASCII ByteString
ByteString BASE64 ByteString
ByteString CN ByteString
ByteString TLV*
(and Tag and TagEncoding specified)
*with enough bytes to accommodate the Tag and the length of the data (if any) for the specified TagEncoding
Unless specified otherwise, this is a read only, don’t delete property. This property is an array of Objects for the
DataElement XML elements defined in the Application Profile. There is one element per DataElement element of
the Application Profile. The index value is the value of the Name attribute of a DataElement element. Each element
has it’s own attributes, based on the <DataElement> tag (i.e., an element can be ReadOnly or R/W depending of
the value of ReadWrite attribute in the profile) Note: a data object can also be retrieved by name using the . (dot)
notation.

7.1.4.3.5 key[]

Application.prototype.key[] Key[]
The key property is an array of GlobalPlatform scripting language Key objects.
The Application object will be created with an array of Key objects which contains the deserialized keys for an
Application Profile. Each key will be deseralized according to its name as its index. Refer to Section 4.4.3 for more
information and examples.
This is a ReadOnly, DontDelete property. This property is an array of Keys defined in the Application Profile. There is
one element per Key Tag of the application. The index value is the value of the Name attribute of a Key Tag. Note: a
Key can also be retrieved by name using the . (dot) notation.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Application.prototype.lifecycle.name ByteString
The lifecycle.name property is a GlobalPlatform scripting language ByteString object.
The lifecycle.name property represents a ReadOnly, DontDelete property. It represents the name of the lifecycle of
the application instance for the script being executed. It is populated from the ApplicationInstance subelement of
the Card Profile whose ProfileID matches the UniqueID of the current application profile. If it is not available or
applicable, then it will contain an empty value.

7.1.4.3.7 lifecycle.value

Application.prototype.lifecycle.value Number
The lifecycle.value property is a GlobalPlatform scripting language ByteString object.
The lifecycle.value property represents a ReadOnly, DontDelete property. It represents the value of the lifecycle
value of the application instance for the script being executed. It is populated from the Value property of the
ApplicationInfo.LifeCycle subelement of the Application Profile that matches the lifecycle.name property. If it
is not available or applicable, then it will contain an empty value.

7.1.4.3.8 order

Application.prototype.order Number
The order property is an ECMAScript Number object.
The order property represents a ReadOnly, DontDelete property. It represents the order on the card of the application
instance for the script being executed. It is populated from the ApplicationInstance subelement of the Card Profile.
If it is not available or applicable, then its value will contain an empty valuebe undefined.

7.1.4.3.9 profile

Application.prototype.profile Object
The profile property is a tree of GlobalPlatform scripting language ByteString and ECMAScript Boolean and
Number objects.
The Application object will be created with a series of objects which replicate, except for Key,
KeyDeclararation, Declaration, and DataElement elements, the GlobalPlatform XML formatted Application
Profile for the application deserialized into a tree of objects. The root XML element of the Application Profile will form the
contents of this root Application.profile object. Refer to Section 4.4.1 for more information and examples.
The data type of the attribute determines the object type to create. The object type is a ByteString or a native
ECMAScript object. Specifically,
GP Systems Profiles Specification GP Scripting Language
XML Attribute Data Type Scripting Object Created
String (or String based Data Type) ByteString
Boolean Boolean
Integer Number

Elements in the XML which can have multiple occurences are created as arrays, which can be indexed by the name of
the first attribute of the element.
For elements which are specified as String data types in the Profiles specification, a ByteString object with the
encoding specified in the Encoding column in the Profiles specification will be created. For those attributes which are
enumerated lists of Strings, then they will be created as ByteString objects with ASCII encoding.

7.1.4.3.10 secureChannel

Application.prototype.secureChannel SecureChannel

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.4.4 Methods

7.1.4.4.1 Constructor

Application.prototype.constructor()
new Application()
new Application(arguments)
There is no constructor function for this object.

Example
None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED

7.1.4.4.2 openSecureChannel()

Application.prototype.openSecureChannel()
Object openSecureChannel(arguments)
Open a secure channel on the card. This method should call implicitly the OpenSecureChannel script fragment
defined in the Security Domain or equivalent Application Profile. Once the secure channel is opened, all APDU’s are
sent through the secure channel using the Wrap script specified in the Application Profile.

Example
mySC = this.openSecureChannel(...);

Parameter Type Description

arguments Defined by application Argument(s) required by application developer to open the secure
developer channel.

returns Object Defined by application developer.

In addition, the SecureChannel object will have its state property
set correctly, indicating that the secure channel is either successfully
opened (SC_OPEN) or closed (SC_CLOSE). This property will be
used to determine whether to invoke the wrap script provided in the
Application Profile for the Application object’s sendApdu()
method.

exception GPError Any exception thrown by the OpenSecureChannel script

fragment is forwarded.

7.1.4.4.3 select()

Application.prototype.select()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

ByteString select()
ByteString select(Boolean next, Boolean noData)
ByteString select(Boolean next, Number[] sw)
ByteString select(Boolean next, Boolean noData, Number[] sw)
Send a select APDU with the AID of the application (AID value is retrieved from the Card Profile). If a secure channel
exists, the select() method should implicitly reset the application’s secure channel security level. If the select()
method invocation is used without parameters, then the next parameter is assumed to be false.
The select() method is used for selecting an application. This refers to the [IS7816-4] SELECT command.

Example
this.select(true);

Parameter Type Description

next Boolean If true send a Select APDU with P2 set to 0x02, otherwise send a
Select APDU with P2 set to 0x00. By default, if next is not provided
as a parameter, then this parameter is false.

noData Boolean If true no AID is required for the select.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU data

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.4.4.4 sendApdu()

Application.prototype.sendApdu()
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number le)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number le,
Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number le)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number le, Number[] sw)
Send an APDU to the card. If the application doesn’t use a secure channel the APDU is sent to the card directly (i.e.
same as Application.card.sendApdu()). If the application uses a secure channel, this method should call
implicitly the Wrap script fragment defined in the appropriate Application Profile for a Security Domain unless Card
Specification defined secure channels and implementation options are used. The APDU field Lc is not specified in the
sendApdu() method, but must be calculated by the method implicitly (see [IS7816-4]).
Any exception thrown by the script provided in a Wrap element is forwarded.

Example
responseAPDU = this.sendApdu(sampleCLA, sampleINS, sampleP1, sampleP2);
// A sendApdu() method sends a command APDU message to the smart card
returnSW = this.card.SW;
// Retrieve the status word returned from the command APDU

Parameter Type Description

cla Number cla refers to the class byte (CLA) of the command message.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

p1 Number P1 parameter.

p2 Number P2 parameter.

data ByteString Optional data field to use with an APDU. This will be a ByteString
object. If a Case 2 command is being constructed, this must be
provided as null.

le Number Optional maximum length of data expected in response to a Case 2

or Case 4 command.
If le is too large, then GPError.INVALID_LENGTH is generated.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.5 GPApplication
GPApplication is a native object used to represent the GlobalPlatform application, where that
application is not a Security Domain or a Card Manager application, for which the script is being
run. When a script for the application is being written, the GPApplication object is referred to
as the this object.
As defined in the ECMAScript specification, native objects are present at the start of the
execution of an ECMAScript program.
A GPApplication object should be created if in the Application Profile, the Type and
SubType attributes of the ApplicationInfo element has a value of “GP” and “APP”
respectively:
<ApplicationInfo Type=“GP” SubType=”APP” />

The GPApplication object implements methods, which support the APDUs in the
GlobalPlatform Card Specification v2.1, and also supplies several additional functions, helping
simplify repetitive or common operations involving these GlobalPlatform APDUs. If a secure
channel exists, the APDU methods will be sent through the secure channel.
The methods and associated properties which represent the commands found in the APDU
Command Reference of the GlobalPlatform Card Specification v2.1 are not extensively
elaborated in this document as to the values to use for properties and which CLA byte to use. It
is expected that the reader understand in which context the method is being used, and format
and supply the properties as required by the GlobalPlatform Card Specification v2.1.
Furthermore, it is expected that an implementation of a GlobalPlatform scripting Interpreter will
make decisions based on what is required by the GlobalPlatform Card Specification v2.1. These
decisions would include which CLA byte to use, where appropriate, whether the supplied property
values are valid, and which additional fields must be populated and or calculated in order for the
command to properly function.
7.1.5.1 Summary
GPApplication.prototype.aid
GPApplication.prototype.appSpecificInstallParams
GPApplication.prototype.card
GPApplication.prototype.crypto
GPApplication.prototype.data[]
GPApplication.prototype.key[]
GPApplication.prototype.lifeCycle.name
GPApplication.prototype.lifeCycle.value
GPApplication.prototype.nonVolatileDataSpaceLimit
GPApplication.prototype.order
GPApplication.prototype.privilege
GPApplication.prototype.profile
GPApplication.prototype.securityDomain
GPApplication.prototype.volatileDataSpaceLimit
GPApplication.prototype.getData()
GPApplication.prototype.getStatus()
GPApplication.prototype.putKey()
GPApplication.prototype.select()
GPApplication.prototype.sendApdu()
GPApplication.prototype.setStatus()
GPApplication.prototype.storeData()
7.1.5.2 Constants
There are no constants for the GPApplication object.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.5.3 Properties

7.1.5.3.1 aid

GPApplication.prototype.aid ByteString
The aid property is a GlobalPlatform scripting language ByteString object.
The aid property represents a ReadOnly, DontDelete property. It represents the application id of the application
instance for the script being executed. It is populated from the ApplicationInstance subelement of the Card Profile.
If it is not available or applicable, then it will contain an empty value.

7.1.5.3.2 appSpecificInstallParams

GPApplication.prototype.appSpecificInstallParams ByteString
The appSpecificInstallParams property is a GlobalPlatform scripting language ByteString object.
The appSpecificInstallParams property represents a ReadOnly, DontDelete property. It represents the install
parameters used in the install command for the application instance for the script being executed. It is populated from
the ApplicationInstance subelement of the Card Profile. If it is not available or applicable, then it will be undefined.

7.1.5.3.3 card

GPApplication.prototype.card Card
The card property is a GlobalPlatform scripting language Card object.
A ReadOnly, DontDelete property. Card object used by the application.

7.1.5.3.4 crypto

GPApplication.prototype.crypto Crypto
The crypto property is a GlobalPlatform scripting language Crypto object.
A ReadOnly, DontDelete property. Crypto object used by the application.

7.1.5.3.5 data[]

GPApplication.prototype.data[] Object[]

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.5.3.6 key[]

GPApplication.prototype.key[] Key[]
The key property is an array of GlobalPlatform scripting language Key objects.
The GPApplication object will be created with an array of Key objects which contains the deserialized keys for an
Application Profile. Each key will be deseralized according to its name as its index. Refer to Section 4.4.3 for more
information and examples.
This is a ReadOnly, DontDelete property. This property is an array of Keys defined in the Application Profile. There is
one element per Key Tag of the application. The index value is the value of the Name attribute of a Key Tag.Note: a Key
can also be retrieved by name using the . (dot) notation.

7.1.5.3.7 lifecycle.name

GPApplicationProfile.prototype.lifecycle.name ByteString
The lifecycle.name property is a GlobalPlatform scripting language ByteString object.
The lifecycle.name property represents a ReadOnly, DontDelete property. It represents the name of the lifecycle of
the application instance for the script being executed. It is populated from the ApplicationInstance subelement of
the Card Profile whose ProfileID matches the UniqueID of the current application profile. If it is not available or
applicable, then it will contain an empty value.

7.1.5.3.8 lifecycle.value

GPApplicationProfile.prototype.lifecycle.value Number
The lifecycle.value property is a GlobalPlatform scripting language ByteString object.
The lifecycle.value property represents a ReadOnly, DontDelete property. It represents the value of the lifecycle
value of the application instance for the script being executed. It is populated from the Value property of the
ApplicationInfo.LifeCycle subelement of the Application Profile that matches the lifecycle.name property. If it
is not available or applicable, then it will contain an empty value.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPApplication.prototype.nonVolatileDataSpaceLimit Number
The nonVolatileDataSpaceLimit property is a ECMAScript Number object.
The nonVolatileDataSpaceLimit property represents a ReadOnly, DontDelete property. It represents the amount
of non-volatile data space specified in the install operation for the application instance for the script being executed. It is
populated from the ApplicationInstance subelement of the Card Profile. If it is not available or applicable, then it
will be undefined.

7.1.5.3.10 order

GPApplicationProfile.prototype.order Number
The order property is an ECMAScript Number object.
The order property represents a ReadOnly, DontDelete property. It represents the order on the card of the application
instance for the script being executed. It is populated from the ApplicationInstance subelement of the Card Profile.
If it is not available or applicable, then it will be undefined.

7.1.5.3.11 privilege

GPApplication.prototype.privilege Number
The privilege property is a GlobalPlatform scripting language Number object.
The privilege property represents a ReadOnly, DontDelete property. It represents the application privileges of the
application instance for the script being executed. Its value will be a hexadecimal encoding of the Privilege child
element of the respective ApplicationInstance element in the Card Profile. Each attribute in the Privilege
element represents a particular byte representation of the privilege property corresponding to the application privileges
coding set forth in the GP Card Specification Version 2.1. Multiple attributes will correspond to the property taking the
value of the logical OR of the specific byte representations associated with each privilege. If there is no Privilege child
element available for the respective ApplicationInstance element, then this property will contain an empty value.

7.1.5.3.12 profile

GPApplication.prototype.profile Object
The profile property is a tree of GlobalPlatform scripting language ByteString and ECMAScript Boolean and
Number objects.
The GPApplication object will be created with a series of objects which replicate, except for Key,
KeyDeclaration, Declaration, and DataElement elements, the GlobalPlatform XML formatted Application
Profile for the application deserialized into a tree of objects. The root XML element of the Application Profile will form the
contents of this root GPApplication.profile object. Refer to Section 4.4.1 for more information and examples.
The data type of the attribute determines the object type to create. The object type is a ByteString or a native
ECMAScript object. Specifically,
GP Systems Profiles Specification GP Scripting Language
XML Attribute Data Type Scripting Object Created
String (or String based Data Type) ByteString
Boolean Boolean
Integer Number

Elements in the XML which can have multiple occurences are created as arrays, which can be indexed by the name of
the first attribute of the element.
For elements which are specified as String data types in the Profiles specification, a ByteString object with the
encoding specified in the Encoding column in the Profiles specification will be created. For those attributes which are
enumerated lists of string, then they will be created as ByteString objects with ASCII encoding.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPApplication.prototype.securityDomain GPSecurityDomain
The securityDomain property is a GlobalPlatform scripting language GPSecurityDomain object.
A ReadOnly, DontDelete property. Object that represents the security domain application for which the specified
application was installed under (information retrieved from the CardProfile).

7.1.5.3.14 volatileDataSpaceLimit

GPApplication.prototype.volatileDataSpaceLimit Number
The volatileDataSpaceLimit property is a ECMAScript Number object.
The volatileDataSpaceLimit property represents a ReadOnly, DontDelete property. It represents the amount of
volatile data space specified in the install operation for the application instance for the script being executed. It is
populated from the ApplicationInstance subelement of the Card Profile. If it is not available or applicable, then it
will be undefined.

7.1.5.4 Methods

7.1.5.4.1 Constructor

GPApplication.prototype.constructor()
new GPApplication()
new GPApplication(arguments)
There is no constructor function for this object.

Example
None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED

7.1.5.4.2 getData()

GPApplication.prototype.getData()
ByteString getData(Number tag)
ByteString getData(Number tag, Number[] sw)
Send a GP GET DATA APDU through the secure channel.
If the application uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
This refers to both the GlobalPlatform GET DATA command.
Any exception thrown by the script provided in the Security Domain’s Wrap element is forwarded.

Example
this.getData(myTagValue);

Parameter Type Description

tag Number The tag value is always aligned internally to a double byte value.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.5.4.3 getStatus()

GPApplication.prototype.getStatus()
ByteString getStatus(Number type, ByteString criteria, Boolean next)
ByteString getStatus(Number type, ByteString criteria, Boolean next,
Number[] sw)
Send a GP GET STATUS APDU through the secure channel.
If the application uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
This refers to the GlobalPlatform GET STATUS command.
Any exception thrown by the script provided in the Security Domain’s Wrap element is forwarded.

Example
this.getStatus(APPS_ONLY, searchQualifier, false);
Parameter Type Description
type Number p1 is the reference control parameter as specified in the Card
Specification:
CM_ONLY Card Manager Only
APPS_ONLY Applications Only
LF_ONLY Load File Only
LFE_ONLY Load Files and All Executable Files
criteria ByteString AID of the criteria. Could be a partial AID.

next Boolean Whether the next occurrence should be returned. Default is false.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.5.4.4 putKey()

GPApplication.prototype.putKey()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

ByteString putKey(Number version, Number newVersion, Number index,

[ [Number type, Key key, ByteString kcv] ])
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number type, Key key, ByteString kcv] ], Number[] sw)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number type, Key key, ByteString kcv] ],
Boolean more)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number type, Key key, ByteString kcv] ],
Boolean more, Number[] sw)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number keyType, Key key, Number componentCte] ])
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number keyType, Key key, Number componentCte] ], Number[] sw)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number keyType, Key key, Number componentCte] ],
Boolean more)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number keyType, Key key, Number componentCte] ],
Boolean more, Number[] sw)
Send a GP PUT KEY APDU through the secure channel. If the application uses a secure channel, this method should
call implicitly the Wrap script fragment defined in the appropriate Application Profile for a Security Domain.
This method should implicitly encrypt key(s) with the card KEK
Any exception thrown by the script provided in the Security Domain’s Wrap element is forwarded.

Example
dataToEncrypt = new ByteString("0000000000000000", HEX);
keyCheckValue = this.crypto.encrypt(this.key.sampleKey, Crypto.DES_ECB, dataToEncrypt);
keyInfo1 = [0x81, this.key.sampleKey, keyCheckValue];
keyInfo = [keyInfo1];
this.putKey(0, 1, 1, keyInfo);

Parameter Type Description

version Number Value of the current key set version as specified in the Control
parameter P1 (see GP Card specification)

newVersion Number Value of the new key set version (see GP Card specification)

index Number Value of the key index as specified in the Control parameter P2 (see
GP Card specification)

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

[[type, key, [[ Number, Where:

kcv]] Key,
ByteString, · type is a Number
]] · key is a Key object
· kcv is a ByteString object
The type parameter corresponds to a value as defined in the Card
Specification.
This method should implicitly encrypt each key with the card KEK.
The key could be encrypted by a kek key, so in that case the method
should perform an implicit UnwrapWrap to decrypt in the HSM and
re-encrypt the key by the card KEK. This method implicitly builds the
correct data field of the APDU.

more Boolean A Boolean value, to indicate if it’s the last or only putKey call. The
default value is false. That value will implicitly change the P1
control parameter of the APDU (for more details see GP card
specification).

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_KEY
GPError.INVALID_TYPE

7.1.5.4.5 select()

GPApplication.prototype.select()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

ByteString select()
ByteString select(Boolean next)
ByteString select(Boolean next, Boolean noData)
ByteString select(Boolean next, Number[] sw)
ByteString select(Boolean next, Boolean noData, Number[] sw)
Send a GP Select APDU (0x00 0xA4 0x04 …) with the AID of the application (AID value is retrieved from the Card
Profile). The select() method should implicitly reset the application’s secure channel security level. If select()
method invocation is used, then the next parameter is assumed to be false.
The select() method is used for selecting an application. This refers to the [IS7816-4] SELECT command.

Example
this.select(true);

Parameter Type Description

next Boolean If true send a Select APDU with P2 set to 0x02, otherwise send a
Select APDU with P2 set to 0x00. By default, if next is not provided
as a parameter, then this parameter is false.

noData Boolean If true no AID is required for the select.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU data

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.5.4.6 sendApdu()

GPApplication.prototype.sendApdu()
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number le)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number le,
Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number le)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number le, Number[] sw)
Send an APDU to the card. If the application doesn’t use a secure channel the APDU is sent to the card directly (i.e.
same as Application.card.sendApdu()). If the application uses a secure channel, this method should call
implicitly the Wrap script fragment defined in the Security Domain or equivalent Application Profile unless Card
Specification defined secure channels and implementation options are used. The APDU field Lc is not specified in the
sendApdu() method, but must be calculated by the method implicitly (see [IS7816-4]).
Any exception thrown by the script provided in the Security Domain’s Wrap element is forwarded.

Parameter Type Description

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

ins Number ins refers to the instruction byte (INS) of the command message.

p1 Number P1 parameter.

p2 Number P2 parameter.

data ByteString Optional data field to use with an APDU. This will be a ByteString
object. If a Case 2 command is being constructed, this must be
provided as null.

le Number Optional maximum length of data expected in response to a Case 2

or Case 4 command.
If le is too large, then GPError.INVALID_LENGTH is generated.

sw Number Optional array of Numbers which correspond to status words which

will be accepted as indication of successful execution of the method.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.5.4.7 setStatus()

GPApplication.prototype.setStatus()
setStatus(Number status)
setStatus(Number status, Number[] sw)
Send a GP SET STATUS APDU through the secure channel. The method should implicitly create the correct APDU for
the P1 parameter (Card Manager or Application) and the Data field (AID of the instance).
If the application uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
Security Domain or equivalent Application Profile.
This refers to the GlobalPlatform SET STATUS command.
Any exception thrown by the script provided in the Security Domain’s Wrap element is forwarded.

Example
// Assume that 0x01 is a valid lifecycle state as defined in the
// Application Profile
this.setStatus(0x01);

Parameter Type Description

status Number A Life Cycle Status Coding value (as defined in the GP Card
specification). Valid values should be retrieved from the Application
Profile in the LifeCycles element.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPApplication.prototype.storeData()
storeData(ByteString data)
storeData(ByteString data, Boolean last)
storeData(ByteString data, Boolean last, Number[] sw)
Send a GP STORE DATA APDU through the secure channel. This method should be implemented in any case, even if
the targeted card is not a GlobalPlatform 2.1 card.
The storeData() method is used to transfer data to an application, and if a secure channel is available, through the
secure channel. This refers to the GlobalPlatform STORE DATA command.
If the application uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
Any exception thrown by the script provided in the Security Domain’s Wrap element is forwarded.

Example
this.storeData(MORE_BLOCKS, x11, dataToStore);

Parameter Type Description

data ByteString Data field APDU. data is a ByteString containing data in the
format expected by the application as specified in the Card
Specification. The lc parameter for the command APDU is calculated
as the length of this data field.

last Boolean A Boolean value, to indicate if it’s the last or only storeData call.
The default value is false. That value will implicitly change the P1
control parameter of the APDU (for more details see GP card
specification 2.1).

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.6 GPSecurityDomain
GPSecurityDomain is a native object used to represent the application for the script being run
when the application is a GlobalPlatform security domain or a card manager. For scripts written
for an application which is a security domain or card manager, the GPSecurityDomain is
accessed using the this object.
As defined in the ECMAScript specification, native objects are present at the start of the
execution of an ECMAScript program.
A GPSecurityDomain object should be created if in the Application Profile the Type and
SubType attributes of the ApplicationInfo element have values of “GP” and “CM” or “SD”,
respectively:
<ApplicationInfo Type=“GP” SubType=”CM” />

<ApplicationInfo Type=“GP” SubType=”SD” />

The GPSecurityDomain object implements methods which support the APDUs in the
GlobalPlatform Card Specification and also supplies several additional functions, helping simplify
repetitive or common operations involving these GlobalPlatform APDUs. The
GPSecurityDomain object inherits the properties and methods of the Application object,
and adds several APDU functions as defined in the GlobalPlatform Card Specification for load
and install operations. If a secure channel exists, APDU commands are sent through the secure
channel.
The methods and associated properties which represent the commands found in the APDU
Command Reference of the GlobalPlatform Card Specification are not extensively elaborated in
this document as to the values to use for properties and which CLA byte to use. It is expected
that the reader understand in which context the method is being used, and format and supply the
properties as required by the GlobalPlatform Card Specification.
Furthermore, it is expected that an implementation of an GlobalPlatform scripting interpreter will
make decisions based on what is required by the GlobalPlatform Card Specification. These
decisions would include which CLA byte to use, where appropriate, whether the supplied property
values are valid, and which additional fields must be populated and or calculated in order for the
command to properly function.
7.1.6.1 Summary
GPSecurityDomain.prototype.aid
GPSecurityDomain.prototype.appSpecificInstallParams
GPSecurityDomain.prototype.card
GPSecurityDomain.prototype.crypto
GPSecurityDomain.prototype.data[]
GPSecurityDomain.prototype.key[]
GPSecurityDomain.prototype.lifeCycle.name
GPSecurityDomain.prototype.lifeCycle.value
GPSecurityDomain.prototype.nonVolatileDataSpaceLimit
GPSecurityDomain.prototype.order
GPSecurityDomain.prototype.privilege
GPSecurityDomain.prototype.profile
GPSecurityDomain.prototype.secureChannel
GPSecurityDomain.prototype.securityDomain
GPSecurityDomain.prototype.volatileDataSpaceLimit
GPSecurityDomain.prototype.deleteAID()
GPSecurityDomain.prototype.getData()
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 93
GPSecurityDomain.prototype.getStatus()
GPSecurityDomain.prototype.installForExtradition()
GPSecurityDomain.prototype.installForInstall()
GPSecurityDomain.prototype.installForInstallAndSelectable()
GPSecurityDomain.prototype.installForLoad()
GPSecurityDomain.prototype.installForPersonalization()
GPSecurityDomain.prototype.load()
GPSecurityDomain.prototype.loadByName()
GPSecurityDomain.prototype.loadWithProfileID()
GPSecurityDomain.prototype.openSecureChannel()
GPSecurityDomain.prototype.putKey()
GPSecurityDomain.prototype.select()
GPSecurityDomain.prototype.sendApdu()
GPSecurityDomain.prototype.setStatus()
GPSecurityDomain.prototype.storeData()
7.1.6.2 Constants
There are no constants for the GPSecurityDomain object.
7.1.6.3 Properties

7.1.6.3.1 aid

GPSecurityDomain.prototype.aid ByteString
The aid property is a GlobalPlatform scripting language ByteString object.
The aid property represents a ReadOnly, DontDelete property. It represents the application id of the application
instance for the script being executed. It is populated from the ApplicationInstance subelement of the Card Profile.
If it is not available or applicable, then it will contain an empty value.

7.1.6.3.2 appSpecificInstallParams

GPSecurityDomain.prototype.appSpecificInstallParams ByteString
The appSpecificInstallParams property is a GlobalPlatform scripting language ByteString object.
The appSpecificInstallParams property represents a ReadOnly, DontDelete property. It represents the install
parameters used in the install command for the application instance for the script being executed. It is populated from
the ApplicationInstance subelement of the Card Profile. If it is not available or applicable, then it will be undefined.

7.1.6.3.3 card

GPSecurityDomain.prototype.card Card
The card property is a GlobalPlatform scripting language Card object.
The card object represents a ReadOnly, DontDelete property. Card object used by the security domain.

7.1.6.3.4 crypto

GPApplication.prototype.crypto Crypto
The crypto property is a GlobalPlatform scripting language Crypto object.
A ReadOnly, DontDelete property. Crypto object used by the application.

7.1.6.3.5 data[]

GPSecurityDomain.prototype.data[] Object[]

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

XML Application Profile DataElement Element GP Scripting Language

Type Attribute Encoding Attribute Scripting Object Created
ByteString HEX ByteString
ByteString UTF8 ByteString
ByteString ASCII ByteString
ByteString BASE64 ByteString
ByteString CN ByteString
ByteString TLV*
(and Tag and TagEncoding specified)
*with enough bytes to accommodate the Tag and the length of the data (if any) for the specified TagEncoding
Unless specified otherwise, this is a read only, don’t delete property. This property is an array of Objects for the
DataElement XML elements defined in the Application Profile. There is one element per DataElement element of
the Application Profile. The index value is the value of the Name attribute of a DataElement element. Each element
has it’s own attributes, based on the <DataElement> tag (i.e., an element can be ReadOnly or R/W depending of
the value of ReadWrite attribute in the profile). Note: a data object can also be retrieved by name using the . (dot)
notation.

7.1.6.3.6 key[]

GPSecurityDomain.prototype.key[] Key[]
The key property is an array of GlobalPlatform scripting language Key objects.
The GPSecurityDomain object will be created with an array of Key objects which contains the deserialized keys for an
Application Profile. Each key will be deseralized according to its name as its index. Refer to Section 4.4.3 for more
information and examples.
This is a ReadOnly, DontDelete property. This property is an array of Keys defined in the Application Profile. There is
one element per Key Tag of the application. The index value is the value of the Name attribute of a Key Tag.Note: a
Key can also be retrieved by using the . (dot) notation.

7.1.6.3.7 lifecycle.name

GPSecurityDomain.prototype.lifecycle.name ByteString
The lifecycle.name property is a GlobalPlatform scripting language ByteString object.
The lifecycle.name property represents a ReadOnly, DontDelete property. It represents the name of the lifecycle of
the application instance for the script being executed. It is populated from the ApplicationInstance subelement of
the Card Profile whose ProfileID matches the UniqueID of the current application profile. If it is not available or
applicable, then it will contain an empty value.

7.1.6.3.8 lifecycle.value

GPSecurityDomain.prototype.lifecycle.value Number
The lifecycle.value property is a GlobalPlatform scripting language ByteString object.
The lifecycle.value property represents a ReadOnly, DontDelete property. It represents the value of the lifecycle
value of the application instance for the script being executed. It is populated from the Value property of the
ApplicationInfo.LifeCycle subelement of the Application Profile that matches the lifecycle.name property. If it
is not available or applicable, then it will contain an empty value.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPSecurityDomain.prototype.nonVolatileDataSpaceLimit Number
The nonVolatileDataSpaceLimit property is a ECMAScript Number object.
The nonVolatileDataSpaceLimit property represents a ReadOnly, DontDelete property. It represents the amount
of non-volatile data space specified in the install operation for the application instance for the script being executed. It is
populated from the ApplicationInstance subelement of the Card Profile. If it is not available or applicable, then it
will be undefined.

7.1.6.3.10 order

GPSecurityDomain.prototype.order Number
The order property is an ECMAScript Number object.
The order property represents a ReadOnly, DontDelete property. It represents the order on the card of the application
instance for the script being executed. It is populated from the ApplicationInstance subelement of the Card Profile.
If it is not available or applicable, then it will be undefined.

7.1.6.3.11 privilege

GPSecurityDomain.prototype.privilege Number
The privilege property is a GlobalPlatform scripting language Number object.
The privilege property represents a ReadOnly, DontDelete property. It represents the application privileges of the
application instance for the script being executed. Its value will be a hexadecimal encoding of the Privilege child
element of the respective ApplicationInstance element in the Card Profile. Each attribute in the Privilege
element represents a particular byte representation of the privilege property corresponding to the application privileges
coding set forth in the GP Card Specification Version 2.1. Multiple attributes will correspond to the property taking the
value of the logical OR of the specific byte representations associated with each privilege. If there is no Privilege child
element available for the respective ApplicationInstance element, then this property will contain an empty value.

7.1.6.3.12 profile

GPSecurityDomain.prototype.profile Object
The profile property is a tree of GlobalPlatform scripting language ByteString and ECMAScript Boolean and
Number objects.
The GPSecurityDomain object will be created with a series of objects which replicate, except for Key,
KeyDeclaration, Declaration, and DataElement elements, the GlobalPlatform XML formatted Application
Profile for the application deserialized into a tree of objects. The root XML element of the Application Profile will form the
contents of this root GPSecurityDomain.profile object. Refer to Section 4.4.1 for more information and examples.
The data type of the attribute determines the object type to create. The object type is a ByteString or a native
ECMAScript object. Specifically,
GP Systems Profiles Specification GP Scripting Language
XML Attribute Data Type Scripting Object Created
String (or String based Data Type) ByteString
Boolean Boolean
Integer Number

Elements in the XML which can have multiple occurences are created as arrays, which can be indexed by the name of
the first attribute of the element.
For elements which are specified as String data types in the Profiles specification, a ByteString object with the
encoding specified in the Encoding column in the Profiles specification will be created. For those attributes which are
enumerated lists of string, then they will be created as ByteString objects with ASCII encoding.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPSecurityDomain.prototype.secureChannel (GPScp01 or GPSCP02)

The secureChannel property is a GlobalPlatform scripting language SecureChannel object.
A ReadOnly, DontDelete property. Object that represents the SecureChannel used by the application.

7.1.6.3.14 securityDomain

GPSecurityDomain.prototype.securityDomain GPSecurityDomain
The securityDomain property is a GlobalPlatform scripting language GPSecurityDomain object.
A ReadOnly, DontDelete property. Object that represents the current Security Domain application (information retrieved
from the Card Profile). If the GPSecurityDomain represents the issuer security domain (card manager), then this
property will point to this GPSecurityDomain object.

7.1.6.3.15 volatileDataSpaceLimit

GPSecurityDomain.prototype.volatileDataSpaceLimit Number
The volatileDataSpaceLimit property is a ECMAScript Number object.
The volatileDataSpaceLimit property represents a ReadOnly, DontDelete property. It represents the amount of
volatile data space specified in the install operation for the application instance for the script being executed. It is
populated from the ApplicationInstance subelement of the Card Profile. If it is not available or applicable, then it
will be undefined.

7.1.6.4 Methods

7.1.6.4.1 Constructor

GPSecurityDomain.prototype.constructor()
new GPSecurityDomain()
new GPSecurityDomain(arguments)
There is no constructor function for this object.

Example
None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED

7.1.6.4.2 deleteAID()

GPSecurityDomain.prototype.deleteAID()
ByteString deleteAID(ByteString aid)
ByteString deleteAID(ByteString aid, Number[] sw)

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
this.deleteAID(myAID);

Parameter Type Description

aid ByteString AID to delete. Tag 4F and length are implicitly added by the method.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response data of response APDU.

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.3 getData()

GPSecurityDomain.prototype.getData()
ByteString getData(Number tag)
ByteString getData(Number tag, Number[] sw)
Send a GP GET DATA APDU through the secure channel.
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
This refers to both the GlobalPlatform GET DATA command.
Any exception thrown by the script provided in a Wrap element is forwarded.

Example
this.getData(myTagValue);

Parameter Type Description

tag Number The tag value is always aligned internally to a double byte value.
The MSB of this double byte is the P1 and LSB is P2.
(i.e.: Tag value of 0x42 will set P1 = 0x00 - P2 = 0x42. Tag value of
0x9F7F will set P1 = 0x9F – P2 = 0x7F)

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.4 getStatus()

GPSecurityDomain.prototype.getStatus()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

ByteString getStatus(Number type, ByteString criteria, Boolean next)

ByteString getStatus(Number type, ByteString criteria, Boolean next,
Number[] sw)
Send a GP GET STATUS APDU through the secure channel.
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
This refers to the GlobalPlatform GET STATUS command.
Any exception thrown by the script provided in a Wrap element is forwarded.

criteria ByteString AID of the criteria. Could be a partial AID.

next Boolean Whether the next occurrence should be returned. Default is false.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.5 installForExtradition()

GPSecurityDomain.prototype.installForExtradition()
ByteString installForExtradition(ByteString secDomAID, ByteString appAID,
ByteString token)
ByteString installForExtradition(ByteString secDomAID, ByteString appAID,
ByteString token, Number[] SW)
Send a GP INSTALL APDU through the secure channel with P1 set to FOR_EXTRADITION (see GP Card specification
for more details).
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
Any exception thrown by the script provided in a Wrap element is forwarded.

Example
this.installForExtradition(mySDAID, myLFAID, myToken);

Parameter Type Description

secDomAID ByteString The application AID assigned to a security domain.

appAID ByteString The application AID assigned to an application.

token ByteString Extradition token.

sw Number[] Array of expected valid SW for the APDU. If not present, the

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.6 installForInstall()

GPSecurityDomain.prototype.installForInstall()
ByteString installForInstall(ByteString execLFAID,
ByteString execModAID,
ByteString appInsAID,
ByteString privileges,
ByteString installParam,
ByteString installToken)
ByteString installForInstall(ByteString execLFAID,
ByteString execModAID,
ByteString appInsAID,
ByteString privileges,
ByteString installParam,
ByteString installToken,
Number [] sw)
Send a GP INSTALL APDU through the secure channel with P1 set to FOR_INSTALL.
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
Any exception thrown by the script provided in a Wrap element is forwarded.

Example
this.installForInstall(myLFAID, myModAID, myInsAID, myPrivileges, myParam, myToken);

Parameter Type Description

execLFAID ByteString Load File AID.

execModAID ByteString Executable Module AID.

appInsAID ByteString Application AID.

privileges ByteString Application Privileges.

installParam ByteString Install Parameter field.

installToken ByteString Install Token.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.7 installForInstallAndSelectable()

GPSecurityDomain.prototype.installForInstallAndSelectable()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

ByteString installForInstallAndSelectable(ByteString execLFAID,

ByteString execModAID,
ByteString appInsAID,
ByteString privileges,
ByteString installParam,
ByteString installToken)
ByteString installForInstallAndSelectable(ByteString execLFAID,
ByteString execModAID,
ByteString appInsAID,
ByteString privileges,
ByteString installParam,
ByteString installToken,
Number [] sw)
Send a GP INSTALL APDU through the secure channel with P1 set to FOR_INSTALL and FOR_MAKE_SELECTABLE.
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
Any exception thrown by the script provided in a Wrap element is forwarded.

Example
this.installForInstallAndSelectable(myLFAID, myModAID, myInsAID, myPrivileges, myParam,
myToken);

Parameter Type Description

execLFAID ByteString Load File AID.

execModAID ByteString Executable Module AID.

appInsAID ByteString Application AID.

privileges ByteString Application Privileges.

installParam ByteString Install Parameter field.

installToken ByteString Install Token.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.8 installForLoad()

GPSecurityDomain.prototype.installForLoad()
ByteString installForLoad(ByteString loadFileAID, ByteString secDomAID,
ByteString loadDBHash, ByteString loadParam,
ByteString loadToken)
ByteString installForLoad(ByteString loadFileAID, ByteString secDomAID,
ByteString loadDBHash, ByteString loadParam,
ByteString loadToken, Number[] SW)

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
this.installForLoad(myLFAID, mySecDomAID, myLoadHash, myLoadParam, myLoadToken);

Parameter Type Description

loadFileAID ByteString The application ID assigned to a load file.

secDomAID ByteString Application ID assigned to a security domain.

loadDBHash ByteString Load File Data Block Hash.

loadParam ByteString Load Parameter field.

loadToken ByteString Load Token.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.9 installForPersonalization()

GPSecurityDomain.prototype.installForPersonalization()
installForPersonalization(ByteString appAID)
installForPersonalization(ByteString appAID, Number[] sw)
Send a GP INSTALL APDU through the secure channel with P1 set to FOR_PERSONALIZATION.
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
Any exception thrown by the script provided in a Wrap element is forwarded.

Example
this.installForPersonalization(myAID);
Parameter Type Description

appAID ByteString The application ID assigned to an application.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU

Exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.10 load()

GPSecurityDomain.prototype.load()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

ByteString load(ByteString loadFile)

ByteString load(ByteString loadFile, Number[] sw)
ByteString load(ByteString loadFile, [ ByteString[] [aid, dap]])
ByteString load(ByteString loadFile, [ ByteString[] [aid, dap]], Number[] sw)
Send a set of GP LOAD APDU through the secure channel to load a Load File structure on the card. This method
implicitly manage the P1 and P2 values of all APDUs.
Note: This method does not use a file name, but the GP Load File Structure (See GP Card specification for more
details)
It is the responsibility of the scripting interpreter implementation to discern whether the contents supplied are the
contents of a CAP or JAR file, and process as required.
This method implicitly:
· checks the type of the file, and eventually decompresses the file before sending APDUs
· manages the P1 and P2 values of all APDUs
· builds the complete Load File Structure by adding Tag and Length (for tags E2, 4F, C3, C4)
This method utilizes the GlobalPlatform LOAD command.
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
Any exception thrown by the script provided in a Wrap element is forwarded.
To enforce versioning control, it is recommended that loadWithProfile() is used instead of load() or loadByName().

Example
// myFileContents will contain a CAP file represented as a hexadecimal
// encoded ByteString. load() will load the file onto the smart card.
myFileContents = new ByteString(“504B03040A000000000007008C2C0…”, HEX);
this.load(myFileContents);

Parameter Type Description

loadFile ByteString Load File Structure (should contain Tag C4 and eventualy Tags E2).

[[aid, dap]] [[ ByteString, Each element [ aid, dap ] represents a “DAP block”, where:
ByteString ]]
· aid is a ByteString for the Security Domain AID value
· dap is a ByteString for the Load File Data Block Signature
value
sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.11 loadByName()

GPSecurityDomain.prototype.loadByName()
ByteString loadByName(ByteString filename)
ByteString loadByName(ByteString filename, [ ByteString[] [aid, dap]])

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
// Load a file named sampleApplication.cap onto the smart card
loadFileName = new ByteString(“sampleApplication.cap”, ASCII);
this.loadByName(loadFileName);

Parameter Type Description

filename ByteString File name to load on the card, including any file type suffix.

[[aid, dap]] [[ ByteString, Each element [ aid, dap ] represents a “DAP block”, where:
ByteString ]]
· aid is a ByteString for the Security Domain AID value
· dap is a ByteString for the Load File Data Block Signature
value
returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.12 loadWithProfile()

GPSecurityDomain.prototype.loadWithProfile()
ByteString loadWithProfile(ByteString loadFileProfileID)
ByteString loadWithProfile(ByteString loadFileProfileID, Number[] sw)
ByteString loadWithProfile(ByteString loadFileProfileID, [ ByteString[] [aid, dap]])
ByteString loadWithProfile(ByteString loadFileProfileID, [ ByteString[] [aid, dap]],
Number[] sw)

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
// myFileContents will contain a CAP file represented as a hexadecimal
// encoded ByteString. loadWithProfile() will load the file onto the smart card.
myFileContents = new ByteString(“504B03040A000000000007008C2C0…”, HEX);
this.loadWithProfile(myFileContents);

Parameter Type Description

loadFileProfileID ByteString The value of the uniqueID attribute of the Load File Profile
corresponding to the load file which is to be loaded.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.13 openSecureChannel()

GPSecurityDomain.prototype.openSecureChannel()
Number openSecureChannel(Number level)
Number openSecureChannel(Number level, Number version)
Number openSecureChannel(Number level, Number version, Number index)
Open a secure channel with the Issuer Security Domain. This method should call implicitly the OpenSecureChannel
script fragment defined in the Issuer Security Domain Application Profile. Once the secure channel is opened, all
APDU’s are sent through the secure channel. It is the responsibility of Issuer Security Domain script fragment to set all
keys needed to manage the secure channel and sessions (Encryption, MACing, KEK).
Once the secure channel is opened, all APDU’s are sent through the secure channel using the Wrap script specified in
the Application Profile, if a Wrap script is provided. For cases where the secure channel is represented by a GPScp01
or GPScp02, and a Wrap script is provided, then the Wrap script takes precedence over the implicit processing of a
GPScp01 or GPScp02 secure channel.
Any exception thrown by the script provided in a Wrap element is forwarded.

Example
// Opens a secure channel with level of zero.
mySC = this.openSecureChannel(0);

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Parameter Type Description

level Number Level of security requested for the secure channel.

version Number Key set version.

index Number Key set version index.

returns Number If success, return the Level of security selected for the secure
channel. If the security level requested is invalid or to low, the
Security Domain script fragment could choose to raise an exception
or change itself the value to a valid security level.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.6.4.14 putKey()

GPSecurityDomain.prototype.putKey()
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number type, Key key, ByteString kcv] ])
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number type, Key key, ByteString kcv] ], Number[] sw)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number type, Key key, ByteString kcv] ],
Boolean more)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number type, Key key, ByteString kcv] ],
Boolean more, Number[] sw)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number keyType, Key key, Number componentCte] ])
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number keyType, Key key, Number componentCte] ], Number[] sw)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number keyType, Key key, Number componentCte] ],
Boolean more)
ByteString putKey(Number version, Number newVersion, Number index,
[ [Number keyType, Key key, Number componentCte] ],
Boolean more, Number[] sw)
Send a GP PUT KEY APDU through the secure channel. This method should implicitly encrypt key(s) with the card
KEK
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
Any exception thrown by the script provided in a Wrap element is forwarded.

Parameter Type Description

version Number Value of the current key set version as specified in the Control
parameter P1 (see GP Card specification)

newVersion Number Value of the new key set version (see GP Card specification)

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

[ [keyType, key, [ [Number, Key, Where:

componentCte] ] Number] ]
· type is a Number
· key is a Key object
· componentCte is a Number object
This method should implicitly encrypt each key with the card KEK.
The key could be encrypted by a KEK key, so in that case the
method should perform an implicit UnwrapWrap to decrypt in the
HSM and re-encrypt the key by the card KEK. For the case of a
public key, there is no implicit wrap or unwrapwrap operation
performed.
This method implicitly builds the correct data field of the APDU.
The type parameter corresponds to a value as defined in the Card
Specification.
componentCte contains a constant corresponding to the type of
component to retrieve. Valid values are:
Key.CRT_P RSA Key Components
Key.CRT_Q RSA Key Components
Key.CRT_DP1 RSA Key Components
Key.CRT_DQ1 RSA Key Components
Key.CRT_PQ RSA Key Components
Key.EXPONENT Exponent Value
Key.MODULUS Modulus Value
If any invalid component type is specified, then a GPError is
generated with a value of GPError.INVALID_DATA.

[[type, key, [[ Number, Where:

kcv]] Key,
ByteString, · type is a Number
]] · key is a Key object
· kcv is a ByteString object
This method should implicitly encrypt each key with the card KEK.
The key could be encrypted by a KEK key, so in that case the
method should perform an implicit UnwrapWrap to decrypt in the
HSM and re-encrypt the key by the card KEK. This method implicitly
builds the correct data field of the APDU.
The type parameter corresponds to a value as defined in the Card
Specification.

more Boolean A Boolean value, to indicate if it’s the last or only putKey call. The
default value is false. That value will implicitly change the P1 control
parameter of the APDU (for more details see GP card specification).

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_KEY
GPError.INVALID_TYPE

7.1.6.4.15 select()

GPSecurityDomain.prototype.select()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

ByteString select()
ByteString select(Boolean next)
ByteString select(Boolean next, Boolean noData)
ByteString select(Boolean next, Number[] sw)
ByteString select(Boolean next, Boolean noData, Number[] sw)
Send a GP Select APDU (0x00 0xA4 0x04 …) with the AID of the application (AID value is retrieved from the Card
Profile). The select() method should implicitly reset the application’s secure channel security level.
The select() method is used for selecting an application. This refers to the [IS7816-4] SELECT command.

Example
this.select(true);

Parameter Type Description

next Boolean If true send a Select APDU with P2 set to 0x02, otherwise send a
Select APDU with P2 set to 0x00.

noData Boolean If true no AID is required for the select.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns ByteString FCI of the selected Application

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_TYPE

7.1.6.4.16 sendApdu()

GPSecurityDomain.prototype.sendApdu()
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number le)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number le,
Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number le)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number le, Number[] sw)
Send an APDU to the card. If the security domain doesn’t use a secure channel the APDU is sent to the card directly
(i.e. same as Application.card.sendApdu()). If the security domain uses a secure channel, this method should
call implicitly the Wrap script fragment defined in the Security Domain or equivalent Application Profile unless Card
Specification defined secure channels and implementation options are used. The APDU field Lc is not specified in the
sendApdu method, but must be calculated by the method implicitly (see [IS7816-4]).
Any exception thrown by the script provided in a Wrap element is forwarded.

Parameter Type Description

cla Number cla refers to the class byte (CLA) of the command message.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

p1 Number P1 parameter.

p2 Number P2 parameter.

data ByteString Optional data field to use with an APDU. This will be a ByteString
object. If a Case 2 command is being constructed, this must be
provided as null.

le Number Optional maximum length of data expected in response to a Case 2

or Case 4 command.
If le is too large, then GPError.INVALID_LENGTH is generated.

sw Number Optional array of Numbers which correspond to valid status words.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.6.4.17 setStatus()

GPSecurityDomain.prototype.setStatus()
setStatus(ByteString aid, Number status)
setStatus(ByteString aid, Number status, Number[] sw)
Send a GP SET STATUS APDU through the secure channel. The method should implicitly create the correct APDU for
the P1 parameter (Card Manager or Application).
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
This refers to the GlobalPlatform SET STATUS command.
Any exception thrown by the script provided in a Wrap element is forwarded.

Example
// This will set the status of the application to GP state PERSONALIZED
this.setStatus(myPaymentApplicationAID, 0x7F);

Parameter Type Description

aid ByteString AID of the application to set the status.

status Number A Life Cycle Status Coding value (as defined in the GP Card
specification). Valid values should be retrieved from the Application
Profile in the LifeCycles element.

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_TYPE

7.1.6.4.18 storeData()

GPSecurityDomain.prototype.storeData()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

storeData(ByteString data, Boolean more)

storeData(ByteString data, Boolean more, Number[] sw)
Send a GP STORE DATA APDU through the secure channel. This method should be implemented in any case, even if
the targeted card is not a GlobalPlatform 2.1 card.
The APDU P2 parameter is implicitly managed by the method (start with 0x00, incremented after each call, and reset to
0x00 after a call with last = true).
If the security domain uses a secure channel, this method should call implicitly the Wrap script fragment defined in the
appropriate Application Profile for a Security Domain.
This refers to the GlobalPlatform STORE DATA command.
Any exception thrown by the script provided in a Wrap element is forwarded.

Example
this.storeData(MORE_BLOCKS, x11, dataToStore);

Parameter Type Description

data ByteString Data field APDU. data is a ByteString containing data in the
format expected by the Security Domain as specified in the Card
Specification. The lc parameter for the command APDU is calculated
as the length of this parameter.

more Boolean A Boolean value, to indicate if it’s the last or only storeData call.
The default value is false. That value will implicitly change the P1
control parameter of the APDU (for more details see GP card
specification 2.1).

sw Number[] Array of expected valid SW for the APDU. If not present, the
expected valid value is 0x9000.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.CARD_COMM_ERROR
GPError.CARD_SW_ERROR
GPError.INVALID_TYPE

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.7 SecureChannel
A SecureChannel object is a native object. A SecureChannel object is used to perform
transformation (like MACing, Encryption) on an APDU based on a security level, specifically for
those instances where the secure channel is not a standard GlobalPlatform secure channel or
one which is not supported by another scripting language object (i.e., GPScp01 and GPScp02 as
per GlobalPlatform Card Specification 2.1). The transformation of the APDU must be done only
when the APDU is sent by an Application object. Sending an APDU using the card property
of one of those objects, will never perform any transformation on the APDU (execpt the
calculation of the Lc field). Refer to Appendix C for more detail.
For this object to be successfully created, the SecureChannel element of the Application
Profile must be fully populated. That is, there needs to be OpenSecureChannel,
CloseSecureChannel and Wrap elements contain the requisite scripts present. This is in
order to facilitate the correct operation of the secure channel related methods in the respective
Application or GPApplication object.
7.1.7.1 Summary
SecureChannel.prototype.crypto
SecureChannel.prototype.state
7.1.7.2 Constants
There are no constants for the SecureChannel object.
7.1.7.3 Properties

7.1.7.3.1 crypto

SecureChannel.prototype.crypto Crypto
The crypto property is a GlobalPlatform scripting language Crypto object.
A ReadOnly, DontDelete property. Crypto object used by the secure channel.

7.1.7.3.2 state

SecureChannel.prototype.state Number
The state property is an ECMAScript Number object.
This is a Number. ReadOnly, DontDelete property. Current state of the secure channel, as specified using one of the
following global constants:
· SC_CLOSE
· SC_OPEN

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.8 GPScp01
A GPScp01 object is a native object. The GPScp01 object is an implementation of the Secure
Channel Protocol 01 described in the GP Card Specification.
A GPScp01 object is used to perform transformation (like MACing, Encryption) on an APDU
based on a security level as specified in the GlobalPlatform Card Specification. The
transformation of the APDU must be done only when the APDU is sent by an GPApplication
or GPSecurityDomain object. Sending an APDU using the card property of one of those
objects, will never perform any transformation on the APDU (execpt the calculation of the Lc
field). Refer to Appendix C for more detail.
The KEK key used is known by the secure channel.
7.1.8.1 Summary
GPScp01.prototype.cardChallenge
GPScp01.prototype.cardCryptogram
GPScp01.prototype.crypto
GPScp01.prototype.diversificationData
GPScp01.prototype.hostChallenge
GPScp01.prototype.keyIndex
GPScp01.prototype.keyVersion
GPScp01.prototype.mac
GPScp01.prototype.option
GPScp01.prototype.securityLevel
GPScp01.prototype.state
GPScp01.prototype.decryptEncryptKek()
GPScp01.prototype.encryptKek()
GPScp01.prototype.externalAuthenticate()
GPScp01.prototype.getDekKey()
GPScp01.prototype.initializeUpdate()
GPScp01.prototype.setDekKey()
GPScp01.prototype.setEncKey()
GPScp01.prototype.setMacKey()
GPScp01.prototype.unwrapWrapKek()
7.1.8.2 Constants
There are no constants for the GPScp01 object.
7.1.8.3 Properties

7.1.8.3.1 cardChallenge

GPScp01.prototype.cardChallenge ByteString
The cardChallenge property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Card challenge value for the secure channel.

7.1.8.3.2 cardCryptogram

GPScp01.prototype.cardCryptogram ByteString
The cardCryptogram property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Card cryptogram returned by the InitializeUpdate APDU.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPScp01.prototype.crypto Crypto
The crypto property is a GlobalPlatform scripting language Crypto object.
A ReadOnly, DontDelete property. Crypto object used by the secure channel.

7.1.8.3.4 diversificationData

GPScp01.prototype.diversificationData ByteString
The diversificationData property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Diversification data returned by the InitializeUpdate APDU.

7.1.8.3.5 hostChallenge

GPScp01.prototype.hostChallenge ByteString
The hostChallenge property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Host challenge used for the InitializeUpdate APDU.

7.1.8.3.6 keyIndex

GPScp01.prototype.keyIndex Number
The keyIndex property is an ECMAScript Number object.
ReadOnly, DontDelete property. Key index returned by the InitializeUpdate APDU or the value of the keyIndex
parameter in the constructor.

7.1.8.3.7 keyVersion

GPScp01.prototype.keyVersion Number
The keyVersion property is an ECMAScript Number object.
ReadOnly, DontDelete property. Key version returned by the InitializeUpdate APDU or the value of the keyVersion
parameter in the constructor.

7.1.8.3.8 mac

GPScp01.prototype.mac ByteString
The mac property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Current value of the MAC in a session

7.1.8.3.9 option

GPScp01.prototype.option Number
The option property is an ECMAScript Number object.
ReadOnly, DontDelete property. Implementation option for the secure channel.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPScp01.prototype.securityLevel Number
The securityLevel property is an ECMAScript Number object.
ReadOnly, DontDelete property. Current security level of the secure channel as defined in the Card Specification.

7.1.8.3.11 state

GPScp01.prototype.state Number
The state property is an ECMAScript Number object.
ReadOnly, DontDelete property. Current state of the secure channel, as specified using one of the following global
constants:
· SC_CLOSE
· SC_INITIALIZE (InitializeUpdate APDU sucessfully executed)
· SC_OPEN

7.1.8.4 Methods

7.1.8.4.1 Constructor

GPSCp01.prototype.constructor()
new GPSCp01()
new GPSCp01(arguments)
There is no constructor function for this object.

Example
None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED.

7.1.8.4.2 decryptEncryptKek()

GPScp01.prototype.decryptEncryptKek()
ByteString decryptEncryptKek(Key decryptKey, Number decryptMech, ByteString data)
ByteString decryptEncryptKek(Key decryptKey, Number decryptMech, ByteString data,
ByteString decryptIV)
Performs a decryption operation using the key specified by the decryptKey parameter, the algorithm specified by the
decryptMech parameter, followed immediately by an encrypt operation using the KEK key and the parameters
specified by the secure channel. The mechanism, and keys for the encrypt operation are known by the secure
channel.
For GlobalPlatform 2.0.1 cards, the only valid algorithm to use is DES in ECB mode (Crypto.DES_ECB).
If the algorithm specified by the decryptMech property requires an initial value parameter, such as Crypto.DES_CBC
or Crypto.DES_CBC_PAD, the initial parameter is used as specified in decryptInitial, otherwise it is ignored.
If the secure channel is not open, then a GPError exception with value GPError.SECURE_CHANNEL_WRONG_STATE is
generated.

Example

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Parameter Type Description

decryptKey Key Key object to use in decrypt operation.

decryptMech Number Crypto.DES_ECB

Crypto.DES_CBC
Crypto.RSA
data ByteString Data to encrypt.

decryptIV ByteString Initial vector to use for the decrypt operation if provided and
depending if required by the algorithm specified by the
decryptMech parameter.

returns ByteString A new ByteString containing the result of the decrypt and
encrypt operations on data.

exception GPError GPError.INVALID_ARGUMENTS

GPError.CRYPTO_FAILED
GPError.INVALID_TYPE
GPError.SECURE_CHANNEL_WRONG_STATE

7.1.8.4.3 encryptKek()

GPScp01.prototype.encryptKek()
ByteString encryptKek(ByteString data)
Performs an encryption operation using the KEK key, using the parameters specified by the secure channel object. The
mechanism, padding, and keys are known by the secure channel.
Note that for GlobalPlatform 2.1 cards, the algorithm information required for this encryption operation can be retrieved.
However, for GlobalPlatform 2.0.1 cards, the only valid algorithm to use is DES in ECB mode.
If the secure channel is not open, then a GPError exception with value GPError.SECURE_CHANNEL_WRONG_STATE is
generated.

Example
mySecureChannel.encryptKek(dataToEncrypt);

Parameter Type Description

data ByteString Value to encrypt.

returns ByteString A ByteString containing the encrypted KEK.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.CRYPTO_FAILED
GPError.INVALID_TYPE
GPError.SECURE_CHANNEL_WRONG_STATE

7.1.8.4.4 externalAuthenticate()

GPScp01.prototype.externalAuthenticate()
externalAuthenticate(Number level)
Send a GP ExternalAuthenticate APDU and update the properties affected. This method should internally generate a
Host cryptogram and calculate the MAC before sending the APDU.
If the host cryptogram or MAC generation fails during execution of this command, then a GPError object with a value of
GPError.CRYPTO_FAILED is generated.

Example
myGPScp01.externalAuthenticate(1);

Parameter Type Description

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.CRYPTO_FAILED
GPError.INVALID_TYPE

Any exception thrown by the sendApdu() method called implicitly is

forwarded.

7.1.8.4.5 getDekKey()

GPScp01.prototype.getDekKey()
getDekKey(Key dekKey)
Get the Data Encryption key (DEK).

Example
myGPScp01.getDekKey(myDekKey);

Parameter Type Description

dekKey Key Target Key object to place DEK key retrieved.

returns None

exception None

7.1.8.4.6 initializeUpdate()

GPScp01.prototype.initializeUpdate()
ByteString initializeUpdate(Number keyVersion, Number keyIndex)
Send a GP InitializeUpdate APDU and update the properties affected.

Example
myGPScp01.initializeUpdate (myKeyVersion, myKeyIndex);

Parameter Type Description

keyVersion Number Key version to use in the APDU (parameter P1)

keyIndex Number Key index to use in the APDU (parameter P2)

returns ByteString Response APDU

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

Any exception thrown by the sendApdu() method called impliticly is

forwarded.

7.1.8.4.7 setDekKey()

GPScp01.prototype.setDekKey()
setDekKey(Key dekKey)
Assign the Data Encryption key (DEK)

Example

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Parameter Type Description

dekKey Key Data Encryption key

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.8.4.8 setEncKey()

GPScp01.prototype.setEncKey()
setEncKey(Key encKey)
Assign the Secure Channel Encryption key

Example
myGPScp01.setEncKey(myEncryptionKey);

Parameter Type Description

encKey Key Encryption Key

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.8.4.9 setMacKey()

GPScp01.prototype.setMacKey()
setMacKey(Key macKey)
Assign the Secure Channel MAC verification key.

Example
myGPScp01.setMacKey(myMACKey);

Parameter Type Description

macKey Key MAC key

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.8.4.10 unwrapWrapKek()

GPScp01.prototype.unwrapWrapKek()
unwrapWrapKek( Key keyToUW, Key keyResult)

Performs an unwrapWrap crypto operation using the session key as the wrap key. The unwrap key to use in defined in
the Key object keyToWU, and is accessible using the getWrapKey() method on this object. The wrap key to use is the
secure session KEK.
The Key Management System and/or scripting host environment will know the algorithm necessariy in order to unwrap
the key. For GlobalPlatform 2.0.1 cards, the only valid algorithm to use is DES in ECB mode.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
myGPScp01.unwrapWrapKek(myKey, myKeyResult);

Parameter Type Description

keyToUW Key Key to perform wrap and unwrap operation on.

keyResult Key The final result of the unwrapWrap operation on the keyToWU.

returns None

exception GPError GPError.ARGUMENTS_MISSING

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.9 GPScp02
A GPScp02 object is a native object. The GPScp02 object is an implemetation of the Secure
Channel Protocol 02 described in the GlobalPlatform Card specification v2.1.
A GPScp02 object is used to perform transformation (like MACing, Encryption) on an APDU
based on a security level as specified in the GlobalPlatform Card Specification. The
transformation of the APDU must be done only when the APDU is sent by an GPApplication
or GPSecurityDomain object. Sending an APDU using the card property of one of those
objects, will never perform any transformation on the APDU (execpt the calculation of the Lc
field).
The KEK key used is known by the secure channel.
7.1.9.1 Summary
GPScp02.prototype.cardChallenge
GPScp02.prototype.cardCryptogram
GPScp02.prototype.crypto
GPScp02.prototype.diversificationData
GPScp02.prototype.hostChallenge
GPScp02.prototype.keyVersion
GPScp02.prototype.option
GPScp02.prototype.rmac
GPScp02.prototype.securityLevel
GPScp02.prototype.sequenceCounter
GPScp02.prototype.smac
GPScp02.prototype.state
GPScp02.prototype.beginRMac()
GPScp02.prototype.decryptEncryptDek()
GPScp02.prototype.encryptDek()
GPScp02.prototype.endRMac()
GPScp02.prototype.externalAuthenticate()
GPScp02.prototype.getDekKey()
GPScp02.prototype.initializeUpdate()
GPScp02.prototype.setBaseKey()
GPScp02.prototype.setDekKey()
GPScp02.prototype.setEncKey(()
GPScp02.prototype.setMacKey()
GPScp02.prototype.unwrapWrapDek()
7.1.9.2 Constants
There are no constants for the GPScp02 object.
7.1.9.3 Properties

7.1.9.3.1 cardChallenge

GPScp02.prototype.cardChallenge ByteString
The cardChallenge property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Card challenge value for the secure channel.

7.1.9.3.2 cardCryptogram

GPScp02.prototype.cardCryptogram ByteString

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.9.3.3 crypto

GPScp02.prototype.crypto Crypto
The crypto property is a GlobalPlatform scripting language Crypto object.
A ReadOnly, DontDelete property. Crypto object used by the secure channel.

7.1.9.3.4 diversificationData

GPScp02.prototype.diversificationData ByteString
The diversificationData property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Diversification data returned by the InitializeUpdate APDU.

7.1.9.3.5 hostChallenge

GPScp02.prototype.hostChallenge ByteString
The hostChallenge property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Host challenge used for the InitializeUpdate APDU.

7.1.9.3.6 keyVersion

GPScp02.prototype.keyVersion Number
The keyVersion property is an ECMAScript Number object.
ReadOnly, DontDelete property. Key version returned by the InitializeUpdate APDU or the value of the keyVersion
parameter in the constructor.

7.1.9.3.7 option

GPScp02.prototype.option Number
The option property is an ECMAScript Number object.
ReadOnly, DontDelete property. Implementation option for the secure channel.

7.1.9.3.8 rmac

GPScp02.prototype.rmac ByteString
The rmac property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Current R-MAC value.

7.1.9.3.9 securityLevel

GPScp02.prototype.securityLevel Number
The securityLevel property is an ECMAScript Number object.
ReadOnly, DontDelete property. Current security level of the secure channel as defined in the Card Specification.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPScp02.prototype.sequenceCounter Number
The sequenceCounter property is an ECMAScript Number object.
ReadOnly, DontDelete property. Sequence Counter returned by the InitializeUpdate APDU

7.1.9.3.11 smac

GPScp02.prototype.smac ByteString
The smac property is a GlobalPlatform scripting language ByteString object.
ReadOnly, DontDelete property. Current S-MAC value.

7.1.9.3.12 state

GPScp02.prototype.state Number
The state property is an ECMAScript Number object.
ReadOnly, DontDelete property. Current state of the secure channel, as specified using one of the following global
constants:
· SC_CLOSE
· SC_INITIALIZE (InitializeUpdate APDU successfully executed)
· SC_OPEN
· SC_RMAC

7.1.9.4 Methods

7.1.9.4.1 Constructor

GPScp02.prototype.constructor()
new GPScp02()
new GPScp02(arguments)
There is no constructor function for this object.

Example
None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED.

7.1.9.4.2 beginRMac()

GPScp02.prototype.beginRMac()
beginRMac(Number level)
beginRMac(Number level, ByteString data)
Send a GP BeginRMac APDU.

Example
myGPScp02.beginRMac(levelRequested);

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Parameter Type Description

level Number Security level requested (parameter P1).

data ByteString Optional data as defined in the Card Spec 2.1.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

Any exception thrown by the sendApdu() method called implicitly is

forwarded.

7.1.9.4.3 decryptEncryptDek()

GPScp02.prototype.decryptEncryptDek()
ByteString decryptEncryptDek(Key decryptKey, Number decryptMech, ByteString data)
ByteString decryptEncryptDek(Key decryptKey, Number decryptMech, ByteString data,
ByteString decryptIV)
Performs a decryption operation using the key specified by the decryptKey parameter, the algorithm specified by the
decryptMech parameter, followed immediately by an encrypt operation using the KEK key and the parameters
specified by the secure channel. The mechanism, and keys for the encrypt operation are known by the secure
channel.
Note that for GlobalPlatform 2.1 cards, the algorithm information required for the encryption operation can be retrieved.
If the algorithm specified by the decryptMech property requires an initial value parameter, such as Crypto.DES_CBC
or Crypto.DES_CBC_PAD, the initial parameter is used as specified in decryptInitial, otherwise it is ignored.

Example
mySecureChannel.decryptEncryptDek(myDecryptKey, this.crypto.DES_ECB,
myData);

Parameter Type Description

decryptKey Key Key object to use in decrypt operation.

decryptMech Number Crypto.DES_ECB

Crypto.DES_CBC
Crypto.RSA
data ByteString Data to encrypt.

decryptIV ByteString Initial vector to use for the decrypt operation if provided and
depending if required by the algorithm specified by the
decryptMech parameter.

returns ByteString A new ByteString containing the result of the decrypt and
encrypt operations on data.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.CRYPTO_FAILED
GPError.INVALID_TYPE

7.1.9.4.4 encryptDek()

GPScp02.prototype.encryptDek()
ByteString encryptDek(ByteString data)
Performs an encryption operation using the KEK key, using the parameters specified by the secure channel object. The
mechanism, padding, and keys are known by the secure channel.
Note that for GlobalPlatform 2.1 cards, the algorithm information required for this encryption operation can be retrieved.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
myGPScp02.encryptDek(dataToEncrypt);

Parameter Type Description

data ByteString Value to encyrpt.

returns ByteString A ByteString containing the encrypted KEK.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.CRYPTO_FAILED
GPError.INVALID_TYPE

7.1.9.4.5 endRMac()

GPScp02.prototype.endRMac()
ByteString endRMac()
Send a GP EndRMac. This method should implictly calculate the C-MAC if needed.

Example
myGPScp02.endRMac();

Parameter Type Description

None

returns ByteString Final R-MAC.

exception GPError GPError.CRYPTO_FAILED

Any exception thrown by the sendApdu() method called implicitly is

forwarded.

7.1.9.4.6 externalAuthenticate()

GPScp02.prototype.externalAuthenticate()
externalAuthenticate(Number level)
Send a GP ExternalAuthenticate APDU and update the properties affected. This method should internaly generate a
Host cryptogram and calculate the MAC before sending the APDU.
If the host cryptogram or MAC generation fails during execution of this command, then a GPError object with a value of
GPError.CRYPTO_FAILED is generated.

Example
myGPScp02.externalAuthenticate(1);

Parameter Type Description

level Number Security level requested (parameter P1)

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE
GPError.CRYPTO_FAILED

Any exception thrown by the sendApdu() method called implicitly is

forwarded.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

GPScp02.prototype.getDekKey()
getDekKey(Key dekKey)
Get the Data Encryption key (DEK).

Example
myGPScp02.getDekKey(myDekKey);

Parameter Type Description

dekKey Key Target Key object to place DEK key retrieved.

returns None

exception None

7.1.9.4.8 initializeUpdate()

GPScp02.prototype.initializeUpdate()
ByteString initializeUpdate(Number keyVersion, Number keyIndex)
Send a GP InitializeUpdate APDU and updates the affected properties

Example
myGPScp02.initializeUpdate (myKeyVersion, myKeyIndex);

Parameter Type Description

keyVersion Number Key version to use in the APDU (parameter P1)

keyIndex Number Key index to use in the APDU (parameter P2)

returns ByteString Response APDU

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

Any exception thrown by the sendApdu() method called implicitly is

forwarded.

7.1.9.4.9 setBaseKey()

GPScp02.prototype.setBaseKey()
setBaseKey(Key baseKey)
Assign the Secure Channel Base key

Example
myGPScp02.setBaseKey(myEncryptionKey);

Parameter Type Description

baseKey Key Base Key
If the base key provided is not valid with the current option
implementation, then a GPError will be generated with a value of

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE
GPError.INVALID_KEY

7.1.9.4.10 setDekKey()

GPScp02.prototype.setDekKey()
setDekKey(Key dekKey)
Assign the Data Encryption key (DEK)

Example
myGPScp02.setDekKey(myDEKKey);

Parameter Type Description

dekKey Key Data Encryption key
If the Data Encryption key provided is not valid with the current option
implementation, then a GPError will be generated with a value of
GPError.INVALID_KEY.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE
GPError.INVALID_KEY

7.1.9.4.11 setEncKey()

GPScp02.prototype.setEncKey()
setEncKey(Key encKey)
Assign the Secure Channel Encryption key

Example
myGPScp02.setEncKey(myEncryptionKey);

Parameter Type Description

encKey Key Encryption Key
If the encryption key provided is not valid with the current option
implementation, then a GPError will be generated with a value of
GPError.INVALID_KEY.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE
GPError.INVALID_KEY

7.1.9.4.12 setMacKey()

GPScp02.prototype.setMacKey()
setMacKey(Key macKey)
Assign the Secure Channel MAC verification key.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Example
myGPScp02.setMacKey(myMACKey);

Parameter Type Description

macKey Key MAC key
If the MAC key provided is not valid with the current option
implementation, then a GPError will be generated with a value of
GPError.INVALID_KEY.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE
GPError.INVALID_KEY

7.1.9.4.13 unwrapWrapDek()

GPScp02.prototype.unwrapWrapDek()
unwrapWrapDek(Key keyToUW, Key keyResult)
Performs an unwrapWrap crypto operation using the session key as the wrap key. The unwrap key to use in defined in
the Key object keyToWU, and is accessible using the getWrapKey() method on this object. The wrap key to use is the
secure session KEK.
The Key Management System and/or scripting host environment will know the algorithm necessariy in order to unwrap
the key. Note that for GlobalPlatform 2.1 cards, the algorithm information required for this encryption operation can be
retrieved.

Example
myGPScp02.unwrapWrapDek(myKey, myKeyResult);

Parameter Type Description

keyToUW Key Key to perform wrap and unwrap operation on.

keyResult Key The final result of the unwrapWrap operation on the keyToWU.

returns None

exception GPError GPError.ARGUMENTS_MISSING

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.10 Card
Card is a native object used to represent the target smart card for the current personalization
script.
The response, SW, SW1 and SW2 properties will return information about the response APDU
regardless of from which method the APDU was sent.
7.1.10.1 Summary
Card.OTHER
Card.PICCA
Card.PICCB
Card.RESET_COLD
Card.RESET_WARM
Card.T0
Card.T1
Card.T14
Card.prototype.profile
Card.prototype.response
Card.prototype.SW
Card.prototype.SW1
Card.prototype.SW2
Card.prototype.baudRate()
Card.prototype.clock()
Card.prototype.powerDown()
Card.prototype.pps()
Card.prototype.reset()
Card.prototype.sendApdu()
Card.prototype.vcc()
7.1.10.2 Constants
Each of these constants must be assigned an unique value within the Card object.
Constant Usage

Card.OTHER reset() method

Card.PICCA pps() method
Card.PICCB pps() method
Card.RESET_COLD reset() method
Card.RESET_WARM reset() method
Card.T0 pps() method
Card.T1 pps() method
Card.T14 pps() method

7.1.10.3 Properties

7.1.10.3.1 profile

Card.prototype.profile Object

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Elements in the XML which can have multiple occurences are created as arrays, which can be indexed by the name of
the first attribute of the element.
For elements which are specified as String data types in the Profiles specification, a ByteString object with the
encoding specified in the Encoding column in the Profiles specification will be created. For those attributes which are
enumerated lists of string, then they will be created as ByteString objects with ASCII encoding.

7.1.10.3.2 response

Card.prototype.response ByteString
The response property is a GlobalPlatform scripting language ByteString object.
This contains in a ByteString object the response value of the most recent command APDU sent to the smart card.
The command APDU could have been sent using the methods from an object other than the Card object.
Specifically, this is the response APDU data less the status word.
If no card was previously reset, or no status word was received since the card was reset, its value is a null value.
This is a ReadOnly property.

7.1.10.3.3 SW

Card.prototype.SW Number
The SW property is an ECMAScript Number object.
Contains the status word of the command APDU most recently sent to the smart card. The command APDU could have
been sent using the methods from an object other than the Card object.
Specifically, this is the two status word bytes of the most recently executed command APDU as a Number.
If no card was previously reset, or no status word was received since the card was reset, its value is a null value.
This is a ReadOnly property.

7.1.10.3.4 SW1

Card.prototype.SW1 Number
The SW1 property is an ECMAScript Number object.
Contains the first byte of the status word of the command APDU most recently sent to the smart card. The command
APDU could have been sent using the methods from an object other than the Card object.
st
Specifically, this is the 1 status word byte of the most recently executed command APDU as a Number.
If no card was previously reset, or no status word was received since the card was reset, its value is a null value.
This is a ReadOnly property.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Card.prototype.SW2 Number
The SW2 property is an ECMAScript Number object.
Contains the second status word byte of the command APDU most recently sent to the smart card. The command
APDU could have been sent using the methods from an object other than the Card object.
nd
Specifically, this is the 2 status word byte of the most recently executed command APDU as a Number.
If no card was previously reset, or no status word was received since the card was reset, its value is a null value.
This is a ReadOnly property.

7.1.10.4 Methods

7.1.10.4.1 Constructor

Card.prototype.constructor()
new Card()
new Card(arguments)
There is no constructor function for this object.

Example
None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED

7.1.10.4.2 baudRate()

card.prototype.baudRate()
Boolean baudRate (Number value)
Set the baud rate in bps for the card object.

Example
this.card.baudRate(9600);

Parameter Type Description

value Number value will contain the desired baud rate.
If the baud rate specified is unsupported or an invalid value, then a
GPError is generated with a value of GPError.INVALID_DATA.

returns Boolean Whether baudRate() method was executed correctly or not.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.10.4.3 clock()

card.prototype.clock()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Boolean clock(Number value)

Set the clock speed in Hz for the card object.

Example
this.card.clock(3571000); // set the clock speed to 3.571x MHz

Parameter Type Description

value Number value will contain the desired clock value in Hz.
If the frequency specified is unsupported or an invalid value, then a
GPError is generated with a value of GPError.INVALID_DATA.

returns Boolean Whether clock() method was executed correctly or not.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.10.4.4 powerDown()

card.prototype.powerDown()
Boolean powerDown()
Power down and logically eject the card, which may or may not imply physical ejection of the card. Unless the card is
physically removed and reinserted into the device, any subsequent method on this card object will fail upon execution.

Example
myCard.powerDown(); // logically eject the card
Parameter Type Description
None

returns Boolean Whether the operation succeeded or not.

exception None

7.1.10.4.5 pps()

card.prototype.pps()
Boolean pps(Number protocol)
Boolean pps(Number protocol, Number f, Number d)
Set the physical protocol for the card. The GP scripting language provides support for contact smart cards through
ISO7816. Other proprietary protocols can be supported, but depend on support by the environment implementing the
GP scripting language.
If the method executes successfully, then a true Boolean value is returned. Otherwise, if the parameters are valid,
but the environment cannot execute the method for the smart card represented by card, then a false value is
returned.
If invalid values (i.e., values not specified in this specification or values not supported by the environment) for any of the
parameters protocol, f, or d are provided, then a GPError object is generated with GPError.INVALID_DATA value.

Example
// On a card with a contact interface
this.card.pps(Card.T1, myFrequency, myDivisor);
// returns false value if the card doesn’t support T=1 protocol

Parameter Type Description

protocol Number The protocol parameter will contain the desired protocol value

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

If any of the above values are specified, then the f and d

parameters are also required.
For a proprietary protocol supported by the card, a unique protocol
value supported by the environment can be used, as long as it does
not conflict with the values defined for the Card constants. The
following is a default constant for representing non-standard
protocols :
Card.OTHER

Refer to ISO specifications for ISO7816.

f Number Clock rate conversion factor

d Number Baud rate adjustment factor

Returns Boolean Whether or not the protocol() method executed

successfully for the target card.
Exception GPError GPError.ARGUMENTS_MISSING
GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.10.4.6 reset()

card.prototype.reset()
Atr reset(Number resetMode)
Send a reset to the card.
If the reset attempt fails, a GPError object with a value of GPError.CARD_COMM_ERROR will be generated.

Example
sampleAtr = this.card.reset(Card.RESET_WARM); // perform a warm reset

Parameter Type Description

resetMode Number Specifies the type of reset that is required when a reset() method
is invoked. The values of resetMode are as follows (either the
constants or the integer values can be used):
Card.RESET_WARM A warm reset is required.
Card.RESET_COLD A cold reset is required.
returns Atr reset(resetMode) will return an Atr object

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.INVALID_DATA

7.1.10.4.7 sendApdu()

card.prototype.sendApdu()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

ByteString SendApdu (Number cla, Number ins, Number p1, Number p2)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number le)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, Number le,
Number[] sw)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number le)
ByteString SendApdu (Number cla, Number ins, Number p1, Number p2, ByteString data,
Number le, Number[] sw)
Send an APDU to the target smart card. The APDU is sent directly to the smart card regardless of whether a secure
channel exists or not.

Example
this.card.sendApdu(sampleCLA, sampleINS, sampleP1, sampleP2);
responseAPDU = this.card.response;
// A sendApdu() method sends a command APDU message to the smart card
returnSW = this.card.SW;
// Retrieve the status word returned from the command APDU

Parameter Type Description

cla Number cla refers to the class byte (CLA) of the command message.

ins Number ins refers to the instruction byte (INS) of the command message.

p1 Number P1 parameter.

p2 Number P2 parameter.

data ByteString Optional data field to use with an APDU. This will be a ByteString
object. If a Case 2 command is being constructed, this must be
provided as null.

le Number Optional maximum length of data expected in response to a Case 2

or Case 4 command.
If le is too large, then GPError.INVALID_LENGTH is generated.

sw Number Optional array of Number objects which correspond to valid status

words.

returns ByteString Response APDU (excluding status word)

exception GPError GPError.ARGUMENTS_MISSING

GPError.CARD_COMM_ERROR
GPError.CARD_INVALID_SW
GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.10.4.8 vcc()

card.prototype.vcc()
Boolean vcc(Number value)
Set the Vcc in mV for the card object. An exception will be thrown if the parameter value is invalid.

Example
this.card.vcc(5000);
// set the vcc to 5.0 V

Parameter Type Description

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

returns Boolean Whether or not the operation succeeded.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_TYPE

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.11 Key
Key is a native object used to represent the keys defined in the Application Profile. Key objects
are created using information from the Key Profile and are named according to the name
specified in the Key XML element in the Application Profile.
Only the values not defined when the key is created can be modified by the set methods. Values
which are provided in the key or Key Profile cannot be modified using the set method. Note that
the set methods do not necessarily alter the contents of the Key Profile XML document; they
only alter contents of the Key object in the script execution context. However, a GP Scripting
Language implementation may decide or even require updates to the Key Profile based on
modifications to a key within a script.
7.1.11.1 Summary
Key.CRT_DP1
Key.CRT_DQ1
Key.CRT_P
Key.CRT_PQ
Key.CRT_Q
Key.DES
Key.EIGHTZEROS
Key.EXPONENT
Key.EXPORTABLE
Key.DECRYPT
Key.DECRYPT_ENCRYPT
Key.DERIVE
Key.ENCRYPT
Key.IMPORTABLE
Key.MODULUS
Key.PRIVATE
Key.PUBLIC
Key.SECRET
Key.SENSITIVE
Key.SIGN
Key.UNWRAP
Key.UNWRAP_WRAP
Key.VERIFY
Key.WRAP
Key.prototype.getAttribute()
Key.prototype.getComponent()
Key.prototype.getEnd()
Key.prototype.getKcv()
Key.prototype.getOwner()
Key.prototype.getProfileID()
Key.prototype.getSize()
Key.prototype.getStart()
Key.prototype.getType()
Key.prototype.getUsage()
Key.prototype.getVersion
Key.prototype.getWrapKey()
Key.prototype.setAttribute()
Key.prototype.setComponent()
Key.prototype.setEnd()
Key.prototype.setOwner()
Key.prototype.setSize()
Key.prototype.setStart()
Key.prototype.setType()
Key.prototype.setUsage()
Key.prototype.setVersion()

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

7.1.11.2 Constants
Each of these constants must be assigned an unique value within the Key object.
For the constants used for the setUsage() and getUsage() methods, these must be unique
values which are combinable with the logical OR function in order to produce another unique
value which enables the developer to confirm an individual usage is present or not present in the
Usage attribute. This is necessary in order to support Key objects with more then one usage
specified in the Usage attribute.

Constant Usage
Key.CRT_DP1 getComponent() and setComponent()
Key.CRT_DQ1 getComponent() and setComponent()
Key.CRT_P getComponent() and setComponent()
Key.CRT_PQ getComponent() and setComponent()
Key.CRT_Q getComponent() and setComponent()
Key.DECRYPT setUsage() and getUsage() methods
Key.DECRYPT_ENCRYPT setUsage() and getUsage() methods
Key.DERIVE setUsage() and getUsage() methods
Key.DES getComponent() and setComponent()
Key.EIGHTZEROS getKcv() method
Key.ENCRYPT setUsage() and getUsage() methods
Key.EXPONENT getComponent() and setComponent()
Key.EXPORTABLE getAttribute() and setAttribute()
Key.IMPORTABLE getAttribute() and setAttribute()
Key.MODULUS getComponent() and setComponent()
Key.PRIVATE type methods
Key.PUBLIC type methods
Key.SECRET type methods
Key.SENSITIVE getAttribute() and setAttribute()
Key.SIGN setUsage() and getUsage() methods
Key.UNWRAP setUsage() and getUsage() methods
Key.UNWRAP_WRAP setUsage() and getUsage() methods
Key.VERIFY setUsage() and getUsage() methods
Key.WRAP setUsage() and getUsage() methods

7.1.11.3 Properties
There are no properties for the Key object.
7.1.11.4 Methods

7.1.11.4.1 Constructor

Key.prototype.constructor()
new Key()
new Key(arguments)
There is no constructor function for this object.

Example

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED

7.1.11.4.2 getAttribute()

Key.prototype.getAttribute()
Number getAttribute()
Retrieve the attribute value for the Key. In the XML, this is the Attribute subelement of the KeyProfile element.

Example
// If the sampleKey has the attributes set to indicate that the key is both exportable
// and importable, then the resultant keyAttribute below will contain a logical OR of
// the Key.EXPORTABLE and Key.IMPORTABLE constants.
keyAttribute = sampleKey.getAttribute();

Parameter Type Description

None

returns Number See PKCS11 specification. Could be one of or a logical OR

combination of:
Key.EXPORTABLE
Key.IMPORTABLE
Key.SENSITIVE
exception None

7.1.11.4.3 getComponent()

Key.prototype.getComponent()
ByteString getComponent(Number type)
Retrieve a component, as specified by the type parameter, for the Key. This value is populated either upon creation of
the Key object in the script environment or is determined at time of method invocation.

Example
// Assume my sampleKey is a public key
myPublicExponent = sampleKey.getComponent(Key.EXPONENT);

Parameter Type Description

type Number Constant corresponding to the type of component to retrieve. Valid
values are:
Key.CRT_P RSA Key Components
Key.CRT_Q RSA Key Components
Key.CRT_DP1 RSA Key Components
Key.CRT_DQ1 RSA Key Components
Key.CRT_PQ RSA Key Components
Key.DES DES Key
Key.EXPONENT Exponent Value
Key.MODULUS Modulus Value
If any invalid component type is specified, then a GPError is
generated with a value of GPError.INVALID_DATA.

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.11.4.4 getEnd()

Key.prototype.getEnd()
ByteString getEnd()
Retrieve the End Date value for the Key. In the XML, this can be found in the KeyInfo subelement of the KeyProfile
element.

Example
myDate = sampleKey.getEnd();

Parameter Type Description

None

returns ByteString A new ByteString containing the date in the format YYYYMMDD
in ASCII.

exception None

7.1.11.4.5 getKcv()

Key.prototype.getKcv()
ByteString getKcv(Number kcvAlgo)
Retrieve the key check value value for the Key. This value is populated either upon creation of the Key object in the
script environment or is determined at time of method invocation.

Example
myKcv = sampleKey.getKcv();

Parameter Type Description

kcvAlgo Number Parameter to specify the KCV algorithm for key check value
calculation.
Key.EIGHTZEROS
** The key check value is based on an encryption with eight
hexadecimal zeroes (0x0000000000000000).

returns ByteString Key check value in hexadecimal representation.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS

7.1.11.4.6 getOwner()

Key.prototype.getOwner()
ByteString getOwner()
Retrieve the Owner attribute value for the Key. In the XML, this can be found in the KeyInfo subelement of the
KeyProfile element.

Example

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Parameter Type Description

None

returns ByteString A new ByteString containing the Owner attribute value from the
Key Profile for the key.

exception None

7.1.11.4.7 getProfileID()

Key.prototype.getProfileID()
ByteString getProfileID()
Retrieve the ProfileID value for the Key. In the XML, this can be found in the UniqueID attribute of the
KeyProfile element or the ProfileID attribute of the Key element.

Example
myProfileID = sampleKey.getProfileID();

Parameter Type Description

None

returns ByteString A new ByteString containing the value of the UniqueID

attribute.

exception None

7.1.11.4.8 getSize()

Key.prototype.getSize()
Number getSize()
Retrieve the size value for the Key. In the XML, this can be found as the Size attribute in the KeyInfo subelement of
the KeyProfile element.

Example
// For the DES key sampleDESKey which has the Size attribute set to 64
// bits in the Key Profile
myDESSize = sampleDESKey.getSize();
// myDESSize will contain the number 64

// For the RSA key sampleRSAKey which has the Size attribute set to 1024
// bits in the Key Profile
myRSASize = sampleRSAKey.getSize();
// myRSASize will contain the number 1024

Parameter Type Description

None

returns Number For DES keys, a Number containing the size value in bits including
the parity bits.
For RSA keys, a Number containing the size of the modulus in bits.

exception None

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Key.prototype.getStart()
ByteString getStart()
Retrieve the Start Date value for the Key. In the XML, this can be found in the KeyInfo subelement of the
KeyProfile element.

Example
myDate = sampleKey.getStart();

Parameter Type Description

None

returns ByteString A new ByteString containing the date in the format YYYYMMDD
in ASCII.

exception None

7.1.11.4.10 getType()

Key.prototype.getType()
Number getType()
Retrieve the Type value for the Key. In the XML, this can be found as the Type attribute in the KeyInfo subelement
of the KeyProfile element.

Example
myType = sampleKey.getType();

Parameter Type Description

None

returns Number A new Number containing the Type attribute value.

Key.SECRET
Key.PRIVATE
Key.PUBLIC

exception None

7.1.11.4.11 getUsage()

Key.prototype.getUsage()
Number getUsage()
Retrieve the Usage values for the Key. In the XML, this can be found as the attributes in the Usage subelement of the
KeyProfile element.
If more then one usage value is specified, it should be extractable from the returned value by comparing against a logical
OR of the desired usages to check for.

Example
// Assume that the Usage subelement for the key sampleKey has usage
// set to Key.DECRYPT. This code will only execute decrypt if sampleKey
// has this usage feature set.
sampleKey = this.key[“keyA”];
dataToDecrypt = new ByteString(“00010203”, HEX);
initialVector = new ByteString(“00000000”, HEX);
myUsage = sampleKey.getUsage();

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

Parameter Type Description

None

returns Number A Number containing one of or, for the case of multiple usages, a
logical OR combination of the usage values:
Key.ENCRYPT
Key.DECRYPT
Key.DECRYPT_ENCRYPT
Key.DERIVE
Key.SIGN
Key.VERIFY
Key.WRAP
Key.UNWRAP
Key.UNWRAP_WRAP
exception None

7.1.11.4.12 getVersion()

Key.prototype.getVersion()
Number getVersion()
Retrieve the Version value for the Key. In the XML, this can be found in the Key element or in the KeyInfo
subelement of the KeyProfile element.

Example
myVersion = sampleKey.getVersion();

Parameter Type Description

None

returns Number A new Number containing the Version attribute value.

exception None

7.1.11.4.13 getWrapKey()

Key.prototype.getWrapKey()
getWrapKey(Key wrapKey)
Retrieve the key that is used to wrap (encrypt) the key.

Example
sampleKey.getWrapKey(theWrapKey);

Parameter Type Description

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.DEVICE_ERROR
GPError.INVALID_ARGUMENTS
GPError.INVALID_KEY
GPError.INVALID_USAGE
GPError.KEY_NOT_FOUND
GPError.UNDEFINED
GPError.UNSUPPORTED
GPError.USER_DEFINED

7.1.11.4.14 setAttribute()

Key.prototype.setAttribute()
setAttribute(Number value)
Attempt to set the Attribute attribute value for a key. If the attribute has already been populated based on information
from the Key Profile, then an exception is thrown.

Example
sampleKey.setAttribute(Key.SENSITIVE);

Parameter Type Description

value Number See PKCS11 specification. Could be one of or a logical OR
combination of:
Key.EXPORTABLE
Key.IMPORTABLE
Key.SENSITIVE

If the Attribute attribute has already been defined in the Key

Profile, then a GPError will be generated with a value of
GPError.ACCESS_DENIED.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.ACCESS_DENIED
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.11.4.15 setComponent()

Key.prototype.setComponent()
setComponent(Number type, ByteString value)
Set a component, as specified by the type parameter, for the Key. If the component’s value is populated upon creation
of the Key object in the script environment, this method shall throw an exception.

Example
// Assume sampleKey is a public key and
// myExponent contains an exponent value
sampleKey.setComponent( Key.EXPONENT, myExponent);

Parameter Type Description

type Number Constant corresponding to the type of component to set. Valid
values are:
Key.CRT_P RSA Key Components
Key.CRT_Q RSA Key Components

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

value ByteString A HEX encoded ByteString containing the value for the Key
component specified by type.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.ACCESS_DENIED
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.11.4.16 setEnd()

Key.prototype.setEnd()
setEnd(ByteString value)
Sets the End Date value for the Key. If the attribute value has already been populated based on information from the
Key Profile, then an exception is thrown.

Example
sampleKey.setEnd(myDate);

Parameter Type Description

value ByteString A ByteString containing the date in the format YYYYMMDD in
ASCII.
If the End attribute has already been defined in the Key Profile, then
a GPError will be generated with a value of
GPError.ACCESS_DENIED.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.ACCESS_DENIED
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.11.4.17 setOwner()

Key.prototype.setOwner()
setOwner(ByteString value)
Sets the Owner attribute value for the Key. If the attribute value has already been populated based on information
from the Key Profile, then an exception is thrown.

Example
sampleKey.setOwner(myOwner);

Parameter Type Description

value ByteString A ByteString containing the owner value.
If the Owner attribute has already been defined in the Key Profile,

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.ACCESS_DENIED
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.11.4.18 setSize()

Key.prototype.setSize()
setSize(Number value)
Sets the Size attribute value for the Key. If the attribute value has already been populated based on information from
the Key Profile, then an exception is thrown.

Example
// For the DES key sampleDESKey which doesn’t have the Size attribute
// specified in the Key Profile, the following will set the size to 64
// bits
sampleDESKey.setSize(64);

// For the RSA key sampleRSAKey which doesn’t have the Size attribute
// specified in the Key Profile, the following will set the size to 1024
// bits
sampleRSAKey.setSize(1024)

Parameter Type Description

value Number For DES keys, a Number containing the size value in bits including
the parity bits.
For RSA keys, a Number containing the size of the modulus in bits.
If the Size attribute has already been defined in the Key Profile, then
a GPError will be generated with a value of
GPError.ACCESS_DENIED.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.ACCESS_DENIED
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.11.4.19 setStart()

Key.prototype.setStart()
setStart(ByteString value)
Sets the Start Date value for the Key. If the attribute value has already been populated based on information from the
Key Profile, then an exception is thrown.

Example
sampleKey.setStart(myDate);

Parameter Type Description

value ByteString A ByteString containing the date in the format YYYYMMDD in
ASCII.
If the Start attribute has already been defined in the Key Profile,
then a GPError will be generated with a value of

Copyright  2003 GlobalPlatform Inc. All Rights Reserved.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.ACCESS_DENIED
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.11.4.20 setType()

Key.prototype.setType()
setType(Number value)
Sets the Type attribute value for the Key.

Example
sampleKey.setType(myType);

Parameter Type Description

value Number A Number containing the type value.
Key.SECRET
Key.PRIVATE
Key.PUBLIC

If the Type attribute has already been defined in the Key Profile,
then a GPError will be generated with a value of
GPError.ACCESS_DENIED.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.ACCESS_DENIED
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.11.4.21 setUsage()

Key.prototype.setUsage()
setUsage(Number value)
Set the Usage subelement attribute values for the Key. If any of the element’s attribute values has already been
populated with true values, based on information from the Key Profile, then an exception is thrown.
If more then one usage value is specified, it can be combined using a logical OR with the other desired usages to arrive
at the usage value to specify for this method.

Example
// Assuming that sampleKey’s usages have not been defined in the Key
// Profile, the following code will set the usage of the key to allow it
// to be used for both decryption and encryption operations.
sampleKey.setUsage(Key.ENCRYPT || Key.DECRYPT);

Parameter Type Description

value Number A Number containing one of or, for the case of multiple usages, a
logical OR combination of the usage values:
Key.ENCRYPT
Key.DECRYPT
Key.DECRYPT_ENCRYPT
Key.DERIVE
Key.SIGN
Key.VERIFY

If the Usage attribute has already been specified in the Key Profile,
then a GPError will be generated with a value of
GPError.ACCESS_DENIED.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.ACCESS_DENIED
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.11.4.22 setVersion()

Key.prototype.setVersion()
setVersion(Number value)
Sets the Version attribute value for the Key. If the Attribute value has already been populated based on information
from the Key Profile, then an exception is thrown.

Example
sampleKey.setVersion(myVersion);

Parameter Type Description

value Number A Number containing the version value.
If the Version attribute has already been specified in the Key
Profile, then a GPError will be generated with a value of
GPError.ACCESS_DENIED.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.ACCESS_DENIED
GPError.INVALID_DATA
GPError.INVALID_TYPE

7.1.12 Atr
The Atr object provides methods to return the value of the sequence of bytes sent by the card to
the interface device as the answer to a reset as defined in [IS7816-3].
Atr objects are created when the reset() method of the card object is executed. It is not
possible to use the Atr object as a constructor with the new operator as no constructor method is
provided.
7.1.12.1 Summary
Atr.prototype.formatByte
Atr.prototype.historicalBytes
Atr.prototype.interfaceBytes
Atr.prototype.tckByte
Atr.prototype.toByteString()
7.1.12.2 Constants
There are no constants for the Atr object.
7.1.12.3 Properties

7.1.12.3.1 formatByte

Atr.prototype.formatByte Number
The formatByte property is an ECMAScript Number object.
Contains the format byte value to the most recent answer to reset operation as specified in [IS7816-3].

7.1.12.3.2 historicalBytes

Atr.prototype.historicalBytes ByteString
The historicalBytes property is a GlobalPlatform scripting language ByteString object.
For smart cards with contact interfaces, contains the historical bytes value to the most recent answer to reset operation
as specified in [IS7816-3].

7.1.12.3.3 interfaceBytes

Atr.prototype.interfaceBytes ByteString
The interfaceBytes property is a GlobalPlatform scripting language ByteString object.
Contains the interface bytes value to the most recent answer to reset operation as specified in [IS7816-3].

7.1.12.3.4 tckByte

Atr.prototype.tckByte Number
The tckByte property is an ECMAScript Number object.
Contains the check byte tck value to the most recent answer to reset operation as specified in [IS7816-3].

7.1.12.4 Methods

7.1.12.4.1 Constructor

Atr.prototype.constructor()
new Atr()
new Atr(arguments)
There is no constructor function for this object.

Example
None

Parameter Type Description

None

returns None

exception GPError GPError.UNDEFINED

7.1.12.4.2 toByteString()

Atr.prototype.toByteString()
ByteString toByteString()
Returns in a ByteString representation the Atr object.

Example
SampleATR = this.card.reset();
myByteString = SampleATR.toByteString();

Parameter Type Description

None

returns ByteString ByteString object containing the answer to reset response.

exception None

7.1.13

ByteBuffer
A ByteBuffer object is a mutable object that can be used to manipulate a sequence of bytes.
The ByteBuffer object is instantiable. There is a constructor method which can be used to
create ByteBuffer objects.
Unlike the ByteString object, all ByteBuffer methods return a reference to the same object.
Table 7.1 summarizes the different types of encoding a ByteBuffer may have. A single
ByteBuffer object may contain segments of bytes which are encoding using different types of
encoding, because there are a variety of append methods which can be utilized to append bytes
which may not correspond to encoding used by the data already in the ByteBuffer object.

Encoding Description
Each byte is encoded as two hexadecimal digits with optional whitespace. When a string
is decoded whitespace is accepted, when a string is encoded it is up to the environment
whether whitespace is inserted or not. Alphabetic characters may be uppercase or
HEX lowercase.
The value { 0xab, 0x34, 0x56 } may be encoded as follows:
ab3456
AB 34 56
Ab34 56
ab 3456

Each byte is encoded as a single Extended ASCII character. No conversions are to occur
ASCII (eg no new-line to CRLF conversion).
The value { 0x47, 0x70, 0x21 }:
Gp!
Bytes are encoded using RFC 521 Base64 encoding. The encoded string may contain
BASE64
non-Base64 characters (eg newlines) which are to be ignored when decoding.
Support for the Compact Numeric magnetic stripe format in [IS7811-6]. Each byte is
encoded as two characters using the character table described in Table 7 of the ISO
specification (excluding the parity bits). When decoding a string with an odd number of
CN characters, an addition end-sentinel is added as the least significant nibble of the last byte.
The value { 0xB1, 0x2D, 0x3F } is encoded as:
;12=3?
The encoding “;2345” has the following value:
{ 0xB2, 0x34, 0x5F }

Table 7.1 - String Encodings for ByteBuffer Data Type

7.1.13.1 Summary
ByteBuffer.prototype.length
ByteBuffer.prototype.constructor()
ByteBuffer.prototype.append()
ByteBuffer.prototype.byteAt()
ByteBuffer.prototype.clear()

7.1.13.3.1 length

ByteBuffer.prototype.length Number
The length property is an ECMAScript Number object.
The current length of the contents of this ByteBuffer.

7.1.13.4 Methods

7.1.13.4.1 Constructor

ByteBuffer.prototype.constructor()
ByteBuffer new ByteBuffer()
ByteBuffer new ByteBuffer(String stringValue, Number encoding)
ByteBuffer new ByteBuffer(ByteString source)
Constructs a new ByteBuffer with empty contents, supplied hexValue or supplied stringValue.
When no parameters are supplied, return a new ByteBuffer object containing no data.
When stringValue and encodingValue is supplied, return a new ByteBuffer object with a value specified by the
supplied string and according to the encoding method specified by encoding to encode the value in stringValue.

Example
myByteBuffer = new ByteBuffer();

myByteBuffer = new ByteBuffer(someStringValue, HEX);

Parameter Type Description

stringValue String String to create ByteBuffer with.

source ByteString A ByteStirng to create ByteBuffer with.

encoding Number Refer to Table 7.1:

HEX
UTF8
ASCII
BASE64
CN
returns ByteBuffer The reference to the new ByteBuffer.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_ENCODING
GPError.INVALID_TYPE

7.1.13.4.2 append()

ByteBuffer.prototype.append()

ByteBuffer append(ByteBuffer source)

ByteBuffer append(ByteString source)
ByteBuffer append(String source)
Append the contents of the given ByteBuffer, ByteString or String to the end of this ByteBuffer.

Example
MyByteBuffer = new ByteBuffer(“Hello World!”, ASCII);

// This will append part of the ByteString sampleByteString

sampleByteString = new ByteString(“Goodbye! Goodbye! Goodbye!”, ASCII);
MyByteBuffer.append(sampleByteString.bytes(10,10));

// MyByteBuffer will now contain the ASCII string

// “Hello World!oodbye! Go”
myString = “ABBA”;

// This will append the String “ABBA”

MyByteBuffer.append(myString);

// MyByteBuffer will now contain the ASCII string

// “Hello World!oodbye! GoABBA”
myString = 0x20;

// This will append a space

MyByteBuffer.append(myString);

// MyByteBuffer will now contain the ASCII string

// “Hello World!oodbye! GoABBA ”

Parameter Type Description

source ByteBuffer The ByteString, ByteBuffer, or String from which bytes will
ByteString be appended.
String
returns ByteBuffer The same reference to this ByteBuffer. This allows convenient
concatenation without creating numerous instances.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.13.4.3 byteAt()

ByteBuffer.prototype.byteAt()
Number byteAt(Number offset)
Returns the byte at the given offset of this buffer’s contents.

Example
MyByteBuffer.byteAt(sampleNumber);

Parameter Type Description

offset Number The zero-based offset in this buffer.
If the offset specified is negative or exceeds the length of the buffer,
then a GPError will be generated with a value of
GPError.INVALID_INDEX.

returns Number The unsigned value of the byte at the given offset in the buffer

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_INDEX
GPError.INVALID_TYPE

ByteBuffer.prototype.clear()
ByteBuffer clear()
ByteBuffer clear(Number offset)
ByteBuffer clear(Number offset, Number count)

Deletes contents from the buffer. If no offset is given, all contents of the buffer will be deleted.

Example
MyByteBuffer.clear();

Parameter Type Description

offset Number The zero-based offset in this buffer. If no offset is given, bytes will be
deleted from the start of the buffer (offset 0).
If the offset specified is negative, then a GPError will be generated
with a value of GPError.INVALID_INDEX.

count Number The number of bytes to delete. If no count is given all bytes after the
given offset will be deleted.
If the number of bytes specified is negative or the sum of offset
and count exceeds the length of the buffer, then a GPError will be
generated with a value of GPError.INVALID_LENGTH.

returns ByteBuffer Returns a ByteBuffer.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_INDEX
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.13.4.5 copy()

ByteBuffer.prototype.copy()
ByteBuffer copy(Number at, ByteBuffer source)
ByteBuffer copy(Number at, ByteString source)
ByteBuffer copy(Number at, String source)
Replaces current contents of the ByteBuffer with contents of the given source object specified, whether a
ByteBuffer, ByteString or String. The copy() method does not insert the value, as this operation is handled by
the insert() method.

Example
// Assume MyByteBuffer contains the ASCII text “Hello There” and the
// sampleByteString contains the ASCII text “World!”. The following
// method call will result in MyByteBuffer containing “Hello World”.
MyByteBuffer.copy(6, sampleByteString);

Parameter Type Description

at Number The zero-based offset in the current buffer for the first byte to be
replaced.
If the offset specified is negative, then a GPError will be generated
with a value of GPError.INVALID_INDEX.

source ByteBuffer The ByteBuffer, ByteString or String from which bytes will be
ByteString appended.
String
If the sum of the offset specified in at and the length of this source
parameter exceeds the length of the current buffer, then a GPError

returns ByteBuffer The same reference to this ByteBuffer. This allows convenient
concatenation without creating numerous instances.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_INDEX
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.13.4.6 find()

ByteBuffer.prototype.find()
Number find(ByteString value)
Number find(ByteString value, Number offset)
Finds the zero based index into the ByteBuffer of the first occurrence of value specified.

Example
sampleByteString = new ByteBuffer (“01020103010401”, HEX);
findThis = new ByteString (“01”, HEX);
sampleByteString.find(findThis);
// will return 0
sampleByteString.find(findThis, 1);
// will return 2

Parameter Type Description

value ByteString ByteString to find

offset Number Zero based offset to start the search for value. Negative offset
should be treated as zero. If the offset exceeds the length of the
buffer, the method should report that the value was not found.

returns Number Absolute zero based offset into the ByteBuffer. –1 returned if
value is not found

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.13.4.7 insert()

ByteBuffer.prototype.insert()
ByteBuffer insert(Number at, ByteBuffer source)
ByteBuffer insert(Number at, ByteString source)
ByteBuffer insert(Number at, String source)

Inserts the contents of the object specified, whether a ByteBuffer, ByteString or String, at the given position in
this ByteBuffer. The length of the contents will increase with the number of bytes inserted. The source bytes will be
inserted before the given at position and the bytes already present from that position will be moved to after the inserted
bytes. If at equals the length of the buffer, the source bytes are appended to the end of the buffer.

Example
MyByteBuffer.insert(sampleNumber, sampleByteString);

Parameter Type Description

at Number The zero-based offset in the current buffer at which the bytes are
inserted.
If the offset specified is negative or at exceeds the length of the
current buffer, then a GPError will be generated with a value of

source ByteBuffer The ByteBuffer, ByteString or String from which bytes will be
ByteString appended.
String
returns ByteBuffer The same reference to this ByteBuffer. This allows convenient
concatenation without creating numerous instances.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_INDEX
GPError.INVALID_TYPE

7.1.13.4.8 toByteString()

ByteBuffer.prototype.toByteString()
ByteString toByteString()
ByteString toByteString(Number offset)
ByteString toByteString(Number offset, Number count)
Returns this buffer’s contents as a new immutable ByteString.

Example
MyByteBuffer.toByteString();

Parameter Type Description

offset Number The zero-based offset in this buffer. If no offset is given the entire
contents of this buffer will be returned.
If the offset specified is negative, then a GPError will be generated
with a value of GPError.INVALID_INDEX.

count Number The number of bytes to copy into the result.

If number of bytes provided is negative or the sum of offset and
count exceeds the length of the current buffer, then a GPError will
be generated with a value of GPError.INVALID_LENGTH.

returns ByteString The reference to the new ByteString.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_INDEX
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.13.4.9 toString()

ByteBuffer.prototype.toString()
String toString()
String toString(Number encoding)
Returns a ECMAScript String representation of the ByteBuffer object.

Example
MyByteBuffer.toString(HEX);

Parameter Type Description

encoding Number Refer to Table 7.1:
HEX
UTF8
ASCII
BASE64
CN

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS

7.1.14 ByteString
The ByteString object describes an ordered series of bytes which cannot be modified once
created. The ByteString object is instantiable. There is a constructor method which can be
used to create ByteString objects. Also, ByteString objects are created by several other
objects in the scripting objects.
ByteString objects are immutable, that is object instances cannot be changed.
Table 7.2 describes the different types of encoding a ByteString may have.

The byte sequence is interpreted as UTF-8. A character may be encoded as one, two or
three bytes depending on the Unicode character value.
For example, the following string “± € 6” translates to:
UTF8 Plus-Minus Sign (0xB1 or 0b10 110001)
Euro Sign (0x20AC or 0b10 000010 101100)
Digit Six (0x36 or 0b110110)
which is represented in UTF-8 as the following value:
{ 0xC2, 0xB1, 0xE2, 0x82, 0xAC, 0x36 }
Each byte is encoded as a single Extended ASCII character. No conversions are to occur
ASCII (eg no new-line to CRLF conversion).
The value { 0x47, 0x70, 0x21 }:
Gp!
Bytes are encoded using RFC 521 Base64 encoding. The encoded string may contain
BASE64
non-Base64 characters (eg newlines) which are to be ignored when decoding.
Support for the Compact Numeric magnetic stripe format in [IS7811-6]. Each byte is
encoded as two characters using the character table described in Table 7 of the ISO
specification (excluding the parity bits). When decoding a string with an odd number of
CN characters, an addition end-sentinel is added as the least significant nibble of the last byte.
The value { 0xB1, 0x2D, 0x3F } is encoded as:
;12=3?
The encoding “;2345” has the following value:
{ 0xB2, 0x34, 0x5F }

Table 7.2 - String Encodings for ByteString Data Type

7.1.14.1 Summary
ByteString.XOR
ByteString.prototype.length
ByteString.prototype.constructor()
ByteString.prototype.and()
ByteString.prototype.byteAt()

Constant Usage
ByteString.XOR crc() method

7.1.14.3 Properties

7.1.14.3.1 length

ByteString.prototype.length Number
The length property is an ECMAScript Number object.
The current length of the contents of this ByteString.

7.1.14.4 Methods

7.1.14.4.1 Constructor

ByteString.prototype.constructor()
ByteString new ByteString(String stringValue, Number encoding)

When stringValue is supplied, return a ByteString object containing the value specified by the supplied string
using the encoding method described by encodingValue.

Example
myByteString = new ByteString("AbcD", HEX);
//returns a bytefield containing the two bytes 0xab, 0xcd.

myByteString = new ByteString("ABC", ASCII);

//returns a ByteString containing the three bytes 0x41, 0x42, 0x43.

Parameter Type Description

stringValue String Contains the string to be expressed as a ByteString.

encoding Number Refer to Table 7.2:

HEX

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_DATA
GPError.INVALID_ENCODING
GPError.INVALID_TYPE

7.1.14.4.2 and()

ByteString.prototype.and()
ByteString and(ByteString value)
The bitwise AND of the two ByteString objects of the same length.
Returns a ByteString object containing the bitwise AND of the two objects.
If the two ByteString objects are of different lengths, then a GPError object is generated with a value of
GPError.INVALID_LENGTH.

Example
// Assume that sampleByteString contains “0x11”
// and otherByteString contains “0x00”
// newByteSting will contain 0x00
newByteString = sampleByteString.and(otherByteString);

Parameter Type Description

Value ByteString value is a ByteString object to perform the bitwise AND operation
with.

returns ByteString The bitwise AND of the two objects as a new ByteString object.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.14.4.3 byteAt()

ByteString.prototype.byteAt()
Number byteAt(Number offset)
Returns the byte at the given offset of this ByteString object’s contents.

Example
MyByteString.byteAt(sampleNumber);

Parameter Type Description

offset Number The zero-based offset in this ByteString object.
If the offset specified is negative or exceeds the length of the buffer,
then a GPError will be generated with a value of
GPError.INVALID_INDEX.

returns Number The unsigned value of the byte at the given offset in the buffer

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_INDEX
GPError.INVALID_TYPE

ByteString.prototype.bytes()
ByteString bytes(Number offsetByte)
ByteString bytes(Number offsetByte, Number countBytes)
Return a ByteString containing part of the ByteString from which the method is invoked.

Example
// assume that sampleByteString contains the value “0x0102”
newByteString = sampleByteString.bytes(0x01, 0x01); // will return x02

Parameter Type Description

offsetByte Number Mandatory parameter, which if not present, is zero by default.
Otherwise represents the zero-offset into the ByteString.
If the offsetByte value is negative, then a GPError object is
generated with a value of GPError.INVALID_INDEX.

countBytes Number Optional parameter, which if not present, is the remaining bytes from
the offsetByte. Otherwise represents the maximum number of
bytes to put into the returned ByteString.
If the countBytes value is negative, then a GPError object is
generated with a value of GPError.INVALID_LENGTH.

returns ByteString A new ByteString.

exception GPError.ARGUMENTS_MISSING
GPError.INVALID_ARGUMENTS
GPError.INVALID_INDEX
GPError.INVALID_LENGTH

7.1.14.4.5 concat()

ByteString.prototype.concat()
ByteString concat(ByteString value)
The concatenation of this object followed by another ByteString object.

Example
// Assume that sampleByteString is a ByteString object which
// contains the binary value “0x0101” and otherByteString
// contains the binary value “0x0202”
newByteString = sampleByteString.concat(otherByteString);
// will create a new ByteString object containing the value 0x01010202

Parameter Type Description

value ByteString value is a ByteString which will be appended to the ByteString
object from which the method is invoked.

returns ByteString A new ByteString representing the concatenation of the supplied

ByteString and the ByteString object from which the method is
invoked.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.14.4.6 crc()

ByteString.prototype.crc()

ByteString crc(Number type)

Perform a CRC calculation using the type specified.

Example
// Assume that sampleByteString is a ByteString object which
// contains the binary value “0x0101”
sampleByteStringCRC = sampleByteString.crc(ByteString.XOR);
// will create the CRC with XOR of sampleByteString

Parameter Type Description

type Number Constant value corresponding to type of crc operation desired.
Valid values are:
ByteString.XOR
**Use exclusive OR CRC calculation method
If the CRC method specified by the type value is not supported,
then a GPError object is generated with a value of
GPError.INVALID_MECH.

returns ByteString A new ByteString representing the results of the CRC operation.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_MECH
GPError.INVALID_TYPE

7.1.14.4.7 equals()

ByteString.prototype.equals()
Boolean equals(ByteString value)
Determines whether the objects have identical contents.
Returns true if the objects are the same length and each byte is identical, false otherwise.

Example
// Assume that the ByteStrings sampleByteString contains
// “0x0101” and otherByteString contains “0x0201”
sampleByteString.equals(otherByteString);
// will return false

Parameter Type Description

value ByteString ByteString to compare to.

returns Boolean Boolean result whether the objects have identical contents.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.14.4.8 find()

ByteString.prototype.find()
Number find(ByteString value)
Number find(ByteString value, Number offset)
Finds the zero based index into the ByteString of the first occurrence of value specified.

Example
sampleByteString = new ByteString (“01020103010401”, HEX);
findThis = new ByteString (“01”, HEX);
sampleByteString.find(findThis);

Parameter Type Description

value ByteString ByteString to find

offset Number Zero based offset to start the search for value. Negative offset
should be treated as zero.

returns Number Absolute zero based offset into the ByteString. –1 returned if
value is not found

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.14.4.9 getL()

ByteString.prototype.getL()
ByteString getL(Number encoding)
A length field in a new ByteString object for the value of the ByteString object from which the method is invoked.
Returns a ByteString object containing L field appropriate to the encoding method specified by encoding.

Example
// Assume that sampleByteString is a ByteString object
// containing a 128 byte length value
myEMVlength = sampleByteString.getL(TLV.EMV);
myDGIlength = sampleByteString.getL(TLV.DGI);
// myEMVlength will contain the value 0x8180
// myDGIlength will contain the value 0x80

Parameter Type Description

encoding Number Format of the return L ByteString. Valid values are
TLV.EMV
TLV.DGI
returns ByteString A encoded L field for the object in a new ByteString object.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_ENCODING
GPError.INVALID_TYPE

7.1.14.4.10 getLV()

ByteString.prototype.getLV()
ByteString getLV(Number encoding)
A LV field-pair for the object based on the encoding method specified by encoding.
Returns a ByteString object containing a L field appropriate to the length of the object, followed by the object itself.
For a ByteString b, the method call b.getLV() will return a ByteString with the same contents as the ByteString
returned by b.getL().concat(b).

Example
// Assume that sampleByteString is a ByteString object
// containing the binary value “0x0101”
otherByteString = sampleByteString.getLV(TLV.EMV);
// will return 0x020101

Parameter Type Description

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_ENCODING
GPError.INVALID_TYPE

7.1.14.4.11 left()

ByteString.prototype.left()
ByteString left(Number value)
Return in a new ByteString object the leftmost number of bytes indicated by value. If the value is greater than the
length, return the maximum number of values.
This is equivalent to the method bytes(0, value).

Example
OtherByteString = myByteString.left(10);

Parameter Type Description

Value Number Number of bytes

returns ByteString New ByteString object.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.14.4.12 neg()

ByteString.prototype.neg()
ByteString neg()
ByteString neg(Number size)
The twos complement (negative) of the object.
Returns a ByteString object containing the twos complement of the object.
There is no limitation on the size of the object.

Example
// Assuming that sampleByteString is a ByteString object
// with the binary value “0x0101”;
otherByteString = sampleByteString.neg();
// will populate otherByteString with “0xFEFF”

Parameter Type Description

Size Number The optional size parameter will contain the size of the resultant
object in bytes. It must be at least the same size of the ByteString
from which this method is invoked, and by default if it isn’t provided,
is the size of the ByteString.
If the size value is smaller than the length of the ByteString, then
a GPError object is generated with a value of
GPError.INVALID_LENGTH.

returns ByteString The twos complement of the object as a new ByteString object.

7.1.14.4.13 not()

ByteString.prototype.not()
ByteString not()
The ones complement (bitwise inverse) of the object.
Returns a ByteString object containing the ones complement of the object.
There is no limitation on the size of the object.

Example
// Assuming that the ByteString object sampleByteString
// contains the binary value “0x0101”
otherByteString = sampleByteString.not();
// will return “0x1010” in a new ByteString object otherByteString

Parameter Type Description

None

returns ByteString The ones complement of the object as a new ByteString object.

exception None

7.1.14.4.14 or()

ByteString.prototype.or()
ByteString or(ByteString value)
The bitwise OR of the two objects.
Returns a ByteString object containing the bitwise OR of the two objects.
If the two ByteString objects are of different lengths, then a GPError object is generated with a value of
GPError.INVALID_LENGTH.

Example
// Assuming that the ByteString object sampleByteString
// contains the value “0x0100” and otherBytesString contains “0x0000”,
// the following operation will return 0x0100 in the new ByteString
// object newByteString
newByteString = sampleByteString.or(otherByteString);
ByteString

Parameter Type Description

value ByteString value is a ByteString object of the same length of the
ByteString object from which the or() method is invoked.

returns ByteString The bitwise OR of the two objects as a new ByteString object.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.14.4.15 pad()

ByteString.prototype.pad()

ByteString pad(Number padMethod)

ByteString pad(Number padMethod, Boolean optional)
Returns the ByteString object, padded as indicated by paddingMethod.

Example
paddedByteString = myByteString.pad(ISO9797_METHOD_1);

Parameter Type Description

padMethod Number See EMV Specification. Valid values are:
Crypto.ISO9797_METHOD_1 (see [IS9797])
Crypto.ISO9797_METHOD_2 (see [IS9797])

If the padding method specified by the padMethod parameter is not

supported, then a GPError object is generated with a value of
GPError.INVALID_MECH.

optional Boolean If true, add padding characters only if ByteString.length % 8 != 0

If false, always add padding characters
The default value is false.

returns ByteString New ByteString with padding operation completed.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_MECH
GPError.INVALID_TYPE

7.1.14.4.16 right()

ByteString.prototype.right()
ByteString right(Number value)
Return in a new ByteString object the rightmost number of bytes indicated by value. If the value is greater than the
length, return the maximum number of values.
This is equivalent to the method call:
sampleByteString.bytes(sampleByteString.length - value, value).

Example
// If myByteString contains 0x1234567879101112131, otherByteString will
// contain 0x112131
otherByteString = myByteString.right(3);

Parameter Type Description

value Number Number of bytes from the right end boundary of the ByteString.
If the value parameter is negative, then a GPError object is
generated with a value of GPError.INVALID_LENGTH.

returns ByteString New ByteString object.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.14.4.17 startsWith()

ByteString.prototype.startsWith()
Number startsWith(ByteString value)

Example
// Assume that sampleByteString contains the value “0x0101” and
// otherByteString the value “0x0102”
similarByteCount = sampleByteString.startsWith(otherByteString);
// will return a number of 1

Parameter Type Description

value ByteString value is a ByteString object to which to compare with.

returns Number The number of identical bytes as an integer.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.14.4.18 toBase64()

ByteString.prototype.toBase64()
ByteString toBase64()
ByteString toBase64(Boolean lineBreak)
Converts a ByteString object in binary representation to the equivalent Base64 representation.
The returned ByteString will contain the value passed to the method expressed as a Base64 representation rather
than as a binary representation.

Example
// Assuming sampleByteString object exists and contains
// the binary value 0x656667.
// newByteString will contain a base64 representation of 0x656667.
newByteString = sampleByteString.toBase64();

Parameter Type Description

lineBreak Boolean Whether a line break should be included at the end of each 64 bytes.
Default is false.

returns ByteString A ByteString object containing the Base64 value of the

ByteString object from which the method was invoked.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TYPE

7.1.14.4.19 toBcd()

ByteString.prototype.toBcd
ByteString toBcd()
ByteString toBcd(Number countBytes)

Example
// Assume that sampleByteString contains the value “0x0101”;
newByteString = sampleByteString.toBcd(2); // will return x0257

Parameter Type Description

countBytes Number The optional parameter countBytes is the length in bytes of the
new ByteString object to create.
If the countBytes parameter is negative, then a GPError object is
generated with a value of GPError.INVALID_LENGTH.

returns ByteString A ByteString containing the binary-coded-decimal representation

of the object.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.14.4.20 toHex()

ByteString.prototype.toHex()
ByteString toHex()
ByteString toHex(Number countBytes)
Transposes a ByteString object in binary representation to the equivalent ASCII string.
The returned ByteString will contain the value passed to the method expressed as an ASCII string rather than as a
binary representation. So, for example, if the ByteString value contains 0x65666768, the equivalent ASCII
representation returned is “65666768”.
If countBytes is too small to hold the number, only the least significant digits will be expressed in the result. If
countBytes is too large, the result will be padded with zeroes on the left.

Example
// Assuming sampleByteString object exists and contains
// the binary value 0x65666768.
newByteString = sampleByteString.toHex();
// will return a ByteString object with the equivalent
// ASCII string “65666768”.

Parameter Type Description

countBytes Number The optional countBytes is a Number containing the length in
bytes of the new ByteString object to create. This parameter does
not have to specify an even number of bytes in order to allow nibbles
to be specified.
If the countBytes parameter is an odd number or negative, then a
GPError object is generated with a value of
GPError.INVALID_LENGTH.

returns ByteString A ByteString object containing an ASCII string which in turn

contains the hexadecimal value contained in the ByteString object

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.14.4.21 toSigned()

ByteString.prototype.toSigned()
Number toSigned()
Number toSigned(Boolean littleEndian)
The signed numeric value of the object.
The returned value will be negative if the most significant bit of the object is a one-bit, and non-negative otherwise. If the
length of the object is zero, zero will be returned. An exception will be thrown if the value cannot be expressed within a
signed 32-bit integer.
If the result of the method invocation does not fit within a 32 bit representation, then a GPError object is generated with
a value of GPError.DATA_TOO_LARGE.

Example
// Assume that the ByteString object sampleByteString
// contains the binary value “0x0101”
sampleInteger = sampleByteString.toSigned();

Parameter Type Description

littleEndian Boolean If this optional parameter is provided as true, then take the Little
Endian representation. Otherwise, take the Big Endian
representation.

returns Number The signed numeric value of the object.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.DATA_TOO_LARGE
GPError.INVALID_TYPE

7.1.14.4.22 toString()

ByteString.prototype.toString()
String toString()
String toString(Number encoding)
Returns a ECMAScript String representation of the ByteString object.

Example
// Assume that SampleBytefield contains “0x0101” and is two bytes long,
// sampleString will contain the string “0101”
sampleString = SampleBytefield.toString(HEX);

Parameter Type Description

encoding Number Refer to Table 7.1:
HEX
UTF8
ASCII
BASE64
CN
returns String An ECMAScript string value representation of the ByteString
object’s contents.

exception None

ByteString.prototype.toUnsigned()
Number toUnsigned()
Number toUnsigned(Boolean littleEndian)
The unsigned numeric value of the object.
If the length of the object is zero, zero will be returned. An exception will be thrown if the value cannot be expressed
within a signed (not unsigned) 32-bit integer.
If the result of the method invocation does not fit within a 32 bit representation, then a GPError object is generated with
a value of GPError.DATA_TOO_LARGE.

Example
// Assume that sampleByteString contains “0x0101”
// the following operation will return the unsigned value in myInteger
myInteger = sampleByteString.toUnsigned();

Parameter Type Description

littleEndian Boolean If this optional parameter is provided as true, then take the Little
Endian representation. Otherwise, take the Big Endian
representation.

returns Number The unsigned numeric value of the object, within a Number object.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.DATA_TOO_LARGE
GPError.INVALID_TYPE

7.1.14.4.24 xor()

ByteString.prototype.xor()
ByteString xor(ByteString value)
The bitwise XOR of the two objects.
Returns a ByteString object containing the bitwise XOR of the two objects. If this method is called repeatedly with the
same argument, it may not necessarily return the same object each time.
If the two ByteString objects are of different lengths, then a GPError object is generated with a value of
GPError.INVALID_LENGTH.

Example
// Assume that sampleByteString contains the value “0x0101”
otherByteString = sampleByteString.xor(“0x0001); // will return 0x0100

Parameter Type Description

value ByteString targetByteString contains the ByteString object to perform
the bitwise XOR with.

returns ByteString The bitwise XOR of the two objects as a new ByteString object.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_LENGTH
GPError.INVALID_TYPE

7.1.15 TLV
The TLV object describes a single Tag Length Value (TLV) object.
The TLV objects are immutable, that is the object instances cannot have their values changed.
TLV objects are created using the constructor method supplied or upon the invocation of certain
methods of a TLVList object.
7.1.15.1 Summary
TLV.DGI
TLV.EMV
TLV.L16
TLV.prototype.encodingMode
TLV.prototype.size
TLV.prototype.constructor()
TLV.prototype.getL()
TLV.prototype.getLV()
TLV.prototype.getTag()
TLV.prototype.getTLV()
TLV.prototype.getTV()
TLV.prototype.getValue()
7.1.15.2 Constants
Each of these constants must be assigned an unique value within the TLV object.

Constant Usage
TLV.DGI encoding mode
TLV.EMV encoding mode
TLV.L16 encoding mode

7.1.15.3 Properties

7.1.15.3.1 encodingMode

TLV.prototype.encodingMode Number
The encodingMode property is an ECMAScript Number object.
Read only property that is set when the object is constructed. The property encodingMode can be checked by the
script to confirm what mode was used for the encoding of a TLV object.
The following modes will be mandatory:
TLV.EMV EMV encoding of TLV
TLV.DGI DGI encoding of TLV
TLV.L16 Encoding of TLV with a two byte tag and length

For TLV.EMV tag encoding requirements, refer to the August 2000 version of EMV.
For TLV.DGI tag encoding requirements, refer to Appendix B.

7.1.15.3.2 size

TLV.prototype.size Number
The size property is an ECMAScript Number object.
Read only property that represents the combined size of the concatenation of (Tag | Length | Value), where Tag and
Length values are determined by encodingMode, as it would be returned from the getTLV method.

7.1.15.4 Methods

7.1.15.4.1 Constructor

TLV.prototype.constructor()
TLV new (Number tag, ByteString value, number encoding)
Returns a new TLV object that will be initialized with Tag, Length, and Value contained within the input parameter Value
ByteString.
If the encoding parameter is incompatible with the tag presented in tag, then a GPError object is generated with a
value of GPError.INVALID_TAG.
If the value parameter contains a value which is too large for a specified encoding method, then a GPError object is
generated with a value of GPError.DATA_TOO_LARGE.
Finally, if the value cannot be decoded using the specified encoding method, then a GPError object is generated
with a value of GPError.INVALID_DATA.

Example
newTLV = new TLV(0x5A, new ByteString(“0123456789”, HEX), TLV.EMV);
newTLV = new TLV(SampleTag, SampleValue, TLV.EMV);

Parameter Type Description

tag Number The Tag that will be assigned to the TLV.

value ByteString The Value data that will be assigned to the TLV.

encoding Number Value representing the Encoding Method that will be assigned to the
TLV. See encodingMode property for valid values.
If the encoding parameter is not supported, then a GPError object
is generated with a value of GPError.INVALID_ENCODING.

returns TLV The created object with contains TLV data.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.DATA_TOO_LARGE
GPError.INVALID_DATA
GPError.INVALID_ENCODING
GPError.INVALID_TAG
GPError.INVALID_TYPE

7.1.15.4.2 getL()

TLV.prototype.getL()
ByteString getL()
Retrieve the L value of the TLV object. The length component will be encoded in the format given to the TLV object in
construction, and specified in the property encodingMode.

Example
newTLV = new TLV(0x5A, new ByteString(“0123456789”, HEX), TLV.EMV);
myTLVLength = sampleTLV.getL();

Parameter Type Description

None

returns ByteString The L of the TLV, suitably encoded.

exception None

TLV.prototype.getLV()
ByteString getLV()
Retrieve the LV value of the TLV object. The length component will be encoded in the format given to the TLV object in
construction, and specified in the property encodingMode.

Example
newTLV = new TLV(0x5A, new ByteString(“0123456789”, HEX), TLV.EMV);
newByteString = sampleTLV.getLV();

Parameter Type Description

None

returns ByteString The LV of the TLV, suitably encoded.

exception None

7.1.15.4.4 getTag()

TLV.prototype.getTag()
Number getTag()
Returns a Number containing Tag associated with the object, the Tag will be encoded in the format that was given in the
construction of the object, and specified in the property encodingMode.

Example
sampleTLV = new TLV(0x5A, new ByteString(“0123456789”, HEX), TLV.EMV);
newByteString = sampleTLV.getTag();

Parameter Type Description

None

returns Tag The Tag element of the TLV.

exception None

7.1.15.4.5 getTLV()

TLV.prototype.getTLV()
ByteString getTLV()
Retrieve the concatenated tag, length, and value components of the TLV object, the Tag and Length component will be
encoded in the format given to the TLV object in construction, and specified in the property encodingMode.

Example
newTLV = new TLV(0x5A, new ByteString(“0123456789”, HEX), TLV.EMV);
newByteString = sampleTLV.getTLV();

Parameter Type Description

None

returns ByteString The TLV in the form of a single stream of the TLV, suitably encoded.

exception None

TLV.prototype.getTV()
ByteString getTV()
Retrieve the concatenated tag and value components of the TLV object, the Tag component will be encoded in the
format given to the TLV object in construction, and specified in the property encodingMode.

Example
newTLV = new TLV(0x5A, new ByteString(“0123456789”, HEX), TLV.EMV);
newByteString = sampleTLV.getTV();

Parameter Type Description

None

returns ByteString The TV in the form of a single stream of the TV, suitably encoded.

exception None

7.1.15.4.7 getValue()

TLV.prototype.getValue()
ByteString getValue()
Retrieve the value compoennt of the TLV object.

Example
newTLV = new TLV(0x5A, new ByteString(“0123456789”, HEX), TLV.EMV);
newByteString = sampleTLV.getValue();

Parameter Type Description

None

returns ByteString The Value element of stored TLV data.

exception None

7.1.16 TLVList
The TLVList object holds a collection of TLVs as they are created into the TLVList object.
The object is mutable, that is the object instances can have TLVs added or removed.
7.1.16.1 Summary
TLVList.prototype.encodingMode
TLVList.prototype.length
TLVList.prototype.constructor()
TLVList.prototype.append()
TLVList.prototype.appendValue()
TLVList.prototype.appendValueIndex()
TLVList.prototype.deleteByIndex()
TLVList.prototype.deleteByTag()
TLVList.prototype.find()
TLVList.prototype.findIndex()
TLVList.prototype.index()
TLVList.prototype.toByteString()
TLVList.prototype.updateValue()
TLVList.prototype.updateValueIndex()
7.1.16.2 Constants
There are no constants for the TLVList object.
7.1.16.3 Properties

7.1.16.3.1 encodingMode

TLVList.prototype.encodingMode Number
The encodingMode property is an ECMAScript Number object.
Read only property that is set when the object is constructed. The property can be checked by the script to confirm
what mode was used.
The following modes will be mandatory:
TLV.EMV EMV encoding of TLVList
TLV.DGI DGI encoding of TLVList
TLV.L16 Encoding with a two byte tag and length of TLVList

For TLV.EMV tag encoding requirements, refer to the August 2000 version of EMV.
For TLV.DGI tag encoding requirements, refer to Appendix B.

7.1.16.3.2 length

TLVList.prototype.length Number
The length property is an ECMAScript Number object.
Read only property that contains the number of entries in the list.

7.1.16.4 Methods

7.1.16.4.1 Constructor

TLVList.prototype.constructor()
TLVList new (ByteString tlvStream, Number encoding)
Parses tlvStream, breaking it down into individual TLVs. These TLVs will be held internally in the TLVList object and

Example
// Creates a TLVList with
// Tag 4F Value A003
// Tag 5F24 Value 020301
newTL = new TLVList(new ByteString(“4F02A0035F2403020301”, HEX), TLV.EMV);

Parameter Type Description

tlvStream ByteString The combined TLV. This value may be empty in which case an
empty list is created.

encoding Number Value representing the encoding method that will be assigned to the
TLVs within the TLVList. Valid encoding methods are:
TLV.EMV EMV encoding
TLV.DGI DGI encoding
TLV.L16 Encoding with a two byte tag and length
If the encoding parameter is not supported, then a GPError object
is generated with a value of GPError.INVALID_ENCODING.

returns TLVList The created object with contain all the TLV data.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.DATA_TOO_LARGE
GPError.INVALID_DATA
GPError.INVALID_ENCODING
GPError.INVALID_TAG
GPError.INVALID_TYPE
GPError.TAG_ALREADY_EXISTS

7.1.16.4.2 append()

TLVList.prototype.append()
append(ByteString tlvStream)
append(TLV tlvToAppend)
append(Number tag, ByteString value)
Appends the specified TLV data to the end of the existing list of TLVs.
The supplied input can either be a TLV stream of bytes, or a separately specified Tag and Value parameter.
The individual TLVs will not break apart TLVs with constructed tags.
If the encoding parameter is incompatible with the tags presented in tlvStream, then a GPError object is generated
with a value of GPError.INVALID_TAG.
If the tlvStream parameter contains a value which is too large for a specified encoding method, then a GPError
object is generated with a value of GPError.DATA_TOO_LARGE.
If the tlvStream cannot be decoded using the specified encoding method, then a GPError object is generated with
a value of GPError.INVALID_DATA.
Finally, if the tlvStream contains TLV(s) with the same tag value or a reoccurance of an existing tag in the TLVList
object, then a GPError object is generated with a value of GPError.TAG_ALREADY_EXISTS.

Example

Parameter Type Description

tlvStream ByteString TLV as a single stream of bytes in a ByteString.

tlvToAppend TLV TLV as a TLV object

tag Number Tag to be used to be added to the list.

value ByteString Value to be used to be added to the List.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.DATA_TOO_LARGE
GPError.INVALID_DATA
GPError.INVALID_TAG
GPError.INVALID_TYPE
GPError.TAG_ALREADY_EXISTS

7.1.16.4.3 appendValue()

TLVList.prototype.appendValue()
appendValue(Number tag, ByteString data)
Appends the data to the existing data for the specified tag.

Example
// Appends to existing tag 4F’s data 0x0102A003
sampleTL.appendValue(0x4F, new ByteString(“0102A003”,HEX));

Parameter Type Description

tag Number Tag to be used to be added to the list.

data ByteString Data to be added to the existing tag.

If the data parameter contains a value which, when appended to
the existing value for the tag, is too large for a specified encoding
method, then a GPError object is generated with a value of
GPError.DATA_TOO_LARGE.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.DATA_TOO_LARGE
GPError.INVALID_TAG
GPError.INVALID_TYPE

7.1.16.4.4 appendValueIndex()

TLVList.prototype.appendValueIndex()
appendValueIndex(Number index, ByteString data)
Appends the data to the existing data for the specified zero-based index into the TLVStream.
The zero-based index identifies the TLV to be modified within the TLVList, by its sequence order in the list.

Example
sampleTL = new TLVList(new ByteString(“1F01112F01223F0133”, HEX), TLV.EMV);
// sampleTL is:
// Tag 1F value 11
// Tag 2F value 22
// Tag 3F value 33

// Appends to the third tag’s data 0x0102A003

sampleTL.appendValueIndex(0x02, new ByteString(“0102A003”,HEX));

// sampleTL now is:

// Tag 1F value 11
// Tag 2F value 22
// Tag 3F value 330102A003

Parameter Type Description

index Number Zero-based index into the TLVStream.
The index represents the rank of the TLV in the TLVList rather than
the position of the Tag in a ByteString representation.
If the index parameter specifies an invalid index, such as a negative
number or a number greater or equal than the length property of the
TLVList object, then a GPError object is generated with a value of
GPError.INVALID_INDEX.

data ByteString Data to be added to the existing tag at the location in the TLVStream
indicated by index.
If the data parameter contains a value which, when appended to
the existing value for the tag at the specified index, is too large for a
specified encoding method, then a GPError object is generated
with a value of GPError.DATA_TOO_LARGE.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.DATA_TOO_LARGE
GPError.INVALID_INDEX
GPError.INVALID_TAG
GPError.INVALID_TYPE

7.1.16.4.5 deleteByIndex()

TLVList.prototype.deleteByIndex()
deleteByIndex (Number index)
Delete the specified TLV from the list using a zero based index.
The zero-based index identifies the TLV to be deleted within the TLVList, by its sequence order in the list.

Example
// Creates a TLVList with
// Tag 4F Value A003
// Tag 5F24 Value 020301
sampleTList = new TLVList(new ByteString(“4F02A0035F2403020301”, HEX), TLV.EMV);
// Delete the TLV from the list
// The TLVList object will look like
// Tag 4F Value A003
sampleTList.deleteByIndex(1);

Parameter Type Description

index Number Zero based index number that represents the Tag that will be deleted
from the list.
The index represents the rank of the TLV in the TLVList rather than
the position of the Tag in a ByteString representation.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_INDEX
GPError.INVALID_TYPE

7.1.16.4.6 deleteByTag()

TLVList.prototype.deleteByTag()
deleteByTag (Number tag)
Delete the specified TLV from the list by tag value.

Example
// Creates a TLVList with
// Tag 4F Value A003
// Tag 5F24 Value 020301
sampleTList = new TLVLlist(new ByteString(“4F02A0035F2403020301”, HEX), TLV.EMV);
// Delete TLV with Tag 0x4F from TLVList
// TLV List will look like
// Tag 5F24 Value 020301
sampleTList.deleteByTag(0x4F);
Parameter Type Description

tag Number Value represents the Tag that will be deleted from the list.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TAG
GPError.INVALID_TYPE
GPError.TAG_NOT_FOUND

7.1.16.4.7 find()

TLVList.prototype.find()
TLV find(Number tag)
Searches the list for a specified tag, and returns a TLV object.

Example
// Creates a TLVList with
// Tag 4F Value A003
// Tag 5F24 Value 020301
sampleTList = new TLVList(new ByteString(“4F02A0035F2403020301”, HEX), TLV.EMV);
// Returns a TLV object in sampleTLV with
// Tag 4F Value A003
sampleTLV = sampleTList.find(0x4F);

Parameter Type Description

tag Number Value represents the Tag that will be searched for within the list.

returns TLV A TLV object which contains the data stored for that Tag. Note any
changes to the returned TLV object will not be made to the TLVList
item.
Returns a null if TLV not found.

7.1.16.4.8 findIndex()

TLVList.prototype.findIndex()
Number FindIndex (Number tag)
Searches the list for a specified tag, and returns a zero based index for that TLV.
The zero-based index identifies the TLV found within the TLVList, by its sequence order in the list.

Example
// Creates a TLVList with
// Tag 4F Value A003
// Tag 5F24 Value 020301
sampleTList = new TLVList(new ByteString(“4F02A0035F2403020301”, HEX), TLV.EMV);
// This returns a value of 1 in sampleTLVIndex
sampleTLVIndex = sampleTLVList.findIndex(0x5F24);

Parameter Type Description

tag Number Value represents the Tag that will be searched for within the list.

returns Number Index that indicates the location of the TLV within TLV list. A
negative index value of –1 returned indicates that the TLV was not
found. Note this index may only be valid as long as no Add or Delete
methods are executed.
The index represents the rank of the TLV in the TLVList rather than
the position of the Tag in a ByteString representation.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_TAG
GPError.INVALID_TYPE

7.1.16.4.9 index()

TLVList.prototype.index()
TLV index (number index)
Returns a TLV object which represents the TLV stored within the TLVList at the given index.
The zero-based index identifies the TLV to be returned within the TLVList, by its sequence order in the list.

Example
// Creates a TLVList with
// Tag 4F Value A003
// Tag 5F24 Value 020301
sampleTList = new TLVList(new ByteString(“4F02A0035F2403020301”, HEX),
TLV.EMV);
// Returns a TLV object with
// Tag 5F24 Value 020301
sampleTLV = sampleTLVList.index(1);

Parameter Type Description

index Number Zero based index into the list of stored TLV items.
The index represents the rank of the TLV in the TLVList rather than
the position of the Tag in a ByteString representation.
If the index parameter specifies an invalid index, such as a negative
number or a number greater or equal than the length property of the
TLVList object, then a GPError object is generated with a value of

returns TLV A TLV object which contains the data stored at that index. Note any
changes to the returned TLV object will not be made to the TLVList
item.

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.INVALID_INDEX
GPError.INVALID_TYPE

7.1.16.4.10 toByteString()

TLVList.prototype.toByteString()
ByteString toByteString()
Returns the contents of the entire list, including T, L and V values in a TLV format as a ByteString object.

Example
// Creates a TLVList with
// Tag 4F Value A003
// Tag 5F24 Value 020301
sampleTList = new TLVList(new ByteString(“4F02A0035F2403020301”, HEX), TLV.EMV);
// sampleByteString will be a ByteString object with the value
// 0x4F02A0035F2403020301
sampleByteString = sampleTLVList.toByteString(TLV.EMV);

Parameter Type Description

None

returns ByteString The concatenated T, L and V values in a TLV format.

exception None

7.1.16.4.11 updateValue()

TLVList.prototype.updateValue()
updateValue(Number tag, ByteString updateValue)
Replaces the value of an already existing tag represented by tag with the value provided in updateValue, and then
recalculate and update the length value for this tag.

Example
// Updates existing tag 4F’s data to 0x0102A003
sampleTL.updateValue(0x4F, new ByteString(“0102A003”,HEX));

Parameter Type Description

tag Number Tag to be used to be added to the list.

updateValue ByteString Data to replace existing value of TLV specified by tag with.
If the updateValue parameter contains a value which, when
replacing the existing value for the tag, is too large for a specified
encoding method, then a GPError object is generated with a value
of GPError.DATA_TOO_LARGE.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.DATA_TOO_LARGE
GPError.INVALID_TAG
GPError.INVALID_TYPE

TLVList.prototype.updateValueIndex()
updateValueIndex(Number index, ByteString updateValue)
Replaces the value of an already existing tag represented by tag with the value provided in updateValue, and then
recalculate and update the length value for this tag.

Example
// Updates the second tag’s data to 0x0102A003
sampleTL.updateValueIndex(1, new ByteString(“0102A003”,HEX));

Parameter Type Description

index Number Zero based index number that represents the Tag that will be
updated from the list.
The index represents the rank of the TLV in the TLVList rather than
the position of the Tag in a ByteString representation.
If the index parameter specifies an invalid index, such as a negative
number or a number greater or equal than the length property of the
TLVList object, then a GPError object is generated with a value of
GPError.INVALID_INDEX.

returns None

exception GPError GPError.ARGUMENTS_MISSING

GPError.INVALID_ARGUMENTS
GPError.DATA_TOO_LARGE
GPError.INVALID_TAG
GPError.INVALID_TYPE

A. Sample Scripts
A.1 Example Scripts for Data Preparation
Application Profile

<?xml version="1.0"?>

<gp:ApplicationProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.ApplicationProfile.xsd" UniqueID="2A864886FC6B640101"
ProfileVersion="1.1.0" ErrataVersion="0">
<gp:Description>Application Profile Test</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2003-04-30" Time="00:00:00" By="Thales e-Security"
Digest="0000"/>
</gp:Revisions>
<gp:ConflictRules arrayElement="ConflictRule" arrayIndex="#"/>
<gp:ApplicationInfo Type="GP" Subtype="APP" Version="1.0.0" Owner="GlobalPlatform"
Developer="Thales e-Security" Provider="GlobalPlatform" Domain="" VolatileDataSpaceMax="1000"
VolatileDataSpaceMin="0" NonVolatileDataSpaceMax="1000" NonVolatileDataSpaceMin="0">
<gp:Privileges/>
<gp:LifeCycles arrayElement="LifeCycle" arrayIndex="Name">
<gp:LifeCycle Name="SampleLifeCycle01" Value="01"/>
<gp:LifeCycle Name="SampleLifeCycle02" Value="02"/>
<gp:LifeCycle Name="SampleLifeCycle03" Value="03"/>
</gp:LifeCycles>
<gp:Codes arrayElement="Code" arrayIndex="ModuleID"/>
</gp:ApplicationInfo>
<gp:Key Name="MasterKey_AC" ProfileID="2A864886FC6B640301" External="true"/>
<gp:Key Name="MasterKey_MAC" ProfileID="2A864886FC6B640302" External="true"/>
<gp:Key Name="DerivedKey_AC" ProfileID="2A864886FC6B640303" External="true"/>
<gp:Key Name="DerivedKey_MAC" ProfileID="2A864886FC6B640304" External="true"/>
<gp:Key Name="IssuerPrivateKey" ProfileID="2A864886FC6B640305" External="true"/>
<gp:Key Name="GeneratedPrivateKey" ProfileID="2A864886FC6B640306" External="true"/>
<gp:Key Name="GeneratedPublicKey" ProfileID="2A864886FC6B640308" External="true"/>
<gp:Key Name="WrappedPrivateKey" ProfileID="2A864886FC6B640308" External="true"/>
<gp:Key Name="ZMK" ProfileID="2A864886FC6B640309" External="true"/>
<gp:Key Name="WrappedDerivedKey_AC" ProfileID="2A864886FC6B64030A" External="true"/>
<gp:Key Name="WrappedDerivedKey_MAC" ProfileID="2A864886FC6B64030B" External="true"/>
<gp:DataElement Name="PAN" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="4" Value="" Tag="" ReadWrite="false" Update="false" Optional="false"
MandatoryAudit="false"/>
<gp:DataElement Name="PSN" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="4" Value="" Tag="" ReadWrite="false" Update="false" Optional="false"
MandatoryAudit="false"/>
<gp:DataElement Name="CardHolderInput" External="true" Type="ByteString" Encoding="HEX"
FixedLength="false" Length="1024" Value="" Tag="" ReadWrite="false" Update="false"
Optional="false" MandatoryAudit="false"/>
<gp:DataElement Name="authenticateTag1" External="true" Type="ByteString" Encoding="HEX"
FixedLength="false" Length="4" Value="" Tag="" ReadWrite="false" Update="false" Optional="false"
MandatoryAudit="false"/>

// =========================== Functions =================================

// ///////////////////////////////////////////////////////////////////////
// padByteString
//
// Returns the data passed in padded to the length specifed in padLength
// with the string specified in padData. Note if padData contains
// something other than a single byte ByteString then whatever it contains
// will be appended each time.
// ///////////////////////////////////////////////////////////////////////
function padByteString(data, padLength, padData)
{
var paddedData = data;
for (var i = data.length; i < padLength; i++)
paddedData = paddedData.concat(padData);

// ///////////////////////////////////////////////////////////////////////
// generateDerivationData
//
// This function generates the derivation data which consists of
// PAN + PSN.
// ///////////////////////////////////////////////////////////////////////
function generateDerivationData(pan, psn)
{
// Create the derivation Data, alter as to what you want the derivation
// data to be.
var derivationData = pan.concat(psn);

var paddeDerivationData = padByteString(derivationData, 16, padVal);

return derivationData;
}

// ///////////////////////////////////////////////////////////////////////
// addToOutput
//
// Takes the output data element and the TLV to add and updates the
// output data with the new TLV. If the tag already exists it is
// replaced, othewise it is appended to the end of the data.
// ///////////////////////////////////////////////////////////////////////
function addToOutput(output, tlv)
{
// Search for tag
// If not present add to end
var index = output.findIndex(tlv.getTag());
if (-1 == index)
output.append(tlv.getTLV());
else
{
// Already present so update data and length
// We need to delete the old empty tag and add a new one
output.deleteByIndex(index);
output.append(tlv.getTLV());
}
}

// ========================= End of Functions ============================

// The value to pad data with

var padVal = new ByteString("00", HEX);

// Mappings to deserialized data

data = this.data;
key = this.key;

// ///////////////////////////////////////////////////////////////////////
// STEP 1:

// ///////////////////////////////////////////////////////////////////////
// STEP 2:
// Derive some keys by generating some derivation data from the PAN and PSN
// and then generating the derived keys.
// ///////////////////////////////////////////////////////////////////////
var derivationData = generateDerivationData(data.PAN, data.PSN);

derivationData = new ByteString("0000000000000001", HEX);

this.crypto.deriveKey(key.MasterKey_AC, Crypto.DES_CBC, derivationData,

key.DerivedKey_AC);
this.crypto.deriveKey(key.MasterKey_MAC, Crypto.DES_CBC, derivationData,
key.DerivedKey_MAC);

// Wrap these derived keys with the ZMK

this.crypto.wrap(key.ZMK, Crypto.DES_CBC, key.DerivedKey_AC,
key.WrappedDerivedKey_AC);
this.crypto.wrap(key.ZMK, Crypto.DES_CBC, key.DerivedKey_AC,
key.WrappedDerivedKey_MAC);

// Create the TLVs for these derived keys

var derivedKeyOut_AC = new TLV(0x5F10,
key.WrappedDerivedKey_AC.getComponent(Key.DES), TLV.EMV);
var derivedKeyOut_MAC = new TLV(0x5F11,
key.WrappedDerivedKey_MAC.getComponent(Key.DES), TLV.EMV);

// Add these wrapped derived keys to the output data

totalOutput.append(derivedKeyOut_AC.getTLV());
totalOutput.append(derivedKeyOut_MAC.getTLV());

// ///////////////////////////////////////////////////////////////////////
// STEP 3:
// Sign some data that requires authentication. This data could come from
// an INI/Parameter file.
// ///////////////////////////////////////////////////////////////////////
var authenticateTLV1 = totalInput.find(data.authenticateTag1.toSigned());
var authenticateTLV2 = totalInput.find(data.authenticateTag2.toSigned());

var authenticateDataList = new TLVList(authenticateTLV1.getTLV(), TLV.EMV);

authenticateDataList.append(authenticateTLV2.getTLV());

// Pad the data

var paddedAuthData = padByteString(authenticateDataList.toByteString(), 64, padVal);

// Sign the authentication data

// Note: The data to be signed must be at least the size of the modulus

// Add the signed authentication data to the output

var authDataTLV = new TLV(0x5F16, signedAuthenticationData, TLV.EMV);
totalOutput.append(authDataTLV.getTLV());

// ///////////////////////////////////////////////////////////////////////
// STEP 4:
// Generate an RSA keyset from which we export the private key and
// create a certificate using the public key.
// ///////////////////////////////////////////////////////////////////////
this.crypto.generateKeyPair(Crypto.RSA_KEY_PAIR_GEN, key.GeneratedPublicKey,
key.GeneratedPrivateKey);

// Wrap the private key in a ZMK

this.crypto.wrap(key.ZMK, Crypto.RSA, key.GeneratedPrivateKey, key.WrappedPrivateKey);

// Export the wrapped private key

var wrappedPrivKeyTLV = new TLV(0x3F34,
key.WrappedPrivateKey.getComponent(Key.MODULUS), TLV.EMV);
totalOutput.append(wrappedPrivKeyTLV.getTLV());

// ///////////////////////////////////////////////////////////////////////
// STEP 5:
// Generate a certificate
// ///////////////////////////////////////////////////////////////////////
// Whatever goes into your certificate.
var cert = new ByteString("6A" +
"03" +
"01" +
key.GeneratedPublicKey.getComponent(Key.MODULUS) +
"BC",
HEX);

var paddedCert = padByteString(cert, 64, padVal);

// Now sign the certificate

var signedCertificate = this.crypto.sign(key.IssuerPrivateKey, Crypto.RSA, paddedCert);

// Add to output
var certTLV = new TLV(0x4B, paddedCert, TLV.EMV);
var signedCertTLV = new TLV(0x5B, signedCertificate, TLV.EMV);
totalOutput.append(certTLV.getTLV());
totalOutput.append(signedCertTLV.getTLV());

// ///////////////////////////////////////////////////////////////////////
// STEP 6:
// Output the data.
// ///////////////////////////////////////////////////////////////////////

// Write to output
data.Output = totalOutput.toByteString();

]]></gp:Script>
</gp:ScriptFragment>
</gp:ApplicationProfile>

Key Profile 101

<?xml version="1.0"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B640301" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="SECRET" SubType="DES" Size="16" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>
<gp:Usage Encrypt="false" Decrypt="false" DecryptEncrypt="false" Sign="false" Verify="false"
Wrap="false" Unwrap="false" UnwrapWrap="false" Derive="true"/>
<gp:Value Format="DES" arrayElement="Component" arrayIndex="#">
<gp:Component/>
</gp:Value>
</gp:KeyProfile>

Key Profile 102

<?xml version="1.0"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B640302" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="SECRET" SubType="DES" Size="16" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>

Key Profile 103

<?xml version="1.0"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B640303" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="SECRET" SubType="DES" Size="16" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>
<gp:Usage Encrypt="false" Decrypt="false" DecryptEncrypt="false" Sign="false" Verify="false"
Wrap="false" Unwrap="false" UnwrapWrap="false" Derive="true"/>
<gp:Value Format="DES" arrayElement="Component" arrayIndex="#">
<gp:Component/>
</gp:Value>
</gp:KeyProfile>

Key Profile 104

<?xml version="1.0"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B640304" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="SECRET" SubType="DES" Size="16" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>

Key Profile 105

<?xml version="1.0"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B640305" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="PRIVATE" SubType="RSA" Size="128" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>
<gp:Usage Encrypt="false" Decrypt="false" DecryptEncrypt="false" Sign="true" Verify="false"
Wrap="false" Unwrap="false" UnwrapWrap="false" Derive="false"/>
<gp:Value Format="CRT" arrayElement="Component" arrayIndex="#">
<gp:Component/>
<gp:Component/>
</gp:Value>
</gp:KeyProfile>

Key Profile 106

<?xml version="1.0"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B640306" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="PRIVATE" SubType="RSACRT" Size="128" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>

Key Profile 107

<?xml version="1.0"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B640307" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="PUBLIC" SubType="RSA" Size="128" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>
<gp:Usage Encrypt="false" Decrypt="false" DecryptEncrypt="false" Sign="false" Verify="false"
Wrap="false" Unwrap="false" UnwrapWrap="false" Derive="false"/>
</gp:KeyProfile>

Key Profile 108

<?xml version="1.0"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B640308" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="PRIVATE" SubType="RSACRT" Size="128" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>
<gp:Usage Encrypt="false" Decrypt="false" DecryptEncrypt="false" Sign="false" Verify="false"
Wrap="false" Unwrap="false" UnwrapWrap="false" Derive="false"/>
</gp:KeyProfile>

Key Profile 109

<?xml version="1.0"?>
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 189

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B640309" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="PRIVATE" SubType="DES" Size="16" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>
<gp:Usage Encrypt="false" Decrypt="false" DecryptEncrypt="false" Sign="false" Verify="false"
Wrap="false" Unwrap="true" UnwrapWrap="false" Derive="false"/>
<gp:Value Format="CRT" arrayElement="Component" arrayIndex="#">
<gp:Component/>
<gp:Component/>
</gp:Value>
</gp:KeyProfile>

Key Profile 110

<?xml version="1.0"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B64030A" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>This is an example key profile</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision Version="1.0.0" Date="2002-01-01" Time="00:00:00" By="Thales e-Security"
Digest="0A0B0C0D"/>
</gp:Revisions>
<gp:KeyInfo Type="SECRET" SubType="DES" Size="16" Owner="10" Version="1"
StartDate="2001-12-01" EndDate="2003-12-01">
<gp:KeyPart/>
<gp:TransportKey/>
</gp:KeyInfo>
<gp:Attribute Sensitive="true" Importable="true" Exportable="true"/>
<gp:Usage Encrypt="false" Decrypt="false" DecryptEncrypt="false" Sign="false" Verify="false"
Wrap="false" Unwrap="false" UnwrapWrap="false" Derive="false"/>
<gp:Value Format="DES" arrayElement="Component" arrayIndex="#">
<gp:Component/>
<gp:Component/>
</gp:Value>
</gp:KeyProfile>

Key Profile 111

A.2 Example Open Secure Channel Script

Excerpt from Application Profile for a Card Manager or Security Domain Application
<gp:SecureChannel SecureChannel="SCP01">
<gp:OpenSecureChannel Param="level">
<gp:KeyDeclaration Name="KDCenc" External="true"/>
<gp:KeyDeclaration Name="KDCkek" External="true"/>
<gp:KeyDeclaration Name="KDCmac" External="true"/>
<gp:Script><![CDATA[

GPSystem.trace("Entering OpenSecureChannel Script.");

// Create a new Secure Channel 01 Protocol object *****************

level = arguments[0];
GPSystem.trace("Level requested is "+level);
sc = this.secureChannel;
GPSystem.trace("Attempting Initailize for Update.");
GPSystem.trace(" initializeUpdate(0,0);");
response = new ByteString(sc.initializeUpdate(0, 0), HEX);
GPSystem.trace("Initialize for Update executed with response "+response);
if (response == null) {
throw new Error("Initialize Update command failed");
}

// Set the life cycle *********************************************

GPSystem.trace("Current secure channel state is "+this.secureChannel.state);
switch (this.secureChannel.state) {
case SC_CLOSE:
GPSystem.trace("Secure Channel state "+level+" corresponds to SC_CLOSE");
break;
case SC_INITIALIZE:
GPSystem.trace("Secure Channel state "+level+" corresponds to SC_INITIALIZE");
GPSystem.trace("Attempting to set the encryption key.");
GPSystem.trace("
setEncKey("+this.key.KDCenc.getComponent(Key.MODULUS)+");");
sc.setEncKey(this.key.KDCenc);
GPSystem.trace("Attempting to set the MAC key.");
GPSystem.trace("
setMacKey("+this.key.KDCmac.getComponent(Key.MODULUS)+");");
sc.setMacKey(this.key.KDCmac);
GPSystem.trace("Attempting to set the key exchange key.");
GPSystem.trace("
setDekKey("+this.key.KDCkek.getComponent(Key.MODULUS)+");");
sc.setDekKey(this.key.KDCkek);
break;
case SC_OPEN:
GPSystem.trace("Secure Channel state "+level+" corresponds to SC_OPEN");
break;
default:
GPSystem.trace("Secure Channel state "+level+" corresponds to an unrecognized
state");
Throw("Card is in an unrecognized state");
break;
}
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 192

// Perform an External Authenticate *******************************

GPSystem.trace("Attempting External Authenticate.");
GPSystem.trace(" externalAuthenticate("+level+");");
sc.externalAuthenticate(level);

]]></gp:Script>
</gp:OpenSecureChannel>
</gp:SecureChannel>

A.3 Example Script for Loading Applets

Excerpt from Application Profile for a Card Manager or Security Domain Application
<gp:ScriptFragment Name="LOAD" Active="true" StartLifeCycle="pre_Load"
EndLifeCycle="post_Load">
<gp:Description>Script for loading an application using the Issuer Security
Domain</gp:Description>
<gp:Declaration Name="cardManagerAID" External="true"/>
<gp:Declaration Name="loadFileAID" External="true"/>
<gp:Declaration Name="loadFileDBHash" External="true"/>
<gp:Declaration Name="loadParamField" External="true"/>
<gp:Declaration Name="loadToken" External="true"/>
<gp:Declaration Name="loadMethod" External="true"/>
<gp:Script><![CDATA[
// Select Card Manager
GPSystem.trace("Select Card Manager.");
GPSystem.trace(" this.select();");
this.select();
GPSystem.trace("Card Manager selected.");

// Establish Secure Channel with MAC

GPSystem.trace("Establish secure channel with MAC.");
GPSystem.trace(" this.openSecureChannel(0x01)");
scLevel = new ByteString (0x01, HEX);
this.openSecureChannel(scLevel);
GPSystem.trace("Secure channel opened.");

// External parameters other than cardManagerAID which are required and depend on the
application specification and issuer choice:
// loadFileAID - the application identifier for the load file (can extract from the Load File
Profile)
// loadFileName - name of the load file (can extract from the Load File Profile)
// loadFileStructure - load file structure (can extract from the load file)
// loadFileDBHash - load file data block hash
// loadParamField - any specific load parameters for the load file
// loadToken - load token
// loadMethod - a boolean parameter which specifies whether to load by filename (true)
or load using load file structure (false)
// - loadMethod could be specified by the card issuer

// Load the load file onto the card

// First, execute a install [for load] command
GPSystem.trace("Execute an Install for Load command.");
GPSystem.trace(" this.installForLoad("+this.data["loadFileAID"]+",
"+this.data["cardManagerAID"]+", "+this.data["loadFileDBHash"]+",
"+this.data["loadParamField"]+");");
this.installForLoad(this.data["loadFileAID"], this.data["cardManagerAID"],
this.data["loadFileDBHash"], this.data["loadParamField"], this.data["loadToken"]);
GPSystem.trace("installForLoad executed successfully.");

// Second, execute a set of load commands

// The load() method implicitly sends the correct number of LOAD commands in either
case

if (this.data.loadMethod == 74727565) {
// Load the load file using the filename of the load file
GPSystem.trace("Attempt to load using the filename "+this.data["loadFileName"]);
GPSystem.trace(" this.loadByName("+this.data["loadFileName"].toString()+");");
this.loadByName(this.data["loadFileName"]);
GPSystem.trace("Load is successful.");
}
else {
// Load using the Load File structure specified in the Card Specification
GPSystem.trace("Attempt to load using the load file structure
"+this.data["loadFileStructure"]);
GPSystem.trace(" this.load(this.data["+this.data["loadFileName"]+"]);");
this.load(this.data["loadFileStructure"]);
GPSystem.trace("Load is successful.");
}
]]></gp:Script>
</gp:ScriptFragment>

A.4 Example Script for Installing Applet

Excerpt from Application Profile for a Card Manager or Security Domain Application
<gp:ScriptFragment Name="INSTALL" Active="true" StartLifeCycle="post_Load"
EndLifeCycle="post_INSTALL">
<gp:Description>Script for installing an application and making its lifecycle SELECTABLE
using the Issuer Security Domain</gp:Description>
<gp:Declaration Name="loadFileAID" External="true"/>
<gp:Declaration Name="moduleAID" External="true"/>
<gp:Declaration Name="applicationAID" External="true"/>
<gp:Declaration Name="privileges" External="true"/>
<gp:Declaration Name="installParamField" External="true"/>
<gp:Declaration Name="installToken" External="true"/>
<gp:Script><![CDATA[
// Select Card Manager
this.select();

// Establish Secure Channel with MAC

scLevel = new ByteString (0x01, HEX);
this.openSecureChannel(scLevel);

// External parameters which are required and depend on the application specification
and issuer choice:
// loadFileAID - the application identifier for the load file (can extract from Load File
Profile)
// moduleAID - application identifier of the desired application module in the load file
(can extract from Load File Profile)
// applicationAID - application identifier to assign to the newly created application
instance (specified by card issuer)
// privileges - privileges for the new application instance (can extract from Application
Profile for application)
// installParamField - application specific installation parameters (valid options should
be documented by application developer in specification)
// installToken - install token

// Install and make selectable the application

this.installForInstallAndSelectable(this.data["loadFileAID"], this.data["moduleAID"],
this.data["applicationAID"], this.data["privileges"], this.data["installParamField"],
this.data["installToken"]);

]]></gp:Script>
</gp:ScriptFragment>

A.5 Complete Example with Scripts for Data Preparation

and Personalization
This is an Application Profile for the application “CPSDemonstrator” which is available for
download from the GlobalPlatform member website. The key profiles for this Application Profile
are illustrated following this XML document.
Application Profile

<?xml version="1.0" encoding="UTF-8"?>

<gp:ApplicationProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.ApplicationProfile.xsd" UniqueID="2A864886FC6B640102"
ProfileVersion="1.1.0" ErrataVersion="0">
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision ProfileID="2A864886FC6B640102" Version="1.0.0" Date="2002-02-13"
Time="15:54:00" By="GlobalPlatform" Digest="0000"/>
</gp:Revisions>
<gp:ConflictRules arrayElement="ConflictRule" arrayIndex="#">


<gp:ConflictRule
Source="CardProfile.CardManufacturerProduct.Chip.ResourcesAvailable.Unit" Target="bytes"
Rule="=="/>

<gp:ConflictRule
Source="CardProfile.CardManufacturerProduct.Chip.ResourcesAvailable.RAM" Target="0"
Rule=">="/>

<gp:ConflictRule
Source="CardProfile.CardManufacturerProduct.Chip.ResourcesAvailable.EEPROM" Target="0"
Rule=">="/>

<gp:ConflictRule
Source="CardProfile.CardManufacturerProduct.Chip.ResourcesAvailable.Flash" Target="0"
Rule=">="/>

<gp:ConflictRule Source="CardProfile.CardManufacturerProduct.Platform.Type"
Target="JAVA" Rule="=="/>

<gp:ConflictRule Source="CardProfile.CardManufacturerProduct.Platform.OSPlatform"
Target="GP" Rule="=="/>
<gp:ConflictRule Source="CardProfile.CardManufacturerProduct.Platform.OSVersion"
Target="2.0.1" Rule="=="/>
</gp:ConflictRules>
<gp:ApplicationInfo Version="0.0.1" Owner="GlobalPlatform" Provider="GP" Domain="Tool"
Developer="KP" Type="GP" Subtype="APP" VolatileDataSpaceMin="0"
NonVolatileDataSpaceMin="4096">
<gp:Privileges/>
<gp:LifeCycles arrayElement="LifeCycle" arrayIndex="Name">
<gp:LifeCycle Name="pre_PersoPrep"/>
<gp:LifeCycle Name="post_PersoPrep"/>
Copyright  2003 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 197
<gp:LifeCycle Name="INSTALLED" Value="03"/>
<gp:LifeCycle Name="SELECTABLE" Value="07"/>
<gp:LifeCycle Name="PERSONALIZED" Value="0F"/>
</gp:LifeCycles>
<gp:Codes arrayElement="Code" arrayIndex="ModuleID">
<gp:Code ProfileID="2A864886FC6B640403" ModuleID="0000100001"/>
</gp:Codes>
</gp:ApplicationInfo>
<gp:Key Name="transportKeyKey" ProfileID="2A864886FC6B64030A" External="true"/>
<gp:Key Name="transportPINKey" ProfileID="2A864886FC6B64030B" External="true"/>
<gp:Key Name="aksKey" ProfileID="2A864886FC6B64030C" External="true"/>
<gp:Key Name="wrappedAksKey" ProfileID="2A864886FC6B64030D" External="true"/>
<gp:Key Name="unwrappedWrappedAksKey" ProfileID="2A864886FC6B64030E"
External="true"/>
<gp:DataElement Name="isid" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="5" ReadWrite="false" Update="false"/>
<gp:DataElement Name="cardExp" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="4" ReadWrite="false" Update="false"/>
<gp:DataElement Name="dgi0101" External="false" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="9" ReadWrite="true" Update="true"/>
<gp:DataElement Name="fName" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="20" ReadWrite="false" Update="false"/>
<gp:DataElement Name="mName" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="20" ReadWrite="false" Update="false"/>
<gp:DataElement Name="lName" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="20" ReadWrite="false" Update="false"/>
<gp:DataElement Name="DoB" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="4" ReadWrite="false" Update="false"/>
<gp:DataElement Name="dgi0102" External="false" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="64" ReadWrite="true" Update="true"/>
<gp:DataElement Name="streetAdd" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="20" ReadWrite="false" Update="false"/>
<gp:DataElement Name="cityAdd" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="20" ReadWrite="false" Update="false"/>
<gp:DataElement Name="zipAdd" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="10" ReadWrite="false" Update="false"/>
<gp:DataElement Name="countryAdd" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="3" ReadWrite="false" Update="false"/>
<gp:DataElement Name="phone" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="15" ReadWrite="false" Update="false"/>
<gp:DataElement Name="dgi0103" External="false" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="68" ReadWrite="true" Update="true"/>
<gp:DataElement Name="ssn" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="17" ReadWrite="false" Update="false"/>
<gp:DataElement Name="cityOB" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="20" ReadWrite="false" Update="false"/>
<gp:DataElement Name="countryOB" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="3" ReadWrite="false" Update="false"/>
<gp:DataElement Name="dgi8101" External="false" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="40" ReadWrite="true" Update="true"/>
<gp:DataElement Name="aks" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="16" ReadWrite="false" Update="false"/>
<gp:DataElement Name="dgi9101" External="false" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="16" ReadWrite="true" Update="true"/>

The technology provided or described herein is subject to updates, revisions, and extensions by
GlobalPlatform. Use of this information is governed by the GlobalPlatform license agreement and any use
inconsistent with that agreement is strictly prohibited
9/24/2003 GlobalPlatform Systems Scripting Language Specification v1.1.0 198
<gp:DataElement Name="dfName" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="16" ReadWrite="false" Update="false"/>
<gp:DataElement Name="applicationLabel" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="16" ReadWrite="false" Update="false"/>
<gp:DataElement Name="applicationPriority" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="1" ReadWrite="false" Update="false"/>
<gp:DataElement Name="languagePreference" External="true" Type="ByteString"
Encoding="HEX" FixedLength="true" Length="8" ReadWrite="false" Update="false"/>
<gp:DataElement Name="issuerCodeTableIndex" External="true" Type="ByteString"
Encoding="HEX" FixedLength="true" Length="1" ReadWrite="false" Update="false"/>
<gp:DataElement Name="applicationPreferredName" External="true" Type="ByteString"
Encoding="HEX" FixedLength="true" Length="16" ReadWrite="false" Update="false"/>
<gp:DataElement Name="applicationProfile" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="2" ReadWrite="false" Update="false"/>
<gp:DataElement Name="adl" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="2" ReadWrite="false" Update="false"/>
<gp:DataElement Name="cntry" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="3" ReadWrite="false" Update="false"/>
<gp:DataElement Name="domain" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="1" ReadWrite="false" Update="false"/>
<gp:DataElement Name="applicationVersionNumber" External="true" Type="ByteString"
Encoding="HEX" FixedLength="true" Length="2" ReadWrite="false" Update="false"/>
<gp:DataElement Name="dgi9102" External="false" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="81" ReadWrite="true" Update="true"/>
<gp:DataElement Name="pinBlock" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="8" ReadWrite="false" Update="false"/>
<gp:DataElement Name="dgi1101" External="false" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="8" ReadWrite="true" Update="true"/>
<gp:DataElement Name="pinCount" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="1" ReadWrite="false" Update="false"/>
<gp:DataElement Name="pinLimit" External="true" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="1" ReadWrite="false" Update="false"/>
<gp:DataElement Name="dgi1102" External="false" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="2" ReadWrite="true" Update="true"/>
<gp:DataElement Name="dgi7FFF" External="false" Type="ByteString" Encoding="HEX"
FixedLength="true" Length="3" ReadWrite="true" Update="true"/>
<gp:ScriptFragment Name="PERSOPREP" Active="true" StartLifeCycle="pre_PersoPrep"
EndLifeCycle="post_PersoPrep">

<gp:Declaration Name="isid" External="true"/>
<gp:Declaration Name="cardExp" External="true"/>
<gp:Declaration Name="fName" External="true"/>
<gp:Declaration Name="mName" External="true"/>
<gp:Declaration Name="lName" External="true"/>
<gp:Declaration Name="DoB" External="true"/>
<gp:Declaration Name="streetAdd" External="true"/>
<gp:Declaration Name="cityAdd" External="true"/>
<gp:Declaration Name="zipAdd" External="true"/>
<gp:Declaration Name="countryAdd" External="true"/>
<gp:Declaration Name="phone" External="true"/>
<gp:Declaration Name="ssn" External="true"/>
<gp:Declaration Name="cityOB" External="true"/>
<gp:Declaration Name="countryOB" External="true"/>
<gp:Declaration Name="dfName" External="true"/>
<gp:Declaration Name="applicationLabel" External="true"/>

// Constants used in this fragment

myObject= this.data;

// Keys used in this fragment

myKey = this.key;

GPSystem.trace("before dgi0101");
// Create DGI 0101 Contents
myDGI = new ByteBuffer();
myDGI.append(myObject.isid);
myDGI.append(myObject.cardExp);
myObject.dgi0101 = myDGI.toByteString();

GPSystem.trace("before dgi0102");
// Create DGI 0102 Contents
myDGI.clear();
myDGI.append(myObject.fName);
myDGI.append(myObject.mName);
myDGI.append(myObject.lName);
myDGI.append(myObject.DoB);
myObject.dgi0102 = myDGI.toByteString();

GPSystem.trace("before dgi0103");
// Create DGI 0103 Contents
myDGI.clear();
myDGI.append(myObject.streetAdd);
myDGI.append(myObject.cityAdd);
myDGI.append(myObject.zipAdd);

GPSystem.trace("before dgi8101");
// Create DGI 8101 Contents
myDGI.clear();
myDGI.append(myObject.ssn);
myDGI.append(myObject.cityOB);
myDGI.append(myObject.countryOB);

myEncDgi8101 = crypto.encrypt(myKey.transportKeyKey, Crypto.DES_ECB,

myDGI.toByteString(), null);
myObject.dgi8101 = myEncDgi8101;

GPSystem.trace("before dgi9101");
// Compute aksKey check value Create DGI 9101 Contents
ToEnc = new ByteString("0000000000000000", HEX);
myEncValue = crypto.encrypt(myKey.aksKey, Crypto.DES_ECB, ToEnc, null);
myCheckValue = (myEncValue.bytes(0,3));

crypto.wrap(myKey.transportKeyKey, Crypto.DES_ECB, myKey.aksKey,

myKey.wrappedAksKey)
myDGI.clear();
myDGI.append(myKey.wrappedAksKey.getComponent(Key.DES));
myObject.dgi9101 = myDGI.toByteString();

GPSystem.trace("before dgi9102");
// Create DGI 9102 Contents
myDGI.clear();
// Tag for FCI Template
myDGI.append("6F", HEX);
// Length of FCI Template
//tempvar = new ByteString("51", HEX);
myDGI.append("51", HEX);
// Tag for DF Name
myDGI.append("84", HEX);
// Length of DF Name
myDGI.append(myObject.dfName.getLV());
// Tag for FCI Proprietary template
myDGI.append("A5", HEX);
// Length of FCI Proprietary template
myDGI.append("3D", HEX);
// Tag for Application Label
myDGI.append("50", HEX);
// Length of Application Label
myDGI.append(myObject.applicationLabel.getLV());
// Tag for Application Priority Indicator
myDGI.append("87", HEX);
// Length of Application Priority Indicator
myDGI.append(myObject.applicationPriority.getLV());
// Tag for Language Preference
myDGI.append("5F2D", HEX);
// Length of Language Preference
myDGI.append(myObject.languagePreference.getLV());

GPSystem.trace("before dgi1101");
// Create DGI 1101 Contents
myDGI.clear();
myDGI.append(myObject.pinBlock);
myObject.dgi1101 = crypto.encrypt(myKey.transportPINKey, Crypto.DES_ECB,
myDGI.toByteString(), null);

GPSystem.trace("before dgi1102");
// Create DGI 1102 Contents
myDGI.clear();
myDGI.append(myObject.pinCount);
myDGI.append(myObject.pinLimit);
myObject.dgi1102 = myDGI.toByteString();

GPSystem.trace("before dgi7FFF");
// Create DGI 7FFF Contents
myDGI.clear();
myDGI.append(myCheckValue);
myObject.dgi7FFF = myDGI.toByteString();

]]></gp:Script>

// Constants used in this fragment

GPSystem.trace("debut myObject= this.data;");
myObject= this.data;
ZEROO= new ByteString("00",HEX);
MACONLY= 0x01;
MACENC = 0x03;
CLASEC = 0x84;
STOREDATA = 0xE2;
ENDPERSO = 0x40;
P1 = 0x00;
P2 = 0x00;

// Keys used in this fragment

myKey = this.key;

this.card.reset(Card.RESET_WARM);

GPSystem.trace("debut this.select;");
GPSystem.trace("aid is: "+this.card.profile.ApplicationInstances.ApplicationInstance[0].AID);
// Selecting the application for secure update
// this.select(1 ,[0x6F00]);
this.select();

GPSystem.trace("debut openSecureChannel;");
// Open a secure channel for update
this.securityDomain.openSecureChannel(MACONLY);

GPSystem.trace("before dgi0101");
// Send DGI0101 to card
myStoreData = new ByteBuffer("0101", HEX);
GPSystem.trace("myStoreData = "+myStoreData);
GPSystem.trace("myObject.dgi0101 = "+myObject.dgi0101);
myStoreData.append(myObject.dgi0101.getLV(TLV.EMV));
this.securityDomain.sendApdu(CLASEC, STOREDATA, P1, 0x00,
myStoreData.toByteString());

GPSystem.trace("before dgi0102");
// Send DGI0102 to card
myStoreData.clear();
myStoreData = new ByteBuffer("0102", HEX);
myStoreData.append(myObject.dgi0102.getLV(TLV.EMV));
this.securityDomain.sendApdu(CLASEC, STOREDATA, P1, 0x01,
myStoreData.toByteString());

GPSystem.trace("before dgi0103");
// Send DGI0103 to card
myStoreData.clear();
myStoreData = new ByteBuffer("0103", HEX);
myStoreData.append(myObject.dgi0103.getLV(TLV.EMV));
this.securityDomain.sendApdu(CLASEC, STOREDATA, P1, 0x02,
myStoreData.toByteString());

GPSystem.trace("before dgi8101");
// Send DGI8101 to card
// Translate PIN Block key from transport key to kek
myEncDgi = this.securityDomain.secureChannel.decryptEncryptKek(myKey.transportKeyKey,
Crypto.DES_ECB, myObject.dgi8101,null);
GPSystem.trace("after decyptEncryptKek");
myStoreData.clear();
myStoreData = new ByteBuffer("8101", HEX);
myStoreData.append(myEncDgi.getLV(TLV.EMV));
this.securityDomain.sendApdu(CLASEC, STOREDATA, 0x60, 0x03,
myStoreData.toByteString());

GPSystem.trace("before dgi9101");
myKey.aksKey.setWrapKey(myKey.transportKeyKey);
myKey.wrappedAksKey.setComponent(Key.DES, myObject.dgi9101);
this.securityDomain.secureChannel.unwrapWrapKek(crypto.DES_ECB,
myKey.wrappedAksKey, myKey.unwrappedWrappedAksKey);
myEncDgi = myKey.unwrappedWrappedAksKey.getComponent(Key.DES);
myStoreData.clear();
myStoreData = new ByteBuffer("9101", HEX);
myStoreData.append(myEncDgi.getLV(TLV.EMV));
this.securityDomain.sendApdu(CLASEC, STOREDATA, 0x60, 0x04,
myStoreData.toByteString());

GPSystem.trace("before dgi9102");
// Send DGI9102 to card
myStoreData.clear();
myStoreData = new ByteBuffer("9101", HEX);
myStoreData.append(myObject.dgi9102.getLV(TLV.EMV));
this.securityDomain.sendApdu(CLASEC, STOREDATA, P1, 0x05,
myStoreData.toByteString());

GPSystem.trace("before dgi1102");
// Send DGI1102 to card
myStoreData.clear();
myStoreData = new ByteBuffer("1102", HEX);
myStoreData.append(myObject.dgi1102.getLV(TLV.EMV));

GPSystem.trace("before dgi1101");
// Send DGI1101 to card
// Translate PIN Block key from transport key to kek
myEncDgi = this.securityDomain.secureChannel.decryptEncryptKek(myKey.transportPINKey,
Crypto.DES_ECB, myObject.dgi1101,null);
myStoreData.clear();
myStoreData = new ByteBuffer(0x1101);
myStoreData.append(myEncDgi.getLV(TLV.EMV));
this.securityDomain.sendApdu(CLASEC, STOREDATA, 0x60, 0x07,
myStoreData.toByteString());

GPSystem.trace("before dgi7FFF");
// Send END PERSONALIZATION command to the card
EndPersoTime = GPSystem.dateTimeBytestring();
TerminalID = GPSystem.getSystemID();
myStoreData.clear();
myStoreData.append("09", HEX);
myStoreData.append(EndPersoTime.bytes(0,5));
myStoreData.append(TerminalID.bytes(0,4));
myStoreData.append(myObject.dgi7FFF);
this.securityDomain.sendApdu(CLASEC, ENDPERSO, P1, P2, myStoreData.toByteString());

]]></gp:Script>
</gp:ScriptFragment>
</gp:ApplicationProfile>

PIN Transport Key Profile

<?xml version="1.0" encoding="UTF-8"?>

<gp:KeyProfile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd" UniqueID="2A864886FC6B64030B" ProfileVersion="1.1.0"
ErrataVersion="0">
<gp:Description>![CDATA[CPS demo Transport Key for PIN block]]</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision ProfileID="2A864886FC6B64030B" Version="1.0.0" Date="2002-03-13"
Time="15:54:00" By="GlobalPlatform" Digest="654321"/>
</gp:Revisions>
<gp:KeyInfo Type="SECRET" Size="128" Owner="0011223344" Version="01" SubType="DES"/>
<gp:Attribute/>
<gp:Usage DecryptEncrypt="true" Unwrap="true" Wrap="true"/>
<gp:Value Format="DES" arrayElement="Component" arrayIndex="#">
<gp:Component Encoding="HEX" Value="202122232425262728292A2B2C2D2E2F"/>
</gp:Value>
</gp:KeyProfile>

Transport Key Profile

<?xml version="1.0" encoding="UTF-8"?>

unwrappedWrappedAks Key Profile

<?xml version="1.0" encoding="UTF-8"?>

<gp:KeyProfile UniqueID="2A864886FC6B64030E" ProfileVersion="1.1.0" ErrataVersion="0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd">
<gp:Description>CPS demo Application Key</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision ProfileID="2A864886FC6B64030E" Version="1.0.0" Date="2002-08-26"
Time="10:16:00" By="GlobalPlatform" Digest="654321"/>
</gp:Revisions>
<gp:KeyInfo Type="SECRET" SubType="DES" Size="128" Owner="0011223344" Version="1"
StartDate="2002-01-01" EndDate="2003-01-01"/>
<gp:Attribute/>
<gp:Usage Encrypt="true" Decrypt="true" DecryptEncrypt="true" Sign="true" Verify="true"
Wrap="true" Unwrap="true" UnwrapWrap="true" Derive="true"/>
</gp:KeyProfile>

wrappedAks Key Profile

<?xml version="1.0" encoding="UTF-8"?>

<gp:KeyProfile UniqueID="2A864886FC6B64030D" ProfileVersion="1.1.0" ErrataVersion="0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gp="http://namespaces.globalplatform.org/systems-profiles/1.1.0"
xsi:schemaLocation="http://namespaces.globalplatform.org/systems-profiles/1.1.0
GP.systems.profiles.1.1.0.KeyProfile.xsd">
<gp:Description>CPS demo Application Key</gp:Description>
<gp:Revisions arrayElement="Revision" arrayIndex="#">
<gp:Revision ProfileID="2A864886FC6B64030D" Version="1.0.0" Date="2002-08-26"
Time="10:16:00" By="GlobalPlatform" Digest="654321"/>
</gp:Revisions>

B. TLV Length Coding

The encoding of the length field for TLV and TLVList objects is determined by the encoding
mode as described in the following table.

Encoding Mode Length < 255 Length >= 255

DGI One byte Three bytes with a leading

0xFF
EMV BER length (as defined in BER length (as defined in
ISO/IEC 8825) ISO/IEC 8825)
L16 Two bytes Two bytes

C. Implicit Secure Channel Modification of APDU

Commands
When the secure channel is successfully opened using openSecureChannel() method of the
GPSecurityDomain object, there may be an impact on the methods which send APDUs to the
card. The Card object’s methods are never impacted.
Where the APDU is impacted by the secure channel, and the secure channel is not a GPScp01 or
GPScp02 secure channel, then the scripting language implementation will modify the APDU using
the script provided in the Wrap subelement of the Application Profile.
Table C.1 below outlines the impact for every method which generates an APDU.
APDU Not Impacted by APDU Impacted by Secure
Secure Channel Channel
Application Object Methods
select() yes
sendApdu() yes

GPApplication Object Methods

getData() yes
getStatus() yes
putKey() yes
select() yes
1
sendApdu() yes
setStatus() yes
storeData() yes

GPSecurityDomain Object Methods

deleteAID() yes
getData() yes
/getStatus() yes
installForExtradition() yes
installForInstall() yes
installForInstallAndSelectable() yes
installForLoad() yes
installForPersonalization() yes
load() yes
loadByName() yes
openSecureChannel() yes
putKey() yes
select() yes
1
sendApdu() yes

Card Object Methods

sendApdu() yes

1
Parameters changed as required

BASE24-eps 3.0.25, 2.1.37, and 2.0.45 - Service Pack Release Notes First Quarter 2025
No ratings yet
BASE24-eps 3.0.25, 2.1.37, and 2.0.45 - Service Pack Release Notes First Quarter 2025
159 pages
Jcard Internals PDF
100% (1)
Jcard Internals PDF
27 pages
PAX EMV Kernel API Programming Guide
No ratings yet
PAX EMV Kernel API Programming Guide
66 pages
Graph Database
No ratings yet
Graph Database
64 pages
ATM/POS Transaction Management
100% (1)
ATM/POS Transaction Management
33 pages
Globalplatform Card Uicc Configuration: Member Release
No ratings yet
Globalplatform Card Uicc Configuration: Member Release
50 pages
EMV CPS v1.1
67% (3)
EMV CPS v1.1
104 pages
PosApp Specification v1.0
100% (1)
PosApp Specification v1.0
24 pages
MATM Test Plan Dev
No ratings yet
MATM Test Plan Dev
241 pages
book2-EMV v4.2 Book 2 Security and Key Management CR05 - 20090122094212
100% (1)
book2-EMV v4.2 Book 2 Security and Key Management CR05 - 20090122094212
176 pages
ECHO ISO 8583 Technical Specification V1.6.5
No ratings yet
ECHO ISO 8583 Technical Specification V1.6.5
115 pages
Jcard Internals
No ratings yet
Jcard Internals
28 pages
EMV Reading PAN Code - Apdu
No ratings yet
EMV Reading PAN Code - Apdu
4 pages
EMV v4.3 Book1 ICC To Terminal Interface 2011113003541414
100% (1)
EMV v4.3 Book1 ICC To Terminal Interface 2011113003541414
189 pages
Java ISO 8583 Socket Programming Guide
50% (2)
Java ISO 8583 Socket Programming Guide
7 pages
Public Key Infrastructure - Certification Authority Interface
No ratings yet
Public Key Infrastructure - Certification Authority Interface
44 pages
JavaScript Guide
No ratings yet
JavaScript Guide
100 pages
GP Guidelines For Developing Apps On GP Cards V1.0a
100% (2)
GP Guidelines For Developing Apps On GP Cards V1.0a
65 pages
BASE24 BIC ISO Interface Manual
No ratings yet
BASE24 BIC ISO Interface Manual
250 pages
Network Specifications - Instructions October 2019
No ratings yet
Network Specifications - Instructions October 2019
355 pages
Sarvatra Switch Iso8583 Message Samples
No ratings yet
Sarvatra Switch Iso8583 Message Samples
27 pages
csfb400 Icsf Apg hcr77d1 PDF
No ratings yet
csfb400 Icsf Apg hcr77d1 PDF
1,720 pages
Documentation JPos Server PDF
No ratings yet
Documentation JPos Server PDF
62 pages
ISO 8583 Data Elements Complete
No ratings yet
ISO 8583 Data Elements Complete
5 pages
DDC V3100 ExtensionGuide en
No ratings yet
DDC V3100 ExtensionGuide en
26 pages
Network Specifications - Authorization October 2019
No ratings yet
Network Specifications - Authorization October 2019
348 pages
Terminal Information To Enhance Contactless Application Selection
No ratings yet
Terminal Information To Enhance Contactless Application Selection
10 pages
VSDC Perso 1 0 Mar 2009
No ratings yet
VSDC Perso 1 0 Mar 2009
118 pages
3DS 2.2 FAQs - v1.0 JULY 2019 FINAL
No ratings yet
3DS 2.2 FAQs - v1.0 JULY 2019 FINAL
4 pages
Users Manual 3704697
No ratings yet
Users Manual 3704697
442 pages
EMV 101 May 10 2012
100% (1)
EMV 101 May 10 2012
38 pages
NDCBS
100% (1)
NDCBS
57 pages
H2Hspecs PDF
100% (1)
H2Hspecs PDF
174 pages
Wincor Nixdorf NDC - Extension For EMV
No ratings yet
Wincor Nixdorf NDC - Extension For EMV
58 pages
200-338 - 0.2 Money Controls CcTalk User Manual
0% (2)
200-338 - 0.2 Money Controls CcTalk User Manual
226 pages
EMV PIN Block Formats Guide
No ratings yet
EMV PIN Block Formats Guide
3 pages
Jpos
100% (1)
Jpos
53 pages
Visa Approved Contact-Only Cards 2011
No ratings yet
Visa Approved Contact-Only Cards 2011
27 pages
Agilis 3.0 SP4 EMV Manual 2015
No ratings yet
Agilis 3.0 SP4 EMV Manual 2015
117 pages
Procash/Ndc V1.3/00 Proconsult/Ndc V1.1/00: User Guide
No ratings yet
Procash/Ndc V1.3/00 Proconsult/Ndc V1.1/00: User Guide
50 pages
BASE24 Atm - Transaction - Processing 331 368
No ratings yet
BASE24 Atm - Transaction - Processing 331 368
38 pages
EMV Request Tags
No ratings yet
EMV Request Tags
7 pages
Personalization Data Specifications: For Debit and Credit On Chip
100% (1)
Personalization Data Specifications: For Debit and Credit On Chip
71 pages
BASE24-eps 2023-03-30 - Standard POS Device Message Specifications
100% (2)
BASE24-eps 2023-03-30 - Standard POS Device Message Specifications
253 pages
R4 Discover D-PASU.S.terminalGuide2017
No ratings yet
R4 Discover D-PASU.S.terminalGuide2017
40 pages
HSM I&O Manual 1270A513-3 PDF
No ratings yet
HSM I&O Manual 1270A513-3 PDF
202 pages
V23. Visa Global Platform 2.1.1 - Card Production Guide
No ratings yet
V23. Visa Global Platform 2.1.1 - Card Production Guide
77 pages
EMV Overview Tecnica
No ratings yet
EMV Overview Tecnica
14 pages
DCI Contactless D-PAS Acquirer Host Test Plan v1.2
100% (1)
DCI Contactless D-PAS Acquirer Host Test Plan v1.2
88 pages
NDC Emv 300pdf
No ratings yet
NDC Emv 300pdf
560 pages
Dynamic Currency Conversion Explained ? 1666789070
No ratings yet
Dynamic Currency Conversion Explained ? 1666789070
1 page
Mpos Development Guidelines
100% (1)
Mpos Development Guidelines
10 pages
Tag Definition EMV
100% (1)
Tag Definition EMV
2 pages
MC - Member ICC Testing Procedures
100% (1)
MC - Member ICC Testing Procedures
161 pages
Us Visa Contactless Transit Terminal Testing v2
No ratings yet
Us Visa Contactless Transit Terminal Testing v2
5 pages
EMV - Understanding
No ratings yet
EMV - Understanding
3 pages
Opacity Secure Channel: Globalplatform Card - Amendment G
No ratings yet
Opacity Secure Channel: Globalplatform Card - Amendment G
50 pages
JavaScript: A Web Developer's Guide
No ratings yet
JavaScript: A Web Developer's Guide
8 pages
Financial Fusion - Trade Force For SWIFT - Version 5
No ratings yet
Financial Fusion - Trade Force For SWIFT - Version 5
90 pages
GP Messaging Specification v1.0 (031014)
No ratings yet
GP Messaging Specification v1.0 (031014)
113 pages
GP - Mapping of 2.1.1 Implementations To 2.2
0% (1)
GP - Mapping of 2.1.1 Implementations To 2.2
89 pages
02 Loop
No ratings yet
02 Loop
5 pages
Logins
100% (1)
Logins
2 pages
Sample Paper 12 IP
No ratings yet
Sample Paper 12 IP
10 pages
Ontario Curriculum Coding Innovation
No ratings yet
Ontario Curriculum Coding Innovation
7 pages
Java Roadmap 2024
No ratings yet
Java Roadmap 2024
1 page
CTG Articles Generics
100% (2)
CTG Articles Generics
51 pages
Interactive Reports
No ratings yet
Interactive Reports
13 pages
Fall 2024 - CS401 - 1
No ratings yet
Fall 2024 - CS401 - 1
2 pages
Java Isce Class 10 Short Question
No ratings yet
Java Isce Class 10 Short Question
24 pages
Examination Papers, 2004: (All India)
No ratings yet
Examination Papers, 2004: (All India)
13 pages
Compiler Design: Three Address Code
No ratings yet
Compiler Design: Three Address Code
11 pages
Lecture Week 11 Model-View-Controller
No ratings yet
Lecture Week 11 Model-View-Controller
17 pages
Digital System Design-Module07-Behavioral Modeling (Cont'd)
No ratings yet
Digital System Design-Module07-Behavioral Modeling (Cont'd)
40 pages
Quick Sort
No ratings yet
Quick Sort
15 pages
Spring Hibernate Integration Guide
No ratings yet
Spring Hibernate Integration Guide
11 pages
HMI Software For CNC Controls
No ratings yet
HMI Software For CNC Controls
76 pages
Purple and White Clean and Professional Resume
No ratings yet
Purple and White Clean and Professional Resume
2 pages
Programs
No ratings yet
Programs
7 pages
Manikanta Kumar Resume
No ratings yet
Manikanta Kumar Resume
2 pages
DSP Exp 4
No ratings yet
DSP Exp 4
4 pages
Data Structures
No ratings yet
Data Structures
7 pages
OpenGL: Setup GLFW & GLEW in VC++ Express
No ratings yet
OpenGL: Setup GLFW & GLEW in VC++ Express
18 pages
Logunfile
No ratings yet
Logunfile
54 pages
Creating and Managing Tables
No ratings yet
Creating and Managing Tables
20 pages
Java RandomAccessFile Guide
No ratings yet
Java RandomAccessFile Guide
2 pages
Computer GuessPaper 2025
No ratings yet
Computer GuessPaper 2025
8 pages
C: A Verification Framework For Concurrent Imperative Programs
No ratings yet
C: A Verification Framework For Concurrent Imperative Programs
13 pages
Notes Unit 4
No ratings yet
Notes Unit 4
10 pages
MPV Manual
No ratings yet
MPV Manual
277 pages