Calypso card configuration audit tool


What is the CNA Tool Card Analyzer App Suite?

The CNA Tool Card Analyzer App Suite consists of two command-line tools:

  • Tool_AnalyzeCardFileStructure: analyzes the file structure of a Calypso smart card and generates a JSON report containing the card’s structure and application data.
  • Tool_CheckCardFileStructure: checks the file structure of a Calypso card against a given JSON file containing the expected file structure.

Why use the CNA Tool Card Analyzer App Suite?

This suite helps developers and testers:

  • Understand the data stored on a Calypso card.
  • Verify compliance with Calypso specifications.
  • Troubleshoot potential issues.
  • Compare card structure against a predefined template.

The following sections provide detailed instructions on using the CNA Tool Card Analyzer App Suite to retrieve and analyze the contents of a Calypso card and to verify its compliance against a reference file.


Prerequisites

  • Java: ensure you have a Java Runtime Environment (JRE) installed on your system. You can download it from www.java.com.
  • PC/SC card reader: a contactless PC/SC compliant card reader is required to interact with the Calypso card.

Download the Apps

  1. Go to the releases page to download the latest version of the application suite.
  2. Download the executable JAR files:
    • Tool_AnalyzeCardFileStructure-x.y.z.jar
    • Tool_CheckCardFileStructure-x.y.z.jar

Analyze a Card

  1. Open a terminal or command prompt.
  2. Navigate to the directory containing Tool_AnalyzeCardFileStructure-x.y.z.jar.
  3. Place your Calypso card on the reader.
  4. Execute the following command:
java -jar Tool_AnalyzeCardFileStructure-x.y.z.jar [readerNameRegex]
  • readerNameRegex (optional): a regular expression to filter the card readers. If not provided, a default regex ( .*(ASK.*|Identiv.*2|ACS ACR122U|SCR3310).*) is used.
  1. The analysis results will be displayed in the terminal and JSON file containing the card structure will be saved.

Supported AID Prefixes

The Tool_AnalyzeCardFileStructure is configured to recognize and analyze Calypso cards with specific AID prefixes. The supported prefixes are:

  • A000000291
  • A000000404
  • D276000085
  • 334D54522E
  • 315449432E
  • 304554502E

If the card’s DF Name does not match one of the supported AID prefixes, you will need to update the configuration in the source code to include the new AID prefix and recompile the application for proper analysis.

JSON Output

The JSON output generated by Tool_AnalyzeCardFileStructure provides a structured view of the Calypso smart card data analyzed. Below is an explanation of the key fields found in the JSON output:

{
  "id": "string",
  "infos": "string",
  "date": "string",
  "version": "integer",
  "software": "string",
  "traceability": "string",
  "applicationList": [
    {
      "fci": "string",
      "calypsoRevision": "string",
      "aid": "string",
      "applicationType": "string",
      "applicationSubtype": "string",
      "issuer": {
        "value": "string",
        "name": "string"
      },
      "csn": "string",
      "csnDec": "integer",
      "sessionModif": "string",
      "sessionModifDec": "integer",
      "bufferSize": "integer",
      "platform": "string",
      "version": "string",
      "revision": "string",
      "transactionCounter": "string",
      "transactionCounterDec": "integer",
      "accessConditions": {
        "group0": {
          "accessCondition": "string",
          "keyLevel": "string",
          "description": "string"
        },
        "group1": {
          "accessCondition": "string",
          "keyLevel": "string",
          "description": "string"
        },
        "group2": {
          "accessCondition": "string",
          "keyLevel": "string",
          "description": "string"
        },
        "group3": {
          "accessCondition": "string",
          "keyLevel": "string",
          "description": "string"
        }
      },
      "status": "string",
      "kif1": "string",
      "kif2": "string",
      "kif3": "string",
      "kvc1": "string",
      "kvc2": "string",
      "kvc3": "string",
      "lid": "string",
      "fileList": [
        {
          "sfi": "string",
          "lid": "string",
          "efType": "string",
          "recSize": "string",
          "recSizeDec": "integer",
          "numRec": "string",
          "numRecDec": "integer",
          "accessConditions": {
            "group0": {
              "accessCondition": "string",
              "keyLevel": "string",
              "description": "string"
            },
            "group1": {
              "accessCondition": "string",
              "keyLevel": "string",
              "description": "string"
            },
            "group2": {
              "accessCondition": "string",
              "keyLevel": "string",
              "description": "string"
            },
            "group3": {
              "accessCondition": "string",
              "keyLevel": "string",
              "description": "string"
            }
          },
          "ref": "string",
          "recordDataList": [
            {
              "index": "string",
              "value": "string"
            }
          ]
        }
      ]
    }
  ]
}

Field Descriptions

  • id: string, unique identifier for the profile.
  • infos: string, type of analysis performed (e.g., "AnalyzeCardFileStructure").
  • date: string, date and time when the analysis was conducted.
  • version: integer, JSON model version.
  • software: string, name of the software used for analysis (e.g., "Calypso Card Analyzer").
  • traceability: string, hexadecimal string encoding traceability information for auditing.

