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 two independent rate limits:
>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, Sentinel LDK CL Service enforces the rate limit requests from any client identity until capacity becomes available.
>Identity-level rate limit: Controls the request rate for an individual client identity and 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.
Each request must satisfy both rate limits before Sentinel LDK CL Service processes the request. If either limit is exceeded, the request is throttled until sufficient capacity becomes available. If the application exceeds either limit, Sentinel LDK CL Service enforces the rate limit until sufficient capacity becomes available.
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, meaning multiple application processes that use the same client identity each have independent token buckets. Every Licensing API call from the application process consumes tokens from the corresponding token bucket.
>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 Sentinel LDK CL Service enforces rate limiting independently of the authentication method. The rate limiting applies to all Licensing API and Licensing REST API calls, whether they are authenticated using machine accounts (client identities) or OAuth 2.0.
>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.
>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.
The interface determines the rate at which the system consumes and handles tokens:
Licensing API:
>The following Licensing API functions consume tokens: hasp_login(), hasp_logout(), hasp_encrypt(), hasp_decrypt(), hasp_read(), hasp_write(), hasp_get_rtc(), and 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 Sentinel LDKerror HASP_IDENTITY_RATE_LIMIT_EXCEEDED in the response body, and returns a Retry-After response header that specifies the required wait interval before the next request.
Rate-Limit Handling
The interface determines how the system handles rate limits:
Licensing API:
>The native Licensing API caches the rate-limit state within the identity session to reduce unnecessary network traffic and server load. 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.
Licensing REST API:
>The Licensing REST API stores no rate-limit state on the client and 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 to reduce retries and additional server load.