# eSIM Applet based on JavaCard

This is an eSIM Applet project based on Javacard. This applet provides basic SIM file 
structure, SIM authentication, and customized 
APDU handling functions. 

You can use Gradle build system to build the eSIM applet.
It also enables you to test the applet with [JCardSim] or on the physical cards.

## Feature List
 - Support read/write standardized/customized SIM structures
 - Support milenage algorithm for SIM authentication

## Usage 
### Javacard reader
The reader is needed for [eSIM-Applet] and [eSIM-Loader] to let you install the 
eSIM applet on the Jcard and load profiles into it.
![reader](./docs/reader.jpeg)
### Overall steps
 - Clone this repository
 - Build the eSIM applet cap file with gradle (using JDK8)
 - Install the cap file to your Java Card smart card with [GlobalPlatformPro]
 - Use the [eSIM-Loader] to load the profile

### Building cap

- Run the `buildJavaCard` task to build the cap file:

```
./gradlew buildJavaCard  --info --rerun-tasks
```
The generated cap file is at `./applet/build/javacard/esim.cap`

Note: `--rerun-tasks` is to force re-run the task even though the cached input/output seems to be up to date.

- You can change applet configurations in the `./applet/build.gradle` including the Javacard SDK version, AID, export name and so on. 
When compiling the cap file for different Javacards, the SDK version `jckit` may need to change to the corresponding version supported by the card.

```
javacard {
    config {
        jckit '../libs-sdks/jc222_kit' // Javacard SDK version, default version is Jcard 2.2.2
            cap {
                packageName 'applet'
                version '0.1'
                aid '01:02:03:04:05:06:07:08:09' // Default package AID is 010203040506070809
                output 'esim.cap' // Name of the cap file
                applet {
                    className 'applet.MainApplet'
                    aid '01:02:03:04:05:06:07:08:09:01:02' // Default applet AID is 0102030405060708090102
                }
            ...
        }
    }
    ...
}
```


### Running tests

```
./gradlew test --info --rerun-tasks
```
Or directly run the test function in the AppletTest.java using IntelliJ IDEA or Android Studio

Output:

```
Running test: Test method hello(AppletTest)

Gradle suite > Gradle test > AppletTest.hello STANDARD_OUT
    Connecting to card... Done.
    --> [00C00000080000000000000000] 13
    <-- 51373E8B6FDEC284DB569204CA13D2CAA23BD1D85DCAB02A0E3D50461E73F1BB 9000 (32)
    ResponseAPDU: 34 bytes, SW=9000
```

### Install CAP file
Using [GlobalPlatformPro] to install the cap file on your Javacard. 
You can run 
```
./config.sh
```
to download the GlobalPlatform .exe and .jar to folder `GlobalPlatformPro`  
Note: We use the Release v20.01.23 and the latest release may cause unknown issues.

Install the cap file (Linux or MacOS):
```
java -jar ./GlobalPlatformPro/gp.jar --install ./esim.cap --default
```
Install the cap file (Windows):
```
./GlobalPlatformPro/gp.exe --install ./esim.cap --default
```
Note: When you want to reinstall the applet, please delete the old one on the card first by the 
package AID (default package AID is 010203040506070809)
```
java -jar ./GlobalPlatformPro/gp.jar -f --delete 010203040506070809
```
For Windows:
```
./GlobalPlatformPro/gp.exe -f --delete 010203040506070809
```



## Dependencies

This project compiling is based on:

- https://github.com/ph4r05/javacard-gradle-template

For more options about compiling you can check [javacard-gradle-template].


[JCardSim]: https://jcardsim.org/
[javacard-gradle-template]: https://github.com/ph4r05/javacard-gradle-template
[GlobalPlatformPro]: https://github.com/martinpaljak/GlobalPlatformPro