Important changes in Skyhigh Web Gateway 10.1 Hardware Security Module configuration
Technical Articles ID:
KB94202
Last Modified: 2023-06-22 12:18:46 Etc/GMT
Environment
Skyhigh Web Gateway (SWG) 10.1 and later
Hardware Security Module (HSM)
Summary
- With SWG 10.1, the nShield HSM client software Security World software has been updated from 12.40 to 12.60. This update supports new nShield HSM cards and nShield HSM appliances.
- In the new 12.60 driver software, the use of the OpenSSL CHIL interface for key generation is deprecated and the PKCS11 interface is used instead.
Any existing CHIL-based keys must be retargeted to PKCS11 after you upgrade to SWG 10.1, before you use the HSM function.
- When you import the keys in SWG, the PKCS11 URI format must be used. For further information about the PKCS11 URI format, see this IETF memo.
- The HSM agent on SWG now uses the OpenSSLl1.1.1 version instead of OpenSSL1.0.2.
Any OpenSSL CLI commands must now be performed using OpenSSL1.1.
- IMPORTANT: If your HSM module firmware doesn't support this driver version, perform the steps below:
- You must obtain the needed firmware version from Entrust.
- Upgrade the HSM firmware.
- Upgrade your SWG installation.
- We strongly recommend that you follow the regular backup procedures stated in your HSM documentation.
- For how to set up a client (SWG) for nShield Connect / Solo, creation of Security World and RFS key generation commands, see the vendor user guide documentation.
- For steps to configure HSM in SWG 10.0.x and earlier, see the "Hardware Security Module" section of the Skyhigh Web Gateway 10.x Product Guide.
- The new driver upgrade changes key generation, import, and use in your SWG HSM solution. The following sections describe these changes in detail with examples.
Solution
1
Configure nShield Connect/Solo from Entrust (formerly nCipher):
Retargeting existing CHIL based "hwcrhk" keys
Existing CHIL engine-based keys don't work directly with SWG 10.1. After you upgrade to SWG 10.1, you must retarget these keys pkcs11:
Type /opt/nfast/bin/generatekey --retarget [OPTIONS] APPNAME [from-application=appname] [from-ident=keyident] and press Enter.
For example, /opt/nfast/bin/generatekey –retarget
[root@mwgappl bin]# /opt/nfast/bin/generatekey --retarget -m1 pkcs11 from-application=hwcrhk from-ident=rsa-mwg1
plainname: Key name? [] > new_rsa-mwg1
key generation parameters:
operation Operation to perform retarget
application Application pkcs11
slot Slot to read cards from 0
verify Verify security of key yes
from-application Source application hwcrhk
from-ident Source key identifier rsa-mwg1
plainname Key name new_rsa-mwg1
Loading `mwgapp5500d':
Module 1: 0 cards of 1 read
Module 1 slot 0: `mwgapp5500d' #3
Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.
Key successfully retargetted.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_uc2e4dbdc237c861ed33a176ee0092bb657d909ab0-e65cdd7e70cf513153b540cffb114d1559fa7307
IMPORTANT: See your HSM user guide documentation for full details about using the generatekey --retarget command.
Generating private keys
When you install a new nfast driver, you must generate the pkcs11 application keys. The hwcrhk application type keys are no longer supported.
To generate a new key, type /opt/nfast/bin/generatekey --generate [OPTIONS] APPNAME [NAME=VALUE ...] and press Enter.
For example, /opt/nfast/bin/generatekey pkcs11
[root@mwgappl bin]# /opt/nfast/bin/generatekey pkcs11
protect: Protected by? (token, module) [token] >
recovery: Key recovery? (yes/no) [yes] >
type: Key type? (DES3, DH, DHEx, DSA, HMACSHA1, HMACSHA256, HMACSHA384,
HMACSHA512, RSA, DES2, AES, Rijndael, Ed25519, X25519) [RSA]
>
size: Key size? (bits, minimum 1024) [2048] >
OPTIONAL: pubexp: Public exponent for RSA key (hex)? []
>
plainname: Key name? [] > test_card_key1
nvram: Blob in NVRAM (needs ACS)? (yes/no) [no] >
key generation parameters:
operation Operation to perform generate
application Application pkcs11
protect Protected by token
slot Slot to read cards from 0
recovery Key recovery yes
verify Verify security of key yes
type Key type RSA
size Key size 2048
pubexp Public exponent for RSA key (hex)
plainname Key name test_card_key1
nvram Blob in NVRAM (needs ACS) no
Loading `mwgsolo':
Module 1: 0 cards of 1 read
Module 1 slot 0: `mwgsolo' #1
Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_uc23c57899105f07825044cd406347da6009184fb9-6271a944ede6ce655dc39ca15ed7d7a7cea1b9ea
Importing private keys (optional)
If you already have a private key, and want to import it into the HSM:
Type /opt/nfast/bin/generatekey --import pkcs11 and press Enter.
For example:
[root@mwgappl bin]# /opt/nfast/bin/generatekey --import pkcs11 pemreadfile=/root/key.pem plainname=imported_pkcs11
type: Key type? (DES3, RSA, DES2) [RSA] >
logkeyusage: Log key usage? (yes/no) [no] >
nvram: Blob in NVRAM (needs ACS)? (yes/no) [no] >
key generation parameters:
operation Operation to perform import
application Application pkcs11
verify Verify security of key yes
type Key type RSA
logkeyusage Log key usage no
pemreadfile PEM file containing RSA key /root/key.pem
plainname Key name imported_pkcs11
nvram Blob in NVRAM (needs ACS) no
Key successfully imported.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ua36b73b72e6af772916cca9385f665576f327684d
Fill in the appropriate fields for import, taking note of the Key identifier as it's needed in later steps.
Create a Certificate Signing Request (CSR)
If you create a new private key within the HSM Security World to obtain a signed certificate, you must generate a CSR.
To generate a CSR using one of the newly protected keys, use the OpenSSL engine and req commands.
Replace the KEYIDENTIFIER with the pkcs11 URI corresponding to the key, according to the PKCS#11 URI Scheme RFC. See this RFC.
NOTE: Use OpenSSL1.1.1 to perform all OpenSSL operations.
For example:
[root@mwg ~] openssl1.1
OpenSSL> engine -pre MODULE_PATH:/opt/nfast/toolkits/pkcs11/libcknfast.so pkcs11
OpenSSL> req -engine pkcs11 -keyform engine -key KEYIDENTIFIER -new -x509 -out FILENAME.crt
Example session and output:
[root@mwgappl bin]# openssl1.1
OpenSSL> engine -pre MODULE_PATH:/opt/nfast/toolkits/pkcs11/libcknfast.so pkcs11
(pkcs11) pkcs11 engine
[Success]: MODULE_PATH:/opt/nfast/toolkits/pkcs11/libcknfast.so
OpenSSL> req -engine pkcs11 -keyform engine -key "pkcs11:object= new_rsa-mwg1" -new -x509 -out pkcs11cert.crt
engine "pkcs11" set.
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:IN
State or Province Name (full name) []:KA
Locality Name (eg, city) [Default City]:BLR
Organization Name (eg, company) [Default Company Ltd]:MCAFEE
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:
Email Address []:
OpenSSL> exit
[root@mwgappl bin]#
MODULE_PATH:/opt/nfast/toolkits/pkcs11/libcknfast.so specifies the PCKS11 module path provided by the Entrust.
PKCS#11 URI examples:
NOTE: taken-name is the token label where the key is stored, and the pin-value is the passphrase of the Operator-Card-Set (OCS)-protected private keys. For keys protected by the module, use the pkcs 11 URI:
pkcs11:object=pkcs11_rsa_mwg
For OCS protected keys, use the pkcs11 URI:
pkcs11:token=<token-name>;object=pkcs11_rsa_key;type=private;pin-value=<xxxxx>
NOTES:
- The PCKS 11 URI is defined by this RFC.
- The URI should be formed depending on where the object is stored in the HSM, so there's no single format for the URI.
For the URI schema see this RFC.
- This format isn't defined by SWG, but by the RFC and how nCipher HSM implements its PKCS11 interface.
See the nCipher user guide for advice that the fields need for URI.
- When adding this key in the SWG user interface, you must prefix it with pkcs11:
For example: pkcs11:<PKCS11-URI>
Loading the private key identifiers in SWG UI
For SWG to use the keys within the HSM's Security World, you must enumerate the available keys in the UI.
Click Configuration, Hardware Security Module and add all key identifiers in the Keys to be loaded section:
The format for adding the keys is <engine-label>:<pkcs11-URI>
Here the engine-label is pkcs11. This label informs SWG that the supplied keys are pkcs11 and that it's applicable only for pkcs11 type keys.
For example, if pcks11 URI is pkcs11:object=pkcs11_rsa_mwg in the SWG manager, the key string to be added is pkcs11:pkcs11:object=pkcs11_rsa_mwg.
Other steps to perform for passphrase or multicard-OCS-protected private keys after configuring the SWG manager:
- Open a Shell connection to the SWG (SSH).
- Type /opt/mwg/bin/hsmagent -c and press Enter.
The command requests the secrets needed to load specially protected private keys. It must be executed after each upgrade and reboot.
The console then guides or asks the administrator for each declared identifier to enter the passphrases or insert the needed smart cards of the OCS into the HSM.
Also, you can inspect the hsmagent.errors.log to see if there are any unexpected errors:
- From the SWG Manager:
- Click Troubleshooting, <Appliance name>, Log Files.
- Open mwg-errors and view the hsmagent.errors.log.
- From the appliance command line:
- Open a command-line session.
- Navigate to /opt/mwg/log/mwg-errors.
- View the hsmagent.errors.log.
Solution
2
Configure Gemalto/Luna/SafeNet Network HSM
The SafeNet HSM configuration steps remain the same in this release, except for the use of OpenSSL1.1.1.
For example, to generate a Key-Cert pair:
openssl1.1 req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt
|
