XML Tags for the Hasp.Config Method
This topic describes the Config method XML tags that are used to:
>Specify the Machine Account (Identity String) for Accessing a Cloud License
>Configure the Server Certificate for HTTPS
>Enable the Built-in Auth RT to Obtain an Access Token for a Cloud License
>Specify the JWT to Access a Cloud License
>Configure Collection of Usage Data
The hasp_config XML tags are described below.
Specify the Machine Account (Identity String) for Accessing a Cloud License
Use the <credentials> tag to specify the client identity string (machine account) for a login session when using device-based licensing.
A client identity string represents the machine account that the login session uses to access a cloud license. Currently, a login session supports one client identity string.
If you want to change the assigned identity string during a login session, include the <clear/> tag to clear the previously-assigned credentials. Otherwise, the previously assigned credential continues to be used.
Use the following syntax:
<?xml version="1.0" encoding="UTF-8" ?>
<haspconfig>
<credentials>
<clear/>
<identity>identityString</identity>
</credentials>
</haspconfig>
Configure the Server Certificate for HTTPS
For Thales-hosted Cloud Licensing (CL), HTTPS is enforced by default. The configuration does not require additional setup for HTTPS.
Use the <server_config> tag to configure the server certificate for HTTPS.
<?xml version="1.0" encoding="UTF-8" ?>
<haspconfig>
<server_config>
<certificate>certificate-string</certificate>
<certificate_store>path</certificate_store>
</server_config>
</haspconfig>
Use the <certificate> tag to specify the certificate string.
Use the <certificate_store> tag to specify the path to the trusted certificate store that verifies the server certificate. When the configuration does not include a certificate store path, the system certificate store is used.
Enable the Built-in Auth RT to Obtain an Access Token for a Cloud License
Applicable for: Sentinel EMS
For user-based licensing, use the <auth_config> tag to enable the built-in Authentication Run-time (Auth RT). The Authentication Run-time retrieves the access token required to access a cloud license.
<?xml version="1.0" encoding="UTF-8" ?>
<haspconfig>
<auth_config>
<hasp_auth_rte>1</hasp_auth_rte>
</auth_config>
</haspconfig>
Set <hasp_auth_rte> to "1" to instruct the embedded or external License Manager to launch the built-in Authentication Run-time for user-based licensing.
When the Authentication Run-time starts, it opens a login screen in a browser (either an embedded browser or the systems default external browser). The user enters their credentials to obtain an access token, which allows the protected application to access the required cloud license.
You can also enable the built-in Authentication Run-time by setting the following parameter in the API configuration (INI) file:
hasp_auth_rte=1
When <hasp_auth_rte> is set to "1", the API launches the built-in Authentication Run-time to obtain the access token required to access the cloud license.
Specify the JWT to Access a Cloud License
Applicable for: Sentinel EMS
Use the <credentials> tag to specify a JWT for a given login session.
If you want to use a different JWT for a new session, first call Logout to release the current session. After the logout operation completes, include the <clear/> tag to clear the cached access token. Without calling Logout and clearing the cached token, the Licensing API continues to use the previously assigned access token.
Use the following syntax:
<?xml version="1.0" encoding="UTF-8" ?>
<haspconfig>
<credentials>
<clear/>
<jwt_token>accessToken@ServerAddress</jwt_token>
</credentials>
</haspconfig>
The <jwt_token> value contains the access token followed by the Sentinel EMS server address, separated by @.
Format: <AccessToken>@<ServerAddress>
Example:
<?xml version="1.0" encoding="UTF-8"?>
<haspconfig>
<credentials>
<clear/>
<jwt_token>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...@demoma.prod.sentinelcloud.com</jwt_token>
</credentials>
</haspconfig>
NOTE The ellipsis (...) indicates truncated content. The actual JWT access token contains additional characters and must be provided in the full value.
where:
>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... is the JWT access token issued by the Sentinel EMS Identity Provider.
>demoma.prod.sentinelcloud.com is the Sentinel EMS server address used to access the cloud license. Obtain the server address from the host portion of the Sentinel EMS URL.
The vendor application obtains the JWT access token from the Sentinel EMS Identity Provider using the OAuth 2.0 public client flow. Below is an example of a JWT response (in JSON format):
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"Token Ttype": "Bearer",
"expires_in": 3300,
"refresh_expires_in": "0"
}
NOTE The ellipsis (...) indicates truncated content. The actual JWT access token contains additional characters and must be provided in the full value.
Use the value from the access_token field in the <jwt_token> element.
The hasp_config configuration allows a vendor application to integrate a custom authentication flow instead of the built-in Authentication Run-time (Auth RT). In this configuration, the vendor application performs user authentication, obtains the JWT from the Sentinel EMS Identity Provider, and supplies the JWT to the Licensing API using the <jwt_token> element.
Call the Login API before the access token expires to establish the session. After a successful login, the session remains valid even after access token expiration.
You can use user-based licensing with Sentinel EMS Identity Provider service to license protected applications.
For Sentinel IDP and user-based licensing for a licensed application running under Windows or Linux: You can use Hasp.Config Method as an optional method that enables a vendor application to implement a custom authentication flow.
For more information, see Sentinel LDK Software Protection and Licensing Guide for Sentinel EMS.
Configure Collection of Usage Data
Applicable for: Sentinel EMS with Sentinel LDK CL Service
Sentinel EMS can collect usage data for Sentinel Data Platform. You can configure Sentinel EMS to:
> collect usage data globally for all applications, OR
>allow each individual login session for applications to determine whether usage data should be collected for that session.
For details on configuring Sentinel EMS, see Sentinel EMS User Guide for Sentinel LDK.
If usage data is being collected (either for all applications or for specific sessions), you have the option to include an application name or version (or both) in the collected data for each session.
Determining Whether Usage Data Should Be Collected for a Specific Session
If the Collect Usage Data attribute in Sentinel EMS is set to Set by Client Application, you use the Hasp.Config Method for a given session to choose whether to opt in or opt out for data collection:
Use the <usage_data_config> tag to configure the data collection behavior. For example:
<haspconfig>
<usage_data_config>
<user_option>opt-in</user_option>
</usage_data_config>
</haspconfig>
Assign the value opt-in or opt-out for <user_option> to indicate whether to opt in or opt out for usage data collection.
If Sentinel EMS is configured to collect usage data globally for all applications, the <user_option> tag is ignored.
When the Collect Usage Data attribute in Sentinel EMS is set to Set by Client Application, the behavior of Sentinel EMS for a given session is as follows:
>Usage data (including personal data) is collected if one of the following is true:
• hasp_config is not called.
• hasp_config is called without passing opt-in or opt-out.
• hasp_config is called and opt-in is passed.
>Usage data is not collected if hasp_config is called and opt-out is passed.
Including an Application Name or Version for Each Session
If usage data is being collected (either for all applications or for specific sessions), you have the option to include an application name or version (or both) in the collected data for a given session, using the Hasp.Config Method.
Use the <usage_data_config> tag to specify values for the application name or version to include in the collected usage data. For example:
<haspconfig>
<usage_data_config>
<app_name>DemoApp</app_name>
<app_version>1.0</app_version>
</usage_data_config>
</haspconfig>