9 SUCI API

(U)SIM API for Java™ Card(U)SIM Application Programming Interface (API)31.1303GPPRelease 17TS

The SUCI API consists of the package uicc.usim.suci. This package defines services to allow an Applet to perform a SUCI computation upon reception of terminal request.

If an applet has registered an object implementing the interface SUCICalculator to the USIM application, then when the ME sends a GET IDENTITY APDU Command in SUCI context to this USIM application, the (U)SAT framework shall invoke the getSUCI method in order to retrieve the SUCI to be returned to the ME. Only one object can be registered per USIM application. The reference to the object is needed to dereference the object. If no object is registered, the USIM shall return the SUCI computed by its own means, according to the USIM configuration.

If an exception is raised, the (U)SAT framework behaviour is implementation specific.

Annex A (normative):
Java Card™ (U)SIM API

The attached files "31130_Annex_A_Java.zip", and "31130_Annex_A_HTML.zip" contains source files and html documentation for the Java Card™ (U)SIM API.

Annex B (normative):
Java Card™ (U)SIM API identifiers

The attached file "31130_Annex_B_Export_files.zip" contains the export files for the uicc.usim.* package.

Annex C (normative):
(U)SIM API package version management

The following table describes the relationship between each TS 31.130 specification version and its packages AID and Major, Minor versions defined in the export files.

uicc.usim.access package

TS 31.130

Major, Minor

AID

1.0

A000000087 1005 FFFF FFFF 89 13 100000

7.7.1

1.1

8.3.0

1.2

9.1.0

1.3

12.0.0

1.4

17.0.0

1.5

17.1.0

1.6

uicc.usim.toolkit package

TS 31.130

Major, Minor

AID

1.0

A000000087 1005 FFFF FFFF 89 13 200000

7.1.0

1.1

7.2.1

1.2

7.7.1

1.3

7.9.0

1.4

8.3.0

1.5

9.1.0

1.6

9.4.0

1.7

10.4.0

1.8

14.2.0

1.9

17.0.0

1.10

17.1.0

1.11

uicc.usim. geolocation package

TS 31.130

Major, Minor

AID

1.0

A000000087 1005 FFFF FFFF 89 13 300000

13.1.0

2.0

uicc.usim.suci package

TS 31.130

Major, Minor

AID

15.1.0

1.0

A000000087 1005 FFFF FFFF 89 13 400000

The package AID coding is defined in ETSI TS 101 220 [1]. The (U)SIM API packages’ AID are not modified by changes to Major or Minor Version.

The Major Version shall be incremented if a change to the specification introduces byte code incompatibility with the previous version.

The Minor Version shall be incremented if a change to the specification does not introduce byte code incompatibility with the previous version.

For a table describing the versioning of a package, a line is introduced only upon changes of Major or Minor version of its package.

The package uicc.usim.access contains only constants, therefore it may not be loaded on the UICC.

Annex D (normative):
USIM API jar files

The attached files "31130_Annex_D.jar", contains class files for the Java Card™ (U)SIM API.

Annex E (informative):
Change History

Change history

Date

Meeting

TDoc

CR

Rev

Cat

Subject/Comment

New version

TP-27

Generation of Version 7.0.0 based on version 6.2.0

7.0.0

TP-27

TP-050023

009

Allow passing of specified status words through the (U)SAT Framework

7.0.0

CT-28

CP-050139

011

Allign paragraph numbering between TS 31.130 and ETSI TS 102 241

7.1.0

CT-28

CP-050139

013

Delete version and author info from the Java source code

7.1.0

CT-28

CP-050141

014

Addition of new events EVENT_FORMATTED_USSD and EVENT_UNFORMATTED_USSD

7.1.0

CT-29

CP-050340

016

Adding missing constant values

7.2.0

2005-11: Adds missing attachment files and adds line to table in annex C.

7.2.1

CT-33

CP-060391

019

1

Correction of misnamed constant

7.3.0

020

1

Addition of missing event download I-WLAN access status

CT-34

CP-060546

0022

2

Clarification on getShortMessageLength() method when applied on a SMS Cell Broadcast.

7.4.0

CP-050548

0024

1

Correction of the USATEnvelopeHandlerSystem method prototype

CT-35

CP-070068

0027

1

Correction of Annex A JAVA.zip, package uicc.usim.toolkit

7.5.0

0028

2

Update the reference to Java Card 2.2.2

CT-36

CP-070302

0029

–

Correction of the reference to ETSI TS 102 241

7.6.0

CP-070298

0029

–

Correction of references to ETSI TS 102 223 and ETSI TS 102 221

CT-38

CP-070844

0032

1

