Repository files navigation

JCMathLib is an open-source library for the JavaCard platform that aims to enable low-level cryptographic computationsunavailable in the standard JavaCard API. In particular, it focuses on providing efficient modular arithmetic andelliptic curve operations.

If you want to get into the technical details of JCMathLib, you can find them in thispaper:https://arxiv.org/abs/1810.01662.

When citing our work, please use the following reference:

@inproceedings{mavroudis2020jcmathlib,  title={JCMathLib: wrapper cryptographic library for transparent and certifiable JavaCard applets},  author={Mavroudis, Vasilios and Svenda, Petr},  booktitle={2020 IEEE European Symposium on Security and Privacy Workshops (EuroS\&PW)},  pages={89--96},  year={2020},  organization={IEEE}}

• Features and Limitations
• Getting Started
• Integration With Your Applet
• Community

JCMathLib includes the following features:

• BigNat arithmetic including modular operations
• Elliptic curve point addition and multiplication
• Option to accelerate computation by utilizingint native type on smartcards that support it (branchints)
• No dependencies on proprietary interfaces (only public JavaCard API)
• Selection of appropriate algorithm implementation based on the card's algorithm support (OperationSupport)
• Resource management (ObjectAllocator,ObjectLocker)
• Predefined common elliptic curves (SecP256r1,SecP256k1,SecP512r1)
• Tool for packaging JCMathLib into a single file for easy integration

Although higher-level cryptographic primitives and protocols can be constructed using JCMathLib, they are not includedin the library. In case you need a higher-level implementation, you may try looking for projects building on topof JCMathLib (e.g., seeour users).

As JCMathLib is implemented for the JavaCard Platform and relies only on public JavaCard API, it is not as efficientas a native implementation could be. This approach has a number of advantages, like easy portability and the possibilityto open-source code. However, it makes it much harder (if not impossible) to perform the operations in constant time,and we do not aim to. The library is thus vulnerable to timing side-channel attacks andis NOT suited for productionuse.

Clone this repository:

git clone --recurse-submodules https://github.com/OpenCryptoProject/JCMathLib.git

For compilation for JavaCards, you need to obtain JavaCard SDKs, which are included as submodule. If you did not use--recurse-submodules in the previous command and your libs-sdks folder is empty, run:

git submodule update --init --recursive

Before using JCMathLib in your projects, you should test that it works properly on your smartcard. For that, you may want to run UnitTests. If you plan to work only with a simulator, you can skip to the last step ofthe following section.

1. Set your card type in theJCMathLib/applet/src/main/java/opencrypto/jcmathlib/UnitTests class. The supported options are listed in classOperationSupport.{SIMULATOR, JCOP21, JCOP3_P60, JCOP4_P71, GD60, GD70, SECORA}.

publicclassUnitTestsextendsApplet {publicfinalstaticshortCARD_TYPE =OperationSupport.SIMULATOR;// TODO set your card here

2. OPTIONAL (depending on card selected in step 1). Change the JavaCard API version inapplet/build.gradle file if you wish to run the code on cards with a JavaCard API version different from 3.0.5.

// JC310b43 supports building also for lower versions (cap.targetsdk).// If another SDK is selected, please comment the cap.targetsdk setting.final def JC_SELECTED = JC310b43 <----...// JC310b43 supports compilation targeting for lower API versions.// Here you can specify path to the SDK you want to use.// Only JC304 and higher are supported for targeting.// If JC310b43 is not used, targetsdk cannot be set.targetsdk JC305  <----

If you would like to build for lower versions, comment out line withtargetsdk JC305 and setfinal def JC_SELECTED = JC310b43 to other value likefinal def JC_SELECTED = JC222.

The list of settings is summarized here:

3. Build the applet by running the following command.

./gradlew buildJavaCard

4. If the build completes successfully, you may install it on a card by running the following command. In case youencounter some issues, you may want to try usingGlobalPlatformProdirectly and install the built cap fileapplet/build/javacard/unit_tests.cap.

./gradlew installJavaCard

If the installation completes successfully, you can run the tests. If theUnitTests contain your card type, thefollowing command will try to run the tests with a connected card. Otherwise, it will run the tests just in a simulator.

./gradlew --rerun-tasks test

If you have multiple readers connected to your device, you may need to adjust the readerindex (runCfg.setTargetReaderIndex inJCMathLib/applet/src/test/java/tests/BaseTest).

For an example usage of the library, see theExample applet.

To enable easy integration of JCMathLib with your applet, we provide a Python script that bundles JCMathLib into asingle.java that can be included in your code.

The script provides the following interface, allowing to specify which parts of JCMathLib to include (to save memory).

$ python package.py -husage: package.py [-h] [-d DIR] [-k] [-c {SecP256k1,SecP256r1,SecP512r1} [{SecP256k1,SecP256r1,SecP512r1} ...]] [-p PACKAGE] [-o OUTPUT]Package the JCMathLib library into a single file.options:  -h, --help            show this help message and exit  -d DIR, --dir DIR     Directory to package  -k, --keep-locks      Keep locks  -c {SecP256k1,SecP256r1,SecP512r1,Wei25519} [{SecP256k1,SecP256r1,SecP512r1,Wei25519} ...], --curves {SecP256k1,SecP256r1,SecP512r1,Wei25519} [{SecP256k1,SecP256r1,SecP512r1,Wei25519} ...]                        Curves to include  -p PACKAGE, --package PACKAGE                        Package name  -o OUTPUT, --output OUTPUT                        Output file

For example, to bundle JCMathLib for your applettest in which you use curveSecP256r1, use the following. Theoutput will be stored injcmathlib.java file.

$ python package.py -p test -c SecP256r1 -o jcmathlib.java

JCMathLib is kindly supported by:

We welcome all contributions, but we especially appreciate contributions in the following form:

• Code improvements. If you discover a bug or have an idea for improving the code, please, submit the change in aPull Request.
• Features. If you wish certain feature was included in JCMathLib, let us know viaIssues or implement it yourself and submit aPull Request.
• Testing on cards. If you have a smart card model that is not yet included in JCMathLib and you manage to get it working, please, create a pull request with the correspondingOperationSupport configuration and include information about the smart card. Also consider submitting your card results toJCAlgTest.

• Myst: Secure Multiparty Key Generation, Signature and Decryption JavaCard applet and host application
• BioID: a Privacy-Friendly Identity Document
• JCEd25519: a JavaCard implementation of Ed25519 signing

(If you can't find yourself here, please let us know viaIssues)