=============================================
QPTOOL2 PKCS11 Demo Application
=============================================

For PKCS11, you should have a User and a Security Officer pre-configured.

-----------------------------------------
STEPS to initialize slot 0 of PKCS#11 API
-----------------------------------------
 
- previously needed: installation of SecurityServer, e.g. v6.0.1.0 (to provide P11 tool)
  (alternative: just the p11tool2 binary accessible + the ADMIN key file)
- the default ADMIN keyfile should be reference with ADMINKEY2 
  (e.g. set ADMINKEY2=C:\Utimaco\SecurityServer\Administration\ADMIN_SIM.key)
 
 
# INITTOKEN (ADMIN->SO):  for slot 0: init token, creates the SO (security officer)
p11tool2 slot=0 login=ADMIN,%ADMINKEY2% inittoken=10203040
 
# SETPIN (SO->SO):  SO changes his/her initial PIN:
# 10203040 is a throwaway password, the actual desired key is that last
# password given on the following line.
p11tool2 slot=0 loginSO=10203040 setpin=10203040,12345677
 
# INITPIN (SO->USER):  SO creates the USER:
p11tool2 slot=0 loginSO=12345677 initPIN=50607080
 
# SETPIN (USER->USER):  USER changes their initial PIN:
# 10203040 is a throwaway password, the actual desired key is that last
# password given on the following line.
p11tool2 slot=0 loginUser=50607080 setPIN=50607080,12345688
 
# as the result, the PIN for the SO is 12345677 and for the USER 12345688,
# or as provided locally.
# csadm listuser --> shows users ADMIN, SO_0000, USER_0000 all with attribute "I[0]"

-------------------------------------------
STEPS to prepare the Visual Studio Solution
-------------------------------------------

For Windows and the Visual Studio Solution, you need to have the environement
variable "INCLUDE_P11_DIR" set.  It should point to the 
.../Crypto_APIs/PKCS11_R3/include directory in your installation.

Then launch the solution in Visual Studio.

=============================================
Base Reproducer
=============================================

If Utimaco asks you for a "reproducer" for your issue, you can use this base 
library as the framework for demonstrating the issue.

There are three source files:

* pkcs11_testcase_main.c:
* pkcs11_testcase_utilities.c:
* test_case.c

You will be reworking test_case.c to demonstrate the problem you are having.

You should not incorporate any third party libraries or modules.  Utimaco is
only responsible for problems in our code, or in your usage of our code.  
Reproducers that rely on third party code/libraries will be rejected as
undebuggable.
 
Your code example should provide an entry point into our libraries, which
will allow us to debug what is happening.  

Prerequisites
=============

We assume for all up-coming sections, that you've already done the following 
steps.

Windows
-------

You've already launched the Windows CryptoServerSetup installer on the 
CryptoServer product CD. The installer automatically sets several environment 
variables, like  ``%CS_PKCS11_R3_CFG%`` and ``%CS_PATH%``

Linux
-----

First copy from the CryptoServer product CD - depending on your system - either
the folder ``Software/Linux/x86-32/Crypto_APIs/PKCS11_R3`` or the folder  
``Software/Linux/x86-64/Crypto_APIs/PKCS11_R3`` to a location where you have 
write permissions. This location will be referred to as <your sample location>. 

You have as well already copied from the CD the folder 
``Software/Linux/Simulator/sim5_linux`` to a location of your convenience. 

You have ensured that you have write permissions on all files and folders in 
the new simulator location. This new simulator location will be referred to 
as <your simulator location>. 

 
Running the example test_case.c
====================================

In order to run a PKCS#11 application you'll first have to adapt the PKCS#11 
configuration file ``cs_pkcs11_R3.cfg``.

Windows
-------

Find your configuration file: Open a DOS command-line window and type

    echo %CS_PKCS11_R3_CFG%
    
The path to the configuration file ``cs_pkcs11_R3.cfg`` will display.

