# Rate Limiting for Vendor-Hosted Cloud Licensing

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.

Rate limiting is implemented by a device-based rate limiting 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 protected application that uses 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.

>Each of the following types of API calls consumes between 1 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.

NOTE Each Restful API consumes 1 token from the bucket.

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

>New tokens are added periodically to the bucket.

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

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 more information, see:

> Sentinel LDK Installation Guide.

>Sentinel LDK Software Protection and Licensing Guide for Sentinel LDK-EMS.

The following mechanisms exist for implementation of rate limiting:

>With Sentinel Licensing API 9.0 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 earlier than version 9.0:

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.

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 invalidates the HASP secure channel, requiring the secure channel to be reestablished, and then consuming 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. The use of the WebService API differs from the Licensing API in that the bucket is stored at the identity level. As a result, all applications that use the same identity share the same bucket.