Management of VCMs

Terminology

Term Description

Active VCM

A VCM that is currently running and available for use by its tenant. An active VCM will consume a portion of the memory, disk and CPU resources of the HSM. The maximum number of active VCMs is a licensable feature.

Inactive VCM

A VCM that is not currently running and is not contactable or usable by its tenant. An inactive VCM consumes negligible memory, disk and CPU resources. If a Security World had previously been loaded on the inactive VCM, this is retained and will be available for use as soon as the VCM is made active without requiring the Security World to be re-loaded and without requiring a quorum of ACS cards to be presented.

Providing VCMs for your tenants

To provide VCMs for your tenants, you must first configure the VCM networking, which is common to all VCMs, and then create as many VCMs as required by following the guidance below.

Set VCM networking

Before you create your first VCM you must decide the network addressing for the VCMs which must be consistent for all VCMs created on the HSM.

You may choose from:

  • IPv4 addresses

  • IPv6 addresses

  • IPv6 link local addresses

Note that IPv6 link local addresses are only useful if all tenants are hosted on the same physical machine in which the nShield HSM is installed. This may be the case if you have only a single VCM created or if you are using a solution in which the tenant host machines are containerized.

Once you have chosen the networking you wish to use, configure the HSM using the command hsmadmin setnetwork

After changing the network settings you must reset the HSM using the command hsmadmin reset in order for them to take effect.

Create a VCM

VCMs are requested by tenants and in order to create a VCM you must have received a tenant request message. The tenant request message will include:

  • A public key to be used for communication with the sshadmin service in the VCM

  • A public key to be used to verify subsequent requests from the tenant

  • Any properties the tenant has requested for the VCM; see VCM properties.

You can view the contents of the tenant request with the command hsmadmin vcm inspect-request.

You may choose to create the VCM with a different set of properties from those requested by the tenant. If you do this you should communicate with the tenant and in some cases it may be necessary to ask the tenant to send an updated request message.

Once you have decided on the VCM properties, create the VCM by using vcmadmin create.

The creation of the VCM will automatically create a configuration file that you must send to the tenant.

A tenant can enroll only one VCM hosted on a given HSM at a time. If you create more than one VCM on the same HSM for the same tenant, they must unenroll the existing VCM before enrolling a new one. In general, create only one VCM per HSM per tenant unless otherwise agreed with the tenant.

Limits on creating VCMs

If you have not purchased a multi-tenant licence, see Maximum number of concurrently active VCMs feature you will only be able to create a single VCM.

If you have purchased a multi-tenant licence, the number of VCMs that you can create will depend on the speed rating of the HSM. Base speed HSMs are limited to a maximum of 5 VCMs. Higher speed HSMs can create up to 1000 VCMs. If you wish to upgrade the speed rating of your HSM you can do this by purchasing a speed upgrade licence. See Speed ratings.

If you try to create a VCM in excess of the limit the command will fail. You must delete an existing VCM using vcmadmin delete.

You can see the maximum number of VCMs that you can create by using the command hsmadmin info and looking at the 'max_creatable_vcms'.

VCM properties

A VCM can be configured with different properties. These properties can be specified when the VCM is created or modified later, as described in Modify a VCM. The VCM must be stopped before its properties can be modified.

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 and send it to the service provider to authorize startup of the VCM.

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 be used only when 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 a time. Therefore, this property is normally granted on a temporary basis, except when an HSM is expected to host only one tenant.

features

This property determines the optional VCM features listed in Available optional features. For more information about managing VCM features, see VCM features.

name

This property sets the name of the VCM as seen by the service provider in some command outputs. It is never used as an input parameter but acts as a 'friendly name' in command outputs that support it.

IP address

This property sets the IP address that the tenant will use to contact their VCM. It must be within the range that was specified in Set VCM networking.

k_tenant_req

This property sets the public key used by the tenant to sign tenant request messages. It is automatically set when the VCM is created and should be changed only if the tenant informs you that the request signing key has changed. A tenant request to change the request signing key must be signed by the current request signing key.

Managing existing VCMs

Once VCMs have been created, you can manage them using the guidance below.

Start a VCM

The tenant will not be able to enroll or use the VCM if it is not started. You can start the VCM using vcmadmin start.

In some cases the tenant may have specified that they wish to authorize the starting of their VCM. If this is the case you must receive a valid request message from the tenant before you can start the VCM. The request message may have a limited validity time and you must start the VCM before this expires. If the request has expired you must ask the tenant to generate a new request.

It is important that the clock on the tenant’s machine is synchronized with the clock on your machine. You will need to contact the tenant to confirm this. It is also important that the module clock is synchronized with your host machine. Refer to Setting the system clock for how to set the system clock, as any error messages received will refer to the module clock. If this is not the first time the VCM is being started since it was created, as would be the case if the VCM had been stopped by following the steps in Stop a VCM then starting a VCM will put the tenant back in the same position they were before the VCM was stopped. Therefore if the VCM was previously enrolled there is no need for the tenant to repeat the enrollment and, if a Security World was previously loaded there is no need to reload the Security World, and thus no need for a quorum of ACS cards.

Limits on starting VCMs

The maximum number of VCMs that can be concurrently active is a licensable feature, see Maximum number of concurrently active VCMs feature. If you try to start VCMs in excess of your current license the command will fail. Either stop another VCM that is currently running using vcmadmin stop or contact Entrust Sales to purchase an updated license.

You can see the maximum number of VCMs that you can start by using the command hsmadmin info and looking at the 'max_active_vcms'.

