SupportConsoleDevelopersStart a trialContact

Chapter 26. tpsclient (Debugging the TPS)

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, which 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 for each 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.
  1. 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=nethsm1:masterkey
    This configuration instructs the TKS to map the master key named masterkey on the nethsm1 token to the #02#01 key.
  2. 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.
  3. 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

Command>op=ra_format uid=jsmith 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.

    Note

    Because it can be tedious to type each operation and parameter through the command line, it is possible to create an input file and then point the tpsclient command to the file. For example: 
    tpsclient < /tmp/input.txt
    Example 26.1, “Example tpsclient Enrollment Input File” and Example 26.2, “Example tpsclient Format Input File” both list examples for an input file.
    The command prompt will return any output given by tpsclient during the operation and the final result of the command.
  4. 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”.

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
The sample input file for an enrollment operation is shown in Example 26.2, “Example tpsclient Format Input File”.

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=jsmith pwd=secret new_pin=newsecret num_threads=1

Note

The host value can be an IPv4 address or an IPv6 address, if one is configured for the host.

26.1. Syntax

The tpsclient tool has the following syntax: 
tpsclient op=operation options
Table 26.1. tpsclient Operations
Operation Description Options
op=help Brings up the help page, which lists all usage and options for the tpsclient tool. N/A
op=debug filename=filename 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.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.