Configure the Vectera Plus

you can complete most tasks in this section by using either excrypt manager or fxcli the exception is the second option of task 7 ( create connection certificates for mutual authentication ), for which you must use fxcli you can optionally complete steps 4 through 6 by using the {{guard}} refer to the applicable guide for configuring hsms for pkcs #11 integrations by using the {{guard}} if you use a virtual hsm for the integration, you must connect to it over the network through fxcli, the excrypt touch, or the {{guard}} to establish a connection between the {{futurex}} pkcs #11 library and the {{vectera}} , perform the following configuration tasks connect to the hsm through the front usb port by using excrypt manager or fxcli validate the enabled features on the hsm set up the network configuration load the ftk, pmk, and bek major keys configure a transaction processing connection and create a new application partition create a new identity that has access to the new application partition configure tls authentication by using one of the following options enable server side authentication create client certificates for mutual authentication the following sections detail each of these action items connect to the hsm through the front usb port for both excrypt manager and fxcli, you must connect your laptop to the front usb port on the hsm choose one of the following methods to connect to the hsm excrypt manager perform the following steps to use excrypt manager to connect to the hsm open excrypt manager and select \[ refresh ] in the lower right corner of the connection page then, select usb connection and select \[ connect ] log in with both default admin identities change the default admin passwords for both your default admin identities ( admin1 and admin2 ) to load the major keys onto the hsm to do so through excrypt manager, perform the following steps open the identity management menu, select the first default admin identity ( admin1 ), and select \[ change password ] enter the old and new password twice select \[ ok ] perform the same steps for the second default admin identity ( admin2 ) fxcli perform the following steps to use fxcli to connect to the hsm start the fxcli application and run the following commands fxcli connect usb login user the login command prompts for the username and password you must run the command twice to log in with both default admin identities change the default admin passwords for both of your default admin identities to load the major keys onto the hsm use the following fxcli commands to change the passwords for each default admin identity fxcli user change password u admin1 user change password u admin2 the preceding user change password commands prompt you to enter the old and new passwords required features in the hsm to establish a connection between the {{futurex}} pkcs #11 library and the {{vectera}} , you must configure the hsm with the following features pkcs #11 > enabled command primary mode > general purpose (gp) for additional information about how to update features on your hsm, refer to the download feature request file section of the {{vectera}} user guide setting the command primary mode on the hsm to general purpose (gp) enables the option to create the ftk major key on the hsm to use the {{futurex}} pkcs #11 library to communicate with the hsm, you need this key for detailed information about how to load major keys on the hsm, refer to the {{vectera}} user guide configure the n etwork (set the hsm ip address) for this step, you must log in with an identity that has a role with permissions communication\ network settings you can use the default administrator role and admin identities choose one of the following methods to configure the network excrypt manager to use excrypt manager to configure the network, go to the configuration menu and modify the ip address configuration as needed fxcli to use fxcli to configure the network, run the network interface modify fxcli command to set an ip address for the hsm the following example shows the command syntax fxcli network interface modify interface ethernet1 –ip 10 221 0 10 –netmask 255 255 255 0 – gateway 10 221 0 1 at this point during the hsm configuration, consider the following except for the final section, which covers creating connection certificates for mutual authentication, you can complete the remaining hsm configurations in this section by using the {{guard}} (see the applicable guide for configuring hsms for pkcs #11 integrations using the {{guard}} ) if you are performing the configuration on the hsm directly but plan to add it to a guardian later, you might have to synchronize the hsm after you add it to a device group on the guardian if your use case requires configuration through a cli, then you should manage the hsms directly load major keys for this step, you must log in with an identity that has a role with the major keys\ load permission you can use the default administrator role and admin identities major keys are the highest level keys in a {{futurex}} hsm environment these symmetric keys, stored locally on the hsm, encrypt working keys and critical security parameters major keys encrypt all other keys beneath them (with the notable exception of key exchange keys) commonly, hsms within the same environment share major keys to enable synchronization and load balancing, though some settings might not require this load the {{futurex}} token key the futurex token key (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 an hsm must have an ftk before you can use it with pkcs #11 choose one of the following methods to load the ftk excrypt manager perform the following steps to use excrypt manager to load the ftk key go to the key management menu, and select \[ load ] for the ftk in the major keys section you can load keys that are xor’d together, m of n fragments, or generated if this is the first hsm in a cluster, we recommend you generate the key and save it to smart cards as m of n fragments fxcli perform the following steps to use fxcli to load the ftk key run the following majorkey fxcli command to load an ftk into the hsm you must generate a random ftk if this is the first hsm you are setting up optionally, you can also load an ftk onto smart cards simultaneously with the fragments required and fragments total flags, as shown in the following example fxcli majorkey random ftk fragments required \[number from 2 to 9] fragments total \[number from 2 to 9] if you're setting up a second hsm in a cluster, load the ftk from smart cards by running the remaining commands in this procedure this example recombines the fragments from only two smart cards however, you can recombine fragments from up to nine smart cards start the major key recombining process for the ftk fxcli majorkey recombine key ftk log in to the first smart card (enter the smart card pin when prompted for a password) fxcli smartcard login continue to the next smart card fxcli smartcard next log in to the second smart card (enter the smart card pin when prompted for a password) fxcli smartcard login complete the fragment recombining process fxcli smartcard next if the key recreation process succeeded, you see a success message, along with the final key checksum, as shown in the following sample smartcard next result status success statuscode 0 operationactive false kcv "9211" load the platform master key the platform master key (pmk) is the primary major key used in general purpose environments or those using aes cryptographic algorithms it wraps all users and subordinate keys on the server the pmk is typically a 256 bit aes key that encrypts system parameters, including smtp passwords and sftp credentials the key is the default for creating or importing keys or certificates and is the major key for asymmetric key generation choose one of the following methods to load the pmk excrypt manager perform the following steps to use excrypt manager to load the pmk go to the key management menu, and select \[ load ] for the pmk in the major keys section you can load keys that are xor’d together, m of n fragments, or generated if this is the first hsm in a cluster, we recommend you generate the key and save it to smart cards as m of n fragments fxcli perform the following steps to use excrypt manager to load the pmk run the following majorkey fxcli commands to load a pmk into the hsm you must generate a random pmk if this is the first hsm you are setting up optionally, you can also load a pmk onto smart cards simultaneously with the fragments required and fragments total flags, as shown in the following example fxcli majorkey random pmk fragments required \[number from 2 to 9] fragments total \[number from 2 to 9] if this is the second hsm you're setting up in a cluster, load the pmk from smart cards by running the remaining commands in this procedure this example recombines fragments from only two smart cards, but you can recombine fragments from up to nine smart cards start the major key recombining process for the pmk fxcli majorkey recombine key pmk log in to the first smart card (enter the smart card pin when prompted for a password) fxcli smartcard login continue to the next smart card fxcli smartcard next log in to the second smart card (enter the smart card pin when prompted for a password) fxcli smartcard login complete the fragment recombining process fxcli smartcard next if the key recreation process succeeded, you see a success message, along with the final key checksum, as shown in the following sample smartcard next result status success statuscode 0 operationactive false kcv "9211" load the backup encryption key the {{vectera}} also supports loading a backup encryption key (bek) to back up the hsm configuration or hsm keys choose one of the following methods to load the bek excrypt manager unlike other major keys on the hsm, if you load the bek through excrypt manager, you must do so from the maintenance menu perform the following steps to use excrypt manager to load the bek go to the maintenance menu, and select any available buttons for backing up keys or configuration when prompted to load the key, select \[ load backup key ] you can load keys that are xor’d together, m of n fragments, or generated if this is the first hsm in a cluster, we recommend you generate the key and save it to smart cards as m of n fragments fxcli perform the following steps to use fxcli to load the bek run the following majorkey fxcli commands to load a bek into the hsm you must generate a random bek if this is the first hsm you are setting up optionally, you can also load a pmk onto smart cards simultaneously with the fragments required and fragments total flags, as shown in the following example fxcli majorkey random bek fragments required \[number from 2 to 9] fragments total \[number from 2 to 9] if this is the second hsm you're setting up in a cluster, load the pmk from smart cards by running the remaining commands in this procedure this example recombines fragments from only two smart cards however, you can recombine fragments from up to nine smart cards start the major key recombining process for the pmk fxcli majorkey recombine key bek log in to the first smart card (enter the smart card pin when prompted for a password) fxcli smartcard login continue to the next smart card fxcli smartcard next log in to the second smart card (enter the smart card pin when prompted for a password) fxcli smartcard login complete the fragment recombining process fxcli smartcard next if the key recreation process succeeded, you see a success message, along with the final key checksum, as shown in the following sample smartcard next result status success statuscode 0 operationactive false kcv "9211" 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 excrypt manager perform the following steps to configure a transaction processing connection on excrypt manager 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) fxcli perform the following steps to configure a transaction processing connection on fxcli 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 choose one of the following methods to create an application partition go to the application partitions menu and select \[ add ] in the basic information tab, configure all of the fields as follows option required configuration role name specify any name that you would like for this new application partition 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 managed roles leave blank because you specify the exact permissions , key slots , and commands for this application partition or role to have access to use dual factor set to never upgrade permissions leave unchecked in the permissions tab, select the following key 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 option 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 hash retrieve device serial rand generate random data rkbd get hsm serial number time set time key operations commands command description gpgs general purpose generate symmetric key gpka general purpose key add gpkm retrieve key table information gpks general purpose key settings get/change data encryption commands command description gpsd general purpose symmetric decrypt gpse general purpose symmetric encrypt run the following role fxcli commands to create the new application partition and enable all needed functions fxcli role add –name role name –application –key range (0,999) –perm "keys\ authorized" –perm "keys\ import pki" – perm "keys\ no usage wrap" fxcli role modify name \[role name] add perm excrypt\ echo add perm excrypt\ hash add perm excrypt\ gpkm add perm excrypt\ gpks add perm excrypt\ gpkr add perm excrypt\ time add perm excrypt\ asyl – add perm excrypt\ gecc –add perm excrypt\ asys 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 choose one of the following methods to create the identity and associate it with the application partition excrypt manager perform the following steps to use excrypt manager to create an identity and associate it with the partition go to the identity management menu and select add 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 application partition you created if the hsm is in fips mode, you must repeat the preceding steps to create a second identity the passwords for the two identities must be identical because of how the {{futurex}} pkcs #11 library logs into the hsm fxcli perform the following steps to use fxcli to create an identity and associate it with the partition run the identity add fxcli command to create a new identity and associate it with the application partition or role that you created fxcli identity add name identity name role role name password safest if the hsm is in fips mode, you must repeat the preceding command to create a second identity after you create an indentity, you must set the name of the identity (or identities if the hsm is in fips mode) in the fxpkcs11 cfg file, in the \<hsm> section, as shown in the following example # hsm crypto operator user name \<crypto opr> \[insert name of identity that you created] \</crypto opr> \#\<crypto opr2> \[insert name of second identity if hsm is in fips mode] \</crypto opr2> 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 excrypt manager perform the following steps to use excrypt manager 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 ] fxcli perform the following steps to use fxcli to enable server side authentication 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