Setting up Key Wrapping

ENTERPRISE  This is a SignServer Enterprise feature.

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.

Follow the steps below to set up key wrapping. For more information and background on key wrapping, see the reference section Key Wrapping.

• Step 1: Set Up Crypto Worker with Source Crypto Token
• Step 2: Set Up Key Wrapping Crypto Worker Referencing the Source Crypto Worker
• Step 3: Set Up Signer with Wrapped Key

Step 1: Set Up Crypto Worker with Source Crypto Token

To set up crypto worker with source crypto token, do the following:

1. Create source crypto worker CryptoTokenP11NG1 using the sample configuration p11ng-crypto.properties. For details, see P11NGCryptoToken.

   Sample source crypto worker configuration

   WORKERGENID1.TYPE=CRYPTO_WORKER
   WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.server.signers.CryptoWorker
   WORKERGENID1.CRYPTOTOKEN_IMPLEMENTATION_CLASS=org.signserver.p11ng.common.cryptotoken.P11NGCryptoToken
   
   # Name for other workers to reference this worker:
   WORKERGENID1.NAME=CryptoTokenP11NG1
   
   # Name of the PKCS#11 shared library to use: 
   WORKERGENID1.SHAREDLIBRARYNAME=SafeNet ProtectServer Gold Emulator
   
   # HSM slot details
   WORKERGENID1.SLOTLABELTYPE=SLOT_NUMBER
   WORKERGENID1.SLOTLABELVALUE=1
   WORKERGENID1.PIN=foo123
   
   #One key to test activation with is required. If this key does not already exist generate it after the worker has been created.
   WORKERGENID1.DEFAULTKEY=testkey0

   CODE

2. When the worker CryptoTokenP11NG1 is ACTIVE, generate a secret key wrapkey001 using algorithm AES and Key specification 128 to use as wrap key.

Step 2: Set Up Key Wrapping Crypto Worker Referencing the Source Crypto Worker

To set up key wrapping crypto worker referencing the source crypto worker, do the following:

1. Create key wrapping crypto worker CryptoTokenP11NG1KeyWrapping using the sample configuration p11ng-keywrapping-crypto.properties. For details, see P11NGKeyWrappingCryptoToken and P11NGKeyWrappingCryptoWorker.

   Sample key wrapping crypto worker configuration

   WORKERGENID1.TYPE=CRYPTO_WORKER
   
   WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.p11ng.common.cryptotoken.P11NGKeyWrappingCryptoWorker
   
   # Name for other workers to reference this worker:
   WORKERGENID1.NAME=CryptoTokenP11NG1KeyWrapping
   
   # References a source crypto CryptoToken
   WORKERGENID1.CRYPTOTOKEN=CryptoTokenP11NG1
   
   # Secret/symmetric key in the referenced crypto token to use for wrapping and unwrapping
   WORKERGENID1.DEFAULTKEY=wrapkey001
   
   # Encryption algorithm
   WORKERGENID1.WRAPPING_CIPHER_ALGORITHM=CKM_AES_CBC_PAD

   CODE

2. Create wrapped key(s).

   The wrapped key can be a common key (for example, wrappedkey001, wrappedkey002) or an individual user key (for example, userkey_foobar) depending on the requirement.
   For an individual user key, the key alias is a combination of user prefix and the user name. For example, for the key alias userkey_foobar, the userkey_ is the user prefix and foobar is the user name.
3. Generate Certificate Signing Request (CSR) for the wrapped key(s) created in the step 2 above, get certificate for the CSR, and install certificate for the key in token.

Step 3: Set Up Signer with Wrapped Key

The wrapped key can be a common/fixed key or an individual user key depending on the requirement.

Fixed Key

Create PlainSigner using the sample configuration plainsigner.properties.

# General properties
WORKERGENID1.TYPE=PROCESSABLE
WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.module.cmssigner.PlainSigner
WORKERGENID1.NAME=PlainSigner
WORKERGENID1.AUTHTYPE=NOAUTH

# Crypto token
WORKERGENID1.CRYPTOTOKEN=CryptoTokenP11NG1KeyWrapping

# Using one key-pair in the above crypto token
WORKERGENID1.DEFAULTKEY=wrappedkey001

WORKERGENID1.SIGNATUREALGORITHM=SHA256withRSA

The sample config keywrapping-fixed_key.properties can also be used to create a XAdESSigner using a fixed wrapped key.

Individual Key

Create PlainSigner using the sample configuration plainsigner.properties and the following properties related to the Individual user key.

# General properties
WORKERGENID1.TYPE=PROCESSABLE
WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.module.cmssigner.PlainSigner
WORKERGENID1.NAME=PlainSigner
WORKERGENID1.AUTHTYPE=NOAUTH
 
# Crypto token
WORKERGENID1.CRYPTOTOKEN=CryptoTokenP11NG1KeyWrapping
 
# Using one key-pair in the above crypto token
WORKERGENID1.DEFAULTKEY=wrappedkey001

# Properties related to individual user key 
# Uses username to select which key to use
# For user "foobar" the key should have alias "userkey_foobar"
WORKERGENID1.AUTHTYPE=org.signserver.server.UsernameAuthorizer
WORKERGENID1.ACCEPT_ALL_USERNAMES=true
WORKERGENID1.ALIASSELECTOR=org.signserver.server.aliasselectors.AuthorizedUsernameAliasSelector
WORKERGENID1.ALIAS_PREFIX=userkey_
 
WORKERGENID1.SIGNATUREALGORITHM=SHA256withRSA

The sample configuration keywrapping-multiple_keys.properties can also be used to create a XAdESSigner using an individual wrapped key.