Smart Card Shell Perso Client

The interactive Perso Client based on the Smart Card Shell is implemented as JavaScript module in scsh/perso. It uses a JSON configuration file for jobs and keys.

A template for jobs.js and keys.js can be found in the sc-hsm-sdk-scripts/perso/template directory of the SmartCard-HSM workspace in the Starterkit or in the sc-hsm-sdk-script repository in the CDN.

The Perso Client can be started by running the jobs.js file.

Note: If you have an older setup that includes a perso.js file, then you can either start that script or move the code for creating the scheduler to jobs.js.

// Jobs go here
// Place at end
load("keys.js");

var Scheduler = require("scsh/perso/Scheduler").Scheduler;
var scheduler = new Scheduler(Jobs);
scheduler.selectJob();
scheduler.selectMode();

When you start the Perso Client, it allows you to select one of the jobs configured in jobs.js. The jobs.js from the template contains

• SmartCard-HSM Personalization to produce a SmartCard-HSM.
• SmartCard-HSM Applet Removal to remove the SmartCard-HSM applet and restore the KST.
• Authentication Test tests the SCP authentication using a KST or KMC configured in keys.js or in the connected DICA token.
• Replace KST replaces the KST with a new value from keys.js
• Test Card Printer allows testing the card printer feeder and eject configuration

Producing a SmartCard-HSM

For producing a SmartCard-HSM you need to have the token to log into the portal at hand. This is required, so that the Perso Client can connect and control your DICA in the portal. Your DICA is part of your TrustCenter, which can be uniquely identified by its URL.

Obtaining the TrustCenter URL

The SmartCard-HSM Personalization job uses the PortalPersonalizer configuration in jobs.js, which requires the URL of the TrustCenter (or Device Issuer) that you want to use. To determine the URL you need to log into the portal and switch to the desired trustcenter.

Here the URL is https://test.pki-as-a-service.net/se/paas/subject/4. This URL must be either entered at the prompt or added in jobs.js.

Login

The PortalPersonalizer prompts to select the card or token to log into the portal.

After entering the PIN, you are logged-in and the client prompts you to remove the token used for login. This prevents accidentially overwriting your login-token during personalization.

Select DICA

You can have multiple DICA instances in your TrustCenter. Unless you have fixed the DICA in jobs.js, you are prompted to select the desired DICA.

The client then summarizes the settings, so you can easily copy the parameter into your jobs.js file.

Connect the DICA Token

The DICA token contains the required key material for the production process, namely the DICA signing key, the KST and KMC.

The are various ways to connect the DICA token with the portal, one is from the Perso Client. You can skip this step, if the DICA token is already online by other means.

The client prompts you to select the token or card reader and enter the PIN of the DICA token. Then you can enter the URL you want the token to connect to.

This URL is in most cases the host name of the portal with the path /sems-rt/hsm.

Select the Mode

The Perso Client has four modes of operation.

• Single-Short starts a single execution for the card or token already present. After that the script stops.
• Single-Card-Insert start the perso process for each inserted card or token. You can monitor progress and result in the shell window.
• Multi-Card-Insert allows to insert multiple cards or token at the same time and the perso process is started asynchronously for each detected card or token. You can monitor process in the Tasks tab.

If you configured a printer control in your job (e.g. ShellPrinterControl), there is a fourth mode One-By-One which synchronizes card insertion of the feeder and card presence events from the card printer.

Once the mode is selected, you can start inserting cards or token.

Stopping the Perso Client

You can stop the Perso Client by closing the shell or entering "restart" in the shell window. If you connected a DICA token, then stop that token in the tasks tab.

Customizing jobs.js

You can create your own jobs by extending the JSON structure in jobs.js

        TestAPDU: {
            apdu: "00A4040008A000000151000000"
        }
    },
    {
        Name: "My new jobs that does nothing
    }
]

Module Overview

The Perso Client comes with several modules, that can be configured and activated in your job. The module source code can be found in the scsh/perso directory of your Smart Card Shell installation.

You can configure a single initializer, personalizer and printer module. The initialization is always done before the personalization. Card feeder control is done before and after initialization or personalization is performed.

Modules that perform initialization are

• TestAPDU sends a single APDU to the card and can be used to test your setup
• Initializer implements a number of JavaCard Card Manager operations
• JCOP4Initializer Allows the low-level configuration of a JCOP4 JavaCard. This initializer requires a dedicated application profile that implements the APDUs protected by an NXP NDA.

Modules that perform personalization are

• PortalPersonalizer connects the card or token to the DICA in the portal. Requires a token for login.

Modules that control a card printer

• ShellPrinterControl allows to configure shell commands to control the card feeder.

You can write your own module and place them in the same directory as the jobs.js file. Use an existing module as template.

PortalPersonalizer

The PortalPersonalizer is a module that connects a token or card with the Device Issuer CA in the portal. To use the PortalPersonalize add the configuration section to your job definition:

{
    Name: "SmartCard-HSM Personalization",

    PortalPersonalizer: {
        url: "https://www.pki-as-a-service.net/se/paas/subject/<id>",
        dicaId: 1835,
        hardware: "Default"
        // kmc: "Default"
    }
},

• The url field contains the URL of your TrustCenter. This is the URL where the PortalPersonalizer connects to for login and to create "Produce Token" service requests.
• The dicaId identifies the Device Issuer CA in your TrustCenter. The id is reported when you run the PortalPersonalizer without this setting.
• The hardware field specifies the type of hardware that you are going to personalize. This identifier must match the name of the KST on the DICA token (e.g. "KST@Default" is the key label and "Default" the hardware name). If this field is missing, the first (or only) hardware configuration by this DICA is selected.
• The kmc field defines the KMC to be used by this DICA. This setting on relevant for the very first device produced with a new DICA. Once a device is produced, the KMC is fixed for this DICA.