Skip to end of metadata
Go to start of metadata

How to configure ADSS Server to use a Key Encryption Key (KEK)?

Key Encryption Key (KEK) is a symmetric key that is used to encrypt the keys generated within the crypto device. The encrypted keys are saved outside the crypto device (HSM), and are then imported into the crypto device again when required (e.g. signing operation). After this, the encrypted keys are discarded. To use KEK in ADSS Server:

  1. Configure an HSM crypto profile within ADSS Key Manager and select the "Enable Key Wrapping for Document Signing Keys" option for this HSM.
    1. Select a KEK from the already available KEKs in HSM. The system automatically tests and verifies whether the HSM supports key wrapping/ unwrapping or not.
    2. Use the HSM provided utilities and tools, to create or backup the KEK. See details to learn more about configuring a crypto profile in ADSS Server.
  2. Create a "Certification Profile" in ADSS Certification Service, and select the crypto profile for which you have selected the "Enable Key Wrapping for Document Signing Keys" option in step 1.
  3. Send a request to ADSS Certification Service to generate a new certificate, by using the profile Id of the same "Certification Profile" created in step (2). Also specify the unique "Certificate Alias" in the request by which the encrypted private key and certificate can be identified at the time of signing. This works as follows:
    1. ADSS Certification Service requests the HSM to generate a key pair according to the "Certification Profile" settings.
    2. ADSS Certification Service requests the HSM to wrap (encrypt) and export the private key using the KEK configured in crypto profile.
    3. ADSS Certification Service stores the exported encrypted private key in database against the "Certificate Alias" provided in the request.
  4. Request the ADSS Signing Service to sign a document using the encrypted private key. This works as follows:
    1. Specify the "Certificate Alias" for the encrypted private key with which the document needs to be signed.
    2. The ADSS Signing Service loads the encrypted private key from the database and imports the signing key into HSM. While importing the key, it also specifies the "Certificate Alias" for the private key and the KEK to be used to unwrap (decrypt) the private key within the HSM.
    3. The ADSS Signing Service produces the final hash of the document and requests the HSM to sign it using the private key identifying it by the Certificate Alias. 
  5. Once the document hash is signed, the private key is deleted from the HSM. The key is not deleted from database so that it can be used later to sign other documents.
Special handling for Thales nCipher HSM

When applying a KEK generated from the nCipher HSM via ADSS Server Console > Key Manager > [nCipher-Crypto-Source], if you get the error "Exporting the private key from crypto source" function fails - as shown below;

 

Check the CKNFASTRC config file (default path is C:\Program Files (x86)\nCipher\nfast) of the HSM for following line:

CKNFAST_NO_UNWRAP=1

This essentially means that the HSM will not allow to unwrap the key resulting in the private key export failure. You will need to change this attribute value to 0; allowing the HSM to unwrap the key and for ADSS Server to set the KEK.

CKNFAST_NO_UNWRAP=0

Can I attach more than one HSM to an ADSS Server?

Multiple HSMs, USB tokens and smartcards can be attached and configured as allowed by the device driver software.  ADSS Server expects a hardware crypto profile for each specific HSM (unless the software driver provides load balanced access to cloned HSMs).  PKCS#11 and Windows CAPI/CNG drivers are supported, although Windows CAPI/CNG HSMs have the restriction that ADSS Server cannot generate new keys within them, Java is unable to tell CAPI/CNG which CSP to use when generating a key so a keygen request is only ever processed in the default software store.
This link discusses how a new hardware crypto profile can be created

Can keys and certificates that already exist in an HSM or within the Windows CAPI/CNG store be used by ADSS Server?

ADSS Server does allow certificates that exist in an HSM or Windows CAPI/CNG store to be imported into ADSS Server.  Only the certificates are imported and as they are imported they must be assigned a certificate purpose. This link describes how to import existing certificates:
http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx?pageid=Importing_existing_keys

How to replace an existing HSM with a new one?

If a business need arrives to replace the configured HSM with a new one, then the following aspects should be considered.  It is recommended to read the complete article first before you go with one of the recommended options.

Retain Old Keys:

It is generally required and recommended to first replicate the existing keys and certificates available in the current HSM into the new one.  Use the HSM vendor utilities to achieve this.  Refer to the relevant manuals from the HSM vendor to find instructions for this or ask for the technical help from the HSM vendor.  If the key wrapping is being used then it is very important that the back-up and restore must include the KEK as well as any other key material.

Now replace the current HSM with the new one as per HSM vendor instructions.  While doing this, if the new HSM is also from the same vendor and can use the existing drivers, then simply go to ADSS Server Key Manager > Crypto Source and perform a test connection with the HSM to make sure it is connectable. The steps 3 and 4 can be ignored in this case.

If the new HSM is from a different vendor or if it should use a newer version of the HSM drivers, then first install the new HSM drivers on the ADSS Server machine to be able to communicate with the new HSM.

