Multi-tenancy on nShield 5s

Introduction to Multi-tenancy

Multi-tenancy enables multiple users ("tenants") to securely share a single nShield HSM while operating as if each tenant had a dedicated HSM. The HSM owner ("service provider") enables this capability by creating secure instances (VCMs) within the HSM for use by individual tenants. Tenants are fully isolated from one another and, once the initial configuration has been completed, experience functionality and behaviour comparable to that of an exclusive HSM. Once commissioned, a VCM is presented to the tenant as an independent module, equivalent to a physical HSM.

This means that on a single nShield HSM, multiple users are able to load their own Security World with the assurance that all keys are securely separated from, and inaccessible to, all other users.

Multi-tenancy is a licensed feature and is only available when a valid multi-tenant license is installed on the system. For more information, see Multi-tenant licensing.

Multi-tenancy terms and definitions

VCM: A discrete isolated instance of a multi-tenant nShield HSM that enables a user ("tenant") to access the cryptographic resources of the HSM.
Tenant: An individual or an organization that uses a "VCM" to perform cryptographic operations. With multi-tenancy, multiple tenants can access a single nShield HSM in a fully isolated way.
See Tenants.
Service provider: The individual or organization that owns the physical nShield HSM and is responsible for maintaining it.
See Service providers.
Active VCM: A VCM that has been started and is currently running.
Inactive VCM: A VCM that has been stopped or that has been created but never started.
Enrolled VCM: An active VCM that has established a communication path with a tenant. You cannot enroll an inactive VCM.

User Roles

The multi-tenant system defines two user types that are not available in single tenant systems:

Service provider
Tenant

Service provider

The service provider installs, ugrades, and manages the nShield HSM and creates and manages the VCMs for the tenants to use. There is only one service provider per HSM. Service providers cannot access the cryptographic secrets created by tenants on their VCMs.

A service provider can also act in a dual role as service provider and tenant, if they create VCMs for their own use. See Tenant - service provider interactions.

Tenant

Tenants access the nShield HSM through a VCM, enabling them to perform cryptographic operations.

A tenant may own multiple VCMs; however, only one VCM may be enrolled on an HSM at a time. If a tenant requires multiple concurrently enrolled VCMs, each VCM must be enrolled on a separate multi-tenant nShield HSM. A single nShield HSM can host multiple tenants, each with an independent VCM. Refer to Active and inactive VCMs for additional details. Cryptographic secrets are strictly isolated and tenants cannot access secrets created by other tenants.

Tenant - service provider interactions

The service provider role and the tenant role could both be held by the same person or organization. In this case, the user must switch between roles to perform the different tasks.

The service provider and tenant need to coordinate with each other when maintaining a VCM. For example, a tenant requests a new VCM from the service provider who then sends a configuration file to the tenant containing the data needed to enroll the new VCM.

The messages are created by the system but the communication method between the tenant and service provider is 'out of band', meaning it is for the two parties to decide on an appropriate method. This could be a secure messaging service, or a shared filesystem.

Similarly if the service provider needs to stop a VCM, they should inform the tenant to whom the VCM belongs, so that they stop using it.

The tenant can optionally specify a validity period on some messages sent to the service provider. If the service provider does not act on the request before the validity period expires, the request will fail and a new request must be generated. It is important that the clock on the tenant’s machine is synchronized with the clock on the service provider’s machine and that the module clock is synchronized with the service provider host machine.

VCMs

The maximum number of active VCMs that a service provider may provision concurrently is determined by the applicable multi-tenancy license. With the exception of licenses issued for base-speed HSMs, all multi-tenancy licenses permit up to 1,000 total VCMs per HSM. For instance a license permitting 15 active VCMs allows for up to 985 inactive VCMs when all active VCMs are in use. Base speed HSMs are limited to a maximum of five VCMs.

VCMs can be created and left inactive, or they can be activated for a period of time and then stopped. The license covers only VCMs that are currently active.

A Security World loaded onto an active VCM will not lose the Security World data when the VCM is stopped. The data is preserved and will be available again when the VCM is restarted. You can only load Security World data onto an active VCM.

Inactive VCMs place no load on the HSM’s processor and they consume minimal memory, apart from any Security World data they contain.

While tenants can have multiple inactive VCMs on an HSM, they can only have a single active VCM enrolled on any one HSM at one time. A tenant could have multiple VCMs on the same HSM, but they would need to unenroll the one they were currently using before enrolling a different one.

