SmartCard-HSM Perso Client

The CLI Perso Client is a Java library and command line interface suitable for integration into automated production systems. The client is contained in the Starterkit, while the library ans source-code is available in the sc-hsm-persoclient repository in the CDN.

Overview

A token or card production in the portal consists of two steps:

  1. Creation of the Produce Token service request in the portal
  2. Connection of the empty card or token to the portal

While the first step is a serial process, the second step can be performed in parallel with a larger number of cards or token.

The connection between step 1 and step 2 is an URL, that uniquely references the Produce Token service request created in step 1 and that carries an authentication token:

https://test.pki-as-a-service.net/sems-rt/sems?03957E8CE79228820411

This URL can be used once to produce a card or token with the parameter in the service request.

In the portal you can monitor the status of the Produce Token service request. Its state is Scheduled for production (Produce) until the actual production starts with the card or token connecting via RAMOverHTTP.

Service Request Produce

After producing the card or token the service requests life-cycle is updated accordingly and a link to the device authentication certificate is linked.

Service Request Completed

This view would also show errors that occured during production. If a production process fails, the request can not be used again. Unless a device certificate is issued (which is the very last step in the process), no license is counted in that case.

Running the Perso Client

Running the client with -? shows the available options:

asc@calzone:~/Downloads$ java -jar sc-hsm-persoclient-1.0.1.jar -?
Usage sc-hsm-persoclient <options>

Commands:
--login,-l <url>                        Start a user login where <url> is refering to dica subject(e.g. "https://www.pki-as-a-service.net/se/paas/subject/<id>") using the SmartCard-HSM defined by the reader option (default first found)
--createBatchFile,-c <Path> <Count>     Create a batch of Personalization Service Requests (login required)
--personalize,-pe                       Create a new personalization request and start personalization (login required)
--personalizeURL,-pu  <url>             Personalize a single card or token for a given request URL
--personalizeBatch,-pb  <url>           Personalize mutliple cards or token using a batch file


Options:
--interactive,-i                Interactive mode
--list,-lr                      List all available card reader and token
--reader,-r <reader>            Define card reader or token to use (default first found)
--pin,-p <alias>                Define PIN for login (default prompt)
--kmc,-k <KMC>                  Define KMC to configure the personalization service request (optional)
--hardware,-h <hardware>        Define hardware to configure the personalization service request (optional)
--dica,-d <DICA>                Define DICA for creating personalization service requests
--verbose,-v                    Show whats going on
  • --login or -l defines the URL of the TrustCenter to log into.
  • --createBatchFile or -c creates the file specified as parameter <Path> filled with <Count> URLs that link to the Produce Token service requests. The file can then be processed with --personalizeBatch (or -pb).
  • --personalize or -pe produces a single card or token after log into the portal.
  • --personalizeURLe or -pu performs a single card or token production with an URL from the file created with -c.
  • --personalizeBatch or -pb performs multiple runs for each inserted card or token with one of the URLs from the file created with -c.

Obtaining the TrustCenter URL

The --login option 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 https://test.pki-as-a-service.net/se/paas/subject/4. This URL must be either entered after the --login argument.

Log into the Portal

To test if your login token works, use

asc@calzone:~/Downloads$ java -jar sc-hsm-persoclient-1.0.1.jar --login https://test.pki-as-a-service.net/se/paas/subject/4
Please select a reader for login:
[1]     Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026211902) 00 00
[2]     Identiv uTrust 3512 SAM slot Token [CCID Interface] (55511725601946) 01 00
[3]     ANY
2
Please enter user PIN:
Logged in as andreas.schwier@cardcontact.de

If you have multiple token or card readers, you can select the one to use or let the client probe for a matching SmartCard-HSM (here [3]);

After entering your token PIN, you are logged-in and your e-mail as registered in your account in the portal is shown.

The login process does not check if the subject id specified in the URL does exist or if you have access to that subject.

Produce a single Card or Token

To login and produce a single card or token start the client with the --personalize or -pe option.

