9.3.2. Loading the Certicom ECC Module

Certicom's ECC module has a slightly different configuration process than the procedure for loading a general ECC module.
  1. Copy the third-party libraries to a common directory, like /usr/lib for 32-bit systems or /usr/lib64 for 64-bit systems.
    There are two library files for the Certicom ECC modules, libsbcpgse.so and libsbgse2.so.
  2. Cache the recent shared libraries.
    ldconfig
  3. Install the instance, but do not go through the configuration wizard.
  4. Stop the instance.
    service instance_name stop
  5. The instance runs as the pkiuser user. As root, create a home directory for pkiuser.
    /usr/sbin/usermod --home /usr/share/pki/pkiuser pkiuser 
    cd /usr/share/pki
    mkdir pkiuser
    HOME=/usr/share/pki/pkiuser
    export HOME
  6. Open the subsystem's alias directory. For example:
    cd /var/lib/instance_name/alias
  7. Install the third-party module in the CA's security databases so it is available for the configuration.
    modutil -dbdir . -nocertdb -add certicom -libfile /usr/lib/libsbcpgse.so
    This creates a .certicom directory in the new pkiuser home directory.
  8. Certicom's ECC module includes an initpin file; copy this into the new pkiuser directory and give it execute permissions. For example:
    cp /tmp/initpin /usr/share/pki/pkiuser
    
    chmod +x initpin
  9. Run Certicom's initpin file from the /usr/share/pki/pkiuser directory. This first prompts for the directory to use for the Certicom token databases; use the pkiuser home directory, /usr/share/pki/pkiuser. This also prompts to set a password for the module, and then proceed with configuring the module.
    /usr/share/pki/pkiuser/initpin
    
    Please enter the directory where the token databases exist or will
       be created: /usr/share/pki/pkiuser
    Enter PIN:
    Confirm PIN:
    
    Security Builder API for PKCS #11 Samples
                     CryptoAes() success
                    CryptoArc4() success
                     CryptoDes() success
                      CryptoDh() success
                     CryptoDsa() success
                    CryptoEcdh() success
                   CryptoEcdsa() success
                   CryptoEcmqv() success
                CryptoPkcs1Enc() success
                CryptoPkcs1Sig() success
                  CryptoRsaEnc() success
                  CryptoRsaSig() success
                    CryptoSha1() success
                         Token() samples starting
    Slot info for Slot 0
    Desc: FIPS Generic Crypto Services V2.0.1d
    manufacturerID:  Certicom Corp.
    flags:           0x1
                       CKF_TOKEN_PRESENT
    hardwareVersion: 1.0
    ...
  10. Edit the pkiuser's home directory so that every file is owned by pkiuser.
    cd /usr/share/pki; chown -R pkiuser:pkiuser pkiuser
  11. List the Certicom ECC module to make sure it has been properly loaded. The module is in security databases in the subsystem's alias directory. For example:
    modutil -dbdir /var/lib/instance_name/alias -list certicom
  12. Add the password for the ECC token to the subsystem's password file. Escape any spaces or special characters in the name. For example:
    vim /etc/instance_name/password.conf
    
    hardware-Certicom\ FIPS\ Cert/Key\ Services=secret
    The hardware- prefix is required.
  13. Edit the instance configuration and add a line to require signature verification. In this file, spaces and special characters do not need to be escaped. For example:
    ca.requestVerify.token=Certicom FIPS Cert/Key Services
  14. Edit file dtomcat5-instance file for the subsystem in the /usr/bin directory, and add a line to use the ECC module.
     umask 00002
     NSS_USE_DECODED_CKA_EC_POINT=1  
     export NSS_USE_DECODED_CKA_EC_POINT
  15. Start the instance.
    service instance_name start
  16. Continue with the instance configuration, with two important configuration settings:
    • In the Key Store panel, the ECC module should be listed as an available token. Select that module for the key store.
    • In the Key Pairs panel, ECC should be listed as an option to use to generate the keys used for the CA's certificates. Select the ECC key type.
  17. After completing the configuration, assuming this is a Java subsystem, try to log into the subsystem console.
    pkiconsole https://server.example.com:admin_port/subsystem_type
    This fails, because the console is not yet configure to run in ECC. However, this does create the security databases for the console, so the ECC module can be loaded.
    Load the ECC module into the console security databases.
    cd ~/.redhat-idm-console/
    
    modutil -dbdir . -nocertdb -add certicom -libfile /usr/lib/libsbcpgse.so
    Now, logging into the console succeeds.
  18. The web browser used to access administrative and agent services pages also needs to be configured to support ECC.
    1. Create a user for the browser profile, such as agent-pki.
    2. Launch Firefox and create a profile for this user; this automatically creates the required security databases and directory.
    3. Set the root home directory to /home/agent-pki, and make sure the directory is owned by root.
      chown -R root:root /home/agent-pki
    4. Copy the ECC module libraries and initpin file to the /home/agent-pki directory. All these files should be owned by root.
    5. Load the ECC module.
      modutil -dbdir /home/agent-pki/.mozilla/profile.default -nocertdb -add certicom -libfile /usr/lib/libsbcpgse.so
    6. Run the initpin file. When prompted, enter the Certicom token database directory, /usr/share/pki/pkiuser, and enter the PIN configured for those databases.
      ./initpin
    7. Change the ownership of the new user's home directory from root to the user. For example:
      chown -R agent-pki:agent-pki /home/agent-pki
    8. In the terminal with the /home/agent-pki directory open, export the environment variable that allows ECC support.
      export NSS_USE_DECODED_CKA_EC_POINT=1
    9. Open Firefox again. The Certicom module should be available and you should be able to log into it successfully.
    10. Then, import the agent certificate and root CA certificate or certificate chain into Firefox so that the user profile can access the agent services pages.
  19. The NSS_USE_DECODED_CKA_EC_POINT environment variable also needs to be set to access the subsystem Java console with an ECC certificate. This can be set in the .bashrc file for the user who uses the console. For example:
     vim /home/jsmith/.bashrc
    
     # User specific aliases and functions
     NSS_USE_DECODED_CKA_EC_POINT=1  
     export NSS_USE_DECODED_CKA_EC_POINT
  20. The Certicom ECC library stores some of its data in the user's home directory. However, this directory is not defined in the Certificate System SELinux file contexts, so some operations could be prevented from accessing the libraries. To avoid this, relable the files to allow the appropriate SELinux context so that the subsystem processes can access the libraries. For example:
    /usr/sbin/semanage fcontext -a -t pki_ca_t /home/jsmith/jsmith.db