Application List

  • applicationList: array, list of applications on the card, each application containing the following fields:
    • fci: string, File Control Information for the application.
    • calypsoRevision: string, Calypso specification version, e.g., "PRIME_REVISION_3".
    • aid: string, Application Identifier (AID) in hexadecimal, (10-32 hexadecimal characters, 5-16 bytes).
    • applicationType: string, application type (2 hexadecimal characters, 1 byte).
    • applicationSubtype: string, application subtype (2 hexadecimal characters, 1 byte).
    • issuer: object, issuer information:
      • value: string, issuer identifier (2 hexadecimal characters, 1 byte).
      • name: string, issuer name.
    • csn: string, Card Serial Number in hexadecimal format.
    • csnDec: integer, Card Serial Number in decimal format.
    • sessionModif: string, session modification identifier in hexadecimal.
    • sessionModifDec: integer, session modification identifier in decimal.
    • bufferSize: integer, maximum buffer size allowed for the application.
    • platform: string, platform identifier.
    • version: string, application version (2 hexadecimal characters, 1 byte).
    • revision: string, application revision (2 hexadecimal characters, 1 byte).
    • transactionCounter: string, transaction counter in hexadecimal or "Not available".
    • transactionCounterDec: integer, transaction counter in decimal format.
    • accessConditions: object, access conditions by group:
      • group0 to group3: each group includes:
        • accessCondition: string, access condition (2 hexadecimal characters, 1 byte).
        • keyLevel: string, key level (2 hexadecimal characters, 1 byte).
        • description: string, description of the access condition.
    • status: string, application status (2 hexadecimal characters, 1 byte).
    • kif1 to kif3: string, key identifiers (2 hexadecimal characters, 1 byte).
    • kvc1 to kvc3: string, key version and category (2 hexadecimal characters, 1 byte).
    • lid: string, long identifier of the application (4 hexadecimal characters, 2 bytes).

File List

  • fileList: array, list of files within the application, each file containing the following fields:
    • sfi: string, short file identifier (2 hexadecimal characters, 1 byte).
    • lid: string, long file identifier (4 hexadecimal characters, 2 bytes).
    • efType: string, elementary file (EF) type (2 hexadecimal characters, 1 byte), e.g., "00" for DF, "01" for binary file, "02" for linear file.
    • recSize: string, record size in hexadecimal (4 characters, 2 bytes).
    • recSizeDec: integer, record size in decimal.
    • numRec: string, number of records in hexadecimal (2 characters, 1 byte).
    • numRecDec: integer, number of records in decimal.
    • accessConditions: object, file-specific access conditions with groups group0 to group3.
    • ref: string, reference identifier for the file.
    • recordDataList: array, list of record data in the file, each entry containing:
      • index: string, record index in hexadecimal (2 characters, 1 byte).
      • value: string, record data in hexadecimal.

Check a card structure

  1. Open a terminal or command prompt.
  2. Navigate to the directory containing Tool_CheckCardFileStructure-x.y.z.jar.
  3. Obtain a JSON file defining the expected card structure:
    • You can use a pre-defined JSON file from the card_profiles directory in the GitHub repository. The file names indicate the type of product they correspond to.
    • Alternatively, you can create your own JSON file defining the expected structure.
  4. Place your Calypso card on the reader and keep it still.
  5. Execute the following command:
java -jar Tool_CheckCardFileStructure-x.y.z.jar <path-to-json-file> [readerNameRegex]
  • <path-to-json-file>: (Required) The path to the JSON file containing the expected card structure. This argument should be replaced with the actual path to your JSON file (e.g., card_profiles/my_card_profile.json).
  • readerNameRegex (optional): a regular expression to filter the card readers. If not provided, a default regex ( .*(ASK.*|Identiv.*2|ACS ACR122U|SCR3310).*) is used.
  1. The tool will compare the card’s structure with the provided JSON file and display a report showing the differences if any.

Understanding the JSON card profile

The JSON file used by the Tool_CheckCardFileStructure tool defines the expected structure of a Calypso card. This section provides a detailed description of the JSON profile.

Overview

The file is organized hierarchically with the following elements:

  • id: A unique identifier for the profile.
  • version: Version number of the profile format.
  • applicationList: A list of all Calypso applications expected to be present in the card. Each application is represented by a JSON object with specific details.

JSON Structure

Here’s a representation of the JSON structure, showing the hierarchy of elements:

