VCM management
VCM creation
VCMs are provisioned for you by your service provider.
To request a VCM you must first generate a request message, including any properties you wish to specify, see VCM properties, using the command hsmadmin vcm create and send the request to your service provider. If you wish to see the information in the request message you can do this using the command hsmadmin vcm inspect-request.
The request will include two public keys. One is the key that will be used to connect to the sshadmin service in your VCM
and the other is the key that will be used to sign request messages sent to the service provider,
known as the 'tenant request key', see Tenant request key.
These keys are automatically created if they do not already exist. If keys already exist they are reused in any subsequent requests.
The sshadmin private key will be stored in your host file system and you should keep this safe and backed-up
according to your security procedures. See SSH Client Key Protection (nShield 5s HSMs).
| If you already have other VCMs provisioned, the service provider will need to ensure that your new VCM is created on a different physical HSM. Therefore the service provider may request information about any existing VCMs that you may have provisioned. If you attempt to enroll two VCMs hosted on the same physical HSM, the second enrollment will fail. You must either unenroll the first VCM or contact the service provider to request that they create the second VCM on a different HSM. |
Once the service provider has created your VCM they will send you a configuration file containing the information needed to setup communication to the VCM using the command hsmadmin vcm enroll.
The VCM created by the service provider may have been configured with different properties than you requested and if this is the case you should seek further clarification from the service provider.
You must issue the hsmadmin vcm enroll command from the same host machine as you issued the hsmadmin vcm create command.
|
VCM properties
A VCM can be configured with different properties. These properties can be specified either when the VCM is created or can be modified on an existing VCM as described in Modifying VCM properties. A VCM must be stopped in order to modify the properties.
autostart
This property determines whether the VCM will automatically start after a reboot of the HSM on which it is hosted.
This property is mutually exclusive with the restrict-startup property.
restrict-startup
This property determines whether the service provider is able to start the VCM without authorization from the tenant.
If this property is selected the tenant must generate a start request message using the command
hsmadmin vcm start and send it to the service provider
to authorize the starting of the VCM. The command can optionally specify a validity period for the request.
This property is mutually exclusive with the autostart property.
serial-cardreader
This property determines whether the VCM has access to the serial cardreader port that is part of the physical HSM on which the VCM is hosted. Since the HSM is owned by the service provider and located within the service provider’s premises this property would normally only be used where the tenant and service provider belong to the same organization.
Only one VCM can have access to the serial cardreader port on a given HSM at any one time. Therefore this property is normally granted on a temporary basis, except in situations where an HSM is expected to host only one tenant.
features
This property determines the optional features of the VCM as listed at Available optional features. For more information on how to manage VCM features see VCM features.
Modifying VCM properties
To modify the properties of an existing VCM you must generate a request message using the command hsmadmin vcm setproperties and send the request to your service provider. If you wish to see the information in the request message you can do this using the command hsmadmin vcm inspect-request.
The command can optionally specify a validity period for the request. You can do this by using the --request-validity option.
This option sets the validity period of the authorization. If the service provider does not modify the VCM properties within the validity period,
the command will fail and you will need to generate a new request.
| When using this option it is important to ensure that the clock on your machine is synchronized with the clock in the service provider’s machine. You will need to contact the service provider to ensure this is the case. |
Modifying autostart property
The autostart property is modified by using the command
hsmadmin vcm setproperties
with the autostart or 'no-autostart' option.
Modifying restrict-startup property
The restrict-startup property is modified by using the command
hsmadmin vcm setproperties
with the restrict-startup or 'no-restrict-startup' option.
Modifying serial-cardreader property
The serial-cardreader property is modified by using the command
hsmadmin vcm setproperties
with the serial-cardreader or 'no-serial-cardreader' option.
Modifying features property
The features property is modified by using the command
hsmadmin vcm setproperties
with the features option and specifying the features requested. See VCM features for
information on how to specify features.
Modifying name property
The name property is modified by using the command
hsmadmin vcm setproperties
with the name option and specifying a new name for the VCM.
Authorizing VCM start
If your VCM has been configured to require authorization to start it, see restrict-startup then you must create a message that authorizes the start and send it to the service provider whenever your VCM needs to be started.
You can create the message with the command hsmadmin vcm start.
The command can optionally specify a validity period for the request. You can do this by using the --request-validity option.
This option sets the validity period of the authorization. If the service provider does not start the VCM within the validity period
the start command will fail and you will need to generate a new request.
| When using this feature, it is important to ensure that the clock on your machine is synchronized with the clock on the service provider’s machine. You will need to contact the service provider to ensure this is the case. |
VCM keys
The client keys that secure communication with the services inside the VCM are the same as the client keys that secure communication with the platform services if you have any locally connected modules. The server keys will be unique for each locally connected module and each VCM. You can see the complete set of client and server keys by using the command hsmadmin keys show.
If you wish to change the client keys, you can do so using the command hsmadmin keys roll.
If you wish to backup the client keys you can do so with the command hsmadmin keys backup.
If you wish to restore the client keys from backup you can do so with the command hsmadmin keys restore. Once you have restored the keys you will need to manually enroll each VCM using the command hsmadmin vcm enroll. You will need the configuration file for each VCM to be able to do this.
VCM logs
VCM system logs
The VCM has its own system log to record events happening inside the VCM. Handling is the same as for logs at platform level, see System logging (nShield 5 HSMs) except that the commands used are from hsmadmin vcm logs.
VCM audit logs
Audit logging is unchanged when operating inside a VCM; see Audit Logging.
The audit segment header in the audit logs, see audit segment header, contains the ESN of the HSM that produced the audit record. Because you can enroll only one VCM on a given HSM at a time, the ESN and timestamp uniquely identify a VCM.
If your VCM is deleted and you enroll another VCM hosted on the same HSM, then the new VCM’s audit logs will have the same ESN in the audit segment header as the deleted VCM. However, the two logs can be distinguished by their timestamps.
The service provider cannot delete a VCM that has an unfinalized audit log unless they use the --force option. This means that, in
normal operation, VCM audit logs should always be finalized before there is any chance of the same ESN being
used for another VCM.
VCM deletion
VCMs are deleted by the service provider when you have told them that they are no longer needed, or in exceptional circumstances may be forcibly deleted by the service provider.
| Before deleting a VCM that is using audit logging, the audit log should be finalized. See Disabling audit logging. |
When a VCM has been deleted, you must remove references to that VCM from your host file system. If you do not do so,
the VCM will show up as failed in an enquiry command and you may get issues whenever you restart your hardserver.
You can remove references to a VCM by using the command hsmadmin vcm unenroll
and specifying the uuid of the VCM to delete. You can find the uuid of a VCM from the output of an
enquiry command or by looking in the config file that you received when the VCM was created and which you used
when enrolling the VCM.
When a VCM is deleted it is good practice to also delete the config file since it is no longer of any use.
Tenant request key
Messages that you send to the service provider to manage your VCM are signed by the tenant request key.
If this key does not exist it is automatically created when you request your first VCM, see VCM creation.
The keypair is stored in the tenant directory of $NFAST.
The public key is stored by the service provider and used to validate any messages sent to them. Messages that fail validation will be ignored. For this reason it is important to keep a backup of the keypair in case you delete your host-side installation, either accidentally or as part of an upgrade.
You can use standard commands for your operating system to copy the keypair to a safe location and copy it back when required.
If for any reason you wish to change the tenant request key you should first delete any VCMs created using
it and then delete the keypair from the tenant directory. A new keypair will then be generated when you
next create a VCM.
| Once you have changed the tenant request key any requests made for VCMs that existed before the change will fail to validate. For this reason it is recommended to delete all VCMs before changing the tenant request key. |