Licensing Protection¶

Introduction¶

The Omnistrate Licensing Protection System is designed to ensure that only authorized subscribed users can access and use your software. This system is particularly important for deployment models where customers bring their own accounts (BYOA/BYOC) or run the software on-premises. In these scenarios, software licensing is crucial for protecting intellectual property and enforcing usage policies.

System Overview¶

The licensing protection system consists of the following key components:

License File: A cryptographically signed license file is generated per deployment with a defined expiration.
Licensing Verification SDK: An SDK provided by Omnistrate that contains the logic necessary to validate leveraging the Public PKI infrastructure.
Licensing Renewal Logic: Automation that will periodically rotate the license while the subscription is active.
Suspend Subscription Logic: A management API and UI that can be used to suspend the rotation of the license file, and automation that attempt to retract the license if the deployment or subscription are deleted.

License Generation and Validation Workflow¶

License Feature Configuration¶

The licensing feature needs to be enabled for the service plan.

By default the license will be generated with a 7 days expiration. The expiration period means the time it will take for the license to expire if the subscription is suspended or the customer attempts to abuse the system. The license is automatically renewed periodically while the subscription is valid.

To ensure the license is unique for your organization, we will use the organization ID and the Product Plan ID to uniquely identify which product the license is generated for. These values need to used to validate the license using the Licensing SDKs. The product plan ID can optionally defined by a value provided in the configuration. Using different product plan keys adds an additional layer of protection that prevents transfer and unauthorized use of licenses across multiple service plans or product you maybe offering to your customers.

Docker Compose Example¶

x-customer-integrations:
  licensing: 
    # optional - defaults to 7 days
    licenseExpirationInDays: 7
    # optional - identifier used to add extra security on validation - defaults to product tier id
    productPlanUniqueIdentifier: '[product plan unique id]'

When used on a compose-spec, Omnistrate orchestrates the deployment of the containers and also takes care of mounting the secret and setting the environment variables for verification.

Service Spec Configuration¶

features:
  CUSTOMER: 
    licensing:
      # optional - defaults to 7 days
      licenseExpirationInDays: 7 
      # optional - identifier used to add extra security on validation - defaults to product tier id
      productPlanUniqueIdentifier: '[product plan unique id]'

When using Helm or Operator, the secret service-plan-subscription-license generated with the license needs to be mounted on /var/subscription/ in the license feature configuration.

License Request & Generation¶

When a customer creates a deployment, Omnistrate generates a license file a fixed expiration date. The file is generated uniquely for an Deployment, Subscription and Organization.

The license is signed. The private key used for signing the license is from a certificate that is part of the PKI infrastructure. That certificate is generated from Let's encrypt to the specific domain licensing.omnistrate.cloud. The private key used to sing the license will be rotate periodically.

License File Distribution & Mounting¶

The license file is distributed along with the public certificate that can be used to validate the signature.

The license files are securely delivered to the user and must be placed in a predefined location (e.g., mounted within a container from a secret in the namespaces of the deployment). For custom resources (e.g., Helm), this file needs to be mounted on the data plane to ensure it is always accessible during software execution. Omnistrate SDKs assume the secret is mounted under /var/subscription/.

The license and certificate files are rotated periodically by Omnistrate while the subscription is valid. Once the subscription is suspended or the deployment deleted the rotation will be paused or the file will be retracted.

License Validation¶

The public key for the certificate used to sign the license is made available along with the license. The certificate is provided as a secret and has a 90-day expiration.

The CA and Intermediary certs, chain of trust for Let's Encrypt, that are required to validate that the certificate is valid are included as constants in the SDK, to the validation does not require the CA certs to be updated on the base container image of the service.

Once the certificate is proven to be valid, the next step is to check for the signature on the license file.

If the signature is valid we can check the license expiration. The SDK will report the license is invalid if the expiration period has passed.

If the license is not expired, the SDK will check that the Organization ID and the Product Plan ID (required when the ValidateLicense method is invoked in the SDK) correspond to the values defined in the license.

Additionally, the SDK will try to obtain the autogenerated Deployment Instance ID from an environment variable INSTANCE_ID and compare that with the value in the license file. This check is performed automatically when using Container image setup, but will be required to inject the Environment variable for Helm, Kustomize and Operators. This is a weak additional check, given that the value is injected and could be tampered, but will discourage license sharing.

An SDK is provided in major programming languages to simplify the validation process. For Go, you can use the Omnistrate Licensing SDK for Go. For Java, you can use the Omnistrate Licensing SDK for Java.

Using the SDK you can, with a single call, ensure that the license is valid and protect your software.

Runtime License Verification¶

On every startup or at predefined intervals, your software can use the SDK to validate the license.

Note: It is recommended to set up a periodic check on the license file to be able to pause the service whenever the license expires, without the need to wait for a process restart.

Examples on how to use the SDK are provided on the SDK code and also we provide some example projects to illustrate how the system works.

Enforcement Actions¶

If the license check fails (e.g., expired, modified, or missing), your software can take actions such as:

Running in a restricted mode.
Displaying a license violation warning.
Shutting down or preventing further usage.

Structure of Licensing File¶

The licensing file is a JSON file that contains the following fields:

ID: Unique identifier for the license.
Creation Time: Timestamp when the license was created.
Expiration Time: Timestamp when the license will expire.
Description: Description of the Product plan as configured in Omnistrate.
Instance ID: Identifier for the deployment associated with the license.
Organization ID: Globally unique identifier for your Organization
Subscription ID: Identifier for the subscription associated with the license.
Product Plan Unique ID: Product Plan Unique Identifier that can be configured. Default to the Product Plan ID (globally unique ID autogenerated by Omnistrate).
Version: Version number of the license.

The file is signed so any content change will invalidate the signature check.

SDKs¶

To simplify the license validation process, Omnistrate provides SDKs in major programming languages:

Examples¶

For practical examples of how to implement the licensing system, you can refer to the following repository:

FAQ¶

Failure Scenarios¶

This section outlines potential failure scenarios and how Omnistrate handles them to ensure the integrity and availability of the licensing system.

1. Rotation is Delayed¶

Omnistrate will make the best effort to retract or rotate licensing files, triggering alarms to the Service Provider in case this is not possible. To prevent issues with rotation we allow a minimum license expiration of 7 days.

2. Failed to Retract License File Upon Suspension¶

In case of suspension, if the customer continues operating the software, the license file will expire and the enforcement action will prevent abuse.

3. End customer decides to permanently revoke access¶

Dataplane disconnection will not cause unavailability as the license enforcement can be done offline using Omnistrate SDK, but the license file will not be rotated and the license will expire.

Malicious Actors¶

This section addresses potential threats and questions related to the misuse of the licensing system by malicious actors.

1. Can Anyone Create a New License?¶

Omnistrate uses asymmetric encryption to sign the licensing file. Only with access to the private key can new license files be generated that will be able to pass the enforcement actions. The private key used for signing will be from a certificate that will be rotated periodically. That certificate will be part of the Public Key Infrastructure.

2. Can Someone Use the License After It Is Revoked?¶

Omnistrate will make the best effort to retract a license for a suspended subscription. In case a malicious actor blocks access to Omnistrate, the license will expire and will become obsolete on the expiration date.

3. Can Someone Copy the License and Use It in an External System?¶

With knowledge on what to look into, a malicious actor could copy the license and use it until the expiration date in an external environment. Once the expiration date is reached, the enforcement actions will consider the license obsolete.

4. Can someone use the license on a different product?¶

The Organization ID and Product Plan Unique Identifier ensures that the license is being used for the correct service plan and prevents unauthorized usage of the license in different environments or for different products.