{
  "id": "string",
  "version": "integer",
  "applicationList": [
    {
      "calypsoRevision": "string",
      "aid": "string",
      "applicationType": "string",
      "applicationSubtype": "string",
      "accessConditions": {
        "group0": {
          "accessCondition": "string",
          "keyLevel": "string"
        },
        "group1": {
          "accessCondition": "string",
          "keyLevel": "string"
        },
        "group2": {
          "accessCondition": "string",
          "keyLevel": "string"
        },
        "group3": {
          "accessCondition": "string",
          "keyLevel": "string"
        }
      },
      "status": "string",
      "kif1": "string",
      "kif2": "string",
      "kif3": "string",
      "kvc1": "string",
      "kvc2": "string",
      "kvc3": "string",
      "lid": "string",
      "fileList": [
        {
          "sfi": "string",
          "lid": "string",
          "efType": "string",
          "recSize": "string",
          "numRec": "string",
          "accessConditions": {
            "group0": {
              "accessCondition": "string",
              "keyLevel": "string"
            },
            "group1": {
              "accessCondition": "string",
              "keyLevel": "string"
            },
            "group2": {
              "accessCondition": "string",
              "keyLevel": "string"
            },
            "group3": {
              "accessCondition": "string",
              "keyLevel": "string"
            }
          }
        }
      ]
    }
  ]
}

Application Structure

Each “application” object in applicationList contains the following information:

  • calypsoRevision: Version of the Calypso specification used. Possible values are: PRIME_REVISION_3, LIGHT, BASIC.
  • aid: Application Identifier (AID) as defined in ISO7816-4, a unique identifier for the application.
  • applicationType: Type of product (string, 2 hexadecimal characters, 1 byte). This field indicates the general category of the application on the Calypso card. For the purposes of this profile, the relevant values are:
    • 2x: Calypso Prime Revision 3. The x digit further specifies the available options within Prime Revision 3.
    • 90h: Calypso Light.
    • 98h: Calypso Basic.
  • applicationSubtype: Identifier of the application’s file structure (string, 2 hexadecimal characters, 1 byte, for values see Calypso Files specification).
  • accessConditions: See Access Conditions
  • status: Status of the application (string, 2 hexadecimal characters, 1 byte). This field indicates the operational status of the application. It is expected to be 00h.
  • kif1, kif2, kif3: Key Identifiers associated with the three key levels: Issuer, Load, Debit (string, 2 hexadecimal characters, 1 byte).
  • kvc1, kvc2, kvc3: Key Version and Category associated with the three key levels: Issuer, Load, Debit (string, 2 hexadecimal characters, 1 byte).
  • lid: Long File Identifier of the DF (string, 4 hexadecimal characters, 2 bytes).
  • fileList: A list of files within the application See File Structure.

File Structure

Each “file” object in fileList contains the following:

  • sfi: Short File Identifier identifying an EF (string, 2 hexadecimal characters, 1 byte, value from 01h to 1Eh). An EF may have no SFI (indicated by the value 00h).
  • lid: Long File Identifier (string, 4 hexadecimal characters, 2 bytes).
  • efType: Elementary File type (string, 2 hexadecimal characters, 1 byte):
    • 00h: DF
    • 01h: Binary file
    • 02h: Linear file
    • 04h: Cyclic file
    • 08h: Simulated Counter file
    • 09h: Counters file
    • Other: RFU value (forbidden)
  • recSize: Record size in bytes (string, 4 hexadecimal characters, 2 byte).
  • numRec: Number of records in the file (string, 2 hexadecimal characters, 1 byte).
  • accessConditions: See Access Conditions

Access Conditions

Access conditions define the security rules for accessing files and executing commands within a Calypso application. They are organized into four groups (group0 to group3), each representing a category of commands.

  • accessCondition: Specifies the access condition (string, 2 hexadecimal characters, 1 byte). Possible values are:
    • 00h: Never or no command associated with this group
    • 01h: PIN
    • 10h: Session
    • 14h: Confidential
    • 15h: Confidential & PIN
    • 1Fh: Always
    • Other: RFU value (forbidden)
  • keyLevel: Key level for access validation (string, 2 hexadecimal characters, 1 byte):
    • 01h: Issuer Key
    • 02h: Load Key
    • 03h: Debit Key
    • Other: RFU value (forbidden)

JSON schema

A JSON schema calypso_app_profile.schema.json is provided to validate the structure and data types of your Calypso application profile.


Troubleshooting

  • Card not found: ensure your card reader is correctly connected and installed, and that the card is presented correctly.
  • Java not found: ensure Java is installed and that its directory is added to your system’s PATH environment variable.
  • Error messages: carefully read any error messages displayed in the terminal for clues on how to resolve the issue.

Disclaimer

This software is provided under the terms of the Eclipse Public License 2.0. See the LICENSE file for more information.


User Requirements and Responsibilities

  • Target Audience: Developers, testers, and anyone interested in analyzing or verifying Calypso card data. Basic knowledge of smart card technology and command-line interfaces is recommended.
  • Prerequisites: Java Runtime Environment, a PC/SC compliant contactless card reader, and necessary drivers.
  • Responsibilities:
    • Ensure proper handling of the card and responsible use

Last updated on 2024-11-13