Skip to content

Latest commit

 

History

History
229 lines (161 loc) · 23.5 KB

README.md

File metadata and controls

229 lines (161 loc) · 23.5 KB

TSM-REST-API

Last updated: 07.07.2023

The module tsm-rest-api is an OpenApi realization of the TSM-Backend REST-API specified in section 4.1 of BSI-TR-03165. It is a submodule of GitHub-BSI-TSMS.

Swagger-ui documentation of latest TSM-REST-API: tsm-rest-api.yaml

Content:

  1. Motivation
  2. Project Results
  3. Documentation
    1. Project Structure
      1. pdf2yaml
      2. yaml2json
      3. json2swaggerui
      4. yaml2javaclient
    2. Code Generation
    3. Setup Development Environment
    4. Build the Project
    5. Use Cases
    6. Data Types
    7. API methods

1. Motivation

The provisioning of secure components usually relies on a Trusted Service Manager (TSM) which provides the necessary server structure for provisioning and holds the organisatoric and cryptographic access rights to the relevant parts of the secure component (not necessarily to the ISD). From a technical point of view, the TSM is an independent component in the TSMS, i.e. not directly connected to applications on the smartphone. To trigger actions like the provisioning or removal of applets, applications on the handset need to communicate to a backend system of the TSM. A prerequisite of this is that the applet in question has been made available to the TSM, including all relevant configuration information.

Uploading JavaCard applets to a TSM-Backend and the configuration of Services via a dedicated API is step two in the usage path of BSI-TR-03165.

TSMS

2. Project Results

The main result of this project is an OpenApi tsm-rest-api.yaml file which specifies the REST-API to configure the TSM-Backend. Beside this, the projects provides scripts to generate additional supporting documents like documentation and transcripts of the API to other formats like JSON and Java.

Latest official version: 1.0.4

The version numbering matches the versions of the BSI-TR-03165, i.e. TR-03165 in version a.b equates to tsm-rest-api-a.b.x. The last digit x is reserved for bugfixes applied on this project itself.

Resulting build artifacts are:

3. Documentation

3.1 Project Structure

This project is separated into the following subfolders:

Folder Description
dist/ Contains resulting build artifacts of this project in several versions.
docs/ Contains a markdown documentation of the java-client for the TSM-Backend REST-API. All files in this folder are generated from the tsm-rest-api.
generate-code/ Contains Maven submodules with several subprojects to generate yaml, json, java and md files related to the TSM-Backend REST-API.
generated-code/ Contains resulting files when executing the code generation scripts.

3.2 Code Generation

This module generates definition files for an interface to access a TSM-Backend via a REST-API from the interface definition provided in the BSI-TR-03165.

This project contains the following Maven submodules to generate files:

# Submodule Code Generation Description
1. pdf2yaml pdf -> txt -> yaml Generates an OpenApi yaml file from TR input.
2. yaml2json yaml -> json Converts the OpenApi yaml file to an OpenApi json file.
3. json2swaggerui json -> html/js -> zip Generates a Swagger-UI html/javascript documentation from the OpenApi json file.
4. yaml2javaclient yaml -> java -> jar Generates java classes from the OpenApi yaml file and compiles it to a jar.

TSM REST-API

Attention: Detailed documentation about each submodule can be found in the README of particular submodule.

3.3 Setup Development Environment

Perform the following steps to set up a development environment to execute the code generators.

  1. Install the following software

    Package Package Name Compatible Versions Download Link
    JDK Java Development Kit >= 1.8 https://openjdk.java.net/install/
    Maven Apache Maven >= 3.0.0 https://maven.apache.org/download.cgi
    Py Python >= 3.7 https://www.python.org/downloads/

  2. Configure Environment Variables

    Environment Variable Path
    JAVA_HOME C:\Program Files\Java\jdk1.8.0
    MVN_HOME C:\Program Files\ApacheMaven
    PY_HOME C:\Program Files\Python\Python310
    Adapt the paths in case you used other installation directories.

  3. Extend the Path Environment Variable

    PATH
    %ANT_HOME%\bin
    %MVN_HOME%\bin
    %PY_HOME%\Scripts

  4. Install Python extensions

    py -m pip install PyMuPDF
py -m pip install fitz
py -m pip install frontend
py -m pip install tools

Attention: Python is only required by the submodule pdf2yaml. The Python installation can be skipped, if pdf2yaml is excluded from the list of executed submodules (see 3.4).

3.4 Build the Project

This project is a Maven aggregate project, which contains all generators described above. Use the following command to build all modules and with this to execute all code generators:

mvn clean install

The submodule pdf2yaml may be skipped in the generation process if the yaml file from the repository is used. In this case, Python is not required. The following command builds the project excluding pdf2yaml:

mvn clean install --projects -:pdf2yaml

Attention: Actually it is not needed to build this project. All final artifacts are already in the repository inside the dist/ folder.

3.5 Use Cases

The TSM-Backend REST-API is an interface that provides methods for the following use cases:

  • upload JavaCard *.cap files to TSM-Backend
  • define a Service which consists of one or multiple *.cap files
  • versionize the Service
  • define Flavors (hardware variants) for each Service
  • associate SecureComponentProfiles (hardware profiles) to each Flavor, e.g. minimal JavaCard version

In summary, the TSM-Backend REST-API is an administration interface for service providers to configure their Services in the TSM-Backend.

