Configure the ADC-Entrust integration
The following flowchart depicts the tasks that you need to perform to use Entrust HSM with a Citrix ADC:
As shown in the preceding flowchart, you perform the following tasks:
- Enable remote configuration push, on the HSM.
- Configure the ADC to use the Entrust HSM.
- Add the NSIP address on the HSM.
- Configure access permission for the ADC on the RFS.
- Configure automatic start of the
Hardserver
at boot time. - Enroll the HSM on the ADC.
- Add RFS details on the ADC.
- Synchronize the ADC to the RFS.
- Verify that Entrust HSM is successfully enrolled on the ADC.
- (Optional) Create an HSM RSA key.
- Configure the entities on the Citrix ADC.
- 添加HSM的关键。
- Add a certificate-key pair by using the HSM key.
- Add a virtual server.
- Add a server object.
- Add a service.
- Bind the service to the virtual server.
- Bind the certificate-key pair to the virtual server.
- 验证配置.
配置委托HSM
Specify the IP address of the RFS on the Entrust HSM so that it accepts the configuration that the RFS pushes to it. Use the nShield Connect front panel on the Entrust HSM to perform the following procedure.
Specify the IP address of a remote computer on the Entrust HSM
- Navigate toSystem Configuration > Config file options > Allow auto push.
- SelectON, and specify the IP address of the computer (RFS) from which to accept the configuration.
Enable pushing the remote configuration on the HSM
Specify the IP address of the RFS on the Entrust HSM so that it accepts the configuration that the RFS pushes to it. Use the nShield Connect front panel on the Entrust HSM to perform the following procedure.
Specify the IP address of a remote computer on the Entrust HSM
- Navigate toSystem Configuration > Config file options > Allow auto push.
- SelectON, and specify the IP address of the computer (RFS) from which to accept the configuration.
Configure the ADC to use the Entrust HSM
Sample values used in this documentation:
NSIP address=10.217.2.43
Entrust HSM IP address=10.217.2.112
RFS IP address=10.217.2.6
Add the NSIP address on the HSM
通常您使用nShield连接面板to add clients to the HSM. For more information, see the nShield Connect Quick Start Guide.
Alternately, use the RFS to add the ADC as a client to the HSM. To add the ADC, you must add the NSIP address in the HSM configuration on the RFS, and then push the configuration to the HSM. Before you can push the configuration, you must know the electronic serial number (ESN) of the HSM.
To get the ESN of your HSM, run the following command on the RFS:
root@ns# /opt/nfast/bin/anonkneti
Example:
root@ns# /opt/nfast/bin/anonkneti 10.217.2.112 BD17-C807-58D9 5e30a698f7bab3b2068ca90a9488dc4e6c78d822
The ESN number is BD17-C807-58D9.
After you have the ESN number, use an editor, such as vi, to edit the HSM configuration file on the RFS.
vi /opt/nfast/kmdata/hsm-BD17-C807-58D9/config/config
In thehs_clients
section, add the following entries:
# Amount of data in bytes to encrypt with a session key before session key# renegotiation, or 0 for unlimitied. (default=1024*1024*8b=8Mb). # datalimit=INT addr=10.217.2.43 clientperm=unpriv keyhash=0000000000000000000000000000000000000000 esn= timelimit=86400 datalimit=8388608 -----
Note:Include one or more hyphens as delimiters to add multiple entries in the same section.
To push the configuration to the HSM, run the following command on the RFS:
/opt/nfast/bin/cfg-pushnethsm --address= --force /opt/nfast/kmdata/hsm-BD17-C807-58D9/config/config
Example:
/opt/nfast/bin/cfg-pushnethsm --address=10.217.2.112 --force /opt/nfast/kmdata/hsm-BD17-C807-58D9/config/config
Configure access permission for the ADC on the RFS
To configure access permission for the ADC on the RFS, run the following command on the RFS:
/opt/nfast/bin/rfs-setup --force -g --write-noauth
Example:
[root@localhost bin]# /opt/nfast/bin/rfs-setup --force -g --write-noauth 10.217.2.43 Adding read-only remote_file_system entries Ensuring the directory /opt/nfast/kmdata/local exists Adding new writable remote_file_system entries Ensuring the directory /opt/nfast/kmdata/local/sync-store exists Saving the new config file and configuring the hardserver Done
Verify that the ADC can reach both the RFS and Entrust HSM by using port 9004.
Configure automatic start of thehardserver
at boot time
Create a file and then restart the appliance. Now, whenever you restart the appliance, and if this file is found, theHardserver
is automatically started.
At the shell prompt, type:
touch /var/opt/nfast/bin/thales_hsm_is_enrolled
At the command prompt, type:
reboot
Enroll the HSM on the ADC
Change directory to /var/opt/nfast/bin.
To add HSM details into the ADC configuration, run the following command on the ADC:
nethsmenroll --force
Example:
root@ns# ./nethsmenroll --force 10.217.2.112 $(anonkneti 10.217.2.112) OK configuring hardserver's nethsm imports
这step adds the following entries after the line # ntoken_esn=ESN in thenethsm_imports
section of the /var/opt/nfast/kmdata/config/config file.
… local_module=0 remote_ip=10.217.2.112 remote_port=9004 remote_esn=BD17-C807-58D9 keyhash=5e30a698f7bab3b2068ca90a9488dc4e6c78d822 timelimit=86400 datalimit=8388608 privileged=0 privileged_use_high_port=0 ntoken_esn=
Change the directory to /var/opt/nfast/bin and run the following command on the ADC:
touch "thales_hsm_is_enrolled"
Note:To remove an HSM that is enrolled on the ADC, type:
./nethsmenroll –-remove
Add RFS details on the ADC
To add RFS details, change the directory to /var/opt/nfast/bin/ and then run the following command:
./rfs-sync --no-authenticate --setup
Example:
./rfs-sync --no-authenticate --setup 10.217.2.6 No current RFS synchronization configuration. Configuration successfully written; new config details: Using RFS at 10.217.2.6:9004: not authenticating.
这step adds the following entries after the # local_esn=ESN line in therfs_sync_client
section of the /var/opt/nfast/kmdata/config/config file.
…… remote_ip=10.217.2.6 remote_port=9004 use_kneti=no local_esn=
Note:To remove an RFS that is enrolled on the ADC, type:
./rfs_sync –remove
Synchronize the ADC to the RFS
To synchronize all the files, change the directory to /var/opt/nfast/bin and then run the following command on the ADC:
./rfs-sync –-update
这command fetches all the World files, module files, and key files from the /opt/nfast/kmdata/local directory on the RFS and puts them into the /var/opt/nfast/kmdata/local directory on the ADC. Citrix recommends that you manually copy the World files, the module_XXXX_XXXX_XXXX files, where XXXX_XXXX_XXXX is the ESN of the enrolled HSM, and only the required RSA key and certificate files.
Verify the Entrust HSM is successfully enrolled on the ADC
After you synchronize the ADC to the RFS, do the following:
- Verify that the local
Hardserver
is UP and running. (Entrust server running). - 配置的状态igured HSMs, and verify that the values for the n_modules (number of modules) field and the km info fields are non-zero.
- Verify that the HSM is enrolled correctly and is usable (state 0x2 Usable) by the ADC.
- Load tests using
sigtest
运行properly.
Change the directory to /var/opt/nfast/bin, and at the shell prompt, run the following commands:
root@ns# ./chkserv root@ns# ./nfkminfo root@ns# ./sigtest
SeeAppendixfor an example.
Create an HSM RSA Key
Only RSA keys are supported as HSM keys.
Note:Skip this step if keys are already present in the/opt/nfast/kmdata/local
folder on the RFS.
Create an RSA key, a self-signed certificate, and a Certificate Signing Request (CSR). Send the CSR to a certificate authority to get a server certificate.
The following files are created in the following example:
- Embed RSA key: key_embed_2ed5428aaeae1e159bdbd63f25292c7113ec2c78
- Self-Signed Certificate: example_selfcert
- Certificate Signing Request: example_req
Note:Thegeneratekey
command is supported in strict FIPS 140-2 Level 3 Security World. An administrator card set (ACS) or an operator card set (OCS) is needed to control many operations, including the creation of keys and OCSs. When you run thegeneratekey
command, you are prompted to insert an ACS or OCS card. For more information about strict FIPS 140-2 Level 3 Security World, see the nShield Connect User Guide.
The following example uses Level-2 Security World. In the example, the commands are in boldface type.
Example:
[root@localhost bin]# ./generatekey embed size: Key size? (bits, minimum 1024) [1024] > 2048 OPTIONAL: pubexp: Public exponent for RSA key (hex)? [] > embedsavefile: Filename to write key to? [] > example plainname: Key name? [] > example x509country: Country code? [] > US x509province: State or province? [] > CA x509locality: City or locality? [] > Santa Clara x509org: Organisation? [] > Citrix x509orgunit: Organisation unit? [] > NS x509dnscommon: Domain name? [] > m.giftsix.com x509email: Email address? [] > example@citrix.com nvram: Blob in NVRAM (needs ACS)? (yes/no) [no] > digest: Digest to sign cert req with? (md5, sha1, sha256, sha384, sha512) [default sha1] > sha512 key generation parameters: operation Operation to perform generate application Application embed verify Verify security of key yes type Key type RSA size Key size 2048 pubexp Public exponent for RSA key (hex) embedsavefile Filename to write key to example plainname Key name example x509country Country code US x509province State or province CA x509locality City or locality Santa Clara x509org Organisation Citrix x509orgunit Organisation unit NS x509dnscommon Domain name m.giftsix.com x509email Email address example@citrix.com nvram Blob in NVRAM (needs ACS) no digest Digest to sign cert req with sha512 Key successfully generated. Path to key: /opt/nfast/kmdata/local/key_embed_2ed5428aaeae1e159bdbd63f25292c7113ec2c78 You have new mail in /var/spool/mail/root
Result:
You have created a CSR (example_req), a self-signed certificate (example_selfcert), and an application key token file in embed format (/opt/nfast/kmdata/local/key_embed_2ed5428aaeae1e159bdbd63f25292c7113ec2c78)
Because the ADC supports keys in simple format only, you must convert the embed key to a simple key.
To convert the embed key to a simple key, run the following command on the RFS:
[root@localhost bin]# ./generatekey -r simple from-application: Source application? (embed, simple) [embed] > embed from-ident: Source key identifier? (c6410ca00af7e394157518cb53b2db46ff18ce29, 2ed5428aaeae1e159bdbd63f25292c7113ec2c78) [default c6410ca00af7e394157518cb53b2db46ff18ce29] > 2ed5428aaeae1e159bdbd63f25292c7113ec2c78 ident: Key identifier? [] > examplersa2048key plainname: Key name? [] > examplersa2048key key generation parameters: operation Operation to perform retarget application Application simple verify Verify security of key yes from-application Source application embed from-ident Source key identifier 2ed5428aaeae1e159bdbd63f25292c7113ec2c78 ident Key identifier examplersa2048key plainname Key name examplersa2048key Key successfully retargetted. Path to key: /opt/nfast/kmdata/local/key_simple_examplersa2048key
Important:
When prompted for the source key identifier, enter2ed5428aaeae1e159bdbd63f25292c7113ec2c78as the embed key.
Result:
A key with the prefix key_simple (for example key_simple_examplersa2048key) is created.
Note:examplersa2048key is the key identifier (ident) and is referred to as the HSM key name on the ADC. A key identifier is unique. All the simple files have the prefix key_simple.
Configure the entities on the ADC
Before the ADC can process traffic, you must do the following:
- Enable features.
- Add a subnet IP (SNIP) address.
- Add the HSM key to the ADC.
- Add a certificate-key pair by using the HSM key.
- Add a virtual server.
- Add a server object.
- Add a service.
- Bind the service to the virtual server.
- Bind the certificate-key pair to the virtual server.
- 验证配置.
Enable features on the ADC
Licenses must be present on the ADC before you can enable a feature.
Enable a feature by using the CLI
At the command prompt, run the following commands:
enable feature lb enable feature ssl
Enable a feature by using the GUI
Navigate toSystem>Settingsand, in theModes and Featuresgroup, selectConfigure basic features, and then selectSSL Offloading.
Add a subnet IP address
For more information about subnet IP addresses, seeConfiguring Subnet IP Addresses.
Add a SNIP address and verify the configuration by using the CLI
At the command prompt, run the following commands:
add ns ip -type SNIP show ns ip
Example:
add ns ip 192.168.17.253 255.255.248.0 -type SNIP Done show ns ip Ipaddress Traffic Domain Type Mode Arp Icmp Vserver State --------- -------------- ---- ---- --- ---- ------- ------ 1) 192.168.17.251 0 NetScaler IP Active Enabled Enabled NA Enabled 2) 192.168.17.252 0 VIP Active Enabled Enabled Enabled Enabled 3) 192.168.17.253 0 SNIP Active Enabled Enabled NA Enabled Done
Add a SNIP address and verify the configuration by using the GUI
Navigate toSystem > Network > IPs, add an IP address, and select theIP Type as Subnet IP.
Copy the HSM key and certificate to the ADC
Use a secure file transfer utility to securely copy the key (key_simple_examplersa2048key) to the/var/opt/nfast/kmdata/local
folder, and the certificate (example_selfcert) to the/nsconfig/ssl
folder on the ADC.
Add the key on the ADC
All the keys have a key-simple prefix. When adding the key to the ADC, use the ident as the HSM key name. For example, if the key that you added is key_simple_XXXX, the HSM key name is XXXX.
Important:
- The HSM key name must be the same as the ident that you specified when you converted an embed key to a simple key format.
- The keys must be present in the
/var/opt/nfast/kmdata/local/
directory on the ADC.
Add an HSM key by using the CLI
At the shell prompt, run the following command:
add ssl hsmKey -key
Example:
add ssl hsmKey examplersa2048key –key key_simple_examplersa2048key Done
Add an HSM key by using the GUI
Navigate toTraffic Management > SSL > HSM, and add an HSM key.
Add a certificate-key pair on the ADC
For information about certificate-key pairs, seeAdd or update a certificate-key pair.
Add a certificate-key pair by using the CLI
At the command prompt, run the following command:
add ssl certKey -cert -hsmKey
Example:
add ssl certKey key22 -cert example_selfcert -hsmKey examplersa2048key Done
Add a certificate-key pair by using the GUI
Navigate toTraffic Management > SSL > Certificates, and add a certificate-key pair.
Add a virtual server
For information about a virtual server, seeSSL virtual server configuration.
Configure an SSL-based virtual server by using the CLI
At the command prompt, run the following command:
add lb vserver
Example:
add lb vserver v1 SSL 192.168.17.252 443
Configure an SSL-based virtual server by using the GUI
Navigate toTraffic Management > Load Balancing > Virtual Servers, create a virtual server, and specify the protocol as SSL.
Add a server object
Before you can add a server object on the ADC, make sure that you have created a back-end server. The following example uses the built-in python HTTP Server module on a Linux system.
Example:
%python –m SimpleHTTPServer 80
Add a server object by using the CLI
At the command prompt, run the following command:
添加服务器<名称> < IPAddress > < !——NeedCopy >
Example:
add server s1 192.168.17.246
Add a server object by using the GUI
Navigate toTraffic Management > Load Balancing > Servers, and add a server.
Add a service
For more information, see配置服务.
Configure a service by using the CLI
At the command prompt, run the following command:
add service
Example:
add service sr1 s1 HTTP 80
Configure a service by using the GUI
Navigate toTraffic Management > Load Balancing > Services, and create a service.
Bind the service to the virtual server
For more information, seeBind services to the SSL virtual server.
Bind a service to a virtual server by using the CLI
At the command prompt, run the following command:
bind lb vserver
Example:
bind lb vserver v1 sr1
Bind a service to a virtual server by using the GUI
- Navigate toTraffic Management > Load Balancing > Virtual Servers.
- Open a virtual server, and click in the Services pane to bind a service to the virtual server.
Bind the certificate-key pair to the virtual server on the ADC
For more information, seeBind the certificate-key pair to the SSL virtual server.
Bind a certificate-key pair to a virtual server by using the CLI
At the command prompt, run the following command:
bind ssl vserver -certkeyName
Example:
bind ssl vserver v1 -certkeyName key22 Warning: Current certificate replaces the previous binding
Bind a certificate-key pair to a virtual server by using the GUI
- Navigate toTraffic Management > Load Balancing > Virtual Servers.
- Open an SSL virtual server and, inAdvanced Settings, clickSSL Certificate.
- Bind a server certificate to the virtual server.
验证配置
To view the configuration by using the CLI:
At the command prompt, run the following commands:
show lb vserver show ssl vserver
Example:
显示磅vserver v1 v1 (192.168.17.252:443) - SSL Type: ADDRESS State: UP Last state change was at Wed Oct 29 03:11:11 2014 Time since last state change: 0 days, 00:01:25.220 Effective State: UP Client Idle Timeout: 180 sec Down state flush: ENABLED Disable Primary Vserver On Down : DISABLED Appflow logging: ENABLED No. of Bound Services : 1 (Total) 1 (Active) Configured Method: LEASTCONNECTION Current Method: Round Robin, Reason: Bound service's state changed to UP Mode: IP Persistence: NONE Vserver IP and Port insertion: OFF Push: DISABLED Push VServer: Push Multi Clients: NO Push Label Rule: none L2Conn: OFF Skip Persistency: None IcmpResponse: PASSIVE RHIstate: PASSIVE New Service Startup Request Rate: 0 PER_SECOND, Increment Interval: 0 Mac mode Retain Vlan: DISABLED DBS_LB: DISABLED Process Local: DISABLED Traffic Domain: 0 1) sr1 (192.168.17.246: 80) - HTTP State: UP Weight: 1 Done
sh ssl vserver v1 Advanced SSL configuration for VServer v1: DH: DISABLED Ephemeral RSA: ENABLED Refresh Count: 0 Session Reuse: ENABLED Timeout: 120 seconds Cipher Redirect: DISABLED SSLv2 Redirect: DISABLED ClearText Port: 0 Client Auth: DISABLED SSL Redirect: DISABLED Non FIPS Ciphers: DISABLED SNI: DISABLED SSLv2: DISABLED SSLv3: DISABLED TLSv1.0: ENABLED TLSv1.1: DISABLED TLSv1.2: DISABLED Push Encryption Trigger: Always Send Close-Notify: YES ECC Curve: P_256, P_384, P_224, P_521 1) CertKey Name: key22 Server Certificate 1) Cipher Name: DEFAULT Description: Predefined Cipher Alias Done
To view the configuration by using the GUI:
Navigate toTraffic Management > Load Balancing > Virtual Servers, and double-click an SSL virtual server to open it and view the configuration.