Skip to content

Architecture

Antonín Dufka edited this page Jul 18, 2023 · 1 revision

Architecture of JCMathLib library

JCMathLib's architecture can be divided into four components: BigNat and ECPoint arithmetic, configurations and definitions, resource management, tests and tooling.

BigNat and ECPoint arithmetic

BigNat arithmetic is implemented in files BigNat.java and BigNatInternal.java. The internal class implements functionality that depends on the underlying BigNat representation (currently byte array, but can be changed to short array for smartcards that support 32-bit int types), typically operations like addition, negation, multiplication, and remainder division, that are not accelerated by the JavaCard API algorithms. The BigNat class extends this internal class and implements higher-level operations that typically utilize accelerators like modular exponentiation, modular inversion, and modular square root.

Elliptic curve arithmetic (over non-binary finite fields) is implemented in ECPoint.java file that uses an elliptic curve structure implemented in ECCurve.java file. The curve definition needs to be instantiated using curve parameters. For convenience, definitions of parameters of commonly used curves are provided in curves/ directory.

JCMathLib additionally provides class Integer, which is a wrapper over BigNat class that provides signed integers.

Configurations and definitions

JCMathLib is designed in a flexible way that allows for supporting various smartcards and can be adapted to the sets of algorithms they support. This is achieved by an implementation that branches depending on a given smartcard configuration that is set using the OperationSupport class. The configuration can be easily adjusted for any card, but it also provides definitions for tested cards.

Parameters of commonly used elliptic curves are provided in curves/ directory.

Return codes that can be thrown from within the library code are defined in ReturnCodes.java file.

Resource management

JCMathLib also implements tools for efficient resource management that lower memory requirements by secure reusing of allocated objects. The main part of this implementation is done in ResourceManager.java file, which is used by all JCMathLib objects that require memory allocation. ResourceManager internaly uses ObjectAllocator, which defines where different internal objects should be allocated. This can be used to set different tradeoffs between RAM and EEPROM allocations, depending on resources available on different smartcards.

Secure handling of shared objects is achieved using ObjectLocker class, which can be used to lock access to a shared object. If then for example some method tries to lock already locked object, it throws an exception. ObjectLocker is mainly used during development and it can be removed for library usage.

Tests and tooling

Applet implemented in UnitTests.java provides an interface for unit testing of the JCMathLib library on smartcards.

Example usage of the library is demonstrated in the Example.java applet.

A Python tool implemented in package.py file can be used for easy packaging of JCMathLib that allows simple integration with user applets.