Autostarting VCMs

When a VCM is created it can be configured to autostart after a reboot of the HSM. This property must be included in the tenant request message. VCMs configured with this property will automatically start after a reboot of the HSM and for this reason this property is mutually exclusive with the property for the tenant to authorize starting of the VCM.

If more VCMs are configured with the autostart property than the maximum number of concurrently active VCMs, see Maximum number of concurrently active VCMs feature then not all of them will be started after the reboot. For this reason you should not create more VCMs with this property than your licence allows. If a tenant requests the autostart property and you choose not to configure it, you should contact the tenant to let them know.

Stop a VCM

When a VCM is temporarily no longer needed it may be stopped using the command vcmadmin stop. This puts the VCM in an inactive state where the tenant can no longer use or contact the VCM, but does not erase any Security World data.

You should not stop a VCM that is currently in use by a tenant. You should first contact the tenant and ask them to put their VCM in maintenance mode by following the instructions at Check and change the mode of operation.

If you intend to permanently delete the VCM after stopping it you should also ask the tenant if the VCM was using audit logging, see Audit Logging and if so ask them to finalize the audit log.

If you need to stop the VCM and cannot contact the tenant then you can use the --force option to force the VCM to stop.

An inactive VCM can be made active by following the steps in Start a VCM. This will allow the tenant to contact and use the VCM again and puts them back in the same position they were prior to the VCM being stopped. However if you used the --force option when stopping the VCM then the tenant will need to restart their hardserver in order to resume communication with it.

Delete a VCM

When a VCM is permanently no longer needed it may be deleted using the command vcmadmin delete. This permanently deletes the VCM and destroys any secrets associated with it, including any Security World data. This action is irreversible.

You can only delete an inactive VCM. If the VCM is currently active you must stop it by following the steps at Stop a VCM before you can delete it.

If the VCM has an unfinalized audit log then you will not be able to delete the VCM unless you use the --force option. See Disabling audit logging for information on how to finalize the audit log.

You cannot delete a VCM that is still running even with the --force option. You must follow the procedures in Stop a VCM first. The --force option for vcmadmin delete is only for the case in which the VCM has an unfinalized audit log.

Modify a VCM

You can view the current properties of a VCM with the command vcmadmin show.

In order to modify the properties of a VCM you must have received a request message from the tenant. The request message may have a limited validity time and you must modify the VCM before this expires. If the request has expired you must ask the tenant to generate a new request.

It is important that the clock on the tenant’s machine is synchronized with the clock on your machine. You will need to contact the tenant to confirm this. It is also important that the module clock is synchronized with your host machine. Refer to Setting the system clock for information about setting the system clock, as any error messages received will refer to the module clock.

You can view the contents of the tenant request with the command hsmadmin vcm inspect-request. You can only modify a property that is contained in the tenant request.

A tenant request message may include requests to change more than one property, but you can modify only one property at a time with this command. To change multiple properties, issue the command multiple times and reuse the same tenant request file each time.

VCM properties are modified using the command vcmadmin properties set.

The properties autostart, restrict_startup, and serial_cardreader are set to either true or false. You can also use True and False. Other properties are supplied as a new value for the property.

For example:

vcmadmin properties set --request AUTOSTART_REQUEST 4f9d05b8-95f4-41ab-8b0a-0c9c7ce14209 autostart "true"
vcmadmin properties set --request NAME_REQUEST 4f9d05b8-95f4-41ab-8b0a-0c9c7ce14209 name "My_new_VCM1"

You can only modify a property to the exact value included in the tenant request. If you attempt to use a different value, you will receive an error similar to the example below:

vcmadmin properties set --request REQUEST_FILE 4f9d05b8-95f4-41ab-8b0a-0c9c7ce14209 restrict_startup "False"
ERROR: Failed to set VCM properties: orchestrator setproperties: Invalid property value: restrict_startup mismatch
The restrict_startup and autostart properties are mutually exclusive and it is not possible to modify them so that both are set to "true".

Show VCM statistics

You can retrieve information about the resource usage of all the VCMs that have been created.

VCM statistics are collected by a background process that periodically polls all VCMs, both active and inactive, and stores the information within the module. Once the information has been collected there is a fixed 30s delay before information is polled again. The command vcmadmin stats is used to retrieve the information from the module. Depending on which point in the polling cycle this command is issued, the retrieved information can be stale by up to a maximum of 30s plus the time taken to poll all VCMs.

The time taken to poll the VCMs depends on how many VCMs that are running and the loading of the HSM at the time. In the worst case, with 21 running VCMs and the HSM at maximum load, information returned may be up to 90s out of date.

VCM resource usage

You can see the memory used by each VCM by using the command vcmadmin stats and looking at the Memory use. You can see the total memory used by the HSM by use of the command hsmadmin getenvstats and looking at mem_used.

The memory used by the HSM will be the total of the memory used by all the VCMs hosted on it plus the memory being consumed by the platform. You can get an approximate figure for the memory used by the platform by seeing the mem_used figure when no VCMs are created.

The amount of persistent data stored by a VCM can be seen by using the command vcmadmin stats and looking at the Disk use. This memory is consumed even when the VCM is inactive.

To prevent a single VCM from consuming too much memory due to persistent storage a VCM will be automatically stopped if its disk usage exceeds 16 MB. Thus you should periodically monitor the disk usage of each VCM and contact the tenant if they are approaching the limit.

Once a VCM has been stopped due to exceeding the limit it must be deleted by using the command vcmadmin delete.