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

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 JackNJI11CryptoToken.

    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.JackNJI11CryptoToken
     
    # 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

  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 JackNJI11KeyWrappingCryptoToken and JackNJI11KeyWrappingCryptoWorker.

    Sample key wrapping crypto worker configuration
    WORKERGENID1.TYPE=CRYPTO_WORKER
     
    WORKERGENID1.IMPLEMENTATION_CLASS=org.signserver.p11ng.common.cryptotoken.JackNJI11KeyWrappingCryptoWorker
     
    # 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

  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.

Sample Plain Signer configuration with fixed wrapped 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
 
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.

Sample Plain Signer configuration with individual user wrapped 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.