Getting Started With Removable Licenses

Licensing using Removable License Stores

A vendor may issue to a customer a license that can be moved between instances of the licensed application using a secure USB device, such that an application instance is only licensed when the USB device is inserted on the machine on which that instance is running.  This ensures that only one instance of the application can avail of the license at any time. Additionally, with this approach:

• Perpetual, time-limited and subscription licensing models are supported
• Multiple licenses for one or more products can be activated on a single USB device
• Licenses can be activated on a device before or after the device is distributed to a customer
• The license can be updated etc without having to return the dongle

To issue a removable license to a customer you will need to:

• Initialize a USB Device
• Issue a license on that Device

USB Device Initialization

A USB device must be correctly initialized by the license vendor before a license can be activated on it.  This must be done before the device is distributed to the customer using the USB Device Manager included in the Software Potential USB SDK.

To initialise a device with the Software Potential USB Device manger:

1. Run UsbDeviceManager.exe from its installation folder
   
   
   
   
2. Login using a valid Software Potential user account credentials
   
   
   
   
3. Insert the USB Device in the machine; the ID of the device should be displayed in Cryptobox field
   If more than one supported USB Device is inserted the USB Manager will display a list of the IDs of all supported USB Devices, from which you will need to select the device to be initialized.
   
   
   
   
4. Enter the Administration password for the device (this will have been supplied by the device vendor)
   
   
   
   
5. Click Initialize to start the initialisation process; once completed a success message will be displayed
   
   
   
   

Device Re-initialization

It is possible at any stage to reinitialize a USB device.  However, doing so will delete any licenses that may have already been activated on that device.  When an attempt is made to initialize a device that has already been initialized the USB Manager will warn of the consequences of re-initialization.

Issuing Licenses Targeting USB Devices

When issuing a license that is intended for activation/installation on a USB Device you need to select the Removable option in the Environment and Locking section of the Issue License page.

Once this setting is selected the license cannot be activated on a machine that does not have a correctly initialised USB device inserted.

If you wish the license to be locked to a USB Device you can set the Initial Device checkbox. This will ensure that the license cannot be activated on another device other than the one on which it first activated.

Issue License using the Software Potential Web Service

It is also possible to programmatically issue a license that is intended for activation/installation on a USB device using the CreateLicense method in the License Management web API.  For such a license the LicenseStore property in the LicenseInfo object must be set to LicenseStore.Linked as illustrated in the following code snippet.

   public License CreateLinkedLicense( Product product, Feature[] features )
   {
       var licenseInfo = new LicenseInfo
       {
            ProductId = product.Id,
            Enabled = true,
            ActivationLimit = 1,
            VirtualMachinesAllowed = true,
            LicenseStore = LicenseStore.Linked,
            Features = features.ToArray()
       };
       return Execute( client => client.CreateLicense( licenseInfo ) );
  }

Activating a License Targeting a USB Device

A license that is intended to be installed on a USB device is activated in the same manner as any other license, using the license Activation Key. 

For a successful activation a correctly initialized USB device must be inserted in the machine on which the activation is taking place. The USB device and the license Activation key may be distributed separately allow the customer to activate the license on the device.

Activation Failures

Activations, both manual and online, of licenses intended for use with USB devices can fail for a number of reasons relating to the presence or absence of a USB device. Additionally activations may fail for the reasons that might generally apply to any license e.g. max activations limit exceeded, Single Machine or Custom Tag activation restrictions.

No USB Device present

An activation request will be rejected by the Software Potential activation service with a LinkedLicenseNoStorageActivationServerException if on the machine in question

• No USB Device is present or
• The USB Device is not correctly initialized

Multiple USB Devices Present

An activation request submitted from a machine where multiple valid USB Devices from the same vendor are installed will be rejected by the Software Potential Activation service with a LinkedLicenseNoStorageActivationServerException.  This is because the service will be unable to unambiguously determine the USB Device to which the license should be bound.

USB Device Mismatch

If during an activation process an attempt is made to write a license file to a different USB device to the one inserted at the time the activation was requested, or there is no USB device inserted, a LicenseTargetEnvironmentMismatchException will result. This is more likely to be encountered in manual activations.

Activation Error Messages

The CryptoBoxActivationExceptionHelper class in the SpAgent.Configuration.Removable file provides helpful USB specific error messages for the above activation exceptions.

Runtime Errors

An attempt to access the store with any of the following conditions will result in a NotLicensedException.

• No USB device inserted
• An un-initialized USB device inserted or
• An initialized USB device inserted but no valid license on the device.

If the device is corrupted such that the removable license store is missing but the anchor file (.rds extension) remains, the initial VerifyStoresInitialized() check will fail with a WritingStorageInaccessibleException.