Use the Guardian Series 3 to configure HSMs for PKCS #11 integrations

this section explains how to create an encryption device group and add hsms to the device group for remote management create a client futurex device group device groups simplify information management on client {{futurex}} devices by controlling them through a single interface use the following procedures to create a device group and add devices select encryption devices from the left toolbar, then select \[ add group ] at the bottom of the window to open the encryption device group window enter a group name in the associated field enter a group description in the associated field select an owner group from the drop down menu select hardware security module in the group type drop down menu devices that you add to the hsm group must all be the same type (such as {{vectera}} , excrypt plus, excrypt ssp enterprise v 2) define group options option description configuration enables remote configuration for all {{futurex}} hsms in the group monitoring enables monitoring for all {{futurex}} hsms in the group balancing enables load balancing between group devices for api calls sent to the group choose the connection pair in the drop down menu the connection pairs available vary depending on the type of device group for pkcs #11, you need only the excrypt/standard connection pair you should disable the http and international connection pairs port description excrypt/standard enables you to connect with the excrypt or standard apis for transaction processing by using {{futurex}} hsms http enables you to connect with one of the following targets the client {{futurex}} device web management portal the registration authority (ra) if you added {{k3}} units with the ra functionality the restful web api of the device international enables you to connect with the international api for transaction processing by using {{futurex}} hsms when you enable the excrypt universal interface license select the allow connection checkbox and choose the port and header size , if applicable select the connection type for each connection pair from the drop down menu the options are clear , ssl (default), or anonymous tls futurex recommends using ssl select \[ ok ] to create the group add devices to a device group groups are defined by device type because you can't mix and match different devices within the same group, choose the group with the same model when selecting a device to add perform the following steps to add a device to a group select the group to add the client device to select \[ add device ] at the bottom of the screen to open the encryption device window enter the hostname or ip address of the client device hsms managed by the {{guard}} in a single group must use the same firmware version and feature set if using {{futurex}} certificates, keep as default all the remaining settings in this menu (steps 4 11) in the connection pair drop down menu, select the proper tls pair for the device in question define the port on which the client devices are configured to operate you don't need to specify a header size designate the desired connection type and configuration by using the drop down menus select the device role from the associated drop down menu to specify the device's use in the assigned group only the primary device role is available for the first device added to the group role description primary device designates a device as a primary device in the device group the configuration details on this device automatically replicate to any additional devices added to the device group the primary device also functions in the same role as a production device production device designates a device as a production device production devices begin actively processing transactions when you synchronize the device with the group you can add multiple production devices to an individual device group backup device designating a device as a backup device causes it to remain synchronized with the group, but not process transactions however, the device automatically begins processing transactions as soon as a production device is removed from service using backup devices is optional, and you can add multiple backup devices to an individual device group select a group from the drop down menu check the box next to balancing enabled to enable balancing this enables the guardian to evenly distribute requests to devices in the group set the number of seconds of failed pings before the guardian considers the device disconnected set the desired number of seconds for the ping timeout the ping timeout is the amount of time before an individual ping is open select \[ ok ] to save changes the details window opens and displays the connection details and status for the device, and enables you to export this information after the process completes to reopen this window, right click on the encryption device and select show connection status troubleshooting failed connections if the connection is failing, consider the following are the device group and device enabled? are the admin and excrypt tls ports configured on the hsm? are the {{guard}} and the hsm by using the same ca tree? if using {{futurex}} certificates, they both need to use either rsa or ecc ca if port 9100 fails to connect, there is a problem with the excrypt port configuration if port 9009 fails to connect, there is a problem with the admin port configuration configure the hsm through the guardian perform the tasks in this section to configure the hsm load the futurex key for this step, you need to log in with an identity that has a role with major keys\ load permisision you can use the default administrator role and admin identities the ftk wraps all keys stored on the hsm used with pkcs #11 if using multiple hsms in a cluster, you can use the same ftk for syncing hsms before you can use an hsm with pkcs #11, it must have an ftk the following instructions are for the {{guard}} , but you can also complete this process by using excrypt manager, fxcli, or the excrypt touch for more information about how to load the ftk into an hsm using the other tools or devices, see the relevant administrative guide after logging in, go to the encryption devices page right click on the device group and select remote manage after you log in on the login screen, select keys in the left hand menu go to the major keys tab and select \[ load ] next to the ftk in the first menu, select the algorithm , key length , and key parts that you want to use load each of the key parts you receive a confirmation that each key part loaded successfully when they finish loading, you receive a final key checksum select \[ next ] to finish loading the key configure a transaction processing connection and create an application partition for this step, you need to log in with an identity that has a role with the following permissions role\ add , role\ assign all permissions , role\ modify , keys\ all slots , and command settings\ excrypt you can use the default administrator role and admin identities this integration guide treats the terms application partition and role as synonymous configure a transaction processing connection before logging in to the hsm with an authenticated user, an application connects through a transaction processing connection to the transaction processing application partition therefore, you must take steps to configure the following items to harden this partition it should not have access to the all slots permissions it should not have access to any key slots enable only the pkcs #11 communication commands choose one of the following methods to configure the transaction processing connection go to the application partitions menu, select the transaction processing application partition, and select \[ modify ] in the permissions tab, leave the top level keys permission checked and uncheck the all slots sub permission in the key slots tab, ensure that the settings do not specify key ranges by default, the transaction processing application partition can access the entire range of key slots on the hsm in the commands tab, make sure to enable only the following pkcs #11 communication commands command description echo communication test/retrieve version prmd retrieve hsm restrictions rand generate random data hash retrieve device serial gpkm retrieve key table information gpks general purpose key settings get/change gpkr general purpose key settings get (read only) run the following role modify fxcli commands to remove all permissions and key ranges that are currently assigned to the transaction processing role and enable only the pkcs #11 communication commands because the transaction processing role was previously called the anonymous role, the following commands specify anonymous in the name field fxcli role modify name anonymous clear perms clear key ranges fxcli role modify name anonymous add perm "keys" add perm excrypt\ echo add perm excrypt\ prmd add perm excrypt\ rand add perm excrypt\ hash add perm excrypt\ gpkm add perm excrypt\ gpks add perm excrypt\ gpkr create an application partition to segregate applications on the hsm, you must create an application partition specifically for your use case application partitions segment the permissions and keys between applications on an hsm between applications the following steps outline the process for configuring a new application partition go to the application partitions tab and select \[ add partition ] in the basic information tab, configure all the fields as follows option required configuration logins required set to 1 if the hsm is in fips mode, you must set logins required to 2 ports set to prod connection sources set to ethernet use dual factor set to never go to the permissions tab and select the following permissions permission description keys top level permission authorized allows for keys that require login import pki allows trusting an external pki generally not recommended, but some applications use this to allow for pki symmetric key wrapping no usage wrap enables interoperable key wrapping without defining key usage as part of the wrapped key use this only if you want to exchange keys with external entities or use the hsm to wrap externally used keys in the key slots tab, we recommend you create a range of 1000 total keys that do not overlap with another application partition within the specified range, you should have ranges for both symmetric and asymmetric keys if the application requires more keys, configure it accordingly to use the hsm functionality, you must enable particular functions on the application partition based on application requirements enable the following commands under commands pkcs #11 communication commands command description echo communication test/retrieve version prmd retrieve hsm restrictions rand generate random data hash retrieve device serial gpkm retrieve key table information gpks general purpose key settings get/change gpkr general purpose key settings get (read only) key operations commands command description apfp generate pki public key from private key asyl load asymmetric key into the key table gecc generate an ecc key pair gpca general purpose add certificate to key table gpgs general purpose generate symmetric key gpka general purpose key add gpkd general purpose key slot delete/clear grsa generate rsa private and public key lrsa load key into rsa key table rpfp get public components from the rsa private key interoperable key wrapping commands command description gpku general purpose key unwrap (unrestricted) gpuk general purpose key unwrap (preserves key usage) gpkw general purpose key wrap (unrestricted) gpwk general purpose key wrap (preserves key usage data encryption commands command description adpk pki decrypt trusted public key ghsh generate a hash (message digest) starting in firmware version 7 x, this function is enabled by default so you don't need to specify it gpse general purpose symmetric encrypt gpsd general purpose symmetric decrypt gpgc general purpose generate cryptogram from key slot gpmc general purpose mac (message authentication code) gpsr general purpose rsa encrypt/decrypt or sign/verify with recovery hmac generate a hash based message authentication code rdpk get clear public key from cryptogram signing commands command description asys generate a signature using a private key asyv verify a signature using a public key gpsv general purpose data sign and verify rsas generate a signature using a private key create a new identity and associate it with the new application partition for this step, you must log in with an identity that has a role with the identity\ add permission you can use the default administrator role and admin identities to create this new identity, select identity management > add identity specify a name for the new identity then, in the roles drop down menu, select the name of the previously created application partition to associate the new identity with the previously created application partition you must set the new identity inside the fxpkcs11 cfg file in the \<crypto opr> tag select \[ finish ] and then \[ yes ] to exit out of this menu and log out of the device group configure tls authentication for this step, you must log in with an identity that has a role with the following permissions keys\ all slots , management commands\ certificates , management commands\ keys , security\ tls sign , and tls settings\ upload key you can use the default administrator role and admin identities to configure tls authentication, choose one of the following methods enable server side authentication create connection certificates for mutual authentication we recommend option 2, mutual authentication option 1 | enable server side authentication we recommend mutually authenticating to the hsm using client certificates, but the {{vectera}} also supports server side authentication the following steps outline the process for enabling server side authentication choose one of the following methods to enable server side authentication go to the ssl/tls setup menu then, select the excrypt port in the connection pair drop down list, check the allow anonymous box, and select \[ save ] run the tls ports set fxcli command to enable server side authentication with the allow anonymous ssl/tls setting fxcli tls ports set p "excrypt port" anon option 2 | create connection certificates for mutual authentication as mentioned previously, we recommend mutually authenticating to the hsm by using client certificates, and the system enforces mutual authentication by default the following example shows how to use fxcli to generate a ca to sign the hsm server certificate and a client certificate then, it shows how to generate the client keys and csr by using openssl for this example, you must connect the computer that is running fxcli to the front usb port of the hsm if you do not specify a file path for commands that create an output file, fxcli saves the file to the current working directory using user generated certificates requires you to load a pmk on the hsm if you run help by itself, a full list of available commands displays you can see all options for a command by running the command name followed by help open the fxcli prompt by running fxcli hsm in a terminal connect your laptop to the hsm by using the usb port on the front, and run the following command fxcli connect usb run the following command to log in with both default admin identities when prompted for the username and password, enter them you must run this command twice fxcli login user generate a tls ca and store it in an available key slot on the hsm fxcli generate algo rsa bits 2048 usage mak name tlscakeypair slot next create a root certificate fxcli x509 sign \\ \ private slot tlscakeypair \\ \ key usage digitalsignature key usage keycertsign \\ \ ca true pathlen 0 \\ \ dn 'o=futurex\cn=root' \\ \ out tlsca pem generate the server keys for the hsm fxcli tls ports request pair "excrypt port" file production csr pki algo rsa sign the server csr with the newly created tls ca fxcli x509 sign \\ \ private slot tlscakeypair \\ \ issuer tlsca pem \\ \ csr production csr \\ \ eku server key usage digitalsignature key usage keyagreement \\ \ ca false \\ \ dn 'o=futurex\cn=production' \\ \ out tlsproduction pem push the signed server pki to the production port on the hsm fxcli tls ports set pair "excrypt port" \\ \ enable \\ \ pki source generated \\ \ clear pki \\ \ ca tlsca pem \\ \ cert tlsproduction pem \\ \ no anon to generate client keys and csr, run the following openssl commands from windows powershell rather than from the fxcli program # generate the client keys $ openssl genrsa out privatekey pem 2048# generate a client csr $ openssl req new key privatekey pem out clientpki csr days 365 using fxcli, sign the client csr that was just generated using openssl fxcli x509 sign \\ \ private slot tlscakeypair \\ \ issuer tlsca pem \\ \ csr clientpki csr \\ \ eku client key usage digitalsignature key usage keyagreement \\ \ dn 'o=futurex\cn=client' \\ \ out signedpki pem run the following command from windows powershell use openssl to create a pkcs #12 file that you can use to authenticate as a client by using our pkcs #11 library openssl pkcs12 export inkey privatekey pem in signedpki pem certfile tlsca pem out pki p12