Chapter 26. tpsclient

26.1. Syntax

The tpsclient tool can be used for debugging or testing the TPS. The tpsclient imitates the Enterprise Security Client and can give debug output or emulate enrolling and formatting tokens without having to use tokens.

The tpsclient tool is launched by running the command tpsclient. The tool has no options. Running this opens a shell which allows specific commands to be directed toward the tpsclient.

tpsclient

Registration Authority Client
'op=help' for Help
Command>

tpsclient and the TPS need to agree on a set of symmetric keys to establish a secure channel. They are both configured with a mutual default token has the default key set (version 1) which contains three keys: authentication key, Mac key, and key encryption key (KEK). The TPS subsystem understands and accepts the default key set.

The default key values are set to 0x40 0x41 0x42 0x43 0x44 0x45 0x46 0x47 0x48 0x49 0x4a 0x4b 0x4c 0x4d 0x4e 0x4f, 16 bytes. The default configuration is shown by running the token_status option within the tpsclient command shell.

Command>token_status
token_status
Output> life_cycle_state : '0'
Output> pin : 'password'
Output> app_ver : '00010203' (4 bytes)
Output> major_ver : '0'
Output> minor_ver : '0'
Output> cuid : '00010203040506070809' (10 bytes)
Output> msn : '00000000' (4 bytes)
Output> key_info : '0101' (2 bytes)
Output> auth_key : '404142434445464748494a4b4c4d4e4f' (16 bytes)
Output> mac_key : '404142434445464748494a4b4c4d4e4f' (16 bytes)
Output> kek_key : '404142434445464748494a4b4c4d4e4f' (16 bytes)
Result> Success - Operation 'token_status' Success (8 msec)
Command>

If the TPS is configured to use a new master key, then the tpsclient must also be reconfigured, or it cannot establish its connection to the TPS.

Get the new key set data to input into tpsclient. The default key set must be stored in the TKS, and the master key must be added. Do this by editing the TKS mapping parameter in the TKS CS.cfg file:
```
tks.mk_mappings.#02#01=lunasa1:masterkey
```
This configuration instructs the TKS to map the master key named masterkey on the lunasa1 token to the #02#01 key.
Enable key upgrade in the TPS by editing the update symmetric keys parameter in the TPS CS.cfg file:
```
op.format.tokenKey.update.symmetricKeys.enable=true
op.format.tokenKey.update.symmetricKeys.requiredVersion=2
```
This setting instructs the TPS to upgrade the token from version 1 to version 2 during the tpsclient format operation.

Format the token using tpsclient, as follows:

tpsclient

Command>op=token_set cuid=a00192030405060708c9
         app_ver=6FBBC105 key_info=0101
Command>op=token_set auth_key=404142434445464748494a4b4c4d4e4f
Command>op=token_set mac_key=404142434445464748494a4b4c4d4e4f
Command>op=token_set kek_key=404142434445464748494a4b4c4d4e4f

 ## Formatting operation ##

Command>op=ra_format uid=test pwd=password num_threads=1 new_pin=password

The CUID can be any 10-byte string; it affects how the TKS computes the new key set for tpsclient.

After running the format operation, tpsclient prints the new key set in the standard output. Save the new values in a new tpsclient input file. The input file can then be used with a production TPS server.

tpsclient can be used for formatting operations or for enrollment operations. The sample input file for an enrollment operation is shown in Example 26.1, “Example tpsclient Enrollment Input File”.

op=var_set name=ra_host value=server.example.com
op=var_set name=ra_port value=7888
op=var_set name=ra_uri value=/nk_service
op=token_set cuid=00000000000000000001
   msn=01020304 app_ver=6FBBC105 key_info=0101 major_ver=0 minor_ver=0
op=token_set auth_key=404142434445464748494a4b4c4d4e4f
op=token_set mac_key=404142434445464748494a4b4c4d4e4f
op=token_set kek_key=404142434445464748494a4b4c4d4e4f
op=ra_enroll uid=jdoe pwd=password new_pin=password num_threads=1

Example 26.1. Example tpsclient Enrollment Input File

The sample input file for an enrollment operation is shown in Example 26.2, “Example tpsclient Format Input File”.

op=var_set name=ra_host value=server.example.com
op=var_set name=ra_port value=7888
op=var_set name=ra_uri value=/nk_service
op=token_set cuid=00000000000000000001
   msn=01020304 app_ver=6FBBC105 key_info=0101 major_ver=0 minor_ver=0
op=token_set auth_key=404142434445464748494a4b4c4d4e4f
op=token_set mac_key=404142434445464748494a4b4c4d4e4f
op=token_set kek_key=404142434445464748494a4b4c4d4e4f
op=ra_format uid=ckannan pwd=netscape new_pin=netscape num_threads=1

Example 26.2. Example tpsclient Format Input File

26.1. Syntax

The tpsclient tool has the following syntax:

tpsclient op=operation options

Operation	Description	Options
op=help	Brings up the help page, which lists all usage and options for the `tpsclient` tool.	N/A
op=debug	Enables debugging.	`filename` sets the debug file.
op=ra_enroll	Tests certificate enrollments.	`uid` gives the user ID of the user running. `pwd` gives the password corresponding to the user ID. `num_threads` sets the number of threads to use `secureid_pin` gives the token password `keygen` set whether server-side key generation is enabled.
op=ra_reset_pin	Resets the token PIN.	`uid` gives the user ID of the user running. `pwd` gives the password corresponding to the user ID. `num_threads` sets the number of threads to use `secureid_pin` gives the token password `new_pin` sets the new PIN (token password).
op=ra_update	Updates the applet.	`uid` gives the user ID of the user running. `pwd` gives the password corresponding to the user ID. `num_threads` sets the number of threads to use `secureid_pin` gives the token password
op=token_set	Sets the token value.	The usage with this operation is name=value, which sets the token name and description.
op=token_status	Returns the current token status/	N/A
op=var_get	Gets the current value of the variable.	This has the usage `name=`name, where name is the variable being checked.
op=var_list	Lists all possible variables.	N/A
op=var_set	Sets variable values.	`name` sets the name of the variable. `value` sets the value of the named variable.

Table 26.1. tpsclient Operations