Rate Limiting for Cloud Licensing (Vendor-Hosted)

Sentinel Licensing API supports rate limiting for cloud licensing. As a result, it possible to implement rate limiting for cloud license API calls by protected applications on customers’ machines. The use of rate limiting prevents overloading the license server and improves the licensed user experience if licensed user interactions with the applications are generating an excessive number of API calls to the license server.

Sentinel LDK enforces rate limiting using an identity-based policy using a token bucket algorithm (https://en.wikipedia.org/wiki/Token_bucket), defining the use of buckets of tokens in the cloud license manager.

The cloud license manager uses the bucket as follows:

>Each client identity that runs protected applications using cloud licensing is assigned a bucket. The bucket is assigned a starting number of tokens. The number assigned is also the maximum number of tokens that the bucket can contain.

>New tokens are added periodically to the bucket.

>Each of the following types of Licensing API calls consumes one or more tokens from the bucket and is affected by exceeding the rate limit: hasp_login, hasp_logout, hasp_encrypt, hasp_decrypt, hasp_read, hasp_write, hasp_get_rtc, and hasp_update_session. These calls can fail with the error HASP_IDENTITY_RATE_EXCEEDED.

Each Licensing REST API consumes one token from the bucket.

>When the bucket is empty, the rate limit is considered to be exceeded.

The rate limit forces you to implement protection of your application using a limited number of API calls.

Implementing Rate Limiting

To implement rate limiting for a cloud license manager hosted on your own server, configure the following parameters in the hasplm.ini file for the license manager:

rate_token_max	Maximum number of tokens in the bucket. This is also the starting value for the number of tokens in the bucket. If rate_token_max or rate_token_period_ms is 0, rate limiting is disabled.
rate_token_period_ms	Interval (in milliseconds) at which new tokens are added to the bucket. For example, a value of 3,000 means that a new token is added every 3 seconds.

For details, see Sentinel LDK Installation Guide.

Complying With Rate Limits

To ensure that API calls from your licensed users do not exceed the rate limits that you implement, you can configure Sentinel Licensing API or Sentinel Licensing REST API to limit the frequency with which API calls are sent to the cloud license manager. (Rate limiting only applies to API calls that use client identities.)

Best practices for complying with the rate limits include:

> Avoid unnecessary but repetitive API calls, such as calling encrypt/decrypt every few second to keep a session alive.

>Set the interval for periodic background checks for a valid license (using Sentinel Licensing API or Sentinel LDK Envelope) to a minimum of 10 minutes.

>Configure the cloud license manager to allow automatic detaching of licenses. This offloads the burden of responses to API calls to the users' machines.

For more information, see Sentinel Licensing API Reference.

Rate Limiting Mechanism

The following mechanisms exist for implementation of rate limiting:

>With Sentinel Licensing API 9.12 or later:

The bucket is stored in the identity session. This means that each application uses a different bucket, and different applications do not interfere with each other. The license server always fulfills the API calls, but if the rate limit is exceeded, the license server notifies the Licensing API how long to wait before making a new call. The Licensing API then causes the API call to fail on the client side, without any connection with the license server, until the stated time has elapsed.

>With Sentinel Licensing API 8.51 or earlier:

It is not possible to make the API call to fail on the client side. Therefore, the license server makes the API call fail and returns the error HASP_IDENTITY_RATE_EXCEEDED to the client. The Licensing API also returns the error HASP_IDENTITY_RATE_EXCEEDED .

NOTE   This method of failing the API call is inefficient. It saves only a fraction of the server work, as the server still has to process the API call. The older Licensing API also consumes additional API calls.

>With Sentinel Licensing REST API:

Once rate limiting is triggered, the license server makes the API call fail and returns the error HASP_IDENTITY_RATE_EXCEEDED at the LDK level, and returns the error 429 at the HTTP level. A Retry-After header is included to this response, indicating how long to wait before making a new API call.