If the new HSM is from a different vendor, then you will also need to create a new Crypto Source on ADSS Server Key Manager > Crypto Source.  The following additional steps will also be needed:

  1. If there were some existing infrastructure keys (service keys) on the old HSM e.g. verification response signing key, OCSP response signing key or timestamp response signing key, issuing CA keys etc., then it will be first required to temporarily switch these keys with dummy keys created in the software keystore (ADSS Server database) to be able to remove the existing keys from the ADSS Server Key Manager > Service Keys
  2. Now from the Key Manager > Service Keys, delete the relevant service keys that exist in the old Crypto Source.
  3. Once the new crypto profile is created, edit this profile and click on the Import Existing Keys button
  4. From the list of the keys available to import from the new HSM, select all the relevant keys with their associated key purposes and import these keys
  5. Now, you can go back and replace the dummy service keys created in step a with the newly imported keys and restart the ADSS Server from Server Manager module

Do not Retain Old Keys:

This is not a recommended approach but if it is a business need, then simply switch any service keys with dummy ones created in the software keystore (ADSS Server database) to be able to remove the existing keys from the ADSS Server Key Manager > Service Keys

Once the keys are removed, detach the current HSM and attach the new one.  If the new HSM is of the same brand and can use the existing drivers, you should be done here.  Simply go to ADSS Server Key Manager > Crypto Source and perform a test connection with the HSM to make sure it is connectable.

If the new HSM is from a different vendor or if it should use a newer version of the HSM drivers, then first install the new HSM drivers on the ADSS Server machine to be able to communicate with the new HSM.

If the new HSM is from a different vendor, then you will also need to create a new Crypto Source on ADSS Server Key Manager > Crypto Source

Now create new keys and associated certificates on the new crypto profile and configure it in relevant services or Manage CAs module accordingly

Restart the ADSS Server from Server Manager module

Icon

It is highly recommended NEVER to detach an HSM without removing the associated keys from the ADSS Server Key Manager > Service Keys as this results in losing the references of these keys on the HSM.  If you still get to this situation by mistake or an unwanted accident, then follow these additional instructions to remove the stale keys from the ADSS Server Key Manager > Service Keys:

 

Launch ADSS Server console

 

Navigate to location: Global Settings > Advanced Settings

From the Property Type drop down select the option Console

Search for the property ENABLE_PKCS11_KEY_DELETION and change the value of this property to FALSE

Save the changes

Restart the ADSS Server console instance from Windows NT Services panel or UNIX daemon to have the changes take into effect

Go to Key Manager and delete the unwanted keys which were generated in the old HSM

Follow the steps 2-6 to set the value of ENABLE_PKCS11_KEY_DELETION back to TRUE

 

Launch ADSS Server console

Navigate to location: Global Settings > Advanced Settings

From the Property Type drop down select the option Console

Search for the property ENABLE_PKCS11_KEY_DELETION and change the value of this property to FALSE

Save the changes

Restart the ADSS Server console instance from Windows NT Services panel or UNIX daemon to have the changes take into effect

Go to Key Manager and delete the unwanted keys which were generated in the old HSM

Follow the steps 2-6 to set the value of ENABLE_PKCS11_KEY_DELETION back to TRUE

What is the relationship between options to manipulate Certificate Templates in the Key Manager, Manage CAs and Certification Service modules?

Certificate Templates are used to define which certification extensions should be included in the certificates being issued under different certificate purposes.  Certificates can be requested within Key Manager, Manage CAs and Certification Service modules and hence the templates can be edited from any of these modules. Updated Certificate Templates are stored centrally in ADSS Server and are available to all three service modules.

What are Certificate Groups and when should these be used?

Certificate groups are valuable when one or more keys may be unavailable to an instance of ADSS Server.  Such a situation may occur when PCIe HSMs, USB HSMs, tokens or smartcards are used, e.g. one token is attached to one server and another token attached to a second server.  
When ADSS Server runs on each server it will identify the first certificate AND key that is available to it and use this for all requests on this server instance.  A key located on the other server will therefore never be chosen.  Click here for more details.

ADSS Server connection is lost with Utimaco after sometime of inactivity

If you are using the Utimaco simulator and you observe that the ADSS Server loses the connection with Utimaco then follow these instructions for a fix:

  1. Search for file cs_pkcs11_R2.cfg in Program Files (e.g. C:\Program Files\Utimaco\CryptoServer\Lib\cs_pkcs11_R2.cfg) and open it in edit mode
  2. Locate the property KeepAlive and set its value to true (KeepAlive = true)
  3. Save the file and restart the Utimaco Simulator for the changes to take effect
  4. Now restart the ADSS Server from Server Manager so it can establish the connection with HSM. 

You will not face the disconnection issue again.

 

  • No labels