Quantum Protect - version 1.5.0.0
=================================

This package contains

  - the Quantum Protect simulator
  - extensive sample code showing how to call the different PQC
    algorithms; the sample code is for use with Utimaco's PKCS11 API
    (extended with VDM) and the CXI API Java (extended with wrapping
    classes)
  - pre-built demo tool qptool2
  - Quick Start Guide documentation

To use this package:

  Just unzip the archive and navigate the resulting folder tree.
  The simulator is designed to run independently and already contains
  the PQC firmware modules along with the SecurityServer firmware.

  Make sure to have the generic Utimaco SecurityServer software
  installed (see Utimaco Download Portal, "simulator"). This provides
  csadm and other tools and APIs to access the simulator.

  To start the simulator in Windows, run the file
    cs_sim.bat
  in the folder "QuantumProtect Evaluation\sim5_windows\bin".

  For Linux, use the corresponding shell script
    cs_sim.sh
  in the folder "QuantumProtect Evaluation\sim5_linux\bin".
  (For the write and execute permissions: chmod -R u+w+x sim5_linux)

  Note also the demo tool qptool2 in the sample code bin folder
  (QuantumProtect Evaluation\Crypto_APIs\PKCS11_R3\samples\qptool2\bin):

Pre-configured Simulators

  Simulators are provided for Windows and Linux, pre-configured with the
  extent PQC modules (pqmi, hbs, ml, ...).

  Additionally, depending on release, the simulators may come pre-configured
  with PKCS11 Users and Security Officers for slot 0.

  **If** the provided simulator has a prepared PKCS11 slot 0, the demo PIN for
  the SO is 12345677 (double-seven) and for the USER is 12345688 (double-eight). 
  
  For non-PKCS11 prepared simulators, the technique for adding these users is 
  described in the Crypto_APIS/PKCS11_R3/sample/qptool2 README.

  With the simulator running, two sample QP demo tool calls would be (each
  in one single command line):

    qptool2 -lib c:\Utimaco\SecurityServer\Lib\cs_pkcs11_R3.dll
            -pin 12345688 -slot 0 -lms

    qptool2 -lib c:\Utimaco\SecurityServer\Lib\cs_pkcs11_R3.dll
            -pin 12345688 -slot 0 -mlkem -keytype 3 -gen -encap -decap

  Note also that the options -kyber and -dil are not available at this time
  (as CRYSTALS-Kyber and CRYSTALS-Dilithium have been superseeded by FIPS
  203/ ML-KEM and FIPS 204/ ML-DSA). You can effectively choose the options
  -lms, -xmss, -hss, -mldsa <params>, -mlkem <params> according to the tool
  syntax (shown with "qptool2 -h").

  For using the sample code a Visual Studio (Windows) project is provided
  as well as a makefile (Linux). Regarding the underlying use of the API's
  PKCS11 or CXI please consult the Utimaco SecurityServer Documentation.
  (Especially for PKCS11, make sure to have the environment variable
  CS_PKCS11_R3_CFG defined, pointing to the PKCS11 configuration file.)

  The VS project relies on a preset Env var.  Please set "INC_DIR_P11" to 
  point to a standard SecurityServer installation, to the 
  .../Crypto_APIs/PKCS11_R3/include directory:

  $ cd ...\prj_14
  $ set INC_DIR_P11=c:\Utimaco\SecurityServer\Crypto_APIs\PKCS11_R3\include
  $ qptool2.sln


  To check the list of firmware modules currently running in the simulator
  use:
    csadm dev=3001@127.0.0.1 listfirmware


  The Quantum Protect Simulator (aka. QP Evaluation) already is provided
  ready-to-use. In case you want to use the provided PQC with an already
  installed SecurityServer simulator, make sure to have the following
  firmware modules removed as they could conflict with the QP Evaluation
  package:

  If any of OSCCA, BRICKS, IQR modules are found on the Simulator, they
  should be removed. This is due to the details of the PKCS11 VDM extension
  registration mechanisms and how they are currently implemented in the
  SecurityServer VDM handling. The PQMI module properly takes care of the
  PQC mechanisms registration, but the legacy modules OSCCA, BRICKS and IQR
  do the registration separately and shall thus not be used along with the
  PQC modules.

  Following is an example for removing OSCCA. If you need to remove IQR and
  or BRICKS also, that can be done using multiple
  "DeleteFile=<name>.msc" entries on the same command line.

  See the LoadFile example below for how that should look.

If necessary:

  (in general, the \<end of line> continuation markers do not work on
   Windows so just type it all out on one line)

csadm Dev=3001@127.0.0.1 LogonSign=<admin,credential> ... \
    DeleteFile=oscca.msc Restart

cd firmware//1.5.0.0/sim5_<arch>

csadm Dev=<device_locator> LogonSign=<admin,credential> \
    LoadFile=hbs_sim_<arch>.mtc \
    LoadFile=ml_sim_<arch>.mtc \
    LoadFile=pqmi_sim_<arch>.mtc \
    Restart

  After restart, in the bootlog of the Simulator/HSM you should see (i.a.):

  24.06.03 01:26:19 module 0xa2 (HBS) initialized successfully
  24.06.03 01:26:19 module 0xa5 (ML) initialized successfully
  24.06.03 01:26:19 module 0xa6 (PQMI) initialized successfully


CHANGELOG:

The changelog has been moved to the Quantum Protect Quickstart Guide pdf file.

------------------------------------------------------------------------------

REPORTING ISSUES

  To report issues found with this pre-release version, please email

  support-cs@utimaco.com

  with the following information:

  1. Your contact details (Name, organization and email address)
  2. The operation you were performing
     Note:  This may include a simple code example that demonstrates the
     problem.  Reports without a simple reproducer application based on the
     supplied example code may not get looked at as the time needed to 
     understand, compile, attempts to run etc will take longer than the time
     needed to identify the problem.
  3. What you expected to happen
  4. What happened (outputs from the test code, etc)