TSM REST-API

3.6 Data Types

For the life-cycle management of secure applications, data provided by the respective SP has to be stored in the TSM-Backend.

The central entity, the Service Provider is shown in orange. Class entities, like Service and Flavor, are shown in dark blue, while helper classes are shown in light blue. As the top-level entity, besides the Service Provider itself, a Service represents the functionality that should be provisioned onto a secure component. A Service may have different Flavors. Flavors are specific realizations of a Service. While the basic functionality is the same, different Flavors cover different characteristics and necessities of different underlying platforms. A Flavor comes with (typically) one or more Executable Load Files (ELFs). ELFs are containers of executable code on a secure component. A realization of a Load File is a Java Card CAP-File, which contains the Load File Data Block and, optionally, a manifest file that is used to retrieve information regarding the content of the CAP file. An ELF may contain several Executable Modules (EMs). An EM represents executable code on a secure component of a single application that can be used for the instantiation of application instances. An example of an Executable Module is a Java Card Applet.

These entities are augmented by various additional components. First of all, a Service has different Versions that can be used for versioning and updating. Other components cover specific requirements and configuration instructions for Flavors, ELFs, and EMs. E.g., during the installation process, the instantiation of application instances from an Executable Module is configured with the ApplicationInstantiationConfig, which itself relies on, respectively specifies, a more general ApplicationConfig. PersonalizationScripts, e.g. for dynamic interactions between TSM-Backend and SP-Backend during the provisioning, add another (optional) layer of flexibility to the data model. The SecureComponentProfiles are managed by the TSM (thus shown in orange), they can be assigned to specific Flavors and are then mapped to Versions accordingly.

Last but not least, the SposConfig is used to configure access to a SP backend for the delivery of order- and status management related data. A single SposConfig may be used by multiple Services.

TSM REST-API

3.6 API Methods

All methods of the TSM-Backend REST-API are described in detail in BSI-TR-03165 Section 4.1.

Additional documentation generated from the TR is available here:

The following table provides an overview about all available API methods. Section numbers refer to TR-03165.

Section Description
Authentication This section lists methods for authentication to the TSM Backend.
Manage SP Account This section lists methods for the management of SP account information.
Retrieve SecureComponentProfiles This section provides methods to retrieve information about by the TSMS supported hardware platforms.
Manage Services and Flavors This section lists methods for the management of Services, Versions, and Flavors. Using these methods, an SP may, e.g., link existing ELFs and ApplicationConfigs to create and modify different Versions and Flavors of a Service. There are methods to list, create, modify, and delete Service entities and their corresponding Version and Flavor entities, and to link ExecutableModule entities and ApplicationConfig entities to a certain Flavor. The methods listed in this section do not provide functionality to upload binary data for ELFs or to create ApplicationConfigs. Uploading ELFs can be done via methods listed in Section 4.1.6.4.27. Managing ApplicationConfigs can be done via methods listed in Section 4.1.6.6.
Manage ELFs and EMs This section lists methods for the upload of executable binary files, usually CAP files, and to provide technical requirements and installation orders for the EMs inside those files. There are methods to list, create, modify, upload, overwrite, and delete ExecutableLoadFile entities and their corresponding InstallationOrder and TechnicalRequirements entities. These methods do not provide functionality to link EMs to certain ApplicationConfigs. Linking EMs and ApplicationConfigs is done using methods listed in Section 4.1.6.4.
Manage ApplicationConfigs This section lists methods to create application configurations for EMs. An ApplicationConfig consists of parameters and certificates necessary for the provisioning of a specific kind of SC. An ApplicationConfig does not depend on a specific EM. There are methods to list, upload, overwrite, and delete ApplicationConfigs, and to link PersonalizationScripts and Certificates to a certain ApplicationConfig. The methods listed here do not provide functionality to link ApplicationConfigs to certain EMs. Linking ApplicationConfigs and EMs is done via methods listed in Section 4.1.6.4. The methods listed here do not provide functionality to upload binary data for PersonalizationScripts or Certificates. Uploading those files is done via methods listed in Section 4.1.6.7 and Section 4.1.6.8.
Manage PersonalizationScripts This section lists methods to upload and manage PersonalizationScripts. A PersonalizationScript is a binary script a SP may use to specify installation instructions or request TSM-support for, e.g., the personalization of a secure application during the provisioning process. A PersonalizationScript is independent of specific EMs and can be linked to an ApplicationConfig. There are methods to list, get, upload, and delete PersonalizationScripts. The methods listed here do not provide functionality to link a PersonalizationScript to an ApplicationConfig or EM. Linking a PersonalizationScript to an ApplicationConfig is done via methods listed in Section 4.1.6.6 , indirect linking to EMs is done via methods listed in Section 4.1.6.4.
Manage Certificates This section lists methods to manage the TLS certificates which are used for communication with a SP backend requested by PersonalizationScripts (if applicable) and for communication between TSM and SPOS. There are methods to list, get, upload, and delete Certificates. The methods listed here do not provide functionality to link a Certificate to certain ApplicationConfigs or SposConfigs. Linking Certificates to ApplicationConfigs is done via methods listed in Section 4.1.6.6, and linking to SposConfigs is done using methods listed in Section 4.1.6.9.
Manage SposConfigs This section lists methods to manage SposConfigs.

Back to Overview