1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
# --- BEGIN COPYRIGHT BLOCK ---
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation;
# version 2.1 of the License.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301 USA
#
# Copyright (C) 2007 Red Hat, Inc.
# All rights reserved.
# --- END COPYRIGHT BLOCK ---
#
Overview
========
tpsclient is a test utility that talks to the TPS
directly using HTTP protocol.
It is a software-based token. It can be used as a driver
for stress/scalability testing.
It can be used for the following operations:
enrollment - This is for getting a certificate
into the token.
pin reset - This is for changing the token's pin.
format - This is for formatting the token to
remove the certificates from the token
and load fresh applets.
Configuration
=============
The tpsclient utility accepts a test script file. Each script
file contains a sequence of operations. Each operation
is composed of a set of name value pairs. For example,
op=var_set name=ra_host value=familiar
It starts with an operation type such as 'op=var_set' and
follows by a list of parameters as 'name=ra_host value=familiar'.
The currently supported operation types are as follows:
op=var_list - list all TPS connection parameters
op=var_get - retrieve the value of a TPS connection parameter
op=var_set - set the value of a TPS conection parameter
op=exit - exit this utility
op=help - get more information about each operation
op=token_status - list all token parameters
op=token_set - set the value of a token parameter
op=ra_enroll - perform an enrollment operation
op=ra_reset_pin - perform a pin reset operation
op=ra_format - perform a format operation
Configuration Examples
======================
Setup TPS's connection information:
op=var_set name=ra_host value=familiar
op=var_set name=ra_port value=9003
op=var_set name=ra_uri value=/nk_service
Setup token's ID, Applet ID, and Key Set Version:
op=token_set cuid=a00192030405060708c9 app_ver=6FBBC105 key_info=0101
Setup Key Data: (Note that '404142434445464748494a4b4c4d4e4f' is the
default key created by the manufacturer in the real token)
op=token_set auth_key=404142434445464748494a4b4c4d4e4f
op=token_set mac_key=404142434445464748494a4b4c4d4e4f
op=token_set kek_key=404142434445464748494a4b4c4d4e4f
Perform an enrollment operation:
op=ra_enroll uid=sectest13 pwd=home-boy new_pin=password
Perform a pin reset operation:
op=ra_reset_pin uid=test pwd=password new_pin=newpassw
Perform a format operation:
op=ra_format uid=test pwd=password new_pin=newpassw
Print the information inside token:
op=token_status
Applet Upgrade Example
======================
To test applet upgrade, you should first setup TPS to enable
applet upgrade. Please consult the TPS documentation for those
details.
You should try to do an enrollment operation with an applet
version that's different from the one that's configured in
the TPS's configuration file. For example, you should have
the following in the test script.
op=token_set cuid=18888883333300000004 app_ver=402428AD key_info=0101
This indicates that the token's applet version is currently at
40248AD.
After execution, you should see an audit event logged on the
TPS's audit log file like this,
...
[2004-11-15 16:56:38] 847f220 Enrollment - op='applet_upgrade'
app_ver='0.0.402428AD' new_app_ver='1.2.416DA155'
...
...
[2004-11-15 16:56:43] 847f220 Enrollment - status='success'
app_ver='1.2.416DA155' key_ver='0101' cuid='18888883333300000004'
msn='00000000' uid='user1' auth='ldap1' time='7243 msec'
Key Change Over Example
=======================
To test key change over, you should setup a version 2 master key
in TKS and enable the key change over feature in TPS. Please
consult the TPS documentation for details.
You should try to do an enrollment with a version 1 key in the
token. TPS should change the key in your token to
version 2. For example, you should have the following in
the test script:
op=token_set cuid=a00192030405060708c9 app_ver=6FBBC105 key_info=0101
op=token_set auth_key=404142434445464748494a4b4c4d4e4f
op=token_set mac_key=404142434445464748494a4b4c4d4e4f
op=token_set kek_key=404142434445464748494a4b4c4d4e4f
Note 'key_info=0101' indicates a version 1 key set.
After the execution, you should see the following in the output:
...
Output> cuid : 'a00192030405060708c9' (10 bytes)
Output> key_info : '0201' (2 bytes)
Output> auth_key : 'a3523ec8c0740b621e18e9cdd99f75fc' (16 bytes)
Output> mac_key : '903af964eb7ede26ea189243a5caad9c' (16 bytes)
Output> kek_key : '44ef9de3775121a871c152563d9b9860' (16 bytes)
...
'key_info: 0201' indicates that the current key set in the
token now changed from '0101' to '0201'. And as you noticed,
the key data for auth, mac, and kek keys are all different.
If you check the TPS's log, you should see an audit event for
the key change over operation.
After this, you should try to enroll with a version 2 keys.
For example, create a new test script that contains:
op=token_set cuid=a00192030405060708c9 app_ver=6FBBC105 key_info=0201
op=token_set auth_key=a3523ec8c0740b621e18e9cdd99f75fc
op=token_set mac_key=903af964eb7ede26ea189243a5caad9c
op=token_set kek_key=44ef9de3775121a871c152563d9b9860
Execute this test script, and you should NOT see an audit
event for key change over. It is because your token already
has a version 2 key set.
You can also try to key change over from version 2 back to
version 1 with appropriate TPS configuration and test
script.
Choose a specific profile in TPS
================================
TPS can be configured to support several profiles like
1) devicekey profile - used to issue only signing certs
2) userKey profile - used to issue signing and encryption certs
the tpsclient can be configured to tell TPS to select the right
profile by adding the following to the op=ra_enroll line in the
test script
op=ra_enroll uid=user1 num_threads=1 pwd=password new_pin=newpassw
extensions=tokenType=userKey
(OR)
op=ra_enroll uid=user1 num_threads=1 pwd=password new_pin=newpassw
extensions=tokenType=deviceKey
Stress test Example
===================
tpsclient can be configured to start multiple threads to perform
enrollment or pin reset or format operations, to stress the TPS
installation.
op=ra_enroll uid=user1 num_threads=1 pwd=password new_pin=newpassw
extensions=tokenType=userKey
In the above test script line, the num_threads parameter indicates
the number of threads that will be started.
Also , to control the number of operations being performed, the
following parameter should be set in the test script line.
op=ra_enroll uid=user1 num_threads=1 pwd=password new_pin=newpassw
extensions=tokenType=userKey max_ops=10
max_ops, indicates the number of operations that will be performed
by all the threads.
Execution
=========
For Enrollment Operation:
tpsclient < enroll.test
For Reset Pin Operation:
tpsclient < reset_pin.test
Note
====
You may need to setup LD_LIBRARY_PATH (On Linux, and Solaris) to
point to the directory where you have NSPR, NSS, TPS shared libraries.
|