If you want to use for test purposes the HSM simulator, then edit the line 
under ``[CryptoServer]`` in the configuration file to

    [CryptoServer]
    # Device specifier 
    Device = 3001@127.0.0.1

For HA/Failover scenarios, the configuration may be set to

    [CryptoServer]
    # Device specifier 
    Device = { 3001@127.0.0.1 3003@127.0.0.1 3005@127.0.0.1 }

or similar.

    
Save the configuration file. Then start the (singleton) HSM simulator by 
clicking on the simulator icon, or navigate to the simulator's bin directory, 
and launch the simulators using ``.\cs_multi.bat <count>``.

To verify the configuration, use the commands

    p11tool2 GetLocalConfig=*

and

    p11tool2 ListSlots=Status

Non-standard responses should be fixed before continuing.


Linux
-----

We assume here, that you've already read the section Prerequisites.
 
Check whether the environment variable for the configuration file is set. In 
a terminal type

    echo $CS_PKCS11_R3_CFG
    
If it is empty, then set this variable to the location of the PKCS#11 config
file.  ``<your sample location>/PKCS11_R3/sample/cs_pkcs11_R3.cfg``. Open the 
configuration file and edit the line under the section``[CryptoServer]``, such 
that ``Device=`` is set to the IP or PCI address of your Cryptoserver. Or, 
alternatively, use the HSM simulator. For the simulator edit the line as follows:

    [CryptoServer]
    # Device specifier 
    Device = 3001@127.0.0.1

For HA/Failover scenarios, the configuration may be set to

    [CryptoServer]
    # Device specifier 
    Device = { 3001@127.0.0.1 3003@127.0.0.1 3005@127.0.0.1 }

or similar.

    
Save the configuration file. Then start the HSM simulator, navigate to the 
simulator's bin directory, and launch the simulator(s) using either 
``./cs_sim.sh`` (singleton) or ``./cs_multi.sh <count>``, depending on your 
configuration setting.

To verify the configuration, use the commands

    p11tool2 GetLocalConfig=*

and

    p11tool2 ListSlots=Status

Non-standard responses should be fixed before continuing.


Compiling the sample files
==========================

Windows
-------

Copy the relevant cs_pkcs11_R3.dll file from 
``<path\to\installation>\Crypto_APIs\PKCS11_R3\lib`` to the 
``<reproducer location>\bin`` directory.

The paths to the necessary header files are defined using the 
environement variable ``INC_DIR_P11``:

    set INC_DIR_P11=<path\to\installation>\Crypto_APIs\PKCS11_R3\include

Choose the Visual Studio Version of your choice. Go to the corresponding folder 
``prj_xx`` and open the file ``Reproducer.sln`` with Visual C++.  

``Build -> Build Solution`` to recompile all files. 

The output executable is found in the ``bin`` folder.

Linux
-----

In order to compile the sample files under Linux, use the ``Makefile`` in 
the folder ``<reproducer location>/mak``. Adjust the ``Makefile`` to fit 
your needs by editing the following variables in the file 
``<reproducer location>/mak/config.inc``.

CC
            Adjust the path to your C compiler executable.
INC_DIR_P11
            Adjust the path </path/to/installation>/Crypto_APIs/PKCS11_R3/include

Enter the folder ``<reproducer location>/mak``. Type ``make`` to compile all sample files. 

Type ``make clean`` to remove all executables and object files. 

The executables are found in the ``<reproducer location>/bin`` folder.

===================================
Providing the Reproducer to Utimaco
===================================

Once you have source code that recreates your issue, using standard PKCS11 calls 
and NO third party libraries, please provide the test_case.c file to Utimaco 
Support.

If you have to modify the setup in pkcs11_testcase_main.c or if you add a utility
function/method to pkcs11_testcase_utilities.c, you can provide those also.

Utimaco Support will place the supplied files into our framework, recompile and
run the reproducer, and provide commentary from there.

//modification history
01a,2025-05-05,riw Added specific notes for PKCS11 qptool2
01a,2024-01-23,riw fwv

