Introduction

Samsung R&D Institute Ukraine team has published OpenSCP-Java [1] and OpenSCP-Python [2]. This is implementation of Secure Element [3] (SE) SCP03 v1.2 and SCP11 v1.4 protocols by Global Platform [4] used for secure communication between a host (e.g., payment terminal) and a Secure Element (SIM, eSE, etc.). While the previous post targeted Samsung partners, this post is mostly for OpenSource contributors.

OpenSCP-Java and OpenSCP-Python are published under Apache 2.0 license, which allows royalty-free re-use and modification. This article provides some technical insights on implementation internals for those willing to use, customize or extend OpenSCP functionality.

Motivation

The reasons to develop OpenSCP-Java and OpenSCP-Python were the following:
    •   Testing and integration difficulties caused by the lack of SCP implementation available for Samsung Partners dealing with Secure Element
    •   Licensing - existing alternatives are under LGPL-3.0
    •   Lack of support of the latest SCP specification features
    •   Lack of standalone implementation (available alternatives are supplied as parts of SE tools and cannot be easily extracted for re-use)

You can find the list of alternative open-source solutions, their characteristics, and reject reasons in the Annex. As a result, we implemented libraries, that support the latest SCP protocols versions, have permissive licensing, and can be easily integrated into any client's business logic.

Solution Overview

GlobalPlatform Secure Channel Protocol [5] has several profiles. OpenSCP-Java and OpenSCP-Python support SCP03 v1.2 and SCP11 v1.4:
    •   SCP03 establishes authenticated, confidentiality- and integrity-protected secure channel between a host (off-card entity) and a secure element (card, SE, or TPM-like device) based on pre-shared symmetric keys
    •   SCP11 provides similar secure channeling using asymmetric crypto (ECC, typically NIST P-256) for authentication and key agreement

The OpenSCP-Java library contains the implementation in Java. OpenSCP-Python is a wrapper around the OpenSCP-Java that provides the same set of features in Python. yubikit-android [6] code was re-used as a base for our Java library. Then, JPype [7] was applied to implement Python wrappers around the Java library.

yubikit-android is an Android Java library for YubiKey tokens integration. It suited our purpose well, because of:
    •   Apache-2.0 license
    •   Modular structure, that allows to extract SCP-related code easily
    •   Rich support of the previous versions of both SCP03 and SCP11 protocols
Still, it has a limitation: it is designed for YubiKey devices, so SCP logic is mixed with hardware-specific logic.

JPype is a Python-to-Java bridge. It works at native level and allows Python objects to interact with Java objects efficiently. JPype was selected after thorough analysis of other alternatives such as Py4J [8], Jython [9], JEP [10], and Pyjnius [11]. The detailed comparison is available in JPype's "Alternatives" [12] documentation section.

OpenSCP-Java

Figure 1. OpenSCP-Java high-level design

The main parts are:
    •   SCP03 and SCP11 session layer protocols ("SCP session" component)
    •   SCP03 and SCP11 transport layer protocols ("Transport" component), that expose an interface to communicate with the SE

Client application ("eSE management app" package) implements transport interface ("Transport layer" component) and uses library's session layer API to establish the SCP communication ("Applet / SD manager" component). The device side ("Device" node) is represented by high-level entities like JavaCard OS on the SE chip. It is out of scope of OpenSCP-Java library implementation. This high-level design diagram and other OpenSCP-Java library documentation can also be found at GitHub [13].

The SCP session layer implementation is fixed and strictly follows Global Platform Secure Channel Protocol specification. The SCP transport layer has special design to address the following obstacle. Similar solutions provide both SCP implementation and some connectors for a specific physical transport (NFC, USB, SPI, I2C, etc.) at the host side. This approach has an advantage of giving ready-for-use tool if a physical protocol (e.g. NFC) suites well and the corresponding host hardware (like USB-connected NFC reader) is available. But issue comes up when any HW changes are required (e.g. SPI instead of NFC) or the hardware vendor / connection type does not match (e.g., a proprietary protocol is applied instead of PS/SC). All existing open-source solutions, that we examined, either have a highly coupled implementation (where SCP logic is mixed with transport or hardware specifics), or are incomplete. To mitigate this issue, we decided to decouple fixed specification-based SCP implementation from transport layer implementation, that can be flexibly customized.

