ENTERPRISE  This is a SignServer Enterprise feature.

Introduction

Key wrapping allows solving issues arising when the number of keys you need to handle exceeds the amount that can be stored in a limited storage space for an HSM. The feature enables exporting the key material in a protected manner and storing the wrapped, encrypted key in an external database.

A key-pair is generated within the HSM and the private key is wrapped (that is, encrypted with a secret key in the HSM) and exported and stored in the database. When you are going to sign with the key, the wrapped key is fetched from the database and unwrapped in the HSM, used for signing and then removed from the HSM again. Keys are thus only available in the HSM when used and only take up space in the HSM during that time.

For information on the steps required to set up key wrapping, see Setting up Key Wrapping.

The following displays an overview of the key wrapping operations:

  • The Source Crypto Worker contains a Crypto Token in order to communicate with the HSM and perform key operations. The wrapping key (secret key: aeskey001) is created in the HSM using the Source Crypto Token.

  • The Key Wrapping Crypto Worker contains a Key Wrapping Crypto Token in order to perform wrapped key operations. The Key Wrapping Crypto Worker references the Source Crypto Worker to get hold of HSM objects and perform key operations in the HSM.

    The main operations of the Key Wrapping Crypto Token are to generate the wrapped key and to unwrap the wrapped key (using the wrapping key) in the HSM to be used for signing.

  • The Plain Signer references the Key Wrapping Crypto Worker in order to perform a signing operation. The Plain Signer can be configured to use either a fixed key (fixedkey01) or an individual user key (userkey1/userkey2/userkey3) depending on the requirement.

Prerequisites

The key wrapping use case requires that the key wrapping functions PKCS#11 C_WrapKey and C_UnwrapKey are supported and allowed by both the HSM and the crypto token.

The SignServer PKCS11CryptoToken uses the SunPKCS11 provider/wrapper from Java for interactions with the HSM and this provider/wrapper does not implement wrapping functions. Instead, the new P11NG provider in SignServer can be used, using the P11NGCryptoToken. Additionally, for the key wrapping functionality, the P11NGKeyWrappingCryptoToken or the P11NGKeyWrappingCryptoWorker can also be used.

Note that since the key material is stored in the database, this use case is not supported when running SignServer without database (also called NoDB mode).

Limitations

As of SignServer 4.3.0, the key wrapping use case has been successfully tested on the SafeNet ProtectServer Gold (HSM emulator).

While the key wrapping feature has been tested on Thales nCipher there are some open issues with stability. If using Thales nCipher, the following environment variable needs to be set:

export CKNFAST_OVERRIDE_SECURITY_ASSURANCES="tokenkeys;explicitness"
CODE

The following algorithms are supported:

  • Key algorithms: AES,  RSA and ECDSA.
  • Signature algorithms: SHAxwithRSA, SHAxwithRSAandMGF1 and SHAxwithECDSA.

Note that EdDSA is not yet supported.