asc@calzone:~/Downloads$ java -jar sc-hsm-persoclient-1.0.1.jar --login https://test.pki-as-a-service.net/se/paas/subject/4 -pe
Please select a reader for login:
[1]     Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026211902) 00 00
[2]     Identiv uTrust 3512 SAM slot Token [CCID Interface] (55511725601946) 01 00
[3]     ANY
3
Please enter user PIN:
Logged in as andreas.schwier@cardcontact.de
Please select a DICA:
[1]     UTDICC07
1
Please remove login token and insert the card or token to personalize
Personalization started
Initializing
Loading Applet
Personalizing
UTCC0700106
Personalization completed

If you have a token and a card reader that you want to use to personalize a card, then select ANY in the reader selection.

The client connects to the portal and allows you to select the Device Issuer CA (DICA). After that you insert the card or token and the production process starts.

Produce a Batch

To produce a batch of URLs use the --createBatchFile or -c option. The parameter takes two arguments, the file to which the URLs are written (here urls.txt) and the number of URLs to produce (here 2):

asc@calzone:~/Downloads$ java -jar sc-hsm-persoclient-1.0.1.jar --login https://test.pki-as-a-service.net/se/paas/subject/4 -c urls.txt 2
Please select a reader for login:
[1]     Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026211902) 00 00
[2]     Identiv uTrust 3512 SAM slot Token [CCID Interface] (55511725601946) 01 00
[3]     ANY
3
Please enter user PIN:
Logged in as andreas.schwier@cardcontact.de
Please select a DICA:
[1]     UTDICC07
1
asc@calzone:~/Downloads$ cat urls.txt 
https://test.pki-as-a-service.net/sems-rt/sems?0399C07F104A6D746DB0
https://test.pki-as-a-service.net/sems-rt/sems?039A16BCDF0B21DB93DE

After login and prompting for the DICA, the requested number of Produce Token service requests are created and their URL written to file.

Process the Batch

To process the batch use the --personalizeBatch or -pb option:

asc@calzone:~/Downloads$ java -jar sc-hsm-persoclient-1.0.1.jar -pb urls.txt 
Please select a reader to start personalization:
[1]     Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026211902) 00 00
[2]     Identiv uTrust 3512 SAM slot Token [CCID Interface] (55511725601946) 01 00
2
Personalization started
Initializing
Loading Applet
Personalizing
UTCC0700107
Personalization completed

Insert next card or token to proceed
Personalization started
Initializing
Loading Applet
Personalizing
UTCC0700108
Personalization completed

Using the ram-client

The ram-client is a native command line tool that is part of the sc-hsm-embedded project. A Windows binary is included in the Starterkit. For Linux or MacOS, the sc-hsm-embedded project must be configured with the --enable-ram option.

The ram-client is typically used to permanently connect a SmartCard-HSM to a PKI-as-a-Service instance. But it can also be used to perform a single production process with a given URL.

asc@calzone:~/Downloads$ ram-client -r "Identive CLOUD 2700 R Smart Card Reader [CCID Interface] (53692026211901) 01 00" -v https://test.pki-as-a-service.net/sems-rt/sems?03957E8CE79228820411
(1) Initializing
C: 00A4040000
R: 6F108408A000000151000000A5049F6501FF9000
C: 80CA00FE02DF2800
R: FE45DF2842010C0001A6BE87F8D1F7A08D723D0208000000000000000103184A335233353130323336333130343030DCE5C19CFE6D0DCF05010007010108082E5AD88409C9BADB9000
C: 80500000086DBEB1F655FA06A000
R: 000023175829982045310103008CA239510AAC574C15B3860D83BC824A9000
C: 8482030010C1EC42D2DC6C56A0B477264D02697B1700
R: 9000
C: 84F28002181D60087350B4982A02D66C3434F2B22E65710C2310CD212900
R: E3264F08A0000001510000009F700101C5039AFE80C407A0000001515350CC08A0000001510000009000
---8<------8<------8<------8<------8<------8<------8<------8<---
A lot of APDUS here...
---8<------8<------8<------8<------8<------8<------8<------8<---
(0) UTCC0700105
Completed

The ram-client can be integrated in a larger setup and indicates the result in the return code. A return code of 0 indicates successful completion.