OpenSCP-Python

Figure 2. OpenSCP-Python high-level design

The OpenSCP-Python serves as a thin wrapper around OpenSCP-Java. Its public API mirrors the respective API of OpenSCP-Java. The way of using it is similar to OpenSCP-Java case: the client provides a custom transport layer (implements abstract class of "Transport" component on the diagram) using the available physical interface to the SE ("Transport layer" component). Then it uses "Applet / SD manager" component to reach the SE chip on the device ("Device" node). The documentation of OpenSCP-Python design can be found in the GitHub project repository [14].

We had choice either to implement OpenSCP-Python as a wrapper around Java code, or to create a self-standing Python implementation. Wrapper option was chosen because of better maintainability of one code base instead of supporting two. Having a single carefully designed and well-tested implementation surrounded by thin wrappers proved to be reliable and flexible approach.

Pitfalls

This section describes challenges and nuances that we faced during OpenSCP implementation. This information will be useful for open-source contributors for proper usage, customization and integration of our libraries.

1. SCP test vectors are hard to find
Testing communication protocol requires pre-defined test messages to be sent from one actor (SE) to another actor (host PC). The issue is that the GlobalPlatform does not provide test vectors for SCP protocols. Test vectors in other sources that we found were either incomplete or hard to re-use. So, our way to get test vectors for SCP03 was to extract them from the logs produced by GPShell [15] tool during communication with SE for the base scenario (SCP03, AES-128 keys, S8 mode). Then, we manually re-calculated test vectors for other SCP03 modes (S8, S16) and other key sizes (AES-128, AES-192, AES-256). In case of SCP11 we had no SCP tool like GPShell. So, we had to manually calculate SCP11 test vectors for various Elliptic Curves (EC) and BrainPool curves. Results of our efforts can be re-used from the OpenSCP-Java project tests [16].

2. GlobalPlatform certificates issue
The SCP11 protocol supports two formats of PKI certificates: widely-used X.509 and rarely-used GlobalPlatform proprietary format. We had difficulties with PKI certificates in GlobalPlatform format: no reference implementation and no official test vectors were found at GlobalPlatform. We had to address this issue and now our reference implementation [17] and the corresponding test vectors [18] can be found in OpenSCP-Java repository.

3. Java security providers
Not all Java security providers support all algorithms required for SCP. For example, the default Android security provider does not support AES-CMAC algorithm and BrainPool elliptic curves. Solution is to use proper security providers, such as the one provided by BouncyCastle.

4. SCP corner cases
Some Command APDUs, like INITIALIZE_UPDATE and PUT_KEY commands, require explicit setting of the 0x00 Le. If this is not done, then MAC calculation becomes broken. Another issue is zero payload of Command APDUs that should not be encrypted. Otherwise, encryption session becomes broken.

5. JPype usage nuances
Firstly, Python bytes and Java's byte[] are totally different types, even though their behavior is similar. Explicit conversion is required to avoid exceptions with vague reasons. Secondly, JVM cannot be shutdown and cannot be started twice. So, the code should track the JVM state and start it only once at the Python code launch. Thirdly, Python typing for static typing tool myPy does not work for Java types. This decreases type checking efficiency in Python projects that use JPype.

Contribution is welcome

We invite partner companies, researchers, and independent developers to integrate OpenSCP-Java and OpenSCP-Python into their solutions. We are honest about the known issues and trade-offs, and are open for the discussion and improvements. At GitHub you can find OpenSCP-Java and OpenSCP-Python roadmaps that describe planned features to be implemented and improvements to be made. Finally, we encourage interested contributors to add implementation for the new SCP specification updates, to report and patch bugs. This way together we will build up-to-date, high-quality solution that fits business needs.

Annex

Table 1. Open-source SCP03 and SCP11 solutions