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.

Choose Job

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.

Determine URL

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

Set URL

Login

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

Select Token

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.

Remove Token

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.

Select DICA

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

Job Config

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 client. You can skip this step, if the DICA token is already online by other means.

Connect DICA

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.

Connect DICA URL

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.

Select Mode

  • 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.

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
    }
]