Sentinel LDK CL Service Rate Limiting
Sentinel LDK CL Service is a hosted cloud licensing service that Thales provides for vendors who use Sentinel LDK with a Sentinel EMS subscription.
Thales hosts a highly available License Manager that serves cloud licenses to your customers. You create and manage cloud licenses and client identities (machine accounts) or associated users in Sentinel EMS.
Throughout this document:
>Licensing API refers to the native Sentinel Licensing API that is available as a static library or dynamic library (DLL/shared library) for direct integration into applications.
>Licensing REST API refers to the HTTP-based REST interface that Sentinel LDK CL Service exposes.
Your Sentinel LDK CL Service subscription includes rate limits for Licensing API and Licensing REST API requests. For the current rate limits, see Thales Knowledge Base article KB0018630.
Rate-Limiting Levels
Sentinel LDK CL Service enforces rate limits at two independent levels:
>Vendor-Level Rate Limit
>Identity-Level Rate Limit
Each request must satisfy both rate limits before Sentinel LDK CL Service processes the request.
Vendor-Level Rate Limit
The vendor-level rate limit controls the total number of Licensing API and Licensing REST API requests that can be processed for a vendor's Sentinel LDK CL Service subscription.
This limit is shared across all client identities, devices, applications, and processes associated with the vendor.
When the vendor-level rate limit is exceeded, requests from any client identity may be throttled until capacity becomes available.
Identity-Level Rate Limit
The identity-level rate limit controls the request rate for an individual client identity. The identity-level rate limit prevents a single client identity from consuming an excessive share of the available request capacity.
Sentinel LDK CL Service uses a token bucket algorithm to enforce the identity-level rate limit.
Rate-Limit Scope
An identity session represents an authenticated session for a client identity.
A token bucket stores the available request tokens for an identity session or client identity.
The scope of the identity session and token bucket depends on the licensing interface that your application uses.
Licensing API
The native Licensing API maintains one token bucket for each identity session.
When your application authenticates by using a client identity, the Licensing API creates one identity session for each application process. Each identity session has an independent token bucket. Every Licensing API call from the application process consumes tokens from the corresponding token bucket.
As a result, multiple application processes that use the same client identity each have independent token buckets.
Licensing REST API
The Licensing REST API maintains one token bucket for each client identity.
All applications and processes that authenticate by using the same client identity share the same token bucket. Requests from one application or process consume tokens from the shared token bucket and reduce the available request capacity for every other application or process that uses the same client identity.
Complying With Rate Limiting
To help ensure that your applications remain within the applicable rate limits, follow these recommendations.
NOTE Rate limiting is enforced independently of the authentication method. It applies to all Licensing API and Licensing REST API calls, whether they are authenticated using machine accounts (client identities) or OAuth 2.0.
Follow these recommendations to help your application remain within the allowed rate limits:
>Make API calls only when the application requires the operation. For example, call hasp_encrypt() or hasp_decrypt() only when the application performs encryption or decryption.
>Configure periodic background license validation (using the Licensing API or Sentinel LDK Envelope) to run no more frequently than once every 10 minutes.
>Leave license detaching enabled in Sentinel EMS when appropriate. Detached licenses reduce the load on the cloud licensing service.
>Upgrade to the latest version of the Licensing API.
>Honor the Retry-After response header before retrying a Licensing REST API request.
>When using the Licensing REST API, honor the Retry-After response header before retrying requests.
Token Consumption
Sentinel LDK CL Service uses a token bucket to enforce the identity-level rate limit.
Each token bucket:
>Starts with a fixed number of tokens.
>Has a maximum capacity.
>Receives replenished tokens at regular intervals.
>Consumes tokens when Sentinel LDK CL Service processes Licensing API or Licensing REST API requests.
>Enforces the identity-level rate limit when no tokens remain.
Licensing API
The following Licensing API functions consume tokens:
>hasp_login()
>hasp_logout()
>hasp_encrypt()
>hasp_decrypt()
>hasp_read()
>hasp_write()
>hasp_get_rtc()
>hasp_update_session()
When the identity-level rate limit is exceeded, the Licensing API returns:
HASP_IDENTITY_RATE_LIMIT_EXCEEDED
NOTE hasp_read() and hasp_write() consume one token for every 1 KB of transferred data. Read or write only the required memory segments whenever possible.
Licensing REST API
Each Licensing REST API request consumes one token.
When the identity-level rate limit is exceeded, Sentinel LDK CL Service:
>Returns HTTP status 429 (Too Many Requests).
>Returns the LDK error HASP_IDENTITY_RATE_LIMIT_EXCEEDED in the response body.
>Returns a Retry-After response header that specifies the required wait interval before the next request.
Licensing API Rate-Limit Handling
The native Licensing API caches the rate-limit state within the identity session.
When the identity-level rate limit is exceeded:
>The Licensing API sends the first request that exceeds the rate limit to the license server.
>The license server returns the required wait interval.
>During the wait interval, the Licensing API immediately returns HASP_IDENTITY_RATE_LIMIT_EXCEEDED without sending additional requests to the license server.
>After the wait interval expires, the application can invoke the Licensing API again. The Licensing API then resumes sending requests to the license server.
This client-side mechanism reduces unnecessary network traffic and server load.
Licensing REST API Rate-Limit Handling
The Licensing REST API stores no rate-limit state on the client. The Licensing REST API sends every request to the license server.
When the identity-level rate limit is exceeded:
>The license server returns HTTP status 429 (Too Many Requests).
>The response body contains HASP_IDENTITY_RATE_LIMIT_EXCEEDED.
>The Retry-After response header specifies the required wait interval before the next request.
Applications must wait for the duration specified in the Retry-After response header before sending another request. Doing so helps prevent unnecessary retries and additional server load.