Tenant - VCM relationship

When a tenant requests the creation of a VCM, they send two public keys to the service provider. The tenant must have possession of the corresponding private keys to be able to use the VCM.

Typically, a VCM has a one-to-one relationship with a tenant, meaning that the tenant has exclusive use of the VCM. While it is possible to share keys between tenants to give multiple tenants access to the same VCM, you should consult with Entrust and your organization’s security policy before doing this.

A tenant can have a one-to many relationship with VCMs, although as noted previously, they can only have a single enrolled VCM on one HSM at a time. If the organization has multiple multi-tenant nShield HSMs, a tenant could have VCMs enrolled on different HSMs. A containerized solution is also possible, where multiple tenants are hosted on the same physical machine, however conceptually this is the same as having multiple tenants on different machines.

Key differences to non multi-tenant systems

Service and module visibility

When using a multi-tenant system, until you create, start, and enroll a VCM, you will not have access to ncoreapi services and the enquiry command will not display any modules.

This is because of the difference in user roles between the service provider and the tenant. When you boot a physical nShield HSM into multi-tenant mode, you are booting the physical hardware, which will not appear in the enquiry command output, because enquiry is looking at the VCMs, not the physical modules.

Until the service provider has created a VCM for a tenant, there are no modules available, so enquiry cannot display them. After the VCM has been created, started, and enrolled, the tenant can then access the ncoreapi services and can use the enquiry command to view the module.

While the same user can be both service provider and tenant, the two roles are distinct, and the user can only use the VCM when acting as the tenant.

Separation of tenant from physical hardware

In a non-multi-tenant system, commands for management and cryptographic operations were run directly on the machine that contained the nShield 5s module. This direct communication between host and module over the PCIe bus made communication extremely reliable. It also meant that rebooting the host automatically rebooted the HSM.

In a multi-tenant system, the tenant typically does not operate from the same machine that hosts the HSM. In this case, commands that are issued locally by the tenant must be transmitted to the VCM across a network. This means that:

The network must be correctly configured for the tenant to interact with the VCM.
Network issues or instability could prevent communication between tenant and VCM.
The tenant’s machine and the HSM that contains the VCM could reboot independently of each other.

This adds complexity to the network configuration and also to the recovery process if a loss of service occurs.

Because the nShield 5s does not support automatic recovery from all network outages, some network events will require manual recovery. You should use multi-tenancy on the nShield 5s over reliable networks to minimise outages, for example, a private LAN.

Startup overview

The following table contains a brief guide on setting up multi-tenancy. Follow the steps in order, paying attention to the user role required for each one.

You only need to complete the first three steps of the process once. The remaining steps should be completed for each new VCM you set up.

Detailed guidance is available in the folowing user guides:

Setup steps
	Service provider	Tenant
1	Purchase and apply the multi-tenant license.
2	Configure service provider networking.
3	Configure automatic system log retrieval
4		Create a tenant request for a VCM.
5		Send the tenant request to the service provider.
6	Create a VCM and allocate an unused address in the subnetwork to it.
7	Start the VCM.
8	Send the configuration file to the tenant.
9		Configure tenant networking.
10		Enroll the VCM.

The total volume of system logs produced will increase with each VCM added. Because of this, Entrust recommends that you use of the nshield audit logging service nshieldauditd to automatically fetch system logs from the HSM. If you do not periodically clear logs from the system, the HSM will eventually stop working when its internal disk becomes full.

Upgrade to and downgrade from v14.1.1

When upgrading to v14.1.1, first upgrade the host Security World software to v14.1.1, and then upgrade the module firmware to v14.1.1. The firmware upgrade will automatically return the module to a factory state.

When downgrading from the v14.1.1 release, downgrade the module firmware first, and then downgrade the host Security World software. The firmware downgrade will automatically return the module to a factory state.

After the module is returned to a factory state, you must enroll it with the hsmadmin enroll command before performing any other operations.

Use v14.1.1 Security World software only with v14.1.1 firmware.

Reinstallation of v14.1.1 host software

If you want to reinstall the v14.1.1 host software on the Service Provider machine, there will be a brief loss of service for all tenants. This is because the scripts used to uninstall the software will remove the device driver and cause the nshield interface to be removed from the Service Provider host machine.

After re-installing the host software you must reapply an IP address to the nshield interface, as described in define the nshield interface.

Once the IP address has been restored, each tenant must restart their hardserver.