Introduction of new constant values for files in the USIM application

7.7.0

Annex A and B attachments provided (2008-08)

7.7.1

CT-42

CP-080908

0034

2

Introduction of a geographical location discovery Java Card™ API

8.0.0

CT-43

CP-090196

0035

1

Introduction of missing constant values for USIM files

8.1.0

CT-45

CP-090719

0039

2

Alignment of constants with 31.111

8.2.0

CT-46

CP-090788

0040

1

References update

8.3.0

CT-46

CP-091013

0042

1

Support of missing event EVENT_EVENT_DOWNLOAD_NETWORK_REJECTION

8.3.0

CT-46

CP-091013

0045

1

Support of missing constants in USAT Terminal Profile

8.3.0

CT-46

–

–

–

Upgrade of the specification to Rel-9

9.0.0

CT-47

CP-100185

0047

1

Addition of missing constant values

9.1.0

CT-47

CP-100198

0048

2

Supporting operator controlled CSG list for H(e)NB

9.1.0

CT-47

CP-100198

0049

2

Support of CSG cell discovery and CSG selection event

9.1.0

——–

Spec reissued as v9.1.1 due to a bad version number on the cover sheet

9.1.1

CT-50

CP-100836

0046

1

Update reference to "Java Card 3.0.1 Classic" reference

9.2.0

SP-51

–

–

–

Upgrade of the specification to Rel-10

10.0.0

CT-52

CP-110507

0050

1

Addition of events and reservation of constant values for Java API

10.1.0

CT-54

CP-110905

0053

–

Correction to TAG_CSG_SELECTION_STATUS

10.2.0

CT-54

CP-110905

0054

–

Correction to constant value in TerminalProfile.java

10.2.0

CT-55

CP-120154

0059

Correction to TAG_CSG_SELECTION_STATUS

10.3.0

CT-55

CP-120154

0060

Correction to constant value in TerminalProfile.java

10.3.0

CT-55

CP-120154

0058

1

Update the reference to ETSI TS 102 241

10.3.0

——–

Editorial version correcting the three lines above

10.3.1

CT-56

CP-120393

0061

1

Correct implementation of CR 0059 for TAG_CSG_SELECTION_STATUS_N

10.4.0

CT-56

CP-120392

0062

1

Adding a constant value in USATTerminalProfile.java for the indication of IMS support

10.4.0

CT-56

CP-120393

0063

1

Adding constant values in USIMConstants.java for missing file identifiers

10.4.0

SP-57

Automatic upgrade to Rel-11

11.0.0

SP-65

Automatic upgrade to Rel-12

12.0.0

CT-70

CP-150827

0071

Missing rule for SMS_PP envelope response handling

13.0.0

CT-73

CP-160550

0072

5

Geo Location API corrections

Note 1: known problem within the change request, to be fixed at CT-74

Note 2: in the CR, the body of the CR and the attached annexes are not identical. The body of the CR contains the correct text and is implemented.

13.1.0

CT-74

CP-160788

0073

1

Geo Location API format alignment

13.2.0

CT-75

CP-170166

0075

Geolocalization API document aligment

13.3.0

SA-75

Automatic upgrade to Rel-14

14.0.0

CT-78

CP-173150

0077

–

Update of reference to ETSI TS 102 241

14.1.0

CT-78

CP-173150

0078

–

Editorial change of Java Card reference

14.1.0

CT-78

CP-173143

0076

3

Corrections in Annex C

15.0.0

Added missing attachments

15.0.1

2019-03

CT#83

TP-050023

0081

1

F

SUCI Package

15.1.0

2019-09

CT#85

CP-192013

0085

1

F

Add support for ENVELOPE (EVENT DOWNLOAD – Data Connection Status Change)

15.2.0

2019-09

CT#85

CP-192014

0083

1

F

Update of reference to ETSI TS 102 241

15.2.0

2019-09

CT#85

CP-192014

0084

–

F

Clarification for SUCI API

15.2.0

2020-01

5G logo updated in a cover page as agreed in CT#86

15.2.1

2020-02

Attachments updated

15.2.2

2020-06

CT#88e

CP-201148

0086

3

F

Update the scope of 31.130 to cover 4/5G aspects

15.3.0

2020-07

–

–

–

–

–

Update to Rel-16 version (MCC)

16.0.0

2022-03

CT#95e

CP-220135

0089

1

B

Aligment with TS 31.111 and TS 31.102 (Rel-17)

17.0.0

2022-12

CT#98e

CP-223084

0091

2

F

Toolkit Event CAG Selection support (EVENT_EVENT_DOWNLOAD_CAG_CELL_SELECTION)

17.1.0