PKCS#11 standard

Cryptosense Analyzer PKCS#11 Compliance Edition
Reference Manual
http://cryptosense.com
[email protected]
Contents
1 Install
4
2 Overview
2.1 Commands . . . . . . . . . . . . . . . . . . . .
2.2 CSD: Device Description Files . . . . . . . . . .
2.3 CST: Test Result Files . . . . . . . . . . . . . .
2.4 Typical Workflow: Testing a PKCS#11 Device
.
.
.
.
4
4
4
4
5
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5
5
5
5
5
6
6
6
7
7
7
8
8
8
8
8
9
9
9
10
10
10
10
11
11
11
12
12
12
12
13
13
13
14
14
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3 Commands
3.1 cs cleanup — Cleanup Device . . . . . . . . . . . . . .
3.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2 Command-Line Options . . . . . . . . . . . . . .
3.2 cs comply — Check Compliance . . . . . . . . . . . . .
3.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 How to Read the Results . . . . . . . . . . . . .
3.2.3 Command-Line Options . . . . . . . . . . . . . .
3.3 cs csd-pkcs11 — Create PKCS#11 CSD . . . . . . . .
3.3.1 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Command-Line Options . . . . . . . . . . . . . .
3.4 cs help — Command-Line Help . . . . . . . . . . . . .
3.4.1 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.4.2 Command-Line Options . . . . . . . . . . . . . .
3.5 cs info — Show Device Information . . . . . . . . . . .
3.5.1 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.5.2 PKCS#11 Device Information . . . . . . . . . .
3.6 cs load-testing — Perform Load-Testing on a Device
3.6.1 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.6.2 Command-Line Options . . . . . . . . . . . . . .
3.7 cs stats — Display CST Statistics . . . . . . . . . . .
3.7.1 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.7.2 How to Read the Results . . . . . . . . . . . . .
3.7.3 Errors and Failures . . . . . . . . . . . . . . . . .
3.8 cs test — Test Device . . . . . . . . . . . . . . . . . .
3.8.1 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.8.2 How to Read the Results . . . . . . . . . . . . .
3.8.3 Command-Line Options . . . . . . . . . . . . . .
3.9 cs version — Show Cryptosense Analyzer Version . .
3.9.1 Usage . . . . . . . . . . . . . . . . . . . . . . . .
3.9.2 Command-Line Options . . . . . . . . . . . . . .
3.10 Common Command-Line Options . . . . . . . . . . . . .
3.10.1 Logging API Calls . . . . . . . . . . . . . . . . .
3.10.2 Quiet and Verbose Modes . . . . . . . . . . . . .
3.10.3 --help and --version . . . . . . . . . . . . . .
2
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4 PKCS#11 CSD
4.1 Header . . . . . . . .
4.2 Connection Settings
4.3 Object Management
4.4 Precision of Tests . .
4.5 Mechanisms . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
14
14
14
15
15
16
Cryptosense Analyzer allows to test your cryptographic devices for compliance and security
issues. This reference manual documents all features of the tool. For a quick start you may
want to take a look at Cryptosense – Getting Started instead.
1
Install
Cryptosense Analyzer is a standalone tool. Installing it is as simple as putting the executable
in a directory of your choice. The executable is named cs on Linux and cs.exe on Windows.
For convenience you may want to put the executable in a directory which is in your PATH
environment variable, such as /usr/local/bin on Linux.
Prerequisites A typical session uses about 200 MB of free memory. This number will go up as
the session lasts longer. Test results are stored in files whose size is proportional to the number
of tests. Short sessions require only a few megabytes, while long sessions can produce files which
use several gigabytes of hard drive space.
Before you get started, make sure the device you want to test is connected. For PKCS#11
devices you need to know the location of the PKCS#11 DLL, as well as the user PIN.
Make sure that you have backups for all key materials before running Cryptosense Analyzer
on a device. Cryptosense Analyzer will not delete preexisting keys, but it tends to reveal bugs
and those bugs may in turn require you to reset the device.
2
2.1
Overview
Commands
Cryptosense Analyzer is a command-line tool, which means it is supposed to be executed from
a terminal. It can also easily be called from scripts.
Similarly to other command-line tools such as Git, it provides several commands. The
complete set of commands is given in Section 3.
In this manual we assume the path to the cs executable to be in the PATH environment
variable. This means that to call command help for instance, we write cs help. This command
displays help on the command-line (see Section 3.4).
2.2
CSD: Device Description Files
A CSD, which stands for Cryptosense Device, is a configuration file which contains information
about how to connect to the device to analyse. You only have to create it once for each device,
and it can be edited by hand easily if needed. It uses the JSON format.
It is the input of the cs test command (see Section 3.8).
See Section 3.3 for information about how to create a new CSD for a PKCS#11 device, and
Section 4 for details about its contents. As well as connection information, it contains various
useful options and allows you to select which commands, attributes and mechanisms to test.
2.3
CST: Test Result Files
A CST, which stands for Cryptosense Tests, is a file which contains the results of tests which
were performed on a device. A CST is needed before performing any in-depth analysis.
It is the output of the cs test command (see Section 3.8), and the input of the cs comply
command (see Section 3.2).
4
2.4
Typical Workflow: Testing a PKCS#11 Device
Here is an example where Cryptosense Analyzer is used to test a PKCS#11 device.
1. Ensure the device is connected and initialized. Find out the location of its PKCS#11
driver DLL and the user PIN code.
2. Use cs csd-pkcs11 to create a CSD with the device configuration (see Section 3.3).
3. (optional) Open the CSD and review the configuration. Remove features that you don’t
want to test (see Section 4).
4. Use cs test to test the device described in the CSD and obtain a CST (see Section 3.8).
This may reveal bugs from the device firmware or driver, such as segmentation faults. In
this case, the CST should still exist.
5. Use cs comply to check compliance properties from results contained in the CST (see
Section 3.2).
3
Commands
3.1
cs cleanup — Cleanup Device
Warning On PKCS#11 devices, this command deletes keys: check that it will not delete
important ones.
The cs cleanup command cleans up a device after a Cryptosense analysis. Normally,
Cryptosense Analyzer cleans up automatically after its analysis; but if, say, the connection was
lost, maybe it was not able to. This command asks for confirmation before actually deleting
anything.
On PKCS#11 devices, this command removes all keys whose CKA LABEL attribute starts with
the value of the "cka label" field of the CSD (see Section 4.3). Command C FindObjects is
used to list the keys to delete. This means that if a key cannot be seen using C FindObjects,
it will not be deleted.
3.1.1
Usage
To clean up a device described in CSD device.csd, run:
cs cleanup device.csd
3.1.2
Command-Line Options
• --force: Do not prompt for confirmation. Keys are listed and then immediately deleted;
use with care.
3.2
cs comply — Check Compliance
The cs comply command takes a CST, i.e. results from cs test, and checks compliance
properties. A CST is a sequence of calls to the device and each call may be relevant for a
number of compliance properties; each of them are tested and accounted for. Results are shown
on the command-line.
5
3.2.1
Usage
To check compliance properties on a CST named device.cst, run:
cs comply device.cst
To save the results into a file named device-compliance-results.txt, run:
cs comply device.cst > device-compliance-results.txt
3.2.2
How to Read the Results
Here is a short extract as an example:
C_GenerateKey
Template matches:
100% (234 tests, 0 failed)
Reference: v2.20 p63 s10.1.1
Default value of CKA_TOKEN is CK_FALSE:
100% (175 tests, 0 failed)
Reference: v2.20 p71 s10.4
Default value of CKA_MODIFIABLE is CK_TRUE: 100% (191 tests, 0 failed)
Reference: v2.20 p71 s10.4
C_CreateObject (RSA, private)
Cannot set CKA_TRUSTED to CK_TRUE:
N/A (untested)
Reference: v2.20 p66,73,81,85 s10.2,10.6.2,10.8,10.10
Ensure CKA_ALWAYS_SENSITIVE is CK_FALSE:
3% (32 tests, 31 failed)
Reference: v2.20 p128 s11.7
Ensure CKA_NEVER_EXTRACTABLE is CK_FALSE:
96% (32 tests, 1 failed)
Reference: v2.20 p128 s11.7
Each command has its own section. Here we see two commands, namely C GenerateKey and
C CreateObject (RSA, private). The (RSA, private) precision means that the section is
about C CreateObject used to create RSA private key objects.
For each command, there are a number of compliance properties. Template matches is
such a property, and we see here that 234 tests in the CST are relevant for this property. Out
of those 234 tests, none showed any issue, resulting in a 100% success rate. Property Ensure
CKA ALWAYS SENSITIVE is CK FALSE, however, has only a 3% success rate: out of 32 relevant
tests, only one did not fail the compliance property.
For each command there is also a reference. v2.20 means that it refers to the PKCS#11
2.20 Cryptographic Token Interface Standard1 . Relevant page numbers from the PDF version
(e.g. p63) and section numbers (e.g. s10.1.1) are given.
Finally, some results may be marked N/A (untested). This means that the CST contains
no relevant test for the compliance property. Here, this is the case for Cannot set CKA TRUSTED
to CK TRUE. This is either because C CreateObject was not tested with CKA TRUSTED set to
CK TRUE, in which case you may want to re-run cs test for a longer amount of time; or because
CKA TRUSTED is not supported by the device.
3.2.3
Command-Line Options
• --force: Do not prompt for confirmation. This may cause cs comply to overwrite the
output file.
1
RSA Security Inc. Public-Key Cryptography Standards (PKCS)
6
3.3
cs csd-pkcs11 — Create PKCS#11 CSD
Warning Supplying the wrong PIN or the wrong slot number may cause the device to
be PIN-locked.
The cs csd-pkcs11 command creates a new CSD describing a PKCS#11 device. This CSD
can be given to cs test (see Section 3.8) or cs info (see Section 3.5) to start the analysis.
3.3.1
Usage
Basic usage is as follows:
cs csd-pkcs11 -d DLL -s SLOT -p PIN device.csd
where DLL is the location of the PKCS#11 driver DLL, SLOT is the index of the slot you want
to test (default is the first slot, of index 0) and PIN is the user PIN code for the token which is
in this particular slot. The result is saved in a new file named device.csd. If this file name is
not specified, the result is printed on the standard output.
3.3.2
Command-Line Options
• -d DLL, --dll=DLL: Path of the PKCS#11 DLL to load, including filename and extension
(usually .so on Linux, .dll on Windows). This argument is mandatory.
• --force: Do not prompt for confirmation. This may cause cs csd-pkcs11 to overwrite
the output file.
• -h COUNT, --max-handle-count=COUNT: Maximum number of handles that the device
can hold at the same time. Any excess handle causes the oldest one to be destroyed
automatically during testing, to avoid using too much memory on the device.
Default value is 10. You may want to specify a greater value if your device has a good
amount of memory. Higher values mean that the analysis will take less time, as keys need
to be recreated less often. Low values cause the analysis to be less precise, as less tests
can be performed.
On smartcards, this value should not be very high; for instance, the default value of 10
should be fine, except on very low-memory models. On HSMs, you can use much higher
values. Setting this value to about 1000 is reasonable.
• --no-strict-cleanup: By default, testing stops if a key cannot be destroyed. This
setting disables this behavior.
The default behavior contains a failsafe which prevents your device from being filled with
keys that cannot be deleted. Indeed, cs test generates or creates new keys on your
device. Eventually, all of those keys are destroyed. If a key cannot be destroyed, cs test
will not perform any new test, as there is a risk that it will create more such keys.
If you don’t care about filling up your device, you can use --no-strict-cleanup to
disable the failsafe. At some point the token will probably stop accepting new keys and
you will have to delete the keys yourself, for instance by reinitializing the token.
• -p PIN, --pin=PIN: User PIN. This argument is mandatory, but it can be empty ("").
Be wary that some devices will lock after a certain number of login attempts have failed.
If cs test stops immediately with error CKR PIN INCORRECT, fix the PIN in the CSD
before continuing.
7
• -s SLOT, --slot=SLOT: Token slot index. The first slot has index 0. Default value is 0.
This is only relevant for devices with multiple slots. Note that some devices may have
more PKCS#11 slots than actual physical slots.
If you don’t know in which slot your token is inserted, you can use default value 0 and
run cs info --safe (see Section 3.5) to list all slots. The --safe option ensures that
Cryptosense Analyzer does not try to log in, which could PIN lock the device if done on
the wrong slot.
• --max-template-size=COUNT: Set the size of tested templates to COUNT. High values mean
more in-depth testing, but it also means that cs test will take more time to initialize.
The default value should be more than enough as it is impossible to test all templates in
a reasonable time anyway.
3.4
cs help — Command-Line Help
The cs help command displays help for another command. It can be seen as a short, easily
accessible version of this reference manual.
3.4.1
Usage
To display help on command test for instance, run:
cs help test
3.4.2
Command-Line Options
• --man-format=FMT: Show output in format FMT (pager, plain or groff). On Linux, the
default is pager, which usually means that the help is displayed using less. On Windows,
the default is plain, which means that the help is printed on standard output directly.
You should use plain if no pager is available.
3.5
cs info — Show Device Information
The cs info command connects to a device to request and display information. It is convenient
to check that communication with the device works before any actual testing.
3.5.1
Usage
To connect to a device described in CSD device.csd, run:
cs info device.csd --safe
If you need to show more information, try:
cs info device.csd
Warning On PKCS#11 devices, removing --safe will cause cs info to use the PIN
and the slot index from the CSD to login. If you entered the wrong PIN, this may lock
your device.
8
3.5.2
PKCS#11 Device Information
For each slot, cs info displays:
• the result of C GetSlotInfo;
• the list of mechanisms returned by C GetMechanismList;
• for each of those mechanisms, the result of C GetMechanismInfo;
• the result of C GetTokenInfo.
Then cs info uses the slot index and the PIN from the CSD to open a session and display:
• the result of C GetSessionInfo.
Finally, unless --safe is specified, cs info logs in using the PIN and the slot index from the
CSD and displays:
• the keys returned by C FindObjects with an empty template as input;
• the template of each of those keys, including the key values if they can be read using
C GetAttributeValue.
Note that not all keys will be shown. In particular, keys from other sessions are normally only
returned by C FindObjects if they are public2 token3 keys.
3.6
cs load-testing — Perform Load-Testing on a Device
The cs load-testing command connects to a device and runs cs test (see Section 3.8) several
times, possibly in parallel. Each run of cs test is called a job.
3.6.1
Usage
To test three devices described in CSDs device1.csd, device2.csd and device3.csd, run:
cs load-testing -d device1.csd -d device2.csd -d device3.csd
This will test the devices sequentially, with one job per device. To run all of them in parallel,
add -j 3:
cs load-testing -d device1.csd -d device2.csd -d device3.csd -j 3
To run two jobs per device, for a total of 6 jobs, add -n 6:
cs load-testing -d device1.csd -d device2.csd -d device3.csd -n 6
In particular, running:
cs load-testing -d device.csd -n 6
Will run a sequence of 6 jobs on the same device device.csd. You can of course add -j with
any value from 1 to 6.
Note that the CSDs may denote the same actual device. A typical example is to have one
CSD per slot for a PKCS#11 device.
2
3
“public” here means CKA PRIVATE = CK FALSE.
“token” here means CKA TOKEN = CK TRUE.
9
3.6.2
Command-Line Options
• -c COUNT, --count=COUNT: Number of tests each job will perform. This option is passed
to each job.
• -d CSD, --device=CSD: Input device information file and test parameters. This argument
is mandatory and may appear several times.
• --fuzzing=VAL: Ratio of fuzzing tests each job will perform. See Section 3.8.3.
• --ignore: Do not create CSTs. The default behavior is to create a CST for each job,
with name CSD-UID.cst where CSD is the CSD filename without the extension and UID is
the job number.
• -j N, --jobs=N: Allow N jobs at once. Default is 1, which means that jobs are executed
sequentially. Cannot be greater than the v alue of -n.
• -n VAL: Number of jobs to run. The default value is the number of CSDs which were
provided using -d. If VAL is higher than this default value, the same CSDs will be reused.
• --random: Randomize the order of the tests.
3.7
cs stats — Display CST Statistics
The cs stats command displays statistics about a CST. Those statistics are exactly the ones
that were displayed by cs test at the end of the analysis. If you are looking for statistics about
compliance properties, see cs comply (Section 3.2).
Statistics displayed by cs stats are useful to get an overview of which commands are
available.
3.7.1
Usage
To display statistics for CST device.cst, run:
cs stats device.cst
3.7.2
How to Read the Results
Here is a short extract as an example:
C_GetTokenInfo
C_GenerateKey
C_GenerateKeyPair
C_CreateObject (DES)
C_CreateObject (DES3)
C_CreateObject (AES)
|
|
|
|
|
|
1
33313
33313
33313
33313
33313
T
T
T
T
T
T
|
|
|
|
|
|
1
8731
192
3953
3953
4838
S
S
S
S
S
S
|
|
|
|
|
|
24582
33121
29360
29360
28475
E
E
E
E
E
|
|
|
|
|
|
0.003s
5.466s
4.757s
2.784s
2.854s
3.572s
|
|
|
|
|
|
0
0
0
0
0
0
Here is the meaning of each column:
• column 1 (e.g. C GetTokenInfo) is the name of the command being considered;
• column 2 (e.g. 33313 T) is the number of tests which were performed;
• column 3 (e.g. 8731 S) is the number of successes, i.e. tests for which the command
returned CKR OK;
10
• column 4 (e.g. 24582 E) is the number of errors, i.e. tests for which the command did
not return CKR OK;
• column 5 (e.g. 5.466s) is the total time spent in the execution of the command;
• column 6 is the remaining number of tests in the queue – it is always 0 for cs stats, and
it may go up and down during cs test as new results from, say, C GenerateKey mean
that more tests for, say, C Encrypt can be performed;
• additionally, an additional column may appear with the number of failures, displayed with
an F suffix;
• additionally, if fuzzing tests were performed, additional columns may appear with the
number of successes, errors and failures for fuzzing tests, displayed with an Sf, Ef and a
Ff suffix respectively (see the --fuzzing option of cs test, Section 3.8.3).
3.7.3
Errors and Failures
The difference between an error (E) and a failure (F) is that errors are expected while failures
are not. For instance, if command C GenerateKey returns CKR TEMPLATE INCONSISTENT, it is
an error as it successfully refused to generate a key because of the requested template. However,
CKR GENERAL ERROR is unexpected and is considered a failure.
3.8
cs test — Test Device
The cs test command connects to a device and runs tests to create a CST. The longer it runs,
the more tests it performs, and the more precise further analyses can be.
Each test generally corresponds to one command call. The Cryptosense methodology is
unique as it reuses the results of previous tests to fuel the inputs of other tests. On PKCS#11,
Cryptosense will look for tests to perform and will find that it can only call a few functions such
as key generation. Once it has generated a key, it automatically finds out that this key can be
used to test encryption, and then it finds out that the ciphertext resulting from this encryption
can be used to test decryption. Eventually it will have performed a sequence of tests which is
perfectly tailored for your device.
This also means that Cryptosense Analyzer will probably not run out of tests to perform.
There is even an infinite mode where it will not stop until the user interrupts the process using
Ctrl+C.
3.8.1
Usage
Let’s assume you want to test a device described in CSD device.csd. To perform the default
number of tests, use:
cs test device.csd
If you want to run, say, a million tests, use:
cs test device.csd -c 1000000
If you want to run an infinite run, use:
cs test device.csd -i
11
3.8.2
How to Read the Results
On POSIX terminals, i.e. most Linux terminals as well as the Cygwin terminal for Windows,
cs test outputs statistics using the same format that cs stats (see Sections 3.7.2 and 3.7.3).
These statistics are updated in real-time.
On other terminals, such as cmd.exe on Windows, cs test will output the number of tests
it has performed, every five seconds. It will output the statistics only after the analysis is
interrupted or finished.
Note that you can make Cryptosense Analyzer believe it is not in a POSIX terminal by
setting the TERM environment variable to dumb. For instance, you can run:
TERM=dumb cs test device.csd
3.8.3
Command-Line Options
• -c COUNT, --count=COUNT: Number of tests to perform. Default is 10000.
• --compact: Output a smaller but less readable CST.
• --force: Do not prompt for confirmation. This may cause cs test to overwrite the
output file.
• --fuzzing=VAL: Ratio of fuzzing tests to perform. Fuzzing test are command calls which
are invalid according to the standard, such as trying to use an RSA key to encrypt using
a DES mechanism.
VAL is the amount of fuzzing to do, expressed as a ratio of the number of non-fuzzing
tests. Setting the value to 1.0 will aim at having as many fuzzing tests as non-fuzzing
tests done. Setting the value to 0.5 will aim at having half as many fuzzing tests done
as non-fuzzing tests. Note that this value tunes the asymptotic behavior of the testing
mechanism for each command.
Default is 0.5, i.e. there will be about 1 fuzzing test for 2 regular tests.
• -i, --interactive, --infinite: Run until the user hits Ctrl+C. This overrides option
-c.
• --random: Randomize the order of the tests.
3.9
cs version — Show Cryptosense Analyzer Version
The cs version command prints the version number of Cryptosense Analyzer. It can also
show the build number.
3.9.1
Usage
To print the version number, run:
cs version
To print the build number, run:
cs version --build
12
3.9.2
Command-Line Options
• --build: Show build number instead of version number.
• --full: Show both version and build number.
3.10
Common Command-Line Options
Most of the commands, including cs test, and cs info, accept additional options, which are
described in this section.
3.10.1
Logging API Calls
Option --log-calls causes all API calls to be written in a log file. The name of this file is
chosen automatically unless option --log-calls-filename=FILE is used as well to specify it.
The default log filename is of the form api-calls-XXXX.log where XXXX are chosen so that the
file does not exist already.
Usage A typical use case is when cs test causes a segmentation fault in the PKCS#11 driver
DLL. To find out which call caused the segmentation fault, one may run cs test as follows:
cs test device.csd --log-calls
This creates a file with a name such as api-calls-0000.log. At the end of this file, the inputs
of the command which caused the error can be found.
Example Here is an extract of such a log file for a PKCS#11 device:
C_Initialize -> driver = <abstract>
C_Initialize <- CKR_OK
C_GetSlotList -> driver = <abstract>
C_GetSlotList -> tokenPresent = CK_FALSE
C_GetSlotList <- slotID = [ 0 ]
C_OpenSession -> slotID = 0
C_OpenSession -> CKF_RW_SESSION = true
C_OpenSession <- session = <abstract>
C_Login -> userType = CKU_USER
C_Login -> pin = "1234"
C_Login <- CKR_OK
C_GenerateKey -> mechanism = CKM_AES_KEY_GEN(16)
C_GenerateKey -> template = [ CKA_VALUE_LEN = 16 ]
C_GenerateKey <- key = 1
and here is how to read part of it.
• C Initialize -> driver = <abstract>
Call the C Initialize command of a driver. Drivers cannot be represented and are thus
designed as abstract.
• C Initialize <- CKR OK
Command C Initialize returned CKR OK.
13
• C GenerateKey -> mechanism = CKM AES KEY GEN(16)
C GenerateKey -> template = [ CKA VALUE LEN = 16 ]
Call C GenerateKey with mechanism CKM AES KEY GEN, asking for a 16-byte key.
• C GenerateKey <- key = 1
Command C GenerateKey returned CKR OK and returned a new key handle. The CK ULONG
value of this handle is 1.
3.10.2
Quiet and Verbose Modes
Options -q and --quiet activate quiet mode. In quiet mode, Cryptosense Analyzer tries to
avoid printing messages, errors and warnings to the user.
Options -v and --verbose activate verbose mode. In verbose mode, Cryptosense Analyzer
displays more messages, errors and warnings to the user.
Quiet mode overrides verbose mode.
3.10.3
--help and --version
Option --help is equivalent to running cs help on the current command. For instance, cs
test --help is equivalent to cs help test. You can also specify the format using --help=FMT.
This is equivalent to cs test --man-format=FMT (see Section 3.4.2).
Option --version is equivalent to running cs version. For instance, cs test --version
is equivalent to cs version.
4
PKCS#11 CSD
This section describes the contents of PKCS#11 CSD. Section 3.3 explains how to obtain such
a file easily using command cs csd-pkcs11. However, some configuration options can only be
modified by editing this file by hand. This includes deactivating commands, mechanisms or
attributes.
For options which are available through cs csd-pkcs11, you will find more documentation
in Section 3.3.2.
4.1
Header
The first fields compose the header of the CSD and should not be modified.
• "format" should be "CSD".
• "build" is the build number of Cryptosense Analyzer when the CSD was originally created.
• "version" is the version number of Cryptosense Analyzer when the CSD was originally
created.
• "api" should be "pkcs11".
4.2
Connection Settings
14
Warning Supplying the wrong PIN or the wrong slot number may cause the device to
be PIN-locked.
The following fields describe how to open a session on the device.
• "dll" contains the location to the PKCS#11 driver DLL for the device. It corresponds
to the --dll option of cs csd-pkcs11.
• "slot" is the index of the slot on which to open a session. It corresponds to the --slot
option of cs csd-pkcs11.
• "pin" is the user PIN used to open a session. It corresponds to the --pin option of cs
csd-pkcs11.
4.3
Object Management
The following fields provide control over objects created by Cryptosense Analyzer on your device.
• "max handle count" is the maximum number of handles that the device can hold at the
same time. It corresponds to the --max-handle-count option of cs csd-pkcs11.
• "strict cleanup", if set to "true", makes Cryptosense Analyzer stop if a key cannot be
destroyed. Setting it to "false" corresponds to the --no-strict-cleanup option of cs
csd-pkcs11.
• "cka label" is the value of CKA LABEL for all objects which are created by Cryptosense
Analyzer. Its default value is "cryptosense". If Cryptosense Analyzer fails to destroy
keys it created, this label can help you remove them.
• "cka label uid", if set to "true", causes a unique integer to be appended to CKA LABEL
for objects which are created by Cryptosense Analyzer. This is helpful to follow one
particular key in the logs.
4.4
Precision of Tests
The following fields provide control over the set of tests that will be performed by Cryptosense
Analyzer. There is a trade-off between precision and time: the more precise the analysis, the
longer it takes to reach a particular test. You may also want to deactivate features which you
know are not implemented, or which take longer to analyse. For instance, RSA is usually much
slower than DES, especially with longer keys.
• "commands" is the list of commands to test. Each command can be either tested ("true")
or not tested ("false").
• "attributes" is the list of attributes to test. Each attribute can be either tested ("true")
or not tested ("false").
• "mechanisms" is the list of mechanisms to test. Each item is a particular mechanism,
with some particular parameters. See Section 4.5 for more information.
• max template size is a limit on the size of templates which are tested. It corresponds to
the --max-template-size option of cs csd-pkcs11.
15
4.5
Mechanisms
The "mechanisms" field of the CSD is the list of mechanisms to test. All mechanisms follow
the following format:
• if the mechanism has no parameter, it is a string, such as "CKM DES KEY GEN";
• if the mechanism has parameters, it is a record with a field "mechanism" containing the
name of the mechanism, such as "CKM AES KEY GEN", and with other fields corresponding
to the parameters of the mechanism.
Here is an example of a "mechanisms" field with the list of all mechanisms which are supported
by Cryptosense Analyzer:
"mechanisms": [
{ "mechanism": "CKM_AES_KEY_GEN", "size": 16 },
{ "mechanism": "CKM_AES_KEY_GEN", "size": 24 },
{ "mechanism": "CKM_AES_KEY_GEN", "size": 32 },
"CKM_DES_KEY_GEN",
"CKM_DES3_KEY_GEN",
{
"mechanism": "CKM_RSA_PKCS_KEY_PAIR_GEN",
"size": 512,
"exponent": "010001"
},
{
"mechanism": "CKM_RSA_X9_31_KEY_PAIR_GEN",
"size": 512,
"exponent": "010001"
},
"CKM_DES_ECB",
{ "mechanism": "CKM_DES_CBC", "iv": "3338313733303138" },
{ "mechanism": "CKM_DES_CBC_PAD", "iv": "3338313733303138" },
"CKM_DES3_ECB",
{ "mechanism": "CKM_DES3_CBC", "iv": "3338313733303138" },
{ "mechanism": "CKM_DES3_CBC_PAD", "iv": "3338313733303138" },
"CKM_AES_ECB",
{ "mechanism": "CKM_AES_CBC", "iv": "33383137333031383139383332383337" },
{
"mechanism": "CKM_AES_CBC_PAD",
"iv": "33383137333031383139383332383337"
},
"CKM_RSA_PKCS",
{
"mechanism": "CKM_RSA_PKCS_OAEP",
"hash": "CKM_SHA256",
"mask": "CKM_SHA256",
"source": ""
},
"CKM_RSA_X_509",
"CKM_DES_MAC",
{ "mechanism": "CKM_DES_MAC_GENERAL", "size": 8 },
16
"CKM_DES3_MAC",
{ "mechanism": "CKM_DES3_MAC_GENERAL", "size": 8 },
"CKM_AES_MAC",
{ "mechanism": "CKM_AES_MAC_GENERAL", "size": 8 },
"CKM_SHA1_RSA_PKCS",
"CKM_SHA256_RSA_PKCS",
"CKM_SHA384_RSA_PKCS",
"CKM_SHA512_RSA_PKCS",
{
"mechanism": "CKM_RSA_PKCS_PSS",
"hash": "CKM_SHA256",
"mask": "CKM_SHA256",
"salt_length": 0
},
{
"mechanism": "CKM_SHA1_RSA_PKCS_PSS",
"hash": "CKM_SHA256",
"mask": "CKM_SHA256",
"salt_length": 0
},
{
"mechanism": "CKM_SHA256_RSA_PKCS_PSS",
"hash": "CKM_SHA256",
"mask": "CKM_SHA256",
"salt_length": 0
},
{
"mechanism": "CKM_SHA384_RSA_PKCS_PSS",
"hash": "CKM_SHA256",
"mask": "CKM_SHA256",
"salt_length": 0
},
{
"mechanism": "CKM_SHA512_RSA_PKCS_PSS",
"hash": "CKM_SHA256",
"mask": "CKM_SHA256",
"salt_length": 0
}
]
This is what you obtain after running cs csd-pkcs11. You may change values such as initialization vectors and public exponents, and you may remove some mechanisms.
The meaning of parameters is as follows.
• "size" is the size of keys to be generated (for generation mechanisms) or of the hash to
be computed (for MAC mechanisms). For RSA mechanisms, the size is in bits; for other
mechanisms, it is in bytes.
• "exponent" is the RSA public exponent, in hexadecimal.
• "iv" is the initialization vector, in hexadecimal.
17
• "hash" is the hash function, which is itself a mechanism.
• "mask" is the mask generation function, which is itself a mechanism.
• "source" is the source string, in hexadecimal.
• "salt length" is the length of the salt, in bytes.
18

Download Report