Using panel.exe for key storage initialization

Edit online

Each application using CCA typically creates key objects that are stored in the host, protected by the master key stored inside the card. Perform the steps described in this topic for key storage initialization.

  1. The default locations for the files are setup by the CCA package in environment variables added in the new profile files /etc/profile.d/csulcca.sh and /etc/profile.d/csulcca.csh during installation. Key storage is unsupported without a master key loaded, so Master key load (Step 8) must be completed before this step. The utility panel.exe can be used to initialize both the default key storage and any separate key storage you might want to set up. The full topic is too lengthy for this explanation (see the key storage topics elsewhere in this manual, including the verb Key Storage Initialization (CSNBKSI)). In brief, an application can specify a particular key storage location. That non-default key storage can be initialized now (or later) by using panel.exe or with a program using the Key Storage Initialization verb.
  2. The key storage environment variables in the default user profile (/etc/profile.d/csulcca.sh) are changed at installation time to point to the /opt/IBM/CCA/keys/ path. There is one set of environment variables for a profile. Users can override this by setting a local profile in their home .profile file that sets the environment variables differently.
  3. Key storage ownership

    The default key storage files are actually partially created (but not fully initialized) during the master key load process. This means the ownership and permissions of those files might have to be changed for them to be fully initialized by the user associated with the application that uses the key storage files.

    Because of the mutually exclusive nature of the master key administrator groups, there can be some harmless access errors reported to the system log during master key load. The example users created previously in Master key load Step 7.3)a) avoids this. You do not need to fix key storage ownership because they were all created with the primary group set to cca_admin (the -g argument to useradd). By doing this, the first master key load creates the key storage files with group set to cca_admin and subsequent users all have membership in that group. You still might want to fix the owner of default key storage at the end to be the root user, but the group membership solves the access issue.

    Typically, the root user needs to fix the ownership and permissions. We recommend that the owner of key storage should be the root user, and that the group be cca_admin (cca_admin group is created during the CCA package install process). We recommend that the permissions be set to 660, which is rw for owner (root), rw for group (cca_admin), and <none> for everyone else, for security. Then add the application user to the group cca_admin with the appropriate procedure detailed in Master key load Step 8.a.

    To be able to use /opt/IBM/CCA/panel.exe, the user must be either root OR a member of the cca_admin group (the owner.group of /usr/lib64/libcsulccamk.so). The reasons for the separate cca_admin group are to allow one owner of /usr/lib64/libcsulccamk.so, and to allow use of panel.exe without allowing any of the master key processing calls.

  4. Key storage initialization with panel.exe. This is the default.
    1. Ensure that the permissions to the default location (/opt/IBM/CCA/keys/) allow your user to perform key storage initialization.
    2. Initialize key storage. DES is where CCA DES key tokens are kept, AES is where CCA AES and HMAC key tokens are kept, PKA is for all the CCA RSA public/private internal key tokens, and CMB (combined key storage) supports storage of all token types: CCA DES, CCA AES (AES and HMAC), CCA PKA (ECC, RSA, QSA), TR-31 DES and TR-31 AES (AES, HMAC) key tokens.

      panel.exe default syntax 

      /opt/IBM/CCA/bin/panel.exe --ks-type=AES --ks-init
/opt/IBM/CCA/bin/panel.exe --ks-type=DES --ks-init
/opt/IBM/CCA/bin/panel.exe --ks-type=PKA --ks-init
/opt/IBM/CCA/bin/panel.exe --ks-type=CMB --ks-init

      panel.exe legacy syntax

      /opt/IBM/CCA/bin/panel.exe -t AES -i
/opt/IBM/CCA/bin/panel.exe -t DES -i
/opt/IBM/CCA/bin/panel.exe -t PKA -i
      Note: Combined key storage (CMB) is not supported with the legacy interface.
  5. Key storage initialization with panel.exe (non-default)
    1. Ensure that you are using the account that uses the key storage. If you are not, you must fix its ownership and permissions later.
    2. Initialize all types of key storage. DES is where CCA DES key tokens are kept, AES is where CCA AES key tokens are kept, PKA is for all the CCA RSA public/private internal key tokens, and CMB (combined key storage) supports storage of all token types: CCA DES, CCA AES, CCA PKA, TR-31 DES and TR-31 AES key tokens. Use a different name for AES, DES, and PKA, because the second initialization would overwrite the first if different names are not used. Export new environment variables in the session where you will initialize the key storage (and where you still use it), then initialize key storage again:

      panel.exe default syntax 

      export CSUAESDS=<AES_file_name>
export CSUDESDS=<DES_file_name>
export CSUPKADS=<PKA_file_name>
export CSUCMBDS=<CMB file name>
/opt/IBM/CCA/bin/panel.exe --ks-type=AES --ks-init
/opt/IBM/CCA/bin/panel.exe --ks-type=DES --ks-init
/opt/IBM/CCA/bin/panel.exe --ks-type=PKA --ks-init
/opt/IBM/CCA/bin/panel.exe --ks-type=CMB --ks-init

      panel.exe legacy syntax

      export CSUAESDS=<AES_file_name>
export CSUDESDS=<DES_file_name>
export CSUPKADS=<PKA_file_namee>
/opt/IBM/CCA/bin/panel.exe -t AES -i
/opt/IBM/CCA/bin/panel.exe -t DES -i
/opt/IBM/CCA/bin/panel.exe -t PKA -i

      For example, if you entered the following commands in default syntax:

      export CSUAESDS=/tmp/a
export CSUDESDS=/tmp/d
export CSUPKADS=/tmp/p
export CSUCMBDS=/tmp/c
/opt/IBM/CCA/bin/panel.exe --ks-type=AES --ks-init
/opt/IBM/CCA/bin/panel.exe --ks-type=DES --ks-init
/opt/IBM/CCA/bin/panel.exe --ks-type=PKA --ks-init
/opt/IBM/CCA/bin/panel.exe --ks-type=CMB --ks-init

      these files would be created:

      /tmp/a
/tmp/a.NDX
/tmp/d
/tmp/d.NDX
/tmp/p
/tmp/p.NDX
/tmp/c
/